Claude Code Code Mode: fix your hooks first

Raising a retry limit from 3 to 5 is three tool calls for Claude Code, one after the other: find the file, edit it, run the tests. Claude asks for one tool call, reads the result, then decides on the next. Across a change that repeats in thirty files, that is ninety round trips, and Claude reads every result whether it needed to or not.

Code Mode, added as an experimental opt-in in Claude Code 2.1.323 on November 12, 2026, changes that. Claude writes a short piece of JavaScript that makes the tool calls, and Claude Code runs it in your session. The Code Mode docs use exactly that retry example:

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

Turn it on with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 for repetitive multi-file edits and for searches whose results need filtering before Claude reads them. But before you do, go and read every PreToolUse hook you have that allows or blocks shell commands. In Code Mode, a git push can reach your hook as cd 'app' && git push, and a hook that only looks at the start of the command will wave it through.

Code Mode itself was not run for this post: it needs an interactive terminal session and a Claude account. Everything about it comes from the docs and the changelog, Claude Code 2.1.326, checked November 18, 2026. The two hook scripts below were run, outside Claude Code, by piping sample JSON into them in a throwaway debian:bookworm-slim container with jq 1.6.

Turning it on

The requirements are narrower than most Claude Code features, so check them first:

  • Claude Code 2.1.323 or later, the native build.
  • A Claude subscription or Console account. Bedrock, gateways, Google Cloud, Microsoft Foundry and API key helpers are all out.
  • Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2.
  • An interactive claude session in a terminal. Not -p, not the Agent SDK, not the VS Code panel, not the Desktop app, not cloud sessions.
  • Not HIPAA-configured or zero-data-retention organisations.

Then start a session with the variable set:

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

Or put it in the env block of ~/.claude/settings.json to have it on in every new session. A project’s own settings file cannot turn it on: the docs say Claude Code ignores this variable there, so a repository you clone does not get to switch it on for you.

Claude Code asks you to confirm once, restarts, and per the docs shows this line near the top of the session:

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

That line is worth taking literally. With the variable unset, claude --resume refuses a Code Mode session.

In the conversation you still see the tool calls, such as an edit’s diff, but not the JavaScript. Press Ctrl+O to open the transcript viewer, where each piece of code sits in a collapsed Code row.

Where it pays off

The docs list three kinds of task: a change that repeats across many files, a search whose results need filtering before Claude reads them, and several independent commands that can run at the same time. The common thread is that Claude does not need to see every intermediate result. The code’s last line decides what comes back.

If you have run the transcript review prompt, the tool-call distribution it reports tells you whether your sessions are mostly long chains of small calls. Those are the sessions this is for.

Agent teams were blocked at first. Claude Code 2.1.326, November 16, 2026 added Code Mode with agent teams on, but only for teammates in the default in-process display mode, per the requirements. Teammates in split panes start without it.

The limits are real too. Code that Claude waits on stops after ten minutes, including time you spend at permission prompts. Remote Control, Claude in Chrome and computer use do not work in a Code Mode session, and you cannot move it to the Desktop app or turn it into a background session.

Why your hooks need a second look

From the permission checks section:

When Claude runs code, each tool call in it goes through your deny and ask permission rules and your PreToolUse hooks under the tool’s usual name, such as Bash.

So your hooks still run. What changes is the shape of the command they receive:

If you have a PreToolUse hook that allows or blocks shell commands, make it check each part of a command, as Bash rules do. In Code Mode, a git push in a folder named app can reach your hook as cd 'app' && git push.

Permission rules already handle this. The compound commands section says Claude Code splits on &&, ||, ;, |, |&, & and newlines, and a deny rule applies when any subcommand matches. Your hook gets none of that. It gets the raw string.

Now look at the exit-code example from the hooks reference, copied verbatim:

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

Piping both commands into it as hook input:

--- rm -rf build
Blocked: rm commands are not allowed
exit 2
--- cd 'app' && rm -rf build
exit 0

