From 7c415c8b07d0f83294fe5629a9b383ac9dba2bd5 Mon Sep 17 00:00:00 2001
From: Ondrej Ulehla <ondrejulehla@gmail.com>
Date: Sun, 12 Jul 2026 14:19:40 +0200
Subject: [PATCH] docs: document env var inheritance into the CLI subprocess

Adds an 'Environment variables' README section documenting how
_spawn_process builds the CLI subprocess environment: full inheritance
minus CLAUDECODE, the CLAUDE_CODE_ENTRYPOINT default, options.env
overrides, the always-set CLAUDE_AGENT_SDK_VERSION, and the conditional
checkpointing/PWD/OTEL keys. Includes a copy-pasteable example of
overriding and blanking inherited variables, and a note that
inheritance is allowlist-free.

Closes #1100

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 8d8445238..ec2e55a3c 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,47 @@ options = ClaudeAgentOptions(
 )
 ```
 
+### Environment Variables
+
+The CLI runs as a subprocess. Its environment is built in this order
+(later entries win):
+
+1. **Everything from the parent process** (`os.environ`) is inherited, with a
+   single exception: `CLAUDECODE` is removed, so an SDK spawned from inside a
+   Claude Code session is not mistaken for a nested Claude Code instance.
+2. `CLAUDE_CODE_ENTRYPOINT=sdk-py` — identifies the entrypoint; can be
+   overridden via `options.env`.
+3. **Your `ClaudeAgentOptions.env`** — every key overrides the inherited value.
+4. `CLAUDE_AGENT_SDK_VERSION` — always set by the SDK (not overridable).
+
+Conditionally, the SDK also sets `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`
+(when `enable_file_checkpointing=True`), aligns `PWD` with `cwd`, and — when
+`opentelemetry-api` is installed and a span is active — injects fresh
+`TRACEPARENT`/`TRACESTATE` unless you set them explicitly in `options.env`.
+
+> **Note:** inheritance is allowlist-free. Any secret exported in the parent
+> shell (cloud credentials, tokens, …) is visible to the CLI subprocess and to
+> the tools it runs. If your agent processes untrusted input, start it from a
+> minimal environment or override sensitive keys via `options.env` — setting a
+> key to an empty string effectively blanks the inherited value:
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, query
+
+options = ClaudeAgentOptions(
+    env={
+        "MY_SERVICE_URL": "https://staging.example.com",  # add/override for the CLI
+        "AWS_SECRET_ACCESS_KEY": "",  # blank an inherited secret
+    },
+)
+
+async for message in query(prompt="Deploy the docs site", options=options):
+    print(message)
+```
+
+The SDK itself honours `CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK=1` to skip the
+CLI version compatibility check.
+
 ## ClaudeSDKClient
 
 `ClaudeSDKClient` supports bidirectional, interactive conversations with Claude