feat(sidecar): taint escalates to HIC approval (v0.5.1 HGW-W1)

[SaulBuilds]

HGW Week 1, runtime, 1 of 5. Stack: this PR (base main) → #80 → #81 → #82 → #83. Each PR is green on its own (fmt on touched files, clippy -D warnings on agent-sidecar / agent-loop / agent-shell, cargo test --workspace --locked); merge in order. Refs #74 (HGW-W1). Owner decision 2026-10-15, HGW (2). Needs the owner's security sign-off (W1 adds a privileged path, per the sprint file).

What changes

Before: any shell_run output (even an approved node -v) tainted the session, and every later command and sidecar-hosted write was declined for the rest of the conversation ("…which this tool's host cannot ask for"). Nothing could clear it.

Now, in a session opened with hicAware: true:

• A tainted, effectful, sidecar-hosted call (fs_*, file_write, sheet_write, the toolchain tools, capsules) waits on a new per-session approval card. The card shows the tool, the exact canonical arguments (subject), a one-line summary, hicReason and every taint source. An allow runs that one call with those arguments.
• shell_run still asks after taint, on its own card, which now also carries hicReason and taintSources.
• An approval releases one action. The session stays tainted, so the next action asks again. Nothing is approved automatically.
• Explicit clear ([v0.5.1 HGW-W1] Taint escalates to an HIC approval #74): POST /sessions/:id/taint/clear {note} calls TaintState::clear_by_member. The clear is recorded first (taint.clear). If no records log is configured, or the record fails, nothing is cleared (503). A scheduled (unattended) session is never cleared (409).
• A declined card tells the model to ask the member instead of retrying.
• Without hicAware (headless or scheduled), nobody can be asked. The call is declined with citrate_agent_loop::cannot_ask_reason, which names the taint source.
• Every decision is recorded write-ahead (sidecar.tool_call), like the shell and MCP cards.

Interface for the core lane

Route	Body / response
GET /sessions/:id/approvals/pending	{pending: [{id: "act-<n>", callId, tool, hic: "required", subject, summary, hicReason, taintSources, expiresInSecs}]}
POST /sessions/:id/approvals/:aid/decide	{allow, subject}. The subject must equal the card's; otherwise 409. A missing session is 404.
POST /sessions/:id/taint/clear	{note}: 200 {ok, cleared: {source, reason}, sources}; 400 for an empty note; 409 when unattended or not tainted; 503 when no records log is configured
GET /sessions/:id/shell/pending	unchanged, plus optional hicReason and taintSources

• Core must open sessions with hicAware: true and poll /approvals/pending next to /shell/pending (sidecarProvider.ts). The card renders summary, subject, hicReason and taintSources.
• Core shows "clear taint" only as an explicit member card and needs CITRATE_HERMES_RECORDS_DIR set.

Tests (red first)

• agent-loop taint_tests: +1 (the headless refusal names its source)
• action_approvals unit: +3
• action_approvals_tests: +8. Covers AT-1.1 (≥3 consecutive shell_runs plus fs_write after taint), one approval per action, exact subject, the headless decline, routes and bearer, records, the explicit clear, and ask-not-retry.
• shell_run_tests: +2 (one test rewritten for the new semantics)
• files_tests: the taint case is rewritten to the card flow (a decline writes nothing)
• Workspace: 2241 → 2255 passed, 0 failed (baseline 5b337ff).

Not here

The ADR-HGW-1 write-up, which the sprint file says lands first (Mac lane, core repo).

🤖 Generated with Claude Code

https://claude.ai/code/session_018wWZZ8GRVU9USh3kKQHsFe

[BerryManifold]

Reviewed per-action taint escalation, exact-subject matching, bearer-protected decision routes, headless refusal, stop/timeout handling, and recorded member taint clearing. The 11 action-approval unit/session tests passed locally on the #81 stack head. No blocking finding in this PR. This approval does not cover later git/auto-approval changes; #85 must land to resolve the existing audit failures.

[Matr0xshka]

Reviewed per-action taint escalation, exact-subject matching, bearer-protected decision routes, headless refusal, stop/timeout handling, and recorded member taint clearing. The 11 action-approval unit/session tests passed locally on the #81 stack head. No blocking finding in this PR. This approval does not cover later git/auto-approval changes; #85 must land to resolve the existing audit failures.