Claude Code Workflows You Can Verify

A coding agent is a model in a loop with tools: it reads files, edits them and runs commands until it decides it is done, then writes a summary. The summary is a claim. It may be accurate. It may also describe the tests the agent ran after it changed which tests run.

Here is a summary from this guide's second lab. It reads well:

Every sentence is true, and the change is wrong in five ways. You will find all five with commands when you review it later in this guide. (That summary and its patch were written for the lab to represent a plausible generated change; they are not captured model output.)

A workflow you can verify replaces trust in the summary with five pieces of evidence you control:

1. A frozen spec. A failing test that reproduces the bug, committed and tagged before the agent runs, plus a written scope.
2. Explicit grants. The session can do only what the task needs, and you chose each permission on purpose.
3. Independent checks. Tests, acceptance cases, scope and integrity checks that run outside the session, from code the change could not edit.
4. A reviewed diff. A person, or a separate read-only review session, reads the change against the spec, including what the checks cannot see.
5. A recovery path. You can return to the spec state in one step and rerun.

Anthropic's own guidance puts verification first: "Give Claude a way to verify its work" with tests, a build or expected outputs, and ask it to show evidence such as "the test output, the command it ran and what it returned" (best practices). This guide adds the other half: you verify too, with checks the agent did not get to edit.

Where each control lives

The most common mistake with coding agents is putting a rule in a layer that cannot enforce it. A prompt that says never to edit the tests is making a request. The same rule as a deny rule, a hook or a scope check is a control. Claude Code's documentation draws the same line: CLAUDE.md files are treated "as context, not enforced configuration," and a PreToolUse hook is the way to block an action regardless of what Claude decides (memory). Hooks are "deterministic and guarantee the action happens," while CLAUDE.md is advisory (best practices).

Five layers, from softest to hardest:

The decision behind the table holds for any agent: anything that must always be true goes in a layer that does not depend on the model's judgment, and the final accept or reject happens outside the session.

Set up a disposable lab

Every command in this guide runs in a throwaway copy of a synthetic repository. Do not point these workflows at real code until you have run them here.

The repository is refund-rules, a small TypeScript library for a fictional retailer, Example Outfitters. Policy POL-DOA-30 says a refund request is inside the window when it is made on or before calendar day 30 after delivery, counting days in UTC with the delivery day as day 0, and that refunds on one order may not exceed $60.00 in total. Ticket T-1042 reports the bug you will fix: a customer whose tent pole section arrived snapped asked for the $48.00 replacement pole set on calendar day 30 and was told the request was late.

Install the pinned version for the live route. The native installer takes a version argument (setup):

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.304

Native installs update in the background. For a class or a CI job where everyone must run the same version, set DISABLE_AUTOUPDATER=1 or use the stable channel, and record the version in every receipt (setup). The lab's receipt check does that for you.

Unzip the lab download into an empty folder, and from that folder create the workspace, install its two pinned development dependencies, check the toolchain and look at the bug:

bash labs/new-workspace.sh labs/starter cc-labcd cc-labpnpm install --frozen-lockfilepnpm preflightpnpm decide T-1042

$ node scripts/decide.ts T-1042{  "ticketId": "T-1042",  "policyId": "POL-DOA-30",  "eligible": false,  "refundCents": 0,  "reason": "outside refund window"}

The seven existing unit tests all pass, which is the first lesson: a green suite only tells you about the cases someone wrote down. The read-only acceptance cases in acceptance/ encode the policy's boundaries, and two of them fail on this code:

FAIL  A1 T-1042: calendar day 30, later clock time than delivery      Expected values to be strictly equal:      false !== truePASS  A2 calendar day 31, earlier clock time than deliveryFAIL  A3 calendar day 30, almost 31 elapsed days

Every lab run in this guide pins --model claude-sonnet-5-5; the spike probes passed the alias sonnet, which resolved to claude-sonnet-5-5 on 2026-10-20. Aliases such as sonnet "update over time," and a full model name pins a version (model configuration). Without --model, Anthropic API accounts default to Opus 5.5, according to the same page on 2026-10-20, which lists at twice Sonnet 5.5's price per token: $4 and $20 against $2 and $10 per million input and output tokens (models overview).

Freeze the spec before the agent touches code

The spec is three files, committed together and tagged, before any agent run:

