Tool firewall and auto mode
Diagrams reflect the change that added
approvals.ts(scoped, revocable approvals), the labelled outcomes andunattended.ts. If the code has changed since, regenerate them. They are Mermaid; the site needs the Mermaid custom fence enabled inmkdocs.ymlto draw them, and otherwise shows them as code.
The tool-firewall extension decides, before every tool call runs, whether it may proceed, parsing shell commands and non-shell tools, classifying them into effects and one of four tiers, folding in session history, then either allowing, denying, or asking a human. In auto mode with the coding policy a small in-process judge decides medium actions, and high actions only when the operator previously allowed something similar in the same workspace. manual mode routes medium and high actions to the operator; the engagement policy does too, except that in auto mode a medium action whose effects are all read or network_read reaches the judge. Operator requests render as a bounded approval card or, headless, through the human-console broker. Every refusal is exactly one of three labelled outcomes: HARD DENY (policy says never), UNCERTAIN (the automatic layers could not settle it, or nobody could be asked) or OPERATOR DECISION (a human allowed or denied it); a high-confidence judge block is a fourth, labelled case. What the operator allows is remembered only as a scoped, inspectable, revocable approval. A worker started by the autonomy supervisor inside a container boundary runs in unattended mode: no prompts and no judge inside the zone, hard classes and anything outside the zone refused. protected-paths runs as a separate tool_call hook that blocks writes to secrets, control surfaces and firewall state.
Components and where state lives
The firewall is wired through three pi.on hooks (session_start, before_agent_start, tool_call) plus a sibling protected-paths hook. Runtime configuration comes from firewall.json with environment overrides, the policy comes from default-policy.json, and all durable state lives under ~/.pi/agent/pi-kit/ and <cwd>/.pi/. Unattended mode is not configuration: it is decided once from the supervisor's environment and a read-only contract file.
flowchart LR
subgraph hooks["pi tool_call hooks, in load order"]
PPH["protected-paths hook"]
SG["secret-guard hook, when enabled"]
FW["tool-firewall decide()"]
end
subgraph analysis["analysis"]
CL["classifyToolCall and parseShell"]
TR["trajectoryFindings"]
JG["judge runJudge, with confidence"]
CARD["buildCard"]
end
subgraph operator["asking someone"]
UI["interactive card, bounded"]
BR["brokerApproval, bounded"]
HC["human-console watcher"]
end
subgraph state["durable state"]
CFG["firewall.json and env overrides"]
POL["default-policy.json"]
APR["firewall-approvals.json"]
FB["firewall-feedback.jsonl and firewall-judgements.jsonl"]
PRO["firewall-profile.json"]
SES["firewall-sessions SESSION.json"]
AUD["tool-firewall-audit.jsonl"]
PEND["human-console pending and resolved"]
end
ENV["supervisor env: PI_KIT_UNATTENDED, _BOUNDARY, _CONTRACT"] --> UN["unattended.ts, decided once at load"]
CON["read-only contract.json"] --> UN
PPH --> FW
SG --> FW
FW --> CL
FW --> TR
FW --> JG
FW --> CARD
FW --> UN
CARD --> UI
CARD --> BR
BR --> PEND
PEND --> HC
HC --> UI
FW --> APR
FW --> FB
FB --> PRO
FW --> CFG
FW --> POL
TR --> SES
FW --> AUD
ROOT["root session env PI_KIT_FIREWALL_ROOT_SESSION"] --> APR
SUB["subagents inherit the root session and the unattended env"] --> ROOT
protected-paths blocks writes to secrets, the control surfaces, the firewall's state (including firewall-approvals.json) and the unattended contract path, plus .git/, node_modules/, .pi/agents/, .pi/pentest/ and .pi/engagement/ under the engagement policy (PI_KIT_PROTECTED_PATHS can only add entries; PI_KIT_WRITE_ALLOWLIST switches it to allowlist mode).
Decision pipeline
Inside decide, the call is hashed, classified into findings, enriched with operator regex rules and trajectory findings, reduced to a tier, and summarised before any allow or block decision. Critical is a HARD DENY at once. In an unattended run the contract's rules apply next. Low runs. Everything else enters the approval, precedent, judge and operator path.
flowchart TD
A["tool_call event"] --> B["toolName and input"]
B --> C["actionHash sha256"]
C --> D["classify shell and tools"]
D --> E["operator regex rules"]
E --> F["trajectory findings"]
F --> G["effects recompute"]
G --> H["effectiveTier"]
H --> I["summarize and signature"]
I --> J{"tier critical?"}
J -- yes --> HD["HARD DENY, labelled"]
J -- no --> U{"unattended run and still valid?"}
U -- yes --> UZ["zone rules: see the unattended diagram"]
U -- no --> K{"tier low?"}
K -- yes --> L["allow by analyser"]
K -- no --> M["approvals, precedents, judge, operator"]
Decision matrix by mode and policy
The effective matrix depends on mode and policy. manual never auto-approves a new action above low and the judge is never called; only an exact approval given for this session, workspace and directory runs without asking. auto with coding lets the judge decide medium actions, and high actions only when the operator allowed something similar in this workspace; engagement disables learning and approvals and denies high actions when no operator is present. An exact approval never overrides a hard deny.
flowchart TD
S["tier low"] --> A1["allow"]
C["tier critical"] --> D1["HARD DENY"]
M["tier medium"] --> MG{"exact approval here?"}
MG -- yes --> MA["allow without asking"]
MG -- no --> Q{"mode and policy"}
Q -- manual --> H1["ask the operator"]
Q -- "auto, coding" --> J1["judge"]
Q -- "auto, engagement" --> R1{"effects only read or network_read?"}
R1 -- yes --> J1
R1 -- no --> H1
J1 -- allow --> J2["allow"]
J1 -- "block, high confidence or no confidence" --> JB["AUTO-MODE BLOCK, reason to the agent"]
J1 -- "block unsure, unavailable, timeout" --> UNC["UNCERTAIN: escalate"]
UNC --> H1
H1 --> HR{"operator reachable?"}
HR -- "card or console answers" --> OD["OPERATOR DECISION"]
HR -- "nobody, or no answer in time" --> UF["UNCERTAIN refused, bounded"]
T["tier high"] --> HG{"exact approval here?"}
HG -- yes --> HA["allow without asking"]
HG -- no --> Q2{"mode and policy"}
Q2 -- manual --> H4["ask the operator"]
Q2 -- "auto, coding" --> G1{"learned exact action in this workspace?"}
G1 -- yes --> HA
G1 -- no --> N1{"similar action allowed before in this workspace?"}
N1 -- yes --> J3["judge scope check"]
N1 -- no --> H4
J3 -- allow --> J2
J3 -- block --> H4
Q2 -- engagement --> H5{"operator present?"}
H5 -- yes --> H4
H5 -- no --> H6["HARD DENY: needs an interactive operator"]
A typical run
This sequence shows the common auto-mode path: a medium action reaches the judge with its inputs, every newly computed verdict is recorded as a judgement before the allow or block branch, a high-confidence block is returned to the agent with its reason, and an unsure one goes to the operator. In manual mode the judge is never called; high, unavailable-judge and non-judged cases fall through to the operator.
sequenceDiagram
participant Agent
participant FW as Tool firewall
participant Judge
participant Op as Operator
participant Files as State files
Agent->>FW: tool_call
FW->>Files: read firewall.json, approvals and goal
FW->>FW: parse, classify, trajectory, tier
alt critical
FW->>Files: audit tool_seen deny, outcome hard_deny
FW-->>Agent: block [HARD DENY]
else low
FW->>Files: audit tool_seen allow
FW-->>Agent: allow
else exact approval in this workspace and session
FW->>Files: audit tool_seen ask, tool_approved by grant
FW-->>Agent: allow
else manual medium or high
FW->>Files: audit tool_seen ask
FW->>Op: approval card, bounded
Op-->>FW: allow or deny, or no answer in time
FW->>Files: appendFeedback, addApproval on a session allow
FW-->>Agent: allow, [OPERATOR DECISION] deny, or [UNCERTAIN] refused
else auto judged
FW->>Files: audit tool_seen ask
FW->>Judge: request, goal, precedents, approvals, profile
Judge-->>FW: verdict JSON with confidence
FW->>Files: appendJudgement
alt judge allows
FW-->>Agent: allow
else judge blocks with high confidence
FW-->>Agent: block [AUTO-MODE BLOCK] with reason
else judge unsure, unavailable, timed out, or a high block
FW->>Files: audit tool_escalated, outcome uncertain
FW->>Op: approval card tagged UNCERTAIN, bounded
Op-->>FW: allow or deny, or no answer in time
FW->>Files: appendFeedback, addApproval on a session allow
FW-->>Agent: allow, [OPERATOR DECISION] deny, or [UNCERTAIN] refused
end
end
Approvals: storage, scope and revocation
Every silent allow of a medium or high action is backed by an entry in firewall-approvals.json. An entry is bound to one exact action, workspace, working directory, policy and, for a session approval, root session; it records who or what granted it, when, and its expiry (24 hours for a session approval, 30 days for a learned one). Decisions read the file on every call, so /firewall revoke takes effect on the next tool call, and an entry of an unknown shape is ignored and reported, never treated as an allow.
flowchart TD
CARD["card or console: Allow for this session"] --> SA["session approval: this exact action, workspace, cwd, root session, 24h"]
ONCE["Allow once, repeated: 3 approvals in 2 sessions within 30 days in one workspace, no denial since"] --> LRN["learned exact action: persistent approval, that workspace, 30 days"]
SA --> FILE["firewall-approvals.json, schemaVersion 1"]
LRN --> FILE
FILE --> USE{"same action, workspace, cwd, policy, root session, not expired, valid shape?"}
USE -- yes --> RUN["allow without asking"]
USE -- no --> ASK["judge or operator as usual"]
LRN -.-> CHK{"a later denial, or learning off, or manual mode?"}
CHK -- yes --> ASK
REV["/firewall revoke id, session, workspace or all"] --> FILE
REV --> FLOOR["floors: approvals before the revocation no longer count towards learning or judge eligibility"]
BAD["invalid JSON, other schemaVersion, unknown shape or key"] --> IGN["ignored, reported on stderr, notice, list and audit"]
Approval cards, the broker and recording
A headless request is written as a pending JSON file and answered by the human-console watcher, which presents the same menu and writes a resolved file. The wait is bounded by PI_KIT_HUMAN_CONSOLE_TIMEOUT_MS and the turn's abort signal, and a console that cannot be written to is UNCERTAIN at once. A session allow becomes an approval under the root session id, so subagents inherit it; every operator decision appends feedback and can trigger background distillation.
sequenceDiagram
participant Sub as Subagent
participant FW as Tool firewall
participant HC as Human console
participant Op as Operator
participant Store as Approvals and feedback
Sub->>FW: tool_call
FW->>HC: pending approval json, with timeout
HC->>Op: menu allow once, allow session, deny, deny and tell
Op-->>HC: choice
HC-->>FW: resolved json
FW->>Store: addApproval under the root session, workspace and cwd
FW->>Store: appendFeedback
Store->>Store: distillInBackground updates profile
Note over Sub,Store: root session approvals shared with siblings and parent, same workspace only
Sub->>FW: identical tool_call, same workspace
FW->>Store: readApprovals
Store-->>FW: exact match, not expired, valid
FW-->>Sub: allow by grant
Note over FW,HC: no answer before the deadline: refused as UNCERTAIN, the request is withdrawn
Unattended mode
The supervisor sets PI_KIT_UNATTENDED=1, a known PI_KIT_UNATTENDED_BOUNDARY and PI_KIT_UNATTENDED_CONTRACT (a read-only JSON copy). unattended.ts decides once at load; nothing in a session can enable it, and a changed contract switches it off. Children read the same environment and validate the contract themselves.
flowchart TD
E1{"PI_KIT_UNATTENDED is exactly 1?"} -- no --> OFF["not unattended: normal rules"]
E1 -- yes --> E2{"boundary kind known? contract path absolute, readable, JSON,<br/>schemaVersion 1, authorised true, boundaryDigest, no contradiction,<br/>not in the workspace or agent dir, read-only for a non-root process,<br/>policy is not engagement?"}
E2 -- no --> WARN["NOT unattended, loud warning: stderr, notice, /firewall status<br/>normal interactive or headless rules, fail closed"]
E2 -- yes --> ON["unattended: publish the footer global, digest recorded"]
ON --> CALL["each tool call: contract bytes unchanged?"]
CALL -- changed or gone --> WARN
CALL -- same --> R1{"critical, or a hard class?<br/>security control, destructive, exfiltration chain, the boundary or contract"}
R1 -- yes --> HD["HARD DENY, actionable text"]
R1 -- no --> R2{"needs authority outside the zone?<br/>host not in egress, remote not listed, publish, cloud or cluster"}
R2 -- yes --> OUT["refused: outside the unattended zone, actionable text"]
R2 -- no --> R3{"policy ask rule or a tool the policy does not name?"}
R3 -- yes --> UNC["UNCERTAIN: nobody to ask"]
R3 -- no --> R4{"low tier?"}
R4 -- yes --> RUN["runs"]
R4 -- no --> R5{"autoApprove true?"}
R5 -- yes --> RUN2["runs: no card, no judge, no console request"]
R5 -- no --> UNC
Key files
packages/extensions/src/tool-firewall/index.ts— hooks,decide, decision matrix, approvals, judge gate, card and broker branching, bounded prompts, outcomes, audit,/firewalland/auto.packages/extensions/src/tool-firewall/approvals.ts— the approvals file: schema, validation, expiry, scope matching, revocation and floors.packages/extensions/src/tool-firewall/unattended.ts— the run contract, unattended state, egress and remote checks, hard and outside-the-zone denials.packages/extensions/src/tool-firewall/config.ts— modes, policies, config file, state paths, known hosts (with sources and revocation), workspace root.packages/extensions/src/tool-firewall/classify.ts— effects, tiers, path classes, per-command handlers, hosts and remotes contacted, signatures and families.packages/extensions/src/tool-firewall/shell.ts— tokenizer and parser feeding the classifier.packages/extensions/src/tool-firewall/trajectory.ts— per-session state, trajectory findings, root-session sharing.packages/extensions/src/tool-firewall/judge.ts— judge prompt, in-process model call, verdict and confidence parsing, timeout.packages/extensions/src/tool-firewall/card.ts— bounded card, choices, detail view, outcome tag.packages/extensions/src/tool-firewall/feedback.ts— feedback record, redaction, learning thresholds, per-workspace scoping, precedents.packages/extensions/src/tool-firewall/profile.ts— judgements, distillation stats, global profile and its lock.packages/extensions/src/tool-firewall/default-policy.json— shipped tools and engagement command rules.packages/extensions/src/human-console/index.ts— pending/resolved broker, approval menu,ask_human(bounded).packages/extensions/third_party/protected-paths/index.ts— protected lists, allowlist mode, path matching, the approvals file and the contract path.docs/autonomy-gate.md— prose description of the same decision gate.