Skip to content

0029: Agent daemon sessions, approvals and purpose-scoped policy

  • Status: accepted
  • Date: 2026-10-03

Context

ADR 0012 says agent sessions may run and inject but never read, and ADR 0011 says approvals are scoped and time-limited. The daemon (ADR 0028) is where both are enforced, so it needs a concrete model: what a session is, how its kind is decided, what each kind may do, how a human approves, and what bounds an automated caller. The decisions below come from openspec/changes/add-agent-daemon/design.md ("Session and policy engine" and the group 4, 5, 9 and 10 decisions).

Decision

Sessions

  • Every request names a session the client opened with session-open. A session has a kind: human, agent, machine (machine identity mode) or browser (the browser extension's native host).
  • The daemon classifies the session from its own observation of the connecting process (its ancestors, and its environment where the OS lets the same user read it: /proc/<pid>/environ on Linux, kern.procargs2 on macOS) together with the signals the client reports. The result is the union: a client's report can raise the kind, never lower it. Signals the daemon does not know are dropped and only counted. The detection rule itself is ADR 0030.
  • Sessions are reused by the next command from the same place: the same harness session id when either side has one, otherwise the same terminal (the controlling terminal's device and session leader, <device>@<sid>, reported by the client), otherwise the same process group. Reuse requires the same kind. A kind is set at open and may only be raised: when the union of a reused session's signals becomes an agent classification, the session becomes an agent session in place and its overrides stop applying.
  • Sessions live in daemon memory only and expire with the unlock TTL. The CLI does not close its session when a command ends, so for-session approvals and redaction carry over to the next command in that terminal.

What each kind may do

  • Requests carry a purpose: display (the value is shown), metadata, inject (the value goes to a child process or file) or write.
  • Human and machine sessions are served without approvals, apart from first contact of an unknown caller (ADR 0028) and the touch policy below. approve and shutdown are refused from a machine session.
  • Agent sessions (ADR 0012 as a control, not a convention):
    • display is refused (agent-session, exit 2), except a resolve of exactly the references a human has allowed with vaultfold agent-mode allow-read <ref>: one reference, at most one hour, created from a human session with a terminal, applying only to agent sessions in that terminal or harness session, and only while the granting human session is still live.
    • Every other resolve and unwrap-kek needs a scope grant covering the reference or collection. Without one the request is answered approval-pending (the CLI exits 3 and says to run vaultfold agent approve outside the agent session) and an approval is queued whose proposed scope is the collection of the first uncovered reference.
    • A caller other than the daemon's own binary or the project signer gets resolve with purpose inject only and no unwrap-kek: the CLI binary is trusted to honour the purpose of the keys it receives, other code is not.
    • Unlocking with a passphrase, approve, trust revocation, prompter registration, shutdown and the agent-mode changes are refused; an unlock without a passphrase queues an unlock approval for a human.
    • sign-event signs only the session's own data events, whole (never a bare hash), naming the vault's unlocked key as author and the session's id. Signing is scoped to the vault, not the collection: the collection is gated where its key is, since the event's ciphertext needs the collection key that unwrap-kek serves an agent only under an approved write scope.
    • redact masks only values that session has itself been served, so it is not an equality oracle for other values the daemon holds.
  • Policy decisions are one pure function over (request, session, caller, approvals, overrides, time) that fails closed on anything it does not recognise; every verb and scenario is a table test.

Approvals

  • An approval is scoped to a session, a vault and a collection or path prefix, and lasts once (one client request, however many references it names) or for the session (8 hours by default). Both defaults were open decisions in docs/adr/README.md and are now decided.
  • A queued approval is shown at once on every available endpoint: the platform dialog (the macOS helper app, a Windows message box, zenity or kdialog on Linux; ADR 0031 to 0033), a registered desktop app, and the pending queue that vaultfold agent approve [<code>] lists and answers (--for-session, --deny). The first answer wins and the others are dismissed. agent approve is accepted only from a human session whose controlling terminal the daemon itself observed. Approvals expire unanswered after approval_timeout (5 minutes by default).
  • Touch policy: a collection named prod defaults to always (a fresh user-presence check per request, through Touch ID or the login password on macOS with the helper app, Windows Hello where set up, otherwise a confirmation dialog), every other collection to session. The vault format has no touch flag yet, so the name is the only signal. Only a platform dialog can confirm presence; where none can be shown the request is refused touch-cancelled, and in machine identity mode policy.
  • Explicit agent mode: vaultfold agent-mode on marks the current terminal, and every later session from it is an agent session. agent-mode off is refused from that terminal; the mode ends when the terminal's session ends or the daemon stops. Allowing it to be lowered from the same terminal would let an undetected agent lower its own classification.

Bounds on automation

  • Rate limits apply to resolve, unwrap-kek and browser requests: one token per request (a batch is one request) from both the session's and the caller's bucket, 60 per minute with a burst of 20 by default (rate and burst in [agent]). The caller bucket is split by session class (human, suspected agent, other) so a runaway agent cannot starve the human's own CLI. Consecutive limiter refusals back off from 1 second, doubling to 60 seconds; the third limiter refusal in 10 minutes shows one notice (an OK-only dialog that never answers an allow) and writes an audit record. The limits apply to human sessions too.
  • Audit: every request except a successful status is recorded in <Data>/audit/agent.log (JSON lines, each line chained to the previous one by BLAKE3 and MACed under a key derived from the machine key; rotated at 10 MiB, five files in all). vaultfold agent log verifies and prints it.
  • Locking: the TTL, an idle limit, system idle, screen lock, sleep (clock divergence plus the platform's suspend notification), vaultfold agent lock and shutdown each zeroise the vault's keys. A lock trigger that becomes unavailable locks every vault.

Consequences

  • An agent can run and inject with values it never sees, after a human approves the scope once; it cannot print a value through the daemon whatever its environment says.
  • Scripts in a human session never prompt after the first unlock, but can meet the rate limit (exit 3, rate-limited) when they run many vault commands back to back.
  • Two agents in one terminal that export no harness session id cannot be told apart and share one session and its approvals.
  • Explicit agent mode and the terminal key are self-reported by the client: they guard against a cooperative agent the detector misses, not against a hostile process that calls setsid, opens a new terminal or speaks the protocol directly. The threat model says so.
  • The audit log fails open: a failed write is a warning, and the request is still answered.

Alternatives considered

  • Classifying from client-reported signals only. Rejected: the client is the process being classified.
  • Approvals per request only. Rejected: an agent running a test suite would ask for the same approval every few seconds, which trains humans to approve without reading.
  • Approvals per vault. Rejected: too broad; the first request's collection is a scope the human can judge.
  • Letting agent-mode off work from the marked terminal. Rejected (above).
  • Blocking requests until a human answers. Rejected: harnesses time out tool calls; a non-blocking approval-pending lets the agent ask the human and retry.