Files
claude_mac/docs/superpowers/specs/2026-11-02-phase2-guards-design.md
T

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:

  1. gitflow finish and git merge run only after a human click (native ask).
  2. The main loop writes code only inside a skill run (model-router guard).
  3. Shell deny and ask rules are no longer bypassed by the rtk rewrite or by a bare shell, sh -c or an absolute shell path.
  4. 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) or notebook_path. Free when it ends in .md or .txt, or has a path segment .claude or a leading docs/ relative to the session root. Everything else is code, config included.
  • Run signal (free when any holds): st.runMain !== null; st.turnMain?.source is skill or model; st.userMain !== null (a /route sticky).
  • 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: reflect for review/investigate/design-review/qa, plan for design-consultation, reflect for the build skills), plus the pack-…: long-name twins. The census lib/skill-routing-census.py and 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 route tool or type /route to 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.ts with no route; free on README.md, .claude/tasks/x.md, docs/a.ts; free in a sub-agent (agentId); free with a typed rowed skill across endMainTurn (runMain); free after a route-tool phase in the turn; free under /route plan; free when /route off; NotebookEdit path; a .json config 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 and lib/code-origin.sh <repo of the file> prints ours (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, else new_string (Edit) or content (Write). Width = characters (LC_ALL=C.UTF-8, awk length). Over 80 → collect line: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 with claude.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: "finish runs 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, 6 rtk 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|off and /clear; plus a route phase declared this turn and a typed /route sticky (a /model hand 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/.txt anywhere, <root>/.claude/ except <root>/.claude/worktrees/, <root>/docs/. A ~/.claude/... path is code.
  • Merge gate [USER]: Bash(git -C * merge *) dropped (it asks on any git -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 plus cat * .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 prep only. A declined finish prompt stops /release-candidate and /capitalize 5C with "nothing merged".
  • ask under auto mode is confirmed interactively by the user before the doctrine is rewritten.