0012: AI agent sessions may run and inject, never read
- Status: accepted
- Date: 2026-09-22
Context
AI coding agents (Claude Code, Cursor and similar) need to start services,
run builds and configure projects that require secrets, and they must never
have secret values in their context window, transcripts or logs. The prior
art, nfi-tools, solves collection (a human supplies a value out of band via a
localhost form or /dev/tty) but its "never read the file afterwards" rule
is prompt text in tool descriptions, not a control, and the values sit in
plaintext files. vaultfold replaces it.
Decision
Principle: agents get references, never values. The model sees
vault://prod/stripe#secret_key; the subprocess gets the value.
- Because values are encrypted at rest (ADR 0003), reading the vault directory yields ciphertext. The only path to plaintext is the daemon (ADR 0011), which is therefore the enforcement point.
- The daemon classifies a session as an agent session when the
requesting process tree carries harness markers (for example a Claude Code
environment marker or an MCP stdio parent) or when the session is created
by the vaultfold MCP server or by
vaultfold agent-mode on. Agent sessions are first-class sessions under a human identity for policy and audit. - Agent-session policy, enforced by the daemon regardless of prompt text:
allowed:
set(out-of-band collection via browser form with one-time token and Origin check, or direct/dev/tty, never agent-controlled stdin),has,list,describe,generate,remove,copy,link(writes a reference into a config file),run,inject(to a subprocess or a fifo, never to the agent's stdout);copyduplicates an entry to another reference and returns no value. Denied:read,get,export,totp, clipboard copy, and any operation returning a value. - The MCP server exposes exactly the allowed verbs plus
describe_capabilities; it has no tool that returns a secret value. Approval flows return a request id and code immediately (non-blocking) and the verb is re-invoked after approval; the daemon holds the pending request. - Harness hooks are shipped for supported agents: a pre-tool hook that
denies
vaultfold readandexportin shell commands during agent sessions, and a post-tool hook that pipes tool output throughvaultfold redact, which runs locally against the daemon's unlocked values and masks any occurrence above a minimum length before the model sees it. runmasks injected values in the child's stdout and stderr (minimum length threshold, binary streams skipped).- Approval prompts for agent sessions show the scope the agent will receive and approvals are scoped to it, so a later off-script request cannot ride on an earlier approval.
- Unattended agents use machine identities (ADR 0008).
- Migration:
vaultfold import --from-nfiencrypts values from plaintext config files into the vault and rewrites the files with references.
Consequences
- The nfi-tools guarantee becomes a technical control instead of a convention.
- Agent sessions appear in audit logs distinctly from the human's own sessions.
- Harness detection is best-effort; explicit
agent-modeexists for harnesses without markers, and the MCP server path is always classified correctly.
Alternatives considered
- Tool-description instructions only (nfi-tools). Rejected: unenforced.
- Denying agents all access. Rejected: prevents the primary use case (starting services with secrets).