claude-code - 💡(How to fix) Fix [FEATURE] Sub-agents should inherit CLAUDE_ENV_FILE environment variables from parent session [1 comments, 2 participants]

Feature Type

New feature request

Description

When a parent session writes environment variables to CLAUDE_ENV_FILE via a SessionStart hook, sub-agents spawned via the Agent tool do not inherit those variables. Each sub-agent gets its own empty CLAUDE_ENV_FILE (under a different session-env/<session-id>/ path), and SessionStart does not fire for sub-agents.

Use Case

We run an orchestrator agent (claude --agent inbound-orchestrator) that dispatches 5 parallel worker sub-agents via the Agent tool. The orchestrator's SessionStart hook loads .env variables (API keys, SMTP credentials, DB paths) into CLAUDE_ENV_FILE. The orchestrator's own Bash commands can access these variables, but the worker sub-agents cannot — their Bash commands see empty environment.

This forces us to work around the limitation by using a PreToolUse hook that prepends set -a && . '.env' && set +a && to every Bash command via updatedInput. This works but adds overhead and visual noise to every command.

Expected Behavior

Sub-agents spawned via the Agent tool should inherit environment variables that the parent session wrote to CLAUDE_ENV_FILE. Either:

1. Sub-agents should receive a pre-populated CLAUDE_ENV_FILE containing the parent's exports, OR
2. Sub-agents should fire their own SessionStart hooks (currently only SubagentStart fires, which cannot inject env vars), OR
3. A new mechanism (e.g., envFile in settings.json that accepts a file path) should propagate .env to all sessions globally

Current Workaround

PreToolUse hook on Bash that sources .env before every command via updatedInput:

# In the PreToolUse hook script:
prefix="set -a && . '${env_file}' && set +a && "
jq -n --arg prefix "$prefix" --arg cmd "$cmd" '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    updatedInput: {command: ($prefix + $cmd)}
  }
}'

Environment

• macOS, Claude Code latest
• Using Agent tool to spawn sub-agents from an orchestrator agent
• SessionStart hook writes to CLAUDE_ENV_FILE (documented pattern)

Impact

High - Blocks reliable use of environment variables in multi-agent pipelines. Any project using Agent tool + API keys/credentials is affected.