Claude Code
Put Coco in front of every tool call Claude Code makes, as a PreToolUse hook.
Put Coco in front of every tool call Claude Code makes.
trustcoco claude-code installs Coco as a PreToolUse hook. The hook decides each tool call before Claude Code's own permission prompt, against contracts in a folder on your machine or through the hosted gate.
Prerequisites: trustcoco-sdk (Install) and Node 20 or later.
Install
The installer, @trustcoco/cli, isn't published to npm yet. Build it from a coco-sdk checkout and run it:
cd coco-sdk/cli && npm ci && npm run build
COCO_PYTHON=/path/to/python-with-the-sdk node dist/src/cli.js claude-code --mode monitorOnce it's published, the command is npx @trustcoco/cli claude-code --mode monitor.
Restart Claude Code so it reads the hook.
What the installer does
- Finds a Python with
trustcoco-sdk:--python, thenCOCO_PYTHON, thenpython3on the path. - Writes
COCO_HOME(~/.cocounless set, or--home) with owner-only permissions:coco.yaml,contracts/claude_code.yaml, and.envwhen you pass--key. - Adds one PreToolUse entry for every tool to
~/.claude/settings.json(orCOCO_CLAUDE_DIR), with a 30 second timeout. Hooks it didn't write stay as they are, and an earlier Coco entry is replaced.
| Flag | Description |
|---|---|
--mode monitor, --mode enforce | The mode written to a new coco.yaml. Defaults to monitor. |
--key KEY, --url URL | Send decisions to the hosted gate. Pass both on a first install, and use coco connect on an existing folder. |
--home DIR | The folder to write instead of ~/.coco. |
--python PATH | The Python that has the SDK. |
Keep in mind: An existing coco.yaml and contracts/ folder are kept, so running the installer with another --mode leaves the mode as it was. To change it, edit mode: in COCO_HOME/coco.yaml.
Modes
| Verdict | In Monitor | In Enforce |
|---|---|---|
| DENY | No output. The receipt records "would deny". | deny: the call doesn't run, and Claude reads the reason. |
| ESCALATE | No output. The receipt records "would escalate". | ask: Claude Code asks you at the terminal. |
| AUTO_EXECUTE, OBSERVE | No output. | No output. |
No output means Claude Code's own permission prompts apply, unchanged. The hook never answers allow, because that would skip a prompt you set up.
The hook fails closed. An error inside it denies the call in Enforce, and in Monitor the call goes ahead.
Keep in mind: When the hook asks you, Claude Code takes your answer. Coco doesn't receive it, and the escalation stays open in Coco's ledger.
What the hook decides
The tool's name is the action, its input the arguments, Claude Code's session id the session, and the tool use id the call id. The working folder and the permission mode go in as state.cwd and state.permission_mode.
The installer writes three starter contracts, all live and all yours to edit:
| Contract | Governs | Verdict |
|---|---|---|
claude_code.shell_commands | Bash: deleting from the filesystem root or the home folder, writing a raw device or making a filesystem, piping a download into a shell, a fork bomb, or chmod -R 777 /. | DENY |
Bash: a force push, or a command touching a credential file. | ESCALATE | |
claude_code.credential_reads | Read of a credential file, such as .env, .ssh/, .aws/, keys, or .pem. | ESCALATE |
claude_code.credential_writes | Write, Edit, or MultiEdit to a credential file. | DENY |
A tool no contract governs takes ungoverned: impact. Claude Code's tools that only read or talk to the session, such as Read, Grep, WebFetch, and TodoWrite, run. Any other ungoverned tool, such as an MCP tool, escalates unless the classifier says it only reads. With no classifier, nobody establishes its impact, so in Enforce Claude Code asks you.
Try it somewhere harmless
Install into temporary folders, then send the hook a dangerous command:
export COCO_HOME="$(mktemp -d)" COCO_CLAUDE_DIR="$(mktemp -d)"
COCO_PYTHON=/path/to/python-with-the-sdk node dist/src/cli.js claude-code --mode enforce
echo '{"session_id":"s","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
| python -m coco_sdk.hooks.claude_codeThe last line prints a decision with "permissionDecision": "deny". Your real Claude Code settings aren't touched while COCO_CLAUDE_DIR points at the temporary folder.
Read the record
The receipts live in COCO_HOME:
cd ~/.coco
coco ledger
coco verifyTo send decisions to the gate after installing, run coco connect --key coco_live_... from COCO_HOME.
Uninstall
Remove the hook:
node dist/src/cli.js uninstall claude-code # once published: npx @trustcoco/cli uninstall claude-codeThis removes every Coco hook entry from Claude Code's settings and leaves COCO_HOME as it is. To remove the contracts and the ledger, delete the folder yourself.
If you used the older guardrails installer
The older installer, npx @trustcoco/guardrails, also writes ~/.coco: its own gate, packs/, mandate.yaml, config.json, and ledger.db. The two collide there.
- Ledger: Both name their ledger
ledger.dbin the same folder. The tables share names and differ in columns, so the new hook is expected to fail writing to the older ledger, which denies every call in Enforce. This hasn't been tested. - Files: The new installer keeps an existing
contracts/folder andcoco.yaml. The older one has neither, so the new one writes its own beside the older files. - Uninstall: The new uninstaller removes only its own hook entry. The older hook stays in
~/.claude/settings.jsonand keeps running.
Uninstall the older one first and move its folder aside, or install the new one into another folder with --home or COCO_HOME.
Set up a managed fleet
Anyone who edits their own ~/.claude/settings.json can remove the hook. On a fleet, put the hook in Claude Code's managed settings, which a user doesn't override, and set allowManagedHooksOnly so only the organisation's hooks load. Managed settings live at /etc/claude-code/managed-settings.json on Linux and /Library/Application Support/ClaudeCode/managed-settings.json on macOS.
{
"allowManagedHooksOnly": true,
"disableBypassPermissionsMode": "disable",
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "COCO_HOME=/opt/coco /usr/bin/python3 -m coco_sdk.hooks.claude_code",
"timeout": 30
}
]
}
]
}
}Write the folder once, in a place users don't write:
python3 -m coco_sdk.hooks.claude_code setup --home /opt/coco --mode monitorThen check three things:
- Read access: Setup makes the folder owner-only. A developer's hook has to read it, so open read access. A hook that can't read its folder denies every call.
- The ledger: A local ledger has to be writable by the user running Claude Code. Connect the folder to the gate instead, and the record lives off the developer's machine.
- Contract changes: Ship them through the configuration management that already reaches those machines, and pin the version you rolled out. A receipt names the contract and version that decided it.
Keep in mind: This hasn't been run on a fleet, and the hook hasn't been tested against Claude Code's permission modes. A session on a machine without the hook isn't governed.