Proposal: Standardize AI_AGENT for agent runtime detection

Abierto
  • ¿Algo no está bien?
#136 9 comentarios 16 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Activo
Área
documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
24.8k
Forks
1.9k
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de agentsmd/agents.md

Todos los issues de agentsmd/agents.md

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.