1. A failing test that reproduces the reported bug for the reported reason.
2. TASK.md: the goal, the policy, the file scope, what not to touch, and done criteria written as commands.
3. .claude/scope.json: the same file scope in machine-readable form, for the hook and the verifier.

Why freeze it first? If the agent writes the reproduction test, the same session decides both what "fixed" means and whether it is fixed. Claude Code's guidance suggests asking it to "write a failing test that reproduces the issue, then fix it" (best practices). In this workflow, you write that test (or you review and commit the one the agent proposes in plan mode), and the agent's job shrinks to making a committed test pass without editing it.

Add the reproduction test to test/window.test.ts:

test('T-1042: request on calendar day 30 is inside the window even when the clock time is later than delivery', () => {  assert.equal(isWithinWindow('2026-09-14T18:30:00Z', '2026-10-14T19:05:00Z', 30), true);});

Run pnpm test and confirm it fails for the right reason: an assertion on this case, not a syntax error or an import failure.

FAIL  T-1042: request on calendar day 30 is inside the window even when the clock time is later than delivery      Expected values to be strictly equal:      false !== truetests 8, pass 7, fail 1

Write the brief. Keep it short and testable; every "done" line is a command with a pass or fail result:

## Scope- Edit only `src/window.ts`.- Do not edit tests, `acceptance/`, `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, `scripts/`, `.claude/`, `CLAUDE.md` or `TASK.md`.- Do not add dependencies. Do not commit.- If the fix seems to need another file, stop and explain which file and why. ## Done when- `pnpm test` passes, including the new T-1042 test.- `pnpm test:acceptance` passes (cases A1 to A7 are the policy's boundary cases).- `pnpm typecheck` passes.- Your final message lists each command you ran with its pass and fail counts, and a two-sentence explanation of the root cause.

The full brief is in the handout and in labs/solutions/lab-001/TASK.md. The scope file says the same thing for machines, and the starter already has it:

{  "task": "T-1042",  "allowEdits": ["src/window.ts"],  "note": "Edit this file in the spec commit, before any agent run. The verifier reads it from the base commit."}

Commit and tag:

git add -Agit commit -q -m "spec: T-1042 day-30 refund window"git tag specgit log --format='%s%d'

The spec tag is now the known state you will verify against and return to.

Run Claude Code headless with explicit grants

You can do this lab interactively: start in plan mode with claude --permission-mode plan, read the plan, then approve it (best practices). This guide uses non-interactive mode, claude -p, because every control can be named on the command line and recorded, which is what a reviewer needs.

Three defaults are why every control is named on the command line:

• The starting permission mode. "In Claude Code v2.1.302 or later, claude -p and Agent SDK runs with no permission mode set start in Manual mode," where calls that need approval are denied unless something approves them (permission modes, checked 2026-10-20). When this guide was first checked, on 2026-10-17, the headless page described that starting mode as one that can be auto. Pass the mode you want.
• What a plain claude -p discovers. Without other flags it reads the repository's .claude/settings.json and CLAUDE.md. The headless page calls --bare, which skips that discovery, "the recommended mode for scripted and SDK calls" and says it "will become the default for -p in a future release" (headless). A route that depends on discovery would silently lose its hooks on that day.
• What --bare drops on this version. The docs say bare mode skips the auto-discovery of hooks. On 2.1.304 it also dropped the hooks in a file passed with --settings: in this guide's spike (2026-10-20, claude-sonnet-5-5, effort medium, n = 1), a bare run with a hook in --settings ran no hook, and the CLI's own --help says bare mode skips "hooks (those defined in settings and by installed plugins; ...)." Where the docs and a receipt disagree, this guide teaches the receipt.

So the lab's route does not depend on discovery or on bare mode. It starts from --restricted and names every input:

mkdir -p .runsclaude -p "$(cat TASK.md)" \  --restricted --tools Bash,Read,Edit \  --settings .claude/settings.json \  --append-system-prompt-file CLAUDE.md \  --permission-mode dontAsk \  --allowedTools "Edit(./src/window.ts)" "Bash(pnpm test)" "Bash(pnpm test:acceptance)" "Bash(pnpm typecheck)" "Bash(git diff *)" "Bash(git status *)" \  --model claude-sonnet-5-5 --effort medium \  --max-turns 12 --max-budget-usd 0.50 \  --no-session-persistence --include-hook-events \  --output-format stream-json --verbose > .runs/lab01.jsonlpnpm check:receipt .runs/lab01.jsonl