rm -rf build starts with rm, so it is blocked. cd 'app' && rm -rf build starts with cd, so it goes straight through. Any hook of yours written in that shape has the same hole, and Code Mode makes the cd … && form a normal thing to receive rather than a rare one. A hook that allows by prefix is worse: a pattern that approves anything starting with cd approves whatever comes after the &&.

Here is one way to check each part. It was tested only by piping JSON into it, not as a live hook inside Claude Code. It splits on the same separators Claude Code uses, and sends anything it cannot see into (command substitution, sh -c) to a prompt instead of guessing:

#!/bin/bash
# Blocks git push in any part of a compound command.
command=$(jq -r '.tool_input.command')

# The split below cannot see inside these, so ask instead of guessing.
if grep -qE '\$\(|`|(^|[[:space:]])(ba|z)?sh[[:space:]]+-c' <<<"$command"; then
  jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Command substitution or sh -c, check it by hand"}}'
  exit 0
fi

# Split on && || |& ; | & (newlines already separate lines).
while IFS= read -r part; do
  part="${part#"${part%%[![:space:]]*}"}"   # trim leading spaces
  if [[ "$part" == "git push"* ]]; then
    echo "Blocked: git push is not allowed in any part of a command" >&2
    exit 2
  fi
done < <(perl -pe 's/&&|\|\||\|&|;|\||&/\n/g' <<<"$command")

exit 0

Fed seven commands, it gave this. The two ask cases each print the same five-line JSON object; only its decision line is kept here:

--- git push
Blocked: git push is not allowed in any part of a command
exit 2
--- cd 'app' && git push
Blocked: git push is not allowed in any part of a command
exit 2
--- ls && rm -rf x
exit 0
--- git status
exit 0
--- echo $(git push)
    "permissionDecision": "ask",
exit 0
--- sh -c 'git push'
    "permissionDecision": "ask",
exit 0
--- git -C . push
exit 0

That last line is the gap: it does not catch git -C . push. Neither does a Bash(git push *) deny rule: the docs list that exact form under what a Bash rule does not stop. Text matching covers the commands Claude usually writes. It is not a boundary around the program. For that, the docs point to sandboxing.

Two more hook changes

Failures now block. Outside Code Mode, a PreToolUse hook that times out does not block the call; the hooks reference says the call continues through the normal permission flow. In Code Mode, the docs say a hook that fails or does not finish on a call from code refuses that call, even with onFailure unset. Timeouts go further: once Claude has run code in the session, a timed-out hook refuses any tool call, not only calls from code. A hook that exits 127 because jq is missing from PATH turns into refused tool calls on calls from code. If you would rather let calls through, set "onFailure": "continue" on that hook. If it is slow, raise its timeout.

You can check the code itself. The JavaScript runs through a tool named REPL. A PreToolUse hook with a REPL matcher can read the code from tool_input.code, per the permission checks section.

Auto mode reviews the code, not the values

If you run in auto mode, read this before relying on the classifier. The permission modes page says:

With Code Mode on, the code that Claude writes goes to the classifier once before it runs, and the tool calls inside it don’t.

And the Code Mode page adds the consequence: the classifier “doesn’t see values computed at run time, such as a path taken from search output”. In the retry example above, the classifier reads edit(target, …). It never sees which file target turned out to be.

That is fine for a retry limit. It is not fine for anything you must control, and the docs say so directly: keep rules or hooks for those calls. Deny and ask rules still apply to each call inside the code.

Before you set the variable

  1. List your hooks: grep -n '"matcher"' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json, and check any plugins you have installed that ship hooks.
  2. For each one matching Bash, find where it reads tool_input.command, and check whether it only looks at the start. Pipe it {"tool_input":{"command":"cd 'app' && <the thing it blocks>"}} and check the exit code, as above.
  3. Make sure every program your hooks call (jq, node, python) is on PATH in the session, because in Code Mode a hook that cannot start refuses the call.
  4. Move anything you can into deny and ask rules, which already split compound commands.
  5. Then start CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude and give it the docs’ test prompt, “Read every Markdown file in this project and list the links that point to local files that don’t exist.”, and press Ctrl+O to read the code it wrote.

Comments

← All posts