Proposal: Standardize AI_AGENT for agent runtime detection

Aperta
  • Qualcosa non va?
#136 9 commenti 16 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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:

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:

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.

Lingua principale
TypeScript
Stelle
24.8k
Fork
1.9k
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di agentsmd/agents.md

Tutte le issue di agentsmd/agents.md

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.