Seven Safety Layers

## Full reference: the 7 layers

### 1. Why layered defense

The VILA-Lab Dive-into-Claude-Code paper (arXiv 2604.14228) concluded that Claude Code is ~1.6% AI decision logic and ~98.4% deterministic infrastructure. The permission system is a large share of that infrastructure — the paper's §Seven Independent Safety Layers lists seven independent layers, any one of which can block a call. This is the graduated-layering commitment applied to security: no single layer is the guard; the stacked probability of bypass is the guard.

The paper names three recurring design commitments that this architecture instantiates: graduated layering over monolithic mechanisms; append-only designs favoring auditability over query power; model judgment within a deterministic harness. Safety layers are where the "deterministic harness" part is most visible — the model proposes, the harness disposes.

### 2. Layer 1 — Tool pre-filtering (architecture.md §Authorization Pipeline)

Blanket-denied tools are stripped from the model's view entirely before the model call. The model cannot even name a tool it is not allowed to call. This is the earliest and cheapest layer; it prevents the model from "trying its luck" on a denied tool and polluting the transcript.

Implementation requirements:

- Tool registry is a static module-level list. No runtime `eval` or string-matched names.
- Pre-filtering is a pure function of (registry, denyRules, permissionMode).
- The filtered list is what gets serialized into the tool schema in the model call.

### 3. Layer 2 — Deny-first rule evaluation (architecture.md §Seven Independent Safety Layers)

Deny always overrides allow, even when allow is more specific. This is the canonical deny-first default safety posture — the paper's fourth design question answers this explicitly: "Default safety posture? Deny-first: deny > ask > allow. Strictest rule wins."

Concretely:

- Rules are (matcher, decision) pairs.
- Matching applies all rules; any deny wins.
- The allow-first alternative (where the more-specific rule wins) is strictly weaker and is the default in many naïve implementations — do not copy it.

### 4. Layer 3 — Permission mode constraints

7 documented modes (architecture.md §7 Permission Modes):

| Mode | Behavior | Trust Level |
|---|---|---|
| plan | User approves all plans before execution | Lowest |
| default | Standard interactive approval | Low |
| acceptEdits | File edits + filesystem shell auto-approved | Medium |
| auto | ML classifier evaluates tool safety | High |
| dontAsk | No prompting, deny rules still enforced | Higher |
| bypassPermissions | Skips most prompts, safety-critical checks remain | Highest |
| bubble | Internal: subagent escalation to parent | Special |

Rules of engagement:

- Mode is explicit per session. Default to `default`.
- `bypassPermissions` still enforces safety-critical checks — it is not a no-op bypass. Explicitly document which checks remain.
- `bubble` is internal-only: subagents escalate to their parent's mode, not to the user.
- Shipping a team default of `auto` requires auditing the classifier's failure modes first (see layer 4).

### 5. Layer 4 — Auto-mode ML classifier (architecture.md §Auto-Mode Classifier)

`yoloClassifier.ts` loads a base system prompt plus permission templates (separate internal and external variants). Two-stage evaluation:

1. **Fast-filter** — cheap predicate-style checks on the tool + args.
2. **Chain-of-thought** — short LLM reasoning pass on the uncertain cases.

The classifier races a pre-computed classification against a timeout. If the pre-computed result is available in time, it wins; if the timeout fires first, the live classification is used; if both fail, the call falls back to interactive approval.

Failure modes documented in the paper:

- Timeout race can leave decisions ambiguous when the pre-computed classification is partially written.
- Classifier is itself an LLM call; it consumes tokens and latency.
- Adversarial input can be designed to force the chain-of-thought path, inflating cost.

### 6. Layer 5 — Shell sandboxing

Filesystem and network isolation for shell commands. Commands run in a scoped environment: the agent cannot read outside the workspace or reach private network ranges without explicit allow.

