Hooks

Hooks are shell scripts that Command Code runs automatically before and after each tool call. They give you deterministic control over Command Code's behavior. Use hooks to enforce project rules, audit tool use, and integrate Command Code with workflows you already have.

What are hooks?

Hooks fire before a shell command runs, before a file read, and after a write. Each hook receives the tool's inputs as JSON on stdin and returns one of four actions: allow, deny, halt the session, or inject extra context for the next turn.

What you can do with hooks?

With hooks configured, you can:

• Block dangerous bash commands before they execute, so rm -rf / never makes it past a policy guard.
• Inject project-specific context when the agent reads sensitive files, nudging the model to redact secrets.
• Audit every write to the disk by forwarding file paths to a local log.
• Halt the session if a tool's output leaks sensitive information.

Supported events

More hook events are coming soon.

Supported tools

For matcher syntax (regex, case-insensitivity, matching multiple tools), see Settings schema.

How hooks work

A hook is any executable that reads a JSON payload on stdin and writes a JSON object on stdout. Write one in bash, Node.js, Python, or anything that can parse JSON.

1. Event fires: Command Code is about to run (or has just run) a tool.
2. Hook triggered: Command Code spawns your executable and writes the tool's details as JSON on its stdin.
3. Hook responds: Your executable writes a JSON response to stdout to allow, deny, inject context, or halt the session.

For the stdin and stdout schema, exit codes, environment variables, and execution semantics, see the reference sections below.

Quickstart

This quickstart wires up your first hook in Command Code.

1. Create the settings file

Create .commandcode/settings.json at the root of your project and paste in the snippet below. The PreToolUse hook triggers before every shell command and prints a message.

.commandcode/settings.json

The command field is what Command Code runs when the hook fires. Here it prints a JSON object with a systemMessage field, and Command Code surfaces that message when running shell commands.

2. Try it out

Hooks initialize on startup. Restart Command Code with cmd, then run a prompt such as Use the shell tool to list the files in the current directory. The message PreToolUse: hook fired should appear before the shell command executes.

The quickstart hook emits a static message. Real hooks parse the JSON payload on stdin and return results, halt sessions, or inject context for the next turn — read on for configuration, the full schema, examples, and best practices.

Configuration

Hooks are configured under the hooks key in a settings.json file. Command Code looks for settings.json in the following paths:

Precedence: project > user. When the exact same command string appears in multiple scopes, the higher-priority source wins.

Ordering

Within the same event, hooks fire in the order they appear in settings.json (project first, then user).

For example, PreToolUse hooks run sequentially. As soon as one blocks the tool, the remaining PreToolUse hooks are skipped. PostToolUse hooks run in parallel because the tool has already finished.

You can wire multiple hooks under a single matcher. They run in listed order:

Here guard-bash.sh runs first. If it denies, log-shell.sh is skipped.

For a complete settings.json wiring multiple matchers across both events, see Example settings.json.

Settings schema

Hooks are configured under the hooks key in settings.json. Each event array has two levels of nesting: a HookDefinition picks which tools the hook applies to (via matcher), and a HookEntry is the handler that runs them.

One HookDefinition can own multiple HookEntry handlers. They all run for the same matcher, in the order listed.

Hook Definition fields (outer)

Chooses which tools this group of handlers applies to.

HookEntry fields (inner)

Describes a single handler to execute.

Example settings.json

In the example below, the PreToolUse hook scopes a 10-second guard to shell and write tool calls. The PostToolUse hook omits timeout (defaults to 30s) and audits every tool after it runs.

Hook input (stdin)

Before your hook runs, Command Code writes a single JSON object to its stdin. Read stdin to the end, parse it as JSON, then write your response to stdout.

Common fields

Present on all events.

Tool-call fields

Present on every event tied to a tool call.

tool_input fields

The shape of tool_input depends on which tool fired. Hooks read these fields to inspect a call. Example, a shell guard checks tool_input.command, a write audit reads tool_input.file_path.

Event-specific fields

An event may add its own fields on top of the common and tool-call sets. New events are introduced over time; each one appears as a subsection below.

PostToolUse

Stop

Stop fires when the assistant produces its final response with no remaining tool calls (end of turn). It carries no tool fields, only the common fields plus:

Environment variables

Command Code injects four environment variables into every hook process.

Your environment variables are forwarded to hook processes with any sensitive variable being stripped out.

Hook output (stdout)

The hook's executable writes a single JSON object to stdout. All fields are optional. Empty stdout on exit 0 means "no opinion, allow".

Common output fields

PreToolUseOutput fields

Adds a hookSpecificOutput object on top of the common fields.

Full shape:

PostToolUseOutput fields

Adds top-level decision / reason and a smaller hookSpecificOutput.

Full shape:

StopOutput fields

Stop uses only top-level fields, with no hookSpecificOutput.

Full shape:

Loop prevention

A naive Stop hook that always returns decision: "block" would loop forever. Two safety layers:

1. stop_hook_active on input is true on the retry fire. Hook authors should exit 0 when they see it.
2. Hard cap of 3 retries per turn enforced by the engine. After the cap, the turn ends with a Stop hook retry cap reached (3) line that names the offending script so you can fix or disable it.

