11 KiB
Phase 2 guards — design (2026-11-02)
BDR-125 phase 2. Contract: .claude/tasks/contracts/2026-11-02-phase2-guards-1545.md
(brainstorm answers 1-9 [gated 2026-11-02]). Branch feature/phase2-guards
off develop, after feature/router-ask-tier and chore/todo-reconcile-bdr125
merge.
Goal
Make three mechanical doctrine rules deterministic and add one soft reminder:
gitflow finishandgit mergerun only after a human click (native ask).- The main loop writes code only inside a skill run (model-router guard).
- Shell deny and ask rules are no longer bypassed by the rtk rewrite or by a
bare shell,
sh -cor an absolute shell path. - Lines over 80 columns that Claude adds to our code are reported back once
per file per session, never blocked.
Mode stays
defaultMode: auto. Nothing in deny is removed.
Unit 1 — merge gate (settings.json permissions.ask)
Rules: Bash(git merge *), Bash(git -C * merge *),
Bash(bash *gitflow.sh finish*), Bash(sh *gitflow.sh finish*),
Bash(gitflow_finish*). No git pull * (the lib pulls; the trailing *
matches the bare form, LRN-194; Gitea protects develop and main).
git push <src>:develop is caught by the existing Bash(git push *) ask once
unit 3's passthrough lands.
Trade-offs accepted: BDR-068 /close auto-finish gets one click; a sub-agent
finish (release-executor span) is measured in the bench, and
/release-candidate runs finish in the main loop regardless (BLK-018 option
b), so the click always reaches the user.
hard_deny gains, inside the "Disarming the guardrails" entry: "never edit
permissions.ask to pass a gate".
Unit 2 — routing guard (mods/model-router)
tool.call hook on Edit, Write, NotebookEdit.
- Scope: main loop only (
e.agentId === undefined); router on (!st.off). - Path:
file_path(Edit, Write) ornotebook_path. Free when it ends in.mdor.txt, or has a path segment.claudeor a leadingdocs/relative to the session root. Everything else is code, config included. - Run signal (free when any holds):
st.runMain !== null;st.turnMain?.sourceisskillormodel;st.userMain !== null(a/routesticky). - Otherwise
{ deny: <reason> }, reason: "model-router: code is written inside a skill run. Enter /hotfix (≤2 files, obvious fix), /feat, /bugfix or /ship-feature, then make this edit. This is a redirect, not a refusal." - Fail open like every other hook (
.catch→next(e), one warnOnce): the guard is doctrine support, its off switches are the router's (/route off,~/.claude/model-router.json"enabled": false). - routing.json rows for the unrowed skills that write code inline:
impeccable, design-html, design-review, design-consultation,
higgsfield-websites, qa, review, investigate (row phase = the skill's
nature:
reflectfor review/investigate/design-review/qa,planfor design-consultation,reflectfor the build skills), plus thepack-…:long-name twins. The censuslib/skill-routing-census.pyand the routing tests pin them. These rows also make them ask once (first use) and, for best-tier, trigger the ask-tier question: intended. - hard_deny gains: "A model-router redirect ('code is written inside a skill
run') is not a refusal to route around: enter the named skill. Never call
the
routetool or type/routeto pass the guard." The "Routing around a guardrail" entry gets one clause: "a redirect that names the path to take is followed, not reported". - Tests (register.test.ts, kit): deny on a main Write of
src/a.tswith no route; free onREADME.md,.claude/tasks/x.md,docs/a.ts; free in a sub-agent (agentId); free with a typed rowed skill acrossendMainTurn(runMain); free after a route-tool phase in the turn; free under/route plan; free when/route off; NotebookEdit path; a.jsonconfig is code.
Unit 3 — shell deny hygiene
rtk rc=3 passthrough
hooks/rtk-rewrite.sh rc=3 arm: exit 0 with no output (the native ask/deny
sees the original command; rtk compression is lost on ask forms only).
Re-pin hooks/.rtk-hook.sha256 in the same commit (edit + re-pin in one
step). Test: lib/tests/rtk-rewrite.test.sh gains T11 with a PATH shim rtk
that returns rc 3 for a probe command (hermetic, independent of the live rtk
and settings), asserting empty stdout; plus a pin check (the sha matches).
Twins
For each of the 14 Bash(cat|head|tail …) deny entries, add
Bash(rtk read <arg>) and Bash(*/rtk read <arg>) (28 entries). If the bench
proves head -5 .env / tail -n 5 .env RUN under the current deny, add
Bash(head * .env*), Bash(tail * .env*) and their rtk-read twins.
Census: a new block in lib/tests/push-guard.test.sh (the deny-lock suite):
every Bash(cat|head|tail X) deny has Bash(rtk read X) and
Bash(*/rtk read X); flip-tested on a fixture settings file missing one twin.
T41 gains the new literals.
Shell forms
permissions.ask += Bash(sh -c *), Bash(bash), Bash(sh),
Bash(bash -s*), Bash(bash <(*), Bash(/bin/sh *), Bash(/bin/bash *),
Bash(/usr/bin/env bash*), Bash(/usr/bin/env sh*). permissions.deny +=
Bash(awk *system(*. Never Bash(/*).
Bench
.claude/tasks/plans/2026-11-02-phase2-bench/: run.sh copied from the
2026-10-25 bench, settings and command files SAVED this time, results.tsv.
Each new rule proven with a harmless analogue (echo SECRET) and the real
forms that are safe to run (git merge --help-class no-ops are not used: the
analogue rule carries the pattern shape). Rows: the 5 merge-gate forms + start
free + plain git free; the 9 shell forms + bash script.sh free; the awk
form; head/tail flag spellings; one sub-agent ask row (Agent dispatch running
an asked command headless).
Limits written down
soft_deny gains one entry: the static matcher cannot see $(…) in command
position, a quoted literal argument, or an inline interpreter
(python3 -c, node -e); those rest on this classifier: refuse a command
that uses one of these shapes to reach an action a deny or ask rule names.
README permissions section states the same in prose, plus "ask prompts under
auto mode (measured 2026-10-25, bench R13)" replacing the inert claim;
templates/settings/SETTINGS.md § "ask is not a prompt under auto mode"
corrected.
Unit 4 — code-limits hook
hooks/code-limits.sh, PostToolUse, matcher Edit|Write|NotebookEdit,
timeout 5.
- Reads
tool_input.file_path,session_id,cwd. Skips unless the extension is one of sh bash ts js mjs py rs jq andlib/code-origin.sh <repo of the file>printsours(cached per repo per session in the sentinel dir). - Sentinel
${TMPDIR:-/tmp}/claude-code-limits-<session_id>/<sha of path>: once a file is reported, it is never reported again this session. - Added lines:
git diff -U0 -- <file>+lines when the file is tracked, elsenew_string(Edit) orcontent(Write). Width = characters (LC_ALL=C.UTF-8, awklength). Over 80 → collectline:width. - Output: at most 5 lines,
{"hookSpecificOutput":{"hookEventName": "PostToolUse","additionalContext":"code-limits: <file> has N added line(s) over 80 columns: L12 (93), …; our code keeps 80 (CLAUDE.md Limits)."}}. Nothing over → no output. Any error → exit 0 silent (never blocks). - Suite
lib/tests/code-limits.test.sh: temp HOME, TMPDIR, a git fixture repo withclaude.origin ours/foreign; over vs under; cap 5; second call silent; foreign silent; .md silent; untracked Write content; no jq → silent rc 0.
Doctrine and docs
- CLAUDE.global.md Workflow ceiling bullet: "Ceiling: the main loop writes no
code outside a skill run, whatever the model (model-router guard); it hands
the edit to /hotfix, /feat, /bugfix or /ship-feature." Refusal clause gains
"a guard redirect naming a skill is followed". Gitflow paragraph: "
finishruns only on an explicit human signal …" stays, followed by "(enforced: an ask rule prompts every finish and merge)"; the BDR-068 sentence kept; no other compression (the rest is not enforced). ≤ 320 lines. - Citers: README.md:72-75 (ceiling), the 15 agents' refusal clause where it restates "a refusal ends the attempt" (one shared sentence appended only where the agent edits code: bugfixer, feater, hotfixer, refactorer, code-cleaner, scaffolder, onboarder), skills/feat|bugfix|hotfix "CLAUDE.md Workflow" references unchanged (heading kept), lib/effort-shift.md if it quotes the ceiling.
- skills/release-candidate/SKILL.md: finish span runs in the main loop.
- CHANGELOG
[Unreleased], TODO phase 2 ticked, T42 dead-entry list handed to the user (12 entries: 6 dead, 6rtk cat|head|tail).
Out of scope (kept deferred)
Commit-msg hook; Bash write forms in the routing guard (the harness's own "prefer Bash" auto-mode instruction is a known path around an Edit-scoped guard: written down as a residual); G2 destructive guard (BLK-022); removal of any deny entry.
Proof
Bench rows for every new rule; guard fixtures; code-limits suite; routing
bench C4 / "doctor.sh rtk version" prompt in a throwaway clone enters a skill;
the user runs /close once and clicks; make test green; shellcheck clean.
R2 amendments (plan challenge round 1, 2026-11-02; [USER] = to confirm at the STEP 3 gate)
- Guard run signal [USER]:
State.skillRun, a latch set by any skill typed by the user or loaded by the model on the main loop (rowed or not), dropped only by/route clear|offand/clear; plus aroutephase declared this turn and a typed/routesticky (a/modelhand pick does not count). Replaces the 16 routing rows (they would also have opened first-use and ask-tier dialogs). Reason text adds "or re-enter the skill you were running". - Free paths:
.md/.txtanywhere,<root>/.claude/except<root>/.claude/worktrees/,<root>/docs/. A~/.claude/...path is code. - Merge gate [USER]:
Bash(git -C * merge *)dropped (it asks on anygit -C … merge …text, e.g. a sub-agent's commit message, and a background sub-agent's ask is refused);Bash(bash "*gitflow.sh" finish*)added for the quoted call-site form every skill types. The quoted form is a hard gate of the bench. - Shell forms [USER]: plus
sh -*c *,bash -*c *,dash -c *,/usr/bin/bash *,/usr/bin/sh *; denies pluscat * .env*,cat * */.env*; awk rule spelled with balanced parentheses. Each lands only if the bench approves it. - rtk hook: arms 2 and 3 share
REWRITTEN="$CMD"(the env-dump redaction still runs). - code-limits: untracked files report the payload's lines, never the whole file; 512 KiB cap; "no commit" origin not cached.
- Release: finish and tag both run in the main loop; release-executor keeps
preponly. A declined finish prompt stops/release-candidateand/capitalize5C with "nothing merged". askunder auto mode is confirmed interactively by the user before the doctrine is rewritten.