feat: vendor permission system source

2026-08-28 08:35:57 +00:00 · 2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
@@ -0,0 +1,333 @@
+---
+issue: 452
+issue_title: "Bash permission gates silently fail after model changes, denial events, or session compaction git add/commit/push/gh pr create bypass all rules"
+---
+
+# Make the bash permission gate fail closed instead of silently allowing
+
+## Release Recommendation
+
+**Release:** ship independently
+
+This issue is not part of any architecture-roadmap batch (no `(#452)` reference in `docs/architecture/architecture.md`, no `Release batches` subsection).
+It is a self-contained security hardening fix and ships on its own.
+
+## Problem Statement
+
+A third-party reporter (`k0valik`) observed that the bash permission gate intermittently stops intercepting `git add` / `git commit` / `git push` / `gh pr create`, letting them run with **no review-log entry at all**, despite an explicit `"git *": "ask"` rule.
+The reported triggers — a rapid `model_change` cascade, a user denial, and session compaction — are correlated from production logs but are **not locally reproducible**, and the reporter's own five ranked root-cause theories are speculative.
+
+The investigation (see Background) found that the report bundles several distinct concerns.
+Rather than chase an unreproducible trigger, this plan fixes the **confirmable defect class**: the gate is **fail-open** in several places, which contradicts the package's own stated invariant ("Default to least privilege — when in doubt, prompt (`ask`), do not silently allow").
+Once the gate fails closed and records every error, the worst case for any present or future bug becomes a **visible** `ask`/block — never an invisible allow — and the one mechanism I could not reproduce becomes diagnosable on recurrence.
+
+## Goals
+
+- Make `PermissionGateHandler.handleToolCall` **fail closed**: any thrown error blocks the tool and writes a review-log entry, rather than letting the SDK pass the command ungated.
+- Make the bash tool gate **fail closed** when a non-empty command parses to zero command units: default to `ask` instead of resolving the opaque whole-command string (which lets `cd X && git push` ride a permissive top-level `*`).
+- Make the tree-sitter parser **resilient**: a transient init failure must not poison the parser for the process lifetime (no cached rejected promise).
+- **Surface the config footgun**: emit a non-fatal config warning when a permissive top-level `*: allow` is set with no `bash` `*` policy, so bash silently inherits `allow`.
+- **Make the boundary structurally fail-closed**: register a single `tool_call` adapter that is the only SDK-facing entry point, owns the `try/catch → block`, and is the only place an internal `GateOutcome` is translated to the SDK result shape — so "we didn't decide" can never silently mean "allow."
+- **Make every tool call traceable**: guarantee exactly one terminal decision per call, add a `debugLog`-gated per-call trace and a `session_shutdown` decision summary, so an evaluated-and-allowed call is distinguishable from a never-evaluated one without hand-reconciling logs.
+- **Add totality tests**: a metamorphic property (wrapping any `ask`/`deny` command in `cd X && …` must not weaken the decision) and a boundary contract test (a throwing handler must block), to catch the fail-open class in development rather than production.
+- **This change is breaking** (more restrictive): commands that previously passed silently on the error path or via the empty-parse fallback will now block or prompt.
+  Use `fix!:` with a `BREAKING CHANGE:` footer on the behavior-changing commits.
+
+## Non-Goals
+
+- Reproducing or directly fixing the specific `model_change`-cascade / denial / compaction triggers — they are addressed indirectly by making the gate fail closed and observable, not by a targeted mechanism fix.
+- The `git`-vs-`rm` asymmetry (some `git` commands bypass while `rm` stays gated in the same period).
+  I could not reconcile this from the source; it is documented as diagnosable-on-recurrence (the new review-log entries will pinpoint it) and deferred to a follow-up issue only if it recurs with new logs.
+- The reporter's suggested *unconditional* `console.log` instrumentation on every `handleToolCall` — A5 instead adds a `debugLog`-gated per-call trace plus a `session_shutdown` summary, so the trace is available on demand without per-call spam in normal operation.
+- Full cross-artifact reconciliation against Pi's session JSONL — A5's in-process counters are the cheaper first tier; reading Pi's session file is a deferred follow-up (see Open Questions).
+- Any change to the `/permission-system` command, the config schema (no new field), or the merge precedence model.
+
+## Background
+
+Relevant modules and the verified findings behind each fix:
+
+- `src/handlers/permission-gate-handler.ts` — `handleToolCall` has **no try/catch**.
+  The SDK's dispatcher (`@earendil-works/pi-coding-agent` `dist/core/extensions/runner.js`, `emitToolCall`) calls `await handler(event, ctx)` with **no try/catch** — unlike `emitUserBash` directly below it, which catches and continues.
+  So a thrown `handleToolCall` produces no `{ block: true }` result and the command is not blocked, with nothing logged.
+  This is the keystone defect (A1): it converts every other latent error into a silent, trace-less bypass.
+- `src/handlers/gates/bash-program.ts` — `parserPromise ??= initParser()` caches a **rejected** promise forever if `initParser()` ever rejects.
+  Every later `getParser()` re-throws, and via A1 that is a permanent silent bypass.
+  `config.loaded` (emitted from `ConfigStore.refresh()`) re-reads config without re-running the factory module, so a reload looks like recovery but does not clear the module-scoped promise — matching "once broken, stays broken until process restart" (A2).
+- `src/handlers/gates/bash-command.ts` — `resolveBashCommandCheck` falls back to resolving the **whole command string** when `BashProgram.parse` yields zero command units.
+  `cd /repo && git push` matches no `git *` rule and falls through to a top-level `*: allow`, producing a silent pass (A3).
+  When parse succeeds, the chain is split into `[cd /repo, git push]` and `pickMostRestrictive` correctly returns `ask`, so this bypass is only reachable through the empty-parse path.
+- `src/config-loader.ts` — config issues collected during `loadAndMergeConfigs` flow through `mergeResult.issues` and are surfaced by `ConfigStore.refresh()` via `ctx.ui.notify(warning, "warning")` and the `config.loaded` debug entry.
+  The shipped `config/config.example.json` sets `bash.*: ask` and is safe; a config with a permissive top-level `*: allow` and no `bash` `*` removes the net that would otherwise catch A3 (A4).
+
+Constraints from AGENTS.md / package skill that apply:
+
+- "Default to least privilege — when in doubt, prompt (`ask`), do not silently allow." — this fix aligns the code with that invariant.
+- "When removing a config field, keep the loader tolerant" — N/A; no field is removed, A4 only adds a derived warning.
+- Keep schema, example config, `docs/configuration.md`, `README.md`, and SKILL aligned.
+
+### Theories ruled out (do not plan around these)
+
+- "Handler deregistration after model changes" — contradicted by the reporter's own data: `rm`/`node` stay gated during bypass, so the handler is firing.
+- "Tree-sitter concurrent corruption mid-parse" — implausible: JS is single-threaded and `parser.parse()` is synchronous with no interleaving `await`.
+  Only a transient *init* failure (A2) is real.
+- "A denial permanently poisons handler state" — no code path mutates shared/module state on denial; denial returns `{ block: true }` cleanly.
+
+## Design Overview
+
+Five defense-in-depth changes plus totality tests.
+A1 is the structural keystone — it closes the whole fail-open class at one boundary; A2–A4 fix the specific defects that boundary would otherwise have to absorb; A5 makes the now-guaranteed decision observable.
+Each is individually correct; together they guarantee no silent allow.
+
+### A1 — Fail-closed boundary adapter (single chokepoint)
+
+The fail-open holes exist because "allow" is the *implicit default* at five different exits: the pipeline's trailing `return { action: "allow" }`, `GateRunner.run`'s null/bypass allow, the handler's `{}` return, `applyPermissionGate`'s fall-through, and — critically — a thrown handler, which the SDK does **not** convert to a block.
+Rather than patch each exit, close the class at one boundary.
+
+Introduce a single SDK-facing adapter that is the only function registered for `pi.on("tool_call")`.
+It is the sole place an internal decision is translated to the SDK result shape, and it owns the `try/catch → block`:
+
+```typescript
+// src/handlers/tool-call-boundary.ts
+/** The only tool_call handler the SDK sees. Guarantees fail-closed: a thrown
+ *  gate becomes a Block, and the internal GateOutcome → SDK-shape translation
+ *  happens here and nowhere else. */
+export function createFailClosedToolCall(
+  gate: (event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>,
+  reporter: DecisionReporter,
+  audit: DecisionAudit,
+): (event: unknown, ctx: ExtensionContext) => Promise<{ block?: true; reason?: string }> {
+  return async (event, ctx) => {
+    try {
+      const outcome = await gate(event, ctx);
+      audit.recordDecision(outcome.action);
+      return outcome.action === "block" ? { block: true, reason: outcome.reason } : {};
+    } catch (error) {
+      audit.recordError();
+      reporter.writeReviewLog("permission_request.blocked", {
+        toolName: bestEffortToolName(event),
+        command: bestEffortCommand(event),
+        resolution: "gate_error",
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return { block: true, reason: formatGateErrorReason(error) };
+    }
+  };
+}
+```
+
+Correspondingly, `PermissionGateHandler.handleToolCall` changes its return type from the loose SDK shape (`{ block?: true; reason? }`) to the internal **total** type `GateOutcome` (`{ action: "allow" } | { action: "block"; reason }`, already defined in `handlers/gates/types.ts`).
+Its validation-block path returns `{ action: "block", reason }` instead of `{ block: true, reason }`.
+The domain handler is now SDK-shape-free, and the `reporter` (plus the new `audit`) dependency lives on the boundary, **not** the handler — so the handler constructor does not widen.
+Use the `DecisionReporter` interface type, not the concrete `GateDecisionReporter` (DIP / narrow-interface rule).
+
+`index.ts` registers `pi.on("tool_call", createFailClosedToolCall((e, c) => gates.handleToolCall(e, c), reporter, audit))`.
+
+The catch helpers (`bestEffortToolName`, `bestEffortCommand`, `formatGateErrorReason`) read from the raw `event` defensively and never throw, so a failure inside `session.activate` still logs and blocks.
+
+Fail-closed choice = **block** (not `ask`) for an *unexpected* exception: the command may be unknown and the prompt infrastructure itself may be what threw — block is the unambiguous safe outcome for an internal error.
+
+### A2 — Resilient parser init
+
+Extract a small, pure, unit-testable helper and use it for the parser cache:
+
+```typescript
+// src/async-cache.ts
+/** Memoize an async factory, but drop a rejected result so the next call retries. */
+export function memoizeAsyncWithRetry<T>(factory: () => Promise<T>): () => Promise<T> {
+  let cached: Promise<T> | null = null;
+  return () => {
+    cached ??= factory().catch((error) => {
+      cached = null; // poisoned result cleared → next call re-attempts
+      throw error;
+    });
+    return cached;
+  };
+}
+```
+
+`bash-program.ts` replaces the module-scoped `parserPromise` + `getParser` with `const getParser = memoizeAsyncWithRetry(initParser)`.
+On success the behavior is identical (single shared parser); on a transient init failure the next tool call retries instead of inheriting a permanently rejected promise.
+A parser-init failure no longer needs a dedicated health signal: the throw from `getParser()` propagates to the A1 boundary, which records it as a `gate_error` review-log entry — so the failure is visible (and the tool blocked) for free.
+This is why a separate "parser health" mechanism is intentionally **not** added.
+
+### A3 — Fail-closed empty-parse fallback
+
+In `resolveBashCommandCheck`, when `commands` is empty:
+
+- If `command` is empty, whitespace-only, or comment-only → resolve the whole string as before (genuinely nothing to gate).
+- Otherwise (a non-empty command that parsed to zero command units — a parse anomaly or an opaque program) → return a synthetic **`ask`** result, fail closed.
+
+```typescript
+if (commands.length === 0) {
+  if (isTriviallyEmptyCommand(command)) {
+    return resolver.resolve("bash", { command }, agentName);
+  }
+  return {
+    state: "ask",
+    toolName: "bash",
+    source: "bash",
+    origin: "builtin",
+    command,
+    matchedPattern: "<unparseable-bash-command>",
+  } satisfies PermissionCheckResult;
+}
+```
+
+The sentinel `matchedPattern` makes the path visible in the review log when the gate runs — directly addressing the "no trace" complaint — without injecting a logger into this pure function.
+The non-empty chain path (the `commands.map(...) → pickMostRestrictive` branch, #301 / #306) is unchanged.
+
+### A4 — Config footgun warning
+
+Add a pure detector run against the **merged** permission map (where the final composed top-level `*` and `bash` surface are both known):
+
+```typescript
+// returns one issue string, or undefined
+export function detectPermissiveBashFallback(
+  permission: FlatPermissionConfig | undefined,
+): string | undefined;
+```
+
+It warns when `permission["*"] === "allow"` (or a deny-with-reason that resolves to allow — not applicable, so a plain `"allow"` check suffices) **and** the `bash` surface either is absent or is an object with no `"*"` key.
+A `bash` value that is the bare string `"allow"`/`"ask"`/`"deny"` (shorthand for `{ "*": … }`) counts as having an explicit `bash` `*` and does not warn.
+Call it in `loadAndMergeConfigs` after the merge and push its result onto `allIssues`, so it rides the existing `mergeResult.issues` → `ctx.ui.notify` path.
+
+#### Consumer call-site sketch (A4 wiring)
+
+```typescript
+// config-loader.ts, end of loadAndMergeConfigs, after `merged` is final
+const bashFallbackIssue = detectPermissiveBashFallback(merged.permission);
+if (bashFallbackIssue) allIssues.push(bashFallbackIssue);
+return { merged, issues: allIssues };
+```
+
+No reach-through: the detector takes the plain map and returns a string; `loadAndMergeConfigs` owns the push.
+
+### A5 — Decision-per-call trace and shutdown summary
+
+The reporter could not distinguish "evaluated and allowed" from "never evaluated" because the allow path writes nothing, and the user-facing review log intentionally stays quiet on allow (noise control).
+With A1 the boundary now produces exactly one terminal decision per call; make that decision *observable* without flooding the review log.
+
+A `DecisionAudit` collaborator (owned by the boundary) holds per-session counters: `toolCalls`, `allowed`, `blocked`, `errors`.
+
+```typescript
+// src/decision-audit.ts
+export class DecisionAudit {
+  recordDecision(action: "allow" | "block"): void; // also bumps toolCalls
+  recordError(): void;                              // also bumps toolCalls
+  writeSummary(logger: PermissionSystemLogger): void;
+}
+```
+
+- When `debugLog` is enabled, the boundary writes one compact `permission.decision` debug entry per call (tool, action, matched pattern) — a full trace on demand, off by default.
+- On `session_shutdown` (already hooked by `SessionLifecycleHandler`), `writeSummary` emits one `permission.session_summary` debug line with the counters.
+  `toolCalls !== allowed + blocked + errors` is an invariant violation logged at warning level — a cheap structural self-check that flags any future regression that re-opens a silent path.
+
+This is in-process self-audit.
+Full reconciliation against Pi's own session JSONL (the cross-artifact check the reporter did by hand) needs to read Pi's session file and is a deferred follow-up (see Open Questions).
+
+## Module-Level Changes
+
+- `src/handlers/tool-call-boundary.ts` — **new** module: `createFailClosedToolCall(gate, reporter, audit)` (the sole `pi.on("tool_call")` target) plus the defensive `bestEffortToolName` / `bestEffortCommand` / `formatGateErrorReason` helpers.
+- `src/decision-audit.ts` — **new** module: `DecisionAudit` (counters + `recordDecision` / `recordError` / `writeSummary`).
+- `src/handlers/permission-gate-handler.ts` — change `handleToolCall`'s return type from `{ block?: true; reason? }` to the internal total `GateOutcome`; the validation-block path returns `{ action: "block", reason }`.
+  No constructor change (the reporter lives on the boundary).
+- `src/handlers/lifecycle.ts` — `SessionLifecycleHandler` gains the `DecisionAudit` (injected) and calls `audit.writeSummary(logger)` in `handleSessionShutdown`.
+- `src/index.ts` — construct `DecisionAudit`; register `pi.on("tool_call", createFailClosedToolCall((e, c) => gates.handleToolCall(e, c), reporter, audit))` instead of the bare handler; pass `audit` into `SessionLifecycleHandler`.
+- `src/async-cache.ts` — **new** module exporting `memoizeAsyncWithRetry`.
+- `src/handlers/gates/bash-program.ts` — replace `parserPromise` + `getParser()` with `memoizeAsyncWithRetry(initParser)`; remove the now-dead module-scoped `let parserPromise`.
+- `src/handlers/gates/bash-command.ts` — add the empty-commands fail-closed branch and the `isTriviallyEmptyCommand` helper.
+- `src/config-loader.ts` — add and export `detectPermissiveBashFallback`; call it in `loadAndMergeConfigs`.
+- `docs/configuration.md` — document the new fail-closed behavior (gate errors block, unparseable bash commands prompt) and the recommendation to set `bash.*` explicitly; describe the new config warning.
+- `README.md` — if it summarizes gate behavior or config recommendations, add the `bash.*` note (grep first; update only if present).
+- `.pi/skills/package-pi-permission-system/SKILL.md` — add a short note under Debugging that the gate now fails closed and emits a `gate_error` review entry, and that an unparseable bash command resolves to `ask` (`<unparseable-bash-command>` sentinel).
+- `config/config.example.json` — verify only; it already sets `bash.*: ask`, no change expected.
+
+Greps performed / to confirm during implementation:
+
+- The only consumer breakage is internal: `handleToolCall`'s return-type change (`{ block?: true }` → `GateOutcome`) breaks every test that asserts the SDK shape (`tool-call.test.ts`, `tool-call-events.test.ts`) — fold those updates into the A1 step (they now assert `GateOutcome` from the handler, or `{ block: true }`/`{}` from the boundary).
+- `getParser` / `parserPromise` are file-local to `bash-program.ts` (no external importers) — confirm before deleting the `let`.
+- Grep `docs/` for any sample review-log output or documented "allow"/fallback wording that the new `gate_error` / `<unparseable-bash-command>` entries would make stale.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled by these changes:**
+   - `test/async-cache.test.ts` — `memoizeAsyncWithRetry`: caches on success (single factory call across N calls); drops a rejected result so the next call re-invokes the factory; surfaces the rejection to the caller each time it fails.
+   - `test/handlers/gates/bash-command.test.ts` — empty `commands` + non-empty command → `ask` with the sentinel `matchedPattern`; empty `commands` + whitespace/comment-only command → whole-string resolve (unchanged).
+   - `test/handlers/tool-call-boundary.test.ts` (new) — the boundary contract: an `allow` `GateOutcome` → `{}`; a `block` outcome → `{ block: true, reason }`; a **throwing** gate → `{ block: true }` plus a `gate_error` review-log entry and `audit.recordError()`.
+     A header comment cites that the SDK's `emitToolCall` lacks a try/catch (unlike `emitUserBash`), documenting why the boundary must absorb the throw.
+   - `test/handlers/gates/bash-command-metamorphic.test.ts` (new) — the totality property: for a table of `ask`/`deny` commands, `resolveBashCommandCheck` over `cd /x && <cmd>` yields a decision no weaker than the bare `<cmd>` (deny ≥ ask ≥ allow).
+     A focused parametrized table over real parse+resolve, not a full fuzzer (tree-sitter fuzzing is brittle); it pins A3 directly.
+   - `test/decision-audit.test.ts` (new) — counters increment per recorded decision/error; `writeSummary` emits the summary line; a forced `toolCalls !== allowed + blocked + errors` mismatch logs the warning-level invariant violation.
+   - `test/config-loader.test.ts` (or a new `detect-permissive-bash-fallback.test.ts`) — detector returns a warning for `{*: "allow"}` with no `bash.*`; returns `undefined` when `bash.*` is set, when `bash` is a bare string, or when top-level `*` is not `allow`.
+2. **Tests that become redundant:** none — all additive.
+3. **Tests that must stay as-is:** the existing `resolveBashCommandCheck` chain / most-restrictive tests (#301 / #306) — they pin that the non-empty path is untouched; the `makeHandler`-based `tool-call.test.ts` happy-path tests pin that the normal allow/block flow is unchanged (updated only for the `GateOutcome` return shape).
+
+## Invariants at risk
+
+This change touches surfaces refactored by earlier roadmap steps; keep their pinned tests green.
+
+- #301 / #306 (bash chain evaluation, most-restrictive-wins) — A3 changes only the `commands.length === 0` branch.
+  Pinned by `test/handlers/gates/bash-command.test.ts` chain tests.
+- #308 (single `BashProgram.parse` per evaluate) — A2 changes `getParser` caching, not the parse-once contract.
+  Pinned by `test/handlers/gates/tool-call-gate-pipeline.test.ts`.
+- The `makeHandler` real-pipeline wiring (#341 / handler-fixtures) — A1 changes `handleToolCall`'s return type to `GateOutcome`; update `makeHandler`'s callers and the `tool-call*.test.ts` assertions in the same commit so all existing handler tests keep compiling/passing.
+  `makeHandler` itself needs no reporter (the reporter moved to the boundary), but the boundary tests construct their own reporter/audit mocks.
+
+## TDD Order
+
+1. **A2 parser resilience.**
+   Red: `test/async-cache.test.ts` for `memoizeAsyncWithRetry` (success-caches, reject-retries, reject-surfaces).
+   Green: add `src/async-cache.ts`; rewire `bash-program.ts` to use it and delete the `let parserPromise`.
+   Run `pnpm run check`.
+   Commit: `fix(pi-permission-system): retry tree-sitter parser init instead of caching a rejected promise (#452)`.
+2. **A4 config footgun warning.**
+   Red: detector tests (warn / no-warn matrix).
+   Green: add and export `detectPermissiveBashFallback`; call it in `loadAndMergeConfigs`.
+   Commit: `feat(pi-permission-system): warn when a permissive top-level "*" leaves bash ungated (#452)`.
+3. **A1 fail-closed boundary + `GateOutcome` handler return.**
+   Red: add `test/handlers/tool-call-boundary.test.ts` (allow/block/throw contract); update `tool-call.test.ts` / `tool-call-events.test.ts` to the new `GateOutcome` return shape.
+   Green: add `src/handlers/tool-call-boundary.ts` and a minimal `src/decision-audit.ts` (counters only — `recordDecision`/`recordError`; `writeSummary` lands in step 5); change `handleToolCall` to return `GateOutcome`; register the boundary in `index.ts` (same commit — interface + sole call site).
+   Run `pnpm run check` (return-type change) and the full suite (shared handler fixtures).
+   Commit: `fix!(pi-permission-system): route tool calls through a fail-closed boundary (#452)` with a `BREAKING CHANGE:` footer covering the whole fail-closed shift (this commit and step 4) and the remediation: set an explicit permissive `bash` policy (e.g. `"bash": { "*": "allow" }`) to opt back into permissive behavior.
+4. **A3 fail-closed empty-parse fallback.**
+   Red: `bash-command.test.ts` empty-non-empty → `ask`; empty-trivial → whole-string resolve; plus `bash-command-metamorphic.test.ts` (the `cd X && <cmd>` no-weaker property).
+   Green: add the empty-commands branch + `isTriviallyEmptyCommand`.
+   Commit: `fix(pi-permission-system): prompt instead of allowing an unparseable bash command (#452)` (the breaking footer is already carried by step 3; reference it in the body).
+5. **A5 decision audit + shutdown summary.**
+   Red: `test/decision-audit.test.ts` (counters, summary line, invariant-violation warning); extend the boundary test for the `debugLog`-gated per-call trace.
+   Green: complete `DecisionAudit.writeSummary`; thread `audit` into `SessionLifecycleHandler.handleSessionShutdown` and the `debugLog`-gated per-call trace in the boundary; wire `audit` in `index.ts`.
+   Commit: `feat(pi-permission-system): trace tool-call decisions and emit a session summary (#452)`.
+6. **Docs + SKILL alignment.**
+   Update `docs/configuration.md`, `README.md` (if applicable), and the package SKILL note (fail-closed boundary, `gate_error` / `<unparseable-bash-command>` / `permission.session_summary` entries).
+   Commit: `docs(pi-permission-system): document fail-closed gate behavior and bash fallback warning (#452)`.
+
+Run the full package suite (`pnpm --filter @gotgenes/pi-permission-system exec vitest run`) after steps 3 and 5, which touch shared handler fixtures and composition-root wiring.
+
+## Risks and Mitigations
+
+- **Risk:** blocking on every transient gate error is too aggressive and surprises users.
+  **Mitigation:** these errors should be rare; the review-log `gate_error` entry tells the user exactly what happened and the generic reason names the gate.
+  Correctness (no silent allow) outweighs convenience for a permission system.
+- **Risk:** A3's `ask` default produces unexpected prompts for unparseable commands in permissive configs.
+  **Mitigation:** documented in the breaking note with a real opt-out (`"bash": { "*": "allow" }`); only triggers on the rare empty-parse path.
+- **Risk:** the `git`-vs-`rm` asymmetry is a distinct, still-unexplained bug that these changes do not fix.
+  **Mitigation:** the new review-log entries make any recurrence visible and attributable; a follow-up issue is filed only if it recurs with fresh logs.
+- **Risk:** the A1 boundary + `GateOutcome` return-type change ripples through `tool-call*.test.ts` assertions.
+  **Mitigation:** the change is mechanical (assert `GateOutcome` from the handler, SDK shape from the boundary) and folded into the A1 step; the reporter moving to the boundary keeps the handler constructor from widening.
+- **Risk:** A5's audit adds per-call work.
+  **Mitigation:** counters are O(1); the per-call trace is gated behind `debugLog`; the summary is one line on `session_shutdown`.
+- **Risk:** scope growth — five changes plus an audit in one issue.
+  **Mitigation:** the steps are independently committable; A5 (step 5) is separable to a follow-up if review prefers, but the A1 boundary is the structural keystone and must land here.
+  A `DecisionAudit` stub (counters only) is introduced in step 3 so the boundary signature is stable before A5 completes it.
+
+## Open Questions
+
+- Should an *unexpected* gate error (A1) prompt (`ask`) rather than hard-block when the context supports a UI?
+  Deferred: hard-block is the unambiguous fail-closed choice and avoids depending on possibly-broken prompt infrastructure.
+  Revisit if blocking proves disruptive in practice.
+- Should A4's detector also warn for other surfaces (`mcp`, `skill`) that inherit a permissive top-level `*`?
+  Deferred to a follow-up; this issue is scoped to the bash bypass.
+- Full reconciliation of A5's in-process counters against Pi's own session JSONL (the cross-artifact check the reporter performed by hand) is deferred — it requires reading Pi's session file, a heavier mechanism than this issue warrants.
+  The in-process summary is the cheaper first tier.
+- Should `GateOutcome` gain an explicit first-class `ask` variant (today `ask` is resolved inside `applyPermissionGate`, and `GateOutcome` carries only `allow`/`block`)?
+  Deferred: the two-variant total type is sufficient for the boundary's fail-closed translation; widening it is a larger decision-model refactor better tracked on its own.