What each choice buys you:

Check the run's own record

A command line says what you asked for; the stream says what the run got. The lab's pnpm check:receipt reads the stream's first record (system/init) and its last (result) and checks seven things: both records exist (R1), the Claude Code version (R2), the permission mode (R3), the tool set (R4), a run of each configured hook for each matching tool call (R5), the instructions (R6) and how the run ended (R7). R6 works through a canary: CLAUDE.md asks Claude to end its final message with one exact line, so a run whose instructions never arrived fails R6. A missing line can also mean the model ignored it, so a failing R6 is a reason to look, not a verdict.

Receipt excerpt, run LIVE-01 (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1):

$ node scripts/check-receipt.ts .runs/lab01.jsonlPASS  R1 receipt: init record found, result record foundPASS  R2 Claude Code 2.1.304PASS  R3 permission mode dontAskPASS  R4 tools Bash, Edit, ReadPASS  R5 hooks: none configured in .claude/settings.jsonPASS  R6 instructions: final message ends with "Rules loaded: refund-rules CLAUDE.md"PASS  R7 run ended: success, 4 turnsINFO  model claude-sonnet-5-5; permission denials 0; estimated cost $0.0167 (client-side estimate) receipt: PASS

The final message of that run:

T-1042 is fixed with a change to `src/window.ts` only, and all three checks pass. - `pnpm test`: 8 tests, 8 pass, 0 fail (includes the new T-1042 test)- `pnpm test:acceptance`: 7 tests, 7 pass, 0 fail (A1 to A7)- `pnpm typecheck` (`tsc --noEmit`): passed with no errors. It prints no counts.

The diff it produced:

-  const elapsed = requested - delivered;-  return elapsed >= 0 && elapsed <= windowDays * DAY_MS;+  if (requested < delivered) {+    return false;+  }+  const deliveryDay = Math.floor(delivered / DAY_MS);+  const requestDay = Math.floor(requested / DAY_MS);+  return requestDay - deliveryDay <= windowDays;

The same command passed the verifier in 2 of 2 runs that day (LIVE-01 at $0.0167 and LIVE-02 at $0.0169, estimated; the two diffs differed and behaved the same). At 95% confidence, a Wilson interval puts 2 of 2 as consistent with a per-run failure rate as high as 66% (NIST e-Handbook). That shows the route can work, not how often it works. The summary is still a claim; the next section is how you check it.

Caps, modes and what they report

Both caps end a run with an error you can read from the result record. In this guide's spike (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1 each), --max-turns 1 ended with exit code 1, subtype error_max_turns and the error "Reached maximum number of turns (1)", while num_turns reported 2. --max-budget-usd 0.001 ended with exit code 1, subtype error_max_budget_usd and an estimated $0.0040, about four times the cap, which is why the CLI reference tells you to leave headroom.

Interactive sessions start in auto mode from v2.1.283, where a separate classifier model reviews actions; the documentation says it "reduces permission prompts but does not guarantee safety" (permission modes). Auto mode was available to claude -p with claude-sonnet-5-5 and an API key on 2.1.304 (spike ST4, 2026-10-20, effort medium, n = 1). Treat a classifier's decision as an observation, never as a control. The failure gallery shows what one auto-mode run allowed.

Verify with checks the change cannot edit

The agent ran the tests. So why run them again? Because the agent ran them through package.json scripts it could, in another run, have edited, against tests it could have edited, and reported the results in its own words. Your verification must not depend on anything inside the change.

The lab's verifier is scripts/verify-change.ts, but you never run the working tree's copy, which a change could edit. Take the copy committed at spec, put it outside the working tree, and run that:

git show spec:scripts/verify-change.ts > ../verify-spec.ts && \  node ../verify-spec.ts

It checks eight things against the spec tag:

Output after the fix:

PASS  V1 verifier is the base copy: sha256 810b9c9f2c67 matches spec:scripts/verify-change.tsPASS  V2 scope (T-1042): changed: src/window.tsPASS  V3 protected files untouched: none changedPASS  V4 existing tests intact: all base test titles present, none skippedPASS  V5 unit tests, base checkout: pass 8, fail 0PASS  V6 acceptance tests, base checkout: pass 7, fail 0PASS  V7 typecheck, base checkout: no type errorsPASS  V8 spec failed before the change: at spec: fail 1; failing: T-1042: request on calendar day 30 is inside the window even when the clock time is later than delivery

V8 is the one most teams skip. If the spec test passed before the change, it never reproduced the bug, and a green result afterward proves nothing.

V5 to V7 run in a fresh checkout because the working tree is part of the change. A change that edits package.json, a test helper or the verifier itself could change what a check measures. In the base checkout, the only thing under test is the part of the change you allowed. Version 1.0.0 of this lab ran them in the working tree and noted that a change could weaken the verifier through a file it depends on; running the spec copy against a base checkout closes that gap. The failure gallery shows a one-line edit that makes the working tree's copy print verdict: PASS for a change the spec copy fails.

The verifier writes a JSON receipt to .runs/ with the base and head commits. Attach it, the run's stream and the diff to the pull request. That bundle is the evidence; the agent's summary is a convenience.

Review an attractive but incorrect change

Now the change from the opening. Put it on a branch from the spec, apply labs/patches/candidate-grace.patch, and do what most people do first, pnpm test:

$ node --test --test-reporter=./test/reporter.mjs --test-concurrency=1 test/window.test.tsPASS  request 10 days after delivery is inside the windowPASS  request 45 days after delivery is outside the windowPASS  request on calendar day 31 is inside the grace periodPASS  invalid timestamp throws RangeErrorPASS  T-1042: request on calendar day 30 is inside the window even when the clock time is later than deliverytests 5, pass 5, fail 0

Green, and only five tests. Now the evidence:

PASS  V1 verifier is the base copy: sha256 810b9c9f2c67 matches spec:scripts/verify-change.tsFAIL  V2 scope (T-1042): out of scope: package.json, src/grace.ts, src/refund.ts, test/window.test.ts (untracked: src/grace.ts)FAIL  V3 protected files untouched: changed: package.jsonFAIL  V4 existing tests intact: test/window.test.ts: removed or renamed "request on calendar day 31 is outside the window"FAIL  V5 unit tests, base checkout: pass 3, fail 1; failing: test/window.test.tsFAIL  V6 acceptance tests, base checkout: pass 0, fail 1; failing: acceptance/window.acceptance.test.tsFAIL  V7 typecheck, base checkout: src/window.ts(1,28): error TS2307: Cannot find module './grace.ts' or its corresponding type declarations.PASS  V8 spec failed before the change: at spec: fail 1; failing: T-1042: request on calendar day 30 is inside the window even when the clock time is later than delivery

V5 to V7 fail before they reach any test case: the one in-scope file, src/window.ts, imports src/grace.ts, which is out of scope, so the base checkout does not have it. A change has to work with only the files it was allowed to touch. Two more commands show the rest. pnpm test:acceptance in the working tree fails A2 and A6, both calendar day 31. Running every unit test file, which the candidate's test script no longer does, shows one more:

FAIL  non-integer cents throws RangeError      Missing expected exception (RangeError).

Five defects, each with its proof:

1. Wrong logic that passes the reported case. A one-day grace period on elapsed time makes T-1042 pass but accepts day-31 requests (A2 and A6). The root cause, elapsed hours versus calendar days, is untouched.
2. A weakened test. The existing day-31 test was renamed and its expectation flipped to match the new behavior (V4).
3. A narrowed test command. package.json now runs only test/window.test.ts, which is why pnpm test ran five tests instead of eight (V3, and the count itself).
4. An unrelated behavior change. The "tidied" cents validation no longer rejects 48.5 cents, and the refund test the narrowed script stopped running now fails.
5. A new file outside the scope. src/grace.ts is untracked, so git diff never shows it (V2), and the in-scope code depends on it (V7).

What to look for in any generated diff

Read the diff after the checks, not instead of them, and ask five questions:

1. Does the change fix the root cause named in the spec, or only the reported example?
2. Did any test, test command or test configuration change?
3. Is every file in scope, including new untracked files that git diff does not show?
4. Are there drive-by edits to unrelated behavior?
5. What input would break this? Write it as a test.

A second session as reviewer

Claude Code's guidance suggests separate writer and reviewer sessions (best practices). The useful version gives the reviewer no way to change anything, no Edit tool and three read-only commands, and asks for a verdict in a JSON shape you define:

git status --short > .runs/before-review.txtclaude -p "$(cat ../labs/review/review-prompt.md)" \  --restricted --tools Bash,Read \  --permission-mode dontAsk \  --allowedTools "Bash(git status *)" "Bash(git diff *)" "Bash(pnpm test:acceptance)" \  --json-schema "$(cat ../labs/review/review-schema.json)" \  --model claude-sonnet-5-5 --effort medium \  --max-turns 12 --max-budget-usd 0.50 \  --no-session-persistence \  --output-format stream-json --verbose > .runs/review.jsonlpnpm check:receipt .runs/review.jsonl --expect-tools Bash,Read --canary none --expect-structured --print-structuredgit status --short | diff .runs/before-review.txt - && echo "reviewer changed nothing"

--tools sets which built-in tools exist in the session; --allowedTools only approves calls in advance (CLI reference). With --json-schema, the verdict arrives in structured_output, which is missing when a run ends without valid output, so check for it before you read it (headless). On 2.1.304 a --json-schema run also lists an extra StructuredOutput tool in system/init (spike ST3 and LIVE-07, 2026-10-20, claude-sonnet-5-5, effort medium, n = 1 each); the receipt check accepts that one tool when you pass --expect-structured.

Observed (LIVE-07, 2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1, $0.0341 estimated): verdict reject with five findings. It rated the window logic (with A2 and A6), the flipped test, the narrowed test script and the removed integer check high, and the new src/grace.ts medium. Its one denied call began with a cd into a mistyped temporary folder outside the workspace and then ran cat src/grace.ts. A cd outside the working directory is not on Claude Code's read-only list, so dontAsk denied the whole call; cat on its own needs no grant (read-only commands), and in the clean-room rerun (2026-10-20, the same version, model and effort, n = 1) cat src/grace.ts ran without one. git status did not change. On 2026-10-17, on Claude Code 2.1.302 with the 1.0.0 command and the same model and effort (n = 1), the same review also returned reject with five blocking findings. That is a useful second opinion. It is still advisory: the reviewer is a model, and the accept decision stays with the deterministic checks and a person.

Recover to a known state

You rejected the change. Get back to the spec state, and prove you are there.

git restore --staged --worktree .git status --short

?? src/grace.ts

git restore puts tracked paths back; the new file the candidate created is untracked, so it is still there (git-restore). Preview, then remove it. git clean deletes untracked files, -n is a dry run, and -f is required by default (git-clean):

git clean -ngit clean -f src/grace.tsgit status --shortpnpm test

Would remove src/grace.tsRemoving src/grace.ts

git status --short then prints nothing, and pnpm test ends with tests 8, pass 7, fail 1: the T-1042 spec test fails again, as it did at the tag. That last command is the proof. "Known state" means the spec test fails again for the original reason.

The lab also ships pnpm reset, which lists what it would discard and changes nothing until you pass --yes. Then it moves the branch and the working tree back to spec and deletes untracked files and folders. Use it only in a disposable workspace.

Checkpoints are not your rollback

Claude Code checkpoints let you rewind code, conversation or both inside an interactive session. They track only edits made through Claude's file-editing tools: "Checkpointing does not track files modified by Bash commands," and the page's own heading says checkpoints are "Not a replacement for version control" (checkpointing). A test script that writes a file, a formatter run through Bash or an mv survives a rewind. The spec tag does not depend on which tool made a change. (Checkpoints are interactive, and this guide did not exercise them.)

A failed run can still leave changes

Run LIVE-03 repeated LIVE-01's command with --max-turns 2. The documented behavior is that the run "Exits with an error when the limit is reached" (CLI reference). Observed (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1): exit code 1, subtype error_max_turns, no final message, and an edited src/window.ts on disk that passed all eight verifier checks. LIVE-03 on 2026-10-17, on 2.1.302, ended the same way.

Run status and repository state are separate facts. A failed run is not a no-op, and a successful run is not a correct change. Decide from the repository: either verify and review the leftover change like any other, or reset to spec and rerun.

Enforce the boundary with deny rules, hooks and the sandbox

Per-run flags bound one run. For rules that should hold in every run, keep them in .claude/settings.json, commit the file, and pass it with --settings as the lab's route does:

• Deny rules. "Rules are evaluated in order: deny, then ask, then allow," and the first match decides (permissions). Deny the files and commands no task should touch: Edit(./package.json), Edit(./test/**), Edit(./acceptance/**), Bash(git push *), Bash(git commit *), Bash(pnpm add *), WebFetch and so on. The full list is in labs/solutions/lab-003/.claude/settings.json.
• A PreToolUse hook that enforces the task scope. Deny rules describe stable repository policy. The task boundary changes every ticket, so it lives in scope.json, and a hook checks every edit against it.
• A Stop hook that keeps Claude working while the tests fail, a bounded number of times.
• No allow rules. Grants come from --allowedTools on each run, where a reviewer can see them.

Write every path rule with ./. The permissions page says a path that starts with / is relative to the settings source. In this guide's spike, a deny rule written as /test/** in a file passed with --settings .claude/settings.json did not protect test/: the edit went through. The same rule written as ./test/** denied it with "File is in a directory that is denied by your permission settings." (Claude Code 2.1.304, claude-sonnet-5-5, effort medium, 2026-10-20, n = 1 each.) The lab's settings test fails any path rule that does not start with ./.

The scope hook

Hooks receive JSON on stdin with tool_name and tool_input; for edits, tool_input.file_path. A PreToolUse hook blocks a call by printing hookSpecificOutput.permissionDecision: "deny" with a reason, or by exiting with code 2 (hooks). The core of labs/solutions/lab-003/.claude/hooks/guard-scope.ts:

const relative = path.relative(projectDir, realTarget(path.resolve(projectDir, raw))).split(path.sep).join('/');if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {  deny(`${raw} is outside this project. Edits must stay inside the repository.`, raw);}

After it reads .claude/scope.json, failing closed when the file is missing or unreadable:

if (!allowed.includes(relative)) {  deny(`${relative} is outside the ${scope.task ?? 'current'} task scope (allowed: ${allowed.join(', ') || 'nothing'}). Do not work around this. If the fix needs this file, stop and explain why in your final message.`, relative);}

Design choices worth copying:

• It only denies. In-scope edits fall through to the normal permission rules, so the hook can never widen access.
• It resolves symlinks and .. first, so src/link.ts pointing at package.json is denied.
• It fails closed on unreadable input (exit 2) and on a missing scope file.
• The denial reason tells the model what to do instead: stop and explain, not work around.

The hook's matcher is Edit|Write|NotebookEdit. On 2.1.304 those were the file-edit tools among the 24 tools a default Linux run listed in system/init (spike S1, 2026-10-20, claude-sonnet-5-5, effort medium, n = 1), which had no Glob or Grep. A matcher sees only the tools it names. A shell command can change a file too, and no file-edit hook sees that; the failure gallery has the run where it happened.

The Stop hook

A Stop hook blocks the stop with {"decision": "block", "reason": "..."}. Claude Code tells the hook when it is already continuing because of a stop hook (stop_hook_active), and "after stop hooks have continued the turn eight times in a row, Claude Code overrides the next block and ends the turn" (hooks). Do not rely on that ceiling. require-green.ts counts its own blocks per session and gives up after three, because a fix that cannot pass within scope should end with an explanation, not a loop. The verifier remains the final gate either way.

Hooks are code: test them offline

"Command hooks execute shell commands with your full user permissions" (hooks). Treat them like production code. Because a hook is a program that reads JSON and writes JSON, you can test it without a model: pnpm test:hooks feeds the hooks the JSON Claude Code sends (an in-scope edit, package.json, a new file, path traversal, a path outside the project, a symlink, a non-edit tool, malformed input, a missing scope file, passing and failing suites, the block limit) and checks the settings file itself: known tool names in every matcher, ./ on every path rule, the boundary files denied, no allow rules, both hooks wired. Against the starter's stubs, 7 of 18 pass; against the reference, 18 of 18.

What the controls did live

Three runs on Lab 3's branch, where the bug is present and the controls are committed (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1 each):

• LIVE-05, Lab 1's command, unchanged. The receipt check counted one scope-hook run for the one edit and one Stop-hook run, and the verifier passed. Hooks from --settings fire under --restricted.
• LIVE-06, an out-of-scope instruction on purpose. The prompt asked for a rename in src/refund.ts while scope.json named T-1042, and the run had a grant that was too broad on purpose, Edit(./src/**). Claude first tried a Bash sed -i on the file, which dontAsk denied because no grant matched it, then two Edit calls, which the scope hook denied. The Stop hook then reported the failing T-1042 test, and Claude fixed src/window.ts, which the prompt never asked for. Its final message said the rename was not done and why.
• LIVE-09, the same command in auto mode. In the failure gallery.

LIVE-06 is the subtle one. Every control worked as written, and the session still did unrequested work, because the prompt, the scope file and the Stop hook disagreed about what the task was. When you configure hooks that push the agent forward, make sure they point at the same task as the prompt and scope.json. Otherwise the agent follows the most specific signal it gets. LIVE-06 on 2026-10-17 (2.1.302, the same model and effort, n = 1), with a different out-of-scope request, went the same way.

The sandbox

Deny rules and hooks decide which tool calls run. The sandbox limits what a shell command can do once it runs. It is off by default; --settings '{"sandbox":{"enabled":true}}' turns it on for one session, and on Linux it needs bubblewrap and socat (sandboxing). In this guide's spike (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1 each), a sandboxed write outside the working directory failed with "touch: cannot touch '/tmp/g05-sb-outside.txt': Read-only file system", and a request to an unlisted host failed with "curl: (7) CONNECT tunnel failed, response 403".

Know what it leaves out. It "covers shell commands only. Claude's file tools, MCP servers, and hooks run outside it." By default a sandboxed command can still write to the working directory, so it would not have stopped the out-of-scope sed in the failure gallery. When a command fails inside the sandbox, Claude Code can retry it unsandboxed: in dontAsk mode Claude Code denies that retry, but an allow rule that matches the command also approves its retry, and allowUnsandboxedCommands: false turns the retry off (sandboxing). This guide did not exercise the retry.

What a headless run takes from a repository

Every command so far named its controls. A plain claude -p instead discovers the repository's settings, and that is where the trust boundary sits.

The permissions page says project permissions.allow rules apply only after you accept the workspace trust dialog, while "deny and ask rules aren't affected, since they only restrict" (permissions). A claude -p run never shows the dialog. The hooks page adds that a -p or SDK session "treats the folder as trusted, so hooks committed in a repository's .claude/settings.json run in a folder you've never trusted" (hooks).

This guide re-observed that on the pinned version. Run LIVE-04 (2026-10-20, Claude Code 2.1.304, claude-sonnet-5-5, effort medium, n = 1) added one allow rule to the lab's committed settings and ran a plain claude -p in a folder that had never been trusted. Its stderr, then the number of hook starts in its stream:

Ignoring 1 permissions.allow entry from .claude/settings.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/tmp/g05-walk-kryzij69/download/cc-lab"].hasTrustDialogAccepted: true in /tmp/g05-cc/home/.claude.json.3

The repository's hooks still ran three times. In the spike's version of the same check, the deny rule applied, the hook saw a variable set by the repository's env block, and CLAUDE.md loaded. On 2026-10-17, on 2.1.302 with the same model and effort (n = 1), LIVE-04 printed the same warning for ten committed allow rules, and the hooks ran.

Extended description

Heading: "From the repository's .claude/settings.json". Three cards. Mint card "Deny rules", status "Applied": "They only restrict, so workspace trust does not gate them." Amber card "Hooks and env", status "Used": "Hooks run with your permissions, and see the env block." Gray card "Allow rules", status "Ignored": "They grant, so they wait for trust, and claude -p never asks." Below, a box labeled "stderr of run LIVE-04, Claude Code 2.1.304, first sentence" quotes: "Ignoring 1 permissions.allow entry from .claude/settings.json: this workspace has not been trusted." Then, in mint: "Grants for the run come from the command line: --allowedTools". Footer: "Live: claude-sonnet-5-5, effort medium. Claude Code 2.1.304. Recorded 2026-10-20. Synthetic data."

In Claude Code 2.1.304, a never-trusted headless run applies a repository's restrictions and runs its hooks, but not its grants. Sources: run LIVE-04 (the warning and three hook starts) and spike S1 on the same CLI (the deny rule's refusal and the hook seeing a variable from the env block), one run each on 2026-10-20 with claude-sonnet-5-5 at effort medium, and the permissions page checked the same day.

The asymmetry is the lesson: in a headless run, the repository's grants are dropped while its code-executing hooks still run, with your permissions. Before you run claude -p over a repository you did not write, pick a defense on purpose. Each was tried on 2.1.304 on 2026-10-20 with claude-sonnet-5-5 at effort medium and the same probe repository (n = 1 each):

What a passing verifier does not prove

The verifier proves the change matches what you encoded: these files, these tests, these cases. It cannot tell you about cases nobody wrote down.

The assessment makes that concrete. Its candidate is a one-line fix for ticket T-3118 that passes all eight verifier checks and is still wrong; finding the input that breaks it is part of the work. So review still matters after a green verifier, and the fifth review question, the input that would break the change, is the one that catches it. When you find such a case, add it as a test before the change is accepted, so the next verifier run encodes it.

Other limits of this lab:

• Synthetic and small. One repository, a few files, fast tests. Real repositories have slow suites, flaky tests and generated code; the pattern holds, the costs change.
• Live results are observations. Every live case on 2026-10-20 is one run on one model and one machine (n = 1), except the Lab 1 command (n = 2). They show what can happen on Claude Code 2.1.304, not how often.
• Not tested here. macOS and native Windows, plan mode, /rewind, the trust dialog itself, signing in with a Claude account, and the sandbox's unsandboxed retry.
• Permission rules are not a sandbox. Bash rules match the command as written; the sandbox, which is off by default, is what limits filesystem and network access for shell commands at the operating-system level, and only for shell commands. For untrusted code, use a container or VM as well.
• Cost figures are estimates. total_cost_usd is Claude Code's client-side estimate, not an invoice. For the cost report the documentation says "The figure is an estimate" and points to the Claude Console for billing (costs).

Labs

The hands-on work is in the lab download, about 105 minutes in total. Every lab has a live route (Claude Code headless) and an offline route that makes the same change by hand, so you can finish every lab without an account, a key or a network connection after installing.

• Lab 1, Fix T-1042 from a frozen spec (guided, about 35 minutes; OBJ-001, OBJ-003). Write the failing test and brief, tag spec, make the change on either route, check the run's receipt, and pass the spec copy of the verifier.
• Lab 2, Reject the grace-period change and recover (diagnostic, about 30 minutes; OBJ-004, OBJ-005). Apply the candidate, prove each defect with a command, optionally ask a read-only reviewer, roll back, and prove you are back at the spec state.
• Lab 3, Make the boundary deterministic (independent, about 40 minutes; OBJ-002, OBJ-003). Implement the two hooks until pnpm test:hooks passes 18 of 18, commit the deny rules and hooks, watch them hold the boundary, and see what a plain claude -p takes from a repository.

Troubleshooting

Each entry was reproduced from the lab download on 2026-10-20, except T-08, which names its run.

Quick reference

The workflow:

1. Reproduce the bug with a failing test. Confirm it fails for the right reason.
2. Write TASK.md (goal, scope, do-not-touch list, done criteria as commands) and scope.json.
3. Commit and git tag spec.
4. Run the agent with every input named: --restricted, a tool set, a settings file, the instructions file, an explicit mode, path-scoped grants, --max-turns and --max-budget-usd. Record the stream.
5. Check the receipt: version, mode, tools, hook runs, instructions, how the run ended.
6. Run the spec copy of the verifier: scope, protected files, test integrity, suites in a base checkout, typecheck, reproduction at spec.
7. Review the diff with the five questions. Add a test for any missing edge case.
8. Keep (commit with the receipts) or roll back (git restore --staged --worktree ., git clean -n, git clean -f), and confirm the spec test fails again.

Commands:

bash labs/new-workspace.sh labs/starter cc-labpnpm decide T-1042pnpm test && pnpm test:acceptance && pnpm typecheckpnpm test:hookspnpm check:receipt .runs/lab01.jsonlgit show spec:scripts/verify-change.ts > ../verify-spec.ts && node ../verify-spec.tspnpm reset

Rules of thumb:

• Guidance asks; deny rules, hooks and verifiers enforce. Put "must" rules in the second group.
• Name every input of a headless run. Pass the permission mode. Pin the model by full ID. Record the version.
• Check the run's own record, not only its summary.
• Run your checks from code the change could not edit.
• Count tests as well as failures: five passing where eight used to run is a finding.
• A hook sees only the tools its matcher names; the verifier sees the repository.
• A passing verifier is necessary, not sufficient.