Known bypass class: the paper documents that approximately 50 shell subcommands bypass the standard analysis (because the sandbox's policy engine does not know them, or because their syntax defeats the argument parser). This is a non-negligible attack surface. Mitigations:

- Maintain a list of known-bypass subcommands; require explicit approval for any shell invocation whose command name is on the list.
- Prefer structured tools (read_file, write_file, list_dir) over raw shell whenever possible.
- Log every shell invocation with full argv; audit weekly for new subcommands appearing.

### 7. Layer 6 — Non-restoration on resume

Permissions never persist across session boundaries. When the user runs `/resume`, the previous session's granted permissions are NOT automatically restored; the user re-establishes trust per session.

This is a deliberate non-feature. The paper's §Session Persistence notes the safety design trade-off: restoring permissions across resumes would reduce friction but eliminate the per-session trust re-check. Do not "fix" this by adding permission persistence to your clone.

Related CVE class: **pre-trust window** — the paper references 4 published CVEs in which extensions executed during a window before the trust dialog appeared. Mitigation: no extension runs any code until the trust dialog has been shown and acknowledged.

### 8. Layer 7 — PreToolUse hooks (architecture.md §Authorization Pipeline)

PreToolUse hooks run before a tool is executed. They can return a `permissionDecision`:

- `allow` — proceed to the next layer.
- `deny` — block the call immediately.
- `ask` — surface to the user for interactive approval.

Hooks are the user's override point. The canonical example: a PreToolUse hook that blocks any Edit whose path matches `**/_generated/**`, returning deny with a message.

Hook safety notes:

- A hook that returns `allow` silently escalates — the call still has to pass the other layers, but the hook can short-circuit the user prompt. Log every allow decision.
- Hooks are user-authored; a malicious or sloppy hook is a hole. Treat the hook directory like code; require review.
- Hooks can time out; define the timeout policy explicitly. Default to "deny on timeout," not "allow on timeout."

### 9. The 4-stage authorization pipeline

Every tool call flows through:

1. **Pre-filtering** — denied tools are stripped before model sees the schema (layer 1).
2. **PreToolUse hooks** — user hooks can return permissionDecision (layer 7).
3. **Rule evaluation** — deny-first (layer 2), mode-aware (layer 3).
4. **Permission handler** — 4 branches: **coordinator** (main session with an interactive user), **swarm worker** (subagent; decisions bubble up via mode `bubble`), **speculative classifier** (auto mode; layer 4's classifier), **interactive** (fallback; user approves).

Layer 5 (shell sandboxing) runs inside the tool execution step, not the authorization step. Layer 6 (non-restoration) runs at session start, not per-call.

### 10. Failure modes the paper calls out explicitly

1. **Shared perf constraints across layers** — all 7 layers share the turn's perf budget. A slow layer stalls the whole turn. If layer 4's classifier is flaky, layer 3's mode check gets slower too. Document the per-layer budget; alert on regressions.
2. **50+ shell subcommands bypass analysis** — layer 5 is not complete. Maintain the bypass list.
3. **Classifier timeout race** — layer 4 can leave decisions ambiguous when the pre-computed race tie-breaks badly.
4. **Pre-trust window CVEs** — 4 published CVEs. Extensions must not execute pre-trust.
5. **Hook permissionDecision silent escalation** — a user hook returning allow can short-circuit the user prompt. Log it.
6. **Deny-rule missing overrides** — allow-first systems are strictly weaker; if you copied the rules but not the evaluation order, deny rules silently lose.

### 11. Cross-references

- **injection-surface-audit** — this pack is the architecture; injection-surface-audit is the checklist. Use together.
- **turn-execution-pipeline** — describes where the permission gate fits in the 9-step loop (step 7).
- **nine-context-sources** — CLAUDE.md is user context, not system prompt; permission rules are the deterministic enforcement layer. This distinction is named there in full.

### 12. Cadence

- **Per-PR**: CI linter asserts that tool registry is static and deny-first matches the rule evaluation order.
- **Pre-release**: walk all 7 layers; require PASS on each.
- **Quarterly**: rotate the reviewer; diff the bypass list for layer 5; replay classifier traces for layer 4.
- **Post-CVE**: treat every permission CVE in a neighboring product as a prompt to re-audit your own harness.

### 13. License + attribution

This pack paraphrases and cites architecture content from VILA-Lab/Dive-into-Claude-Code (arXiv 2604.14228, CC-BY-NC-SA-4.0). Attribution to VILA-Lab is required; non-commercial + share-alike terms inherited on any verbatim excerpts. Paraphrased summaries are original and credited per the license. Do not remove the attribution entry from `sources[]`.