0030: Agent detection by independent, cited signals
- Status: accepted
- Date: 2026-10-03
Context
ADR 0012 classifies a session as an agent session when the process tree
carries harness markers. The first table (implement-cli-v1) matched three
environment variable prefixes, AIDER_*, CLINE_* and GOOSE_*, and
refused value-returning commands on any one marker. Each prefix misfired
on ordinary shells: GOOSE_* matches the pressly/goose database migration
tool (GOOSE_DRIVER, GOOSE_DBSTRING) and a Goose user's own settings
exported from dotfiles (GOOSE_PROVIDER, GOOSE_MODEL); AIDER_*
matches aider's configuration variables; CLINE_* matched no documented
variable at all. A detector that refuses humans trains them to work around
it or to abandon the tool, while the real control is the daemon
(ADR 0029).
Decision
- Exact markers only, never a prefix or a wildcard. Every row is an exact variable name, with a fixed value where the harness sets one.
- Every row is cited. A row is added only when the harness's own
documentation or source shows it, and the citation is kept beside the
row in
internal/agentdetect.vaultfold agent-help --detectionprints the rule and every row with its harness and source. The table as built:CLAUDECODE,CURSOR_AGENT,CODEX_SANDBOX,GEMINI_CLI,OPENCODE,CLINE_ACTIVE=true,GOOSE_TERMINAL=1andAGENT=goose(the two Goose markers count as one signal;AGENTwith any other value, such as a CI system'sAGENT=builder-7, is not a marker), and the ancestry namesclaude,codex,gemini,opencode,gooseandaider. aider sets no documented variable and is detected by ancestry only; Cursor's CLI runs asnode index.jsand is detected by its marker only. - Two independent signals, or one explicit signal. Signals have
classes: an environment marker, and an ancestor (up to 16 levels) whose
executable name, interpreter script name (for
node,python*,bun,deno) or argv[0] base name matches the ancestry table. A session is an agent session when two different classes are present, or when an explicit signal is:VAULTFOLD_AGENT=1,vaultfold agent-mode onfor the terminal, or the vaultfold MCP server among the ancestors. One signal alone prints a warning and the command runs.agent_detection = "strict"inprofile.tomlrestores refusal on one signal. Two environment markers from different harnesses are still one class. - argv[0] can only add a signal. Claude Code's native installer runs
a version-named file through a
claudesymlink, so the resolved executable never matches; the ancestor's argv[0] base name is therefore also matched. A process controls its own argv[0], but trusting it here gives an agent nothing, since a match only makes a session more restricted. argv is never evidence of a caller's identity for trust. - The CLI computes the classification itself for the nudge before any
daemon contact, and sends its signals in
session-open; the daemon recomputes ancestry and environment from its own observation and takes the union.
Consequences
- Users whose shells export
GOOSE_*,AIDER_*or other prefix-matching variables are no longer nudged. Users who relied on one-marker refusal setagent_detection = "strict". - A harness with neither a documented marker nor a recognisable ancestor gets one or zero signals and is treated as the human. Explicit agent mode and the MCP server (a later change) remain the reliable paths, and the audit log records sessions flagged as suspected agents. A harness that rewrites its argv[0] to something unlisted is detected by its environment marker alone, which only warns unless detection is strict.
- A command that detaches from its ancestry before contacting the daemon (a new session plus a double fork) loses its ancestry signal.
- Claude Code's tool processes have no controlling terminal, so
agent-mode oncannot cover them; they are classified byCLAUDECODEplus ancestry. - The browser extension's native host refusal (add-browser-extension) stays one-signal over this exact table: a false positive there only disables autofill with a message.
Alternatives considered
- Keep the prefixes and add exceptions. Rejected: the variable space of unrelated tools is open-ended.
- One signal refuses (the old rule). Rejected as the default for the
reason above; kept as
strict. - Detect agents by heuristics on behaviour (request rate, timing). Rejected: unexplainable to users and easy to tune around; the rate limits (ADR 0029) bound automation without classifying it.