Skip to content

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); copy duplicates 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 read and export in shell commands during agent sessions, and a post-tool hook that pipes tool output through vaultfold redact, which runs locally against the daemon's unlocked values and masks any occurrence above a minimum length before the model sees it.
  • run masks 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-nfi encrypts 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-mode exists 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).