Proposal: Standardize AI_AGENT for agent runtime detection

The issue names no files or tests in this repository. Start by reading the Producers, Consumers, Open questions, and Out of scope sections, then review the cited registry agents.json and adoption entry points such as gh's internal/agents/detect.go; done means a resolved, maintainable specification rather than an implementation patch.

Last verified: 2026-10-02. Corrections welcome in the comments — please include a source (code link, docs, or observed env dump).

Problem

Scripts and CLIs detect CI via CI=true and adapt: no prompts, CI-friendly output. There is no equivalent for AI coding agents, so every tool builds its own detection matrix of vendor-specific variables (CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, CODEX_CI, …).

Agents need something different from CI:

• Interactivity — like CI, agents can't answer prompts
• Output — CI wants less output; agents want more actionable output (full tracebacks, failing test names, structured errors)
• Attribution — tools want to know which agent drove a command (telemetry, User-Agent, commit attribution)

Proposal

Standardize AI_AGENT, the variable the ecosystem has already converged on, and define what nobody has yet: its value format and semantics.

Producers (agents)

1. MUST set AI_AGENT in the environment of every command they spawn.
2. The value MUST match ^[A-Za-z0-9_-]{1,64}$ (the format gh enforces) and SHOULD start with the agent's registered slug. Qualifiers (surface, version) MAY follow, e.g. claude-code_2-1-284_agent, github_copilot_vscode_agent.
3. SHOULD NOT overwrite an inherited AI_AGENT set by another agent: the outermost agent wins.
4. MAY keep setting their tool-specific variables.

Consumers (tools)

1. MUST treat any non-empty value other than 0, false, no, off as "running under an agent".
2. SHOULD identify the agent by matching the value against a registry, by registered slug prefix, falling back to unknown.
3. MUST NOT use it for authorization or to skip confirmations. It is an unauthenticated hint.
4. SHOULD sanitize the value before putting it in URLs, headers, or logs.

AGENT (legacy)

Producers MAY also set AGENT. Consumers MAY read it as a fallback after AI_AGENT, treating 1/true as an unnamed agent and any other value as a name.

Producer adoption

Agent	AI_AGENT	AGENT	Tool-specific	Ref
Claude Code	claude-code_<version>_agent	–	CLAUDECODE=1, CLAUDE_CODE_CHILD_SESSION=1	Changelog 2.1.120
VS Code Copilot	github_copilot_vscode_agent	–	COPILOT_AGENT=1	microsoft/vscode#320129, #327433
pi	pi	–	PI_CODING_AGENT=true	earendil-works/pi#7493
Crush	crush	crush	CRUSH=1	internal/shell/shell.go
OpenCode	opencode	1	OPENCODE=1	anomalyco/opencode#51975
Hermes Agent	hermes-agent	–	HERMES_AGENT=true	sdairs/is-ai-agent#6 (observed)
OpenHands	openhands	–	–	OpenHands/software-agent-sdk#4366
Kilo Code	requested	1	KILO=1, OPENCODE=1	Kilo-Org/kilocode#12854
Goose	–	goose (regressed in shell tool)	GOOSE_TERMINAL=1	aaif-goose/goose#12606
Codex CLI	requested	–	CODEX_CI=1, CODEX_THREAD_ID	openai/codex#36883
Gemini CLI	–	–	GEMINI_CLI=1	shellExecutionService.ts
GitHub Copilot CLI	unknown	–	COPILOT_CLI=1	Changelog
Cursor	–	–	CURSOR_AGENT	Docs
Augment	–	–	AUGMENT_AGENT=1	Docs
Cline	–	–	CLINE_ACTIVE=true (VS Code terminals)	VscodeTerminalRegistry.ts
Qwen Code	–	–	QWEN_CODE=1	shellExecutionService.ts
Kimi CLI	requested	–	–	MoonshotAI/kimi-cli#2585
Aider	requested	–	–	Aider-AI/aider#5521
Amp	unknown	unverified	AMP_CURRENT_THREAD_ID	AGENT=amp documented only for the permission delegate helper
Devin	–	–	/opt/.devin (file)	vercel/detect-agent

