claude-code - 💡(How to fix) Fix [DOCS] Bash tool docs missing `AI_AGENT` subprocess environment variable [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Bash tool behavior, specifically the subprocess environment that Claude Code provides to shell commands

Current Documentation

The Bash tool reference currently says:

The Bash tool runs each command in a separate process with the following persistence behavior:

• When Claude runs cd in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings. Subagent sessions never carry over working directory changes.
• Environment variables do not persist. An export in one command will not be available in the next.

The environment variables reference documents user-configurable variables and subprocess-related controls such as:

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB - Set to 1 to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers).

No current page documents that Claude Code sets AI_AGENT for subprocesses.

What's Wrong or Missing?

Changelog v2.1.120 includes:

Set AI_AGENT environment variable for subprocesses so gh can attribute traffic to Claude Code

That entry describes a user-visible subprocess environment variable, but the documentation does not explain:

1. that Claude Code injects AI_AGENT into subprocess environments,
2. which subprocess surfaces receive it, such as Bash commands, hooks, MCP stdio servers, or only a subset,
3. what value users and tools should expect, and
4. how this relates to gh attribution and existing subprocess environment behavior.

Users who inspect command environments, write scripts that branch on agent identity, or troubleshoot gh/GitHub traffic attribution have to infer this behavior from the changelog rather than from the tool or environment-variable references.

Suggested Improvement

Add a short note under Bash tool behavior that documents the subprocess environment Claude Code provides.

Suggested content:

• State that Claude Code sets AI_AGENT for subprocesses as of v2.1.120.
• Document the exact value and whether users should treat it as stable.
• Specify which subprocess types receive the variable.
• Explain that tools such as gh can use the variable to attribute traffic to Claude Code.
• Clarify how this interacts with environment persistence: export values from one Bash command still do not persist to the next, but Claude Code-provided subprocess environment variables are added by the parent process for each command.

Also add an entry or cross-reference on the environment variables page so users searching for AI_AGENT can find the behavior from the complete environment variable reference.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.120

Exact changelog entry: Set AI_AGENT environment variable for subprocesses so gh can attribute traffic to Claude Code