Skip to content

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 --detection prints 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=1 and AGENT=goose (the two Goose markers count as one signal; AGENT with any other value, such as a CI system's AGENT=builder-7, is not a marker), and the ancestry names claude, codex, gemini, opencode, goose and aider. aider sets no documented variable and is detected by ancestry only; Cursor's CLI runs as node index.js and 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 on for the terminal, or the vaultfold MCP server among the ancestors. One signal alone prints a warning and the command runs. agent_detection = "strict" in profile.toml restores 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 claude symlink, 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 set agent_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 on cannot cover them; they are classified by CLAUDECODE plus 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.