Permission System

Every tool call is allowed by a rule or read-only analysis, or denied with a reason. Nothing prompts.

The tool-policy gate (cmd/toolpolicy) hooks every tool call, permission request, prompt submit, Skill result and mid-session directory add, in every host (terminal, Desktop, headless, subagents) and mode. Its settings: Settings § Permission gate.

The closed world

When something is denied

The deny reason is the model's only channel at failure: the cause, the rule that would have allowed the call, what works instead.

tool-policy: denied Bash — no allow rule matches. candidate rule: Bash(mdfind *).
Nothing prompts in this environment; a denied capability stays denied until a rule is added.
Use an allowlisted form or a read-only alternative; do not retry the same call.

Where a rule belongs

One home per rule.

Skill grants

Self-service

toolpolicy allow '<rule>' … appends to the anchor's settings.local.json. The agent never edits that file directly.

Plan rules

A plan's rules live in plans/<feature folder>/<plan dir>/permissions.json (git-ignored): rules (each rule, target, needed_for) and checked. Never in, or read from, the plan file. Outside plan mode, smine-rules plan-display <plan file> <session plan file> writes plan plus rules into the session plan file under ~/.claude/plans/, the display copy. That directory is global, not a repo's plans/: it works across sessions, so a plan and its rules survive a hand-off to another session.

1. The design run freezes the file

   toolpolicy freeze plans/<feature folder>/<plan dir> records the file, even an empty set, in ~/.claude/tool-policy/frozen.jsonl and applies its rules to that worktree. Each rule passes the self-service shape check and equals the gate's narrowest rule for its target.

   toolpolicy freeze plans/2026-10-02-x-7ea30b5/2026-10-02-x-wip-7ea30b5

2. One freeze per typed design prompt

   One per /fdesign prompt you typed, one per unattended design run. Refreezing needs such a prompt naming the plan file. The rules file is write-protected except in a session that may still freeze its plan.

3. A typed /fimplement is the code gate's approval

   Plan at its code gate, no record, session may still freeze it: the hook freezes it on that prompt (same checks), noted in the report's approval: line. The word counts anywhere in the prompt (later line, mid-sentence, pasted block); the freeze lands at prompt submit, before the agent acts. Never: a prompt opening with another harness tag (cross-session message), a Skill(fimplement) call.

4. Every /fimplement applies the record

   /fimplement <plan file name> applies it to the anchor's settings.local.json, any worktree. Plan: the first argument word naming a plan file (arguments: all after the command, line breaks included, as the harness splits them); else the plan this session last ran smine-rules plan-sections on (a design run's one plan record, forced by fdesign's enforce block before the code gate's turn ends); neither: best-effort. A master plan applies every derived plan whose master: link names it, in one write one toolpolicy revert undoes. No record: nothing applied, the run continues.

   tool-policy /fimplement hook:
   - plan: …/plans/2026-10-02-x-7ea30b5/2026-10-02-x-wip-7ea30b5/design/x.md
   - Permissions: appended 2 rule(s), 0 already present — Bash(lsof *) Bash(./bin/heartbeat serve *)

Headless cells

A claude -p session started by the routine runner, fleet worker launcher, eval runner or a config-server probe; the launcher sets SMINE_HEADLESS=1 on the child process.

What the marker changes

Decision rows: the archived plan dirs above, in ~/GolandProjects/agent-plans/claude-configs/.

Probed 2026-10-03

CLI 2.1.282; cells started from a session's shell, unmarked, without --allowedTools.

How a call is decided

Checks run in this order on every PreToolUse call; the first answer wins.

The pieces

Make is the command surface

Approvals: the # commands

A line of your message whose first word is #allow, #deny, #add, #set, #reset, #disable or #enable; one grammar for all seven (cmd/toolpolicy/hashtag.go). Other lines: ignored prose. Lines apply in order; a misshaped one (third word on #allow, words after #reset) is nothing.

What counts as your message

Counts: a typed prompt (turnOrigin: human, every text block) and a message typed mid-turn (queued_command attachment, human origin, no meta mark): interruptions, their addenda and runs of interruptions all arrive as such rows. A Desktop paste wrapper drops with its body wherever it sits: no command inside a paste counts, a pasted transcript fires nothing; typed text around it counts.

Never counts (internal/transcript.Classify): hook block reasons written back as user rows (isMeta, "Stop hook feedback:", above all the session-title hook's rename instruction), the [Request interrupted by user] marker, tool results, compaction summaries, local commands like /model, peer relays, task notifications, headless prompts.

The gate reads commands from the transcript on every call, plus the submitted prompt. A mid-turn #add counts at the agent's next tool call; a #set rule is written on that call and admits it. A submitted prompt prints one result line per command as context; mid-turn messages apply silently. The file is the applied state: already reflected messages write nothing; toolpolicy revert never touches these entries. Claude Code's DirectoryAdded hook (/add-dir, the SDK's register_repo_root) runs the gate, appending that directory likewise; --add-dir and the Desktop "+" raise no such event.

Features for #disable and #enable

A bare group word names all members, <group>:a,b some; words expand before the fold, so #disable rgate then #enable rgate:go leaves all rgate members but go off. The gate folds these lines (last per member wins) into switches.off of its session record ~/.claude/tool-policy/state/<session_id>.json, written only on change; every hook binary and heartbeat reads it before acting, fail-open, so switches apply from the next hook event. Each change appends to switches.history ({action: disabled|enabled, at, feature}, stamped at the gate's write), shown under Session features on the session's config-server context page /sessions-report/<id>. Never features: the gate, its message channel, the worktree write guard, the heart attack, the help hook. /smine-help prints what each feature keeps on.

tool-policy #disable: rejected — unknown feature "gate"; features: rgate[:global|invoked|plan|<ext|guide>], skill[:enforce|invokegate], inject[:global|skill|acdsl|env|plan], session[:title], hb, all
tool-policy #disable: off — rgate, hb (from the next hook event on)
tool-policy #enable: on — rgate:go; still off — hb

Rule dialect

The git floor

No rule lifts these.

Read-only analysis

Fail-closed: a command is read-only only when the analysis says so.

Cards the gate cannot reach

The gate's PermissionRequest answer covers only what Claude Code asks through that hook; cards the Desktop app raises itself are controlled in its Settings.

• Browser pane cards: per-site consent; "submit sign-in credentials" for a URL with embedded credentials (kept away by the gate's deny of that URL form).
• ccd_* approval cards.
• Unlisted Desktop MCP servers: denied by the gate; admit by rule.

Files and tests