Notes:

• GROK_AGENT is an input setting of Grok Build (which agent profile to run), not a marker it sets (docs).
• CLAUDECODE is also set in Claude Code IDE terminals, and REPL_ID across the whole Replit platform: both cause false positives when used alone.

Consumer adoption

AI_AGENT is read first, before vendor-specific variables, by:

• CLIs: gh, Firebase, Supabase, Netlify, Stripe, Sentry, CircleCI, DuckDB, Dagger
• JS tooling: Jest, Vitest, Storybook, Turborepo, Next.js
• PHP tooling: Composer, PHPStan, Psalm, Laravel Pint
• Python: Pydantic AI, MLflow, huggingface_hub, crewAI
• Detection libraries: detect-agent, std-env, laravel/agent-detector, mise-agent-env, is-ai-agent

AGENT is read four incompatible ways, which is why this proposal keeps it as legacy only:

Interpretation	Consumers
Only AGENT=1 counts; any other value means not an agent	Bun (oven-sh/bun#44459), ami
Only known names count	Psalm (goose), gh / Netlify (amp), Wrangler
Any non-empty value counts	Stripe, DuckDB, Dagger, Modal, Sentry, testthat
Ignored on purpose	std-env, detect-agent, Composer, PHPStan, mise

Registries

Two machine-readable agent registries exist:

• vercel/detect-agent agents.json (with JSON Schema)
• Hugging Face /api/agent-harnesses (docs)

This proposal relies on an existing registry for slugs rather than creating another.

Security considerations

• AI_AGENT is a hint, not an identity. Anything in the process tree can set it, and prompt injection can poison environment variables (CVE-2026-22708).
• Keep agent-specific behavior to output and interactivity. Never auto-confirm destructive actions because an agent is detected.
• Behavior changes should be overridable: PHP-CS-Fixer#9655 made detection opt-in after user pushback, and several CLIs expose --agent yes|no|auto or a tool-specific override (e.g. NETLIFY_AGENT).

Precedent

• CI=true: set by GitHub Actions, GitLab CI, CircleCI, Jenkins, …
• NO_COLOR: no-color.org
• TERM=dumb: limited terminal capabilities

Out of scope

• Per-agent identity in multi-agent runs (raised by @withzombies). Agents already expose session IDs (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, PI_SESSION_ID, AGENT_SESSION_ID), and W3C TRACEPARENT covers parent/child relationships. Worth a separate proposal.
• Agent-specific instructions: #185 depends on agents knowing their own identity, which this proposal provides.

Open questions

1. Version — keep it inside the value (as Claude Code does) or move it to a separate variable?
2. Nesting — is "outermost agent wins" the right default? Terminal multiplexers and agent-in-agent setups can leak a stale value (herdrdev/herdr#4631).
3. Defaults — should producers also set NO_COLOR, TERM=dumb, and PAGER=cat (as Codex and Mistral Vibe already do)?
4. Registry governance — can one of the existing registries move to neutral ownership (e.g. under AAIF, alongside AGENTS.md)?
5. Allowlisted boundaries — AcceptEnv/SendEnv, containers, CI secret allowlists each need AI_AGENT added explicitly (ddev/ddev#8378). Should this spec recommend forwarding it?

Decision log

2026-10 — AGENT discarded in favor of AI_AGENT. This issue originally proposed AGENT=[agent-name]|1|true. The industry moved to AI_AGENT instead:

• Claude Code (2.1.120), VS Code Copilot (#320129), pi (#7493), Hermes, OpenHands, and OpenCode shipped AI_AGENT. Requests for AGENT were closed by Claude Code (#24838), Codex (#13416), and Gemini CLI (#21032).
• Most consumers read AI_AGENT first, and several ignore AGENT on purpose.
• AGENT never got a defined value format and is now read in four incompatible ways (see above).
• AGENT is generic enough to collide with unrelated tooling, the original concern raised by VS Code (#258911), which itself adopted AI_AGENT.

Supporting both names as equals was also discarded: every allowlisted boundary (ssh, containers, CI) needs each name added separately, so two names cost more than one.