pssah4_vault-operator/docs/reference
Sebastian Hanke 9f2b76abbb feat(approval): EPIC-44 effect-based approval governance + Wave A-E hardening
Make CUD actions default-deny and enforced by construction (ADR-153), then
close every bypass and drift the approval audit found.

Core (FEAT-44-01):
- checkApproval runs on EVERY tool call; the effect class comes from a central
  registry (toolEffects.ts), not from a tool's self-declared isWriteOperation.
  Unknown tool fails closed. config/self-modify can never be auto-approved, so
  the agent cannot self-escalate. A pre-write diff gate is a real write gate for
  the CUD tools (preview == write, reject means the tool never runs).

Wave A (gate bypasses):
- FIX-44-04 SandboxBridge writes obey IgnoreService + take a checkpoint;
  governanceTaskId is reference-counted so overlapping executions never lose a
  snapshot.
- FIX-44-22/24 the agent config folder is a deny-zone (skills/, skill-data/
  excepted) for both the sandbox and the vault tools (shared agentFolderGuard).
- FIX-44-05 skill trust (source: pro) is verified against a plugin-controlled
  provenance manifest with a content hash and ADR-152 seed, not read from
  SKILL.md frontmatter. A corrupt manifest fails closed (does not re-seed).

Wave B (silent escalation):
- FIX-44-03b Always-allow no longer silently flips the master and re-arms dormant
  flags; sandbox grant requires a confirm.
- FIX-44-03a plugin-api read/write resolved from the call input, shared between
  gate and UI.
- FIX-44-06 conjunction-plus-mutation method names (getOrCreate, findAndReplace,
  getItemsAndDelete, get_or_create) classify as writes, never auto-promoted.
- FIX-44-25 presets are complete records (sandbox explicit).
- FIX-44-26 MCP save_to_memory/update_memory gated fail-closed.
- FIX-44-29 the runtime mode gate is bound in production; custom_* and the always
  -injected meta-tools (find_tool, read_skill) are exempted.

Wave C (honest UI): dead toggles removed/replaced, labels and preset summaries
aligned to EFFECT_POLICY, permissive warning rendered live.

Wave D (wiring): FastPath forwards the approval/checkpoint callbacks; run-scope
consent survives the subtask boundary with an inline button (mass-rollback tools
exempt); approval card fails closed; MCP write_vault snapshots; read_skill wraps
untrusted skills in a non-authoritative envelope; invoke_skill inherits the mode.

Wave E (hygiene + docs): dead config keys removed with a migration; global
settings write failure surfaces a Notice; governance/settings/safety docs and
REVIEWER_NOTES aligned to ADR-153 (the Node-vm sandbox was removed at SBX-1).

Verification round: an adversarial 6-area workflow over the real code (41 checks,
36 correct) found and fixed 5 defects (sandbox concurrency, provenance fail-open
on a corrupt manifest, mode-gate meta-tool regression, compound-write regex,
MCP tools/list visibility).

A drift contract (autoApprovalConfigDrift.test.ts) enforces that every settings
key gates a real effect and every effect resolves to a real key. Full suite
416 files / 4340 tests pass, tsc clean, 0 ESLint errors.

Also includes FEAT-02-11 folder-mention (developed on this branch): @-folder
autocomplete recursive/top-level, shared i18n keys.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 22:45:07 +02:00
..
languages.md docs(coding): EPIC-42 complete -- languages reference, spec writeback, backlog 2026-07-03 14:35:13 +02:00
providers.md docs: rewrite docs + website to match v2.14.15 implementation 2026-06-21 21:21:12 +02:00
settings.md feat(approval): EPIC-44 effect-based approval governance + Wave A-E hardening 2026-07-13 22:45:07 +02:00
tools.md chore: release 3.2.2 -- docs and backlog closure 2026-07-08 00:07:31 +02:00
troubleshooting.md docs: sweep docs+website for v3.0.x and EPIC-33 inline chat 2026-06-23 17:49:18 +02:00