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) orbrowser(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>/environon Linux,kern.procargs2on 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) orwrite. - Human and machine sessions are served without approvals, apart from
first contact of an unknown caller (ADR 0028) and the touch policy below.
approveandshutdownare refused from a machine session. - Agent sessions (ADR 0012 as a control, not a convention):
displayis refused (agent-session, exit 2), except aresolveof exactly the references a human has allowed withvaultfold 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
resolveandunwrap-kekneeds a scope grant covering the reference or collection. Without one the request is answeredapproval-pending(the CLI exits 3 and says to runvaultfold agent approveoutside 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
resolvewith purposeinjectonly and nounwrap-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,shutdownand theagent-modechanges are refused; an unlock without a passphrase queues an unlock approval for a human. sign-eventsigns 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 thatunwrap-kekserves an agent only under an approvedwritescope.redactmasks 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 approveis accepted only from a human session whose controlling terminal the daemon itself observed. Approvals expire unanswered afterapproval_timeout(5 minutes by default). - Touch policy: a collection named
proddefaults toalways(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 tosession. 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 refusedtouch-cancelled, and in machine identity modepolicy. - Explicit agent mode:
vaultfold agent-mode onmarks the current terminal, and every later session from it is an agent session.agent-mode offis 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-kekand 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 (rateandburstin[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
statusis 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 logverifies and prints it. - Locking: the TTL, an idle limit, system idle, screen lock, sleep (clock
divergence plus the platform's suspend notification),
vaultfold agent lockand 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 offwork from the marked terminal. Rejected (above). - Blocking requests until a human answers. Rejected: harnesses time
out tool calls; a non-blocking
approval-pendinglets the agent ask the human and retry.