Feeding text to the model on retry

Both retry triggers feed text to the model before the next turn. The conversation can't end on an assistant turn, so a retry always carries a user-role message:

• decision: "block" + reason: reason is wrapped in framing ("a Stop hook asked you to revise…") so the model treats it as revision feedback on its previous response, not a fresh request.
• exit 2 + stderr: the full stderr (capped, so multi-line tsc/lint diagnostics come through intact) is fed raw, so the model treats it like tool output and can act on it directly:

Use reason for natural-language revision guidance; use exit 2 + stderr for machine-style diagnostics the model should act on verbatim.

Who sees each field

Use this to pick the right field for the audience you want to reach.

Rule of thumb: for machine-style detail the model should act on verbatim, use exit 2 + stderr. For natural-language revision guidance, use Stop's reason. For a user-only notice, use systemMessage or stopReason.

Exit codes

The exit code is the fast path. Most hooks only ever use 0.

Exit code 2 block-reason resolution

The text sent to the model when a hook exits 2 is resolved in this order:

1. hookSpecificOutput.permissionDecisionReason (if stdout parses and sets one)
2. Top-level reason (PostToolUse only)
3. Trimmed first line of stderr
4. Generic fallback text naming the hook and its exit code

Exit code 0 stdout handling

• Empty or whitespace-only stdout means "no opinion" and the tool proceeds.
• Non-empty stdout that fails to parse as JSON, or parses but fails schema validation, is logged as a warning and the tool proceeds.

Block and halt decision matrix

Each hook result produces two effects: whether the tool runs, and whether the session continues afterward.

When a PreToolUse hook denies the tool: the model receives the permissionDecisionReason (or stderr on exit 2) as the tool result. Remaining PreToolUse hooks for that call are skipped.

When any hook sets continue: false: every hook in the current batch still runs to completion. The session halts after.

Execution semantics

How the engine runs hooks once a tool call fires.

Shell

Every hook command is spawned through a system shell. The JSON input is piped on stdin, the hook writes its response JSON to stdout. The first non-empty line of stderr is used as a fallback block reason when a hook exits 2.

Execution order

• PreToolUse hooks run sequentially in the order they appear in settings.json. Execution stops as soon as one hook denies the tool (via permissionDecision: "deny" or exit 2); later hooks for the same event do not run.
• PostToolUse hooks run in parallel. One crashing hook cannot cancel another. Returned results preserve the order they appear in settings.json, not completion order.
• Stop hooks run in parallel, like PostToolUse. Matchers on Stop hooks are silently ignored, since Stop has no tool to match against.

Timeouts

• Default timeout is 30 seconds. Override per hook with timeout (seconds, capped at 600).
• On timeout the engine sends SIGTERM. Hooks that trap SIGTERM get a 5-second grace period before SIGKILL.

Isolation

Each hook fires with its own process and its own copy of stdin. Hooks cannot read each other's stdout or stderr, and cannot pass information between themselves. When multiple hooks match the same tool call, the outputs are combined by the rules in the decision matrix; no hook sees any other hook's result.

Permission modes

The permission_mode field on stdin is one of:

Plan mode is read-only by design, so no PreToolUse guard is needed and no PostToolUse audit will fire. If your hook looks broken, check whether the session is in plan mode first.

Example: full hook script

.commandcode/hooks/guard-shell.sh

Examples

A set of working hooks you can copy into your project. Each shows a different use case, so you can modify them as you see fit. All are bash scripts here, but a hook can be any executable that parses JSON on stdin.

Every example has two files:

1. A settings.json that wires the hook.
2. A shell script at .commandcode/hooks/<name>.sh.

Ensure each script is executable with chmod +x before Command Code fires the hook.

Each example ends with a Test block containing a prompt to paste into Command Code and the result to expect so you can confirm the hook fires.

Block dangerous bash commands

Match the model's shell command against a short list of dangerous patterns. On a hit, deny the tool and tell the model why, so it doesn't retry the same pattern.

.commandcode/settings.json

.commandcode/hooks/deny-dangerous.sh

Test: Block dangerous bash commands

Prompt in Command Code:

Expected result:

• ❌ The command is blocked before it runs (it matches the rm -rf / pattern, even though the target is harmless).
• The agent sees "Command matched a dangerous pattern. Policy forbids…" and moves on without retrying.

How it works

• Reads tool_input.command from stdin with jq.
• Matches against four patterns: rm -rf /, curl | sh, a :(){} fork bomb, sudo rm.
• On a hit, emits permissionDecision: "deny". The tool is skipped and the model receives permissionDecisionReason as the tool result.
• On a miss, exits 0 with no stdout. The tool runs normally.

Warn the agent about sensitive files on read

Allow every read, but quietly inject a note when the path looks sensitive. The model sees the note as extra context and adjusts its response.

.commandcode/settings.json

.commandcode/hooks/warn-sensitive-reads.sh

Test: Warn on sensitive reads

Prompt in Command Code:

Expected result:

• ✅ The read is allowed. The hook never blocks it.
• The agent receives the injected note "SENSITIVE READ: …/.env. Redact any keys or tokens before quoting from this file." and refuses to paste the full contents.

How it works

• Always returns permissionDecision: "allow". The Read is never blocked.
• Sends additionalContext to the model, appended to the tool result before the next turn.
• Upgrades the note to an explicit redaction warning when the path matches .ssh/, .env, .pem, or id_rsa.

Audit tool calls to a log file

Log every matching tool call to an append-only file. The hook writes nothing to stdout, so it's observe-only: the tool runs unchanged. The pattern (read tool_input with jq, append a tab-separated line) is the same for any tool. Swap the event, matcher, and extracted field to fit what you want to observe.

Use PostToolUse to log what completed. Use PreToolUse to log what was attempted; this also catches commands that a later hook denies, as long as the audit hook runs first.

Writes and edits (PostToolUse)

Fires after the file mutation completes. Uses COMMANDCODE_PROJECT_DIR and COMMANDCODE_SESSION_ID directly, so there's no need to parse cwd or session_id from stdin.

.commandcode/settings.json

.commandcode/hooks/audit-writes.sh

Test: Audit writes

Prompt in Command Code:

Expected result:

• ✅ The file is created.
• The hook appends one line to .commandcode/write-audit.log.
• Verify with cat .commandcode/write-audit.log. You should see a tab-separated line (timestamp, session ID, file path).

Shell commands (PreToolUse)

Fires before execution, so this logs every shell command the agent issues.

.commandcode/settings.json

.commandcode/hooks/log-shell.sh

Test: Audit shell commands

Prompt in Command Code:

Expected result:

• ✅ The command runs as normal.
• The hook appends one line to /tmp/cmd-shell.log.
• Verify with cat /tmp/cmd-shell.log. Each entry in /tmp/cmd-shell.log has the shape (fields are tab-separated):

Quality gate (Stop hook)

Block the agent from finishing the turn while a DO NOT SHIP marker is still in the code. The Stop event fires at end of turn; this hook greps for the marker and exits 2 when it finds one, sending the assistant back for another pass with the offending lines as feedback. The stop_hook_active check is the canonical loop-prevention pattern. Without it, the hook would fire forever.

.commandcode/settings.json

.commandcode/hooks/no-ship-gate.sh

Test: Quality gate

Prompt in Command Code:

Expected result: the turn is blocked, the agent retries on its own, and it finishes once the marker is gone. Step by step:

• ❌ First turn: the assistant finishes → the hook greps → finds the DO NOT SHIP marker → exits 2 with the matching lines on stderr. A gray Stop frame appears in the feed:

• The engine feeds that stderr text back to the model as a user-role message and re-runs the turn.
• ✅ Second turn: the assistant removes the marker and adds error handling. The hook fires again with stop_hook_active: true → exits 0. The turn ends.

If the hook keeps blocking (e.g. it's broken), the engine caps retries at 3 and ends the turn with Stop hook retry cap reached (3). Ending turn. Same outcome ×4. Fix or disable: ./.commandcode/hooks/no-ship-gate.sh.

Best practices

How to pick hooks over other mechanisms, write ones you can trust, test them without running Command Code, and debug the ones that misfire.

When to use hooks

Hooks are the right tool when you need deterministic, out-of-model enforcement in your workflows. When to use hooks vs. other Command Code features:

Writing safe hooks

• Parse stdin with jq -r, never eval. Everything in tool_input came from the model and should be treated as untrusted.
• Quote every variable before passing it to shell. The deny-dangerous.sh example uses grep -qE on a quoted printf, never eval $cmd.
• Keep timeout tight (10 seconds or less for sync hooks). A slow hook blocks the tool call and makes Command Code feel laggy.
• Prefer additionalContext over systemMessage when guiding the model, and systemMessage when explaining a policy violation to the user.

Testing a hook locally

You don't need to run Command Code to iterate on a hook. Pipe a fake payload in:

Inspect stdout (JSON, or empty for "no opinion") and the exit code (echo $?). Ensure the script has execute permissions (chmod +x) to run as a hook in Command Code.

Common failure modes

What you'll see when a hook doesn't behave the way you expect:

For all of these, cmd --debug logs each hook evaluation (see below).

Debugging hooks

When a hook fires but doesn't behave the way you expect, run Command Code with --debug and tail the log:

The log records every hook evaluation: trust checks, config loads, matcher decisions, stdin/stdout payloads, and non-zero exit codes. You can see exactly why a hook was (or wasn't) invoked and what it returned.

The log file only exists while --debug is active and appends across sessions, so clear it between runs if noisy.

Performance

Hooks fire on every matching tool call. A slow hook means added latency on every matching tool call.

• Keep hooks fast. Well under a second. Users notice lag immediately.
• Push slow work to PostToolUse. It runs after the tool completes and in parallel, so slowness there doesn't block the agent.
• Move truly slow work out of process. If you need to talk to a SIEM or policy server, send a fire-and-forget HTTP request or append to a local log. Don't block on the round trip.

Next steps

• CLI Reference: flags and commands that pair with hooks
• Skills: give the model workflows it can choose to invoke
• Stuck on a schema edge case? Ask in our Discord community