[Bug]: Subagent spawn fails with missing ANTHROPIC_API_KEY even when parent process has valid configuration

[ouyinghui]

What happened?

Problem Description

When using the agent tool to spawn a subagent (subintelligence), the spawn fails with an error requiring ANTHROPIC_API_KEY, even though the parent process (ohmo gateway) already has a valid API key configured in settings.json.

Error Message

ValueError: Local agent tasks require ANTHROPIC_API_KEY or an explicit command/argv override

Root Cause Analysis

Code Locations

• /usr/local/lib/python3.12/site-packages/openharness/tasks/manager.py (lines 135-143)
• /usr/local/lib/python3.12/site-packages/openharness/swarm/spawn_utils.py (lines 22-67)

Issue 1: create_agent_task doesn't inherit parent's API key

Current code (manager.py):

if command is None and argv is None:
    effective_api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
    if not effective_api_key:
        raise ValueError(
            "Local agent tasks require ANTHROPIC_API_KEY or an explicit command/argv override"
        )
    argv = ["python", "-m", "openharness", "--api-key", effective_api_key]

Problem: Only checks api_key parameter or ANTHROPIC_API_KEY env var.
Does NOT load from parent's settings.json.

Issue 2: Subprocess backend doesn't forward API key env vars

Current code (spawn_utils.py):

_TEAMMATE_ENV_VARS = [
    "ANTHROPIC_API_KEY",
    "ANTHROPIC_BASE_URL",
    # ... other vars ...
]
# Missing: OPENHARNESS_API_KEY or settings.json path

Problem: Subprocess doesn't inherit openharness's api_key from settings.

Issue 3: No documentation for subagent API key configuration

Current state:

• No clear documentation on how to configure API key for subagents
• User might securely pass API key via prompt (security risk!)
• No guidance on proper ambient credentials pattern

---

Impact Analysis

Affected Users

• ✅ All ohmo users using agent tool
• ✅ Any OpenHarness user spawning subagents
• ✅ Multi-agent workflows

Severity

Critical: Blocks core functionality (subagent spawning)

Workarounds (Not Recommended)

1. ❌ Set ANTHROPIC_API_KEY in shell (security risk if shared)
2. ❌ Pass api_key parameter in prompt (exposes key to LLM)
3. ❌ Use custom command with embedded key (security risk)

---

Proposed Fix

Option A: Load API key from parent's settings.json (Recommended)

Option B: ......

Option C: Documentation + warnings

Add comprehensive documentation about:

1. Subagent API key requirements
2. Secure credential handling
3. Recommended patterns (ambient credentials via settings.json)

---

Security Considerations

Current Design Intent

The current ANTHROPIC_API_KEY requirement appears to be intentional for:

1. Security isolation: Subprocess doesn't inherit parent's credentials
2. Explicit configuration: Forces clear API key handling

Problem with Current Approach

1. No ambient credentials pattern: Parent's settings.json is ignored
2. User temptation to leak keys: May pass API key in prompt
3. Configuration duplication: Must configure API key twice

Recommended Secure Pattern

Parent Process (ohmo gateway)
├── reads api_key from /opt/data/.openharness/settings.json
│   (secure, file permissions controlled)
├── spawns subprocess with:
│   ├── --api-key flag (CLI argument, not logged)
│   └── no env var leakage
└── subprocess uses inherited --api-key

---

Files Modified

File	Changes
manager.py	Add _load_api_key_from_parent() helper, update create_agent_task()
spawn_utils.py	Add OPENHARNESS_SETTINGS_PATH to _TEAMMATE_ENV_VARS
Documentation	Add "Subagent API Key Configuration" section

---

Steps to reproduce

Reproduction Steps

1. Configure ohmo with API key in /opt/data/.openharness/settings.json:

   {
     "api_key": "sk-xxx",
     "model": "XXX-model",
     "provider": "openai",
     "base_url": "https://api.XXX-model.com/v1"
   }

2. In ohmo gateway, spawn subagent:

   {
     "agent": {
       "description": "Hello World",
       "prompt": "print('Hello, World!')",
       "subagent_type": "worker"
     }
   }

3. Expected: Subagent spawns successfully using parent's API key

4. Actual: Spawn fails with "ANTHROPIC_API_KEY required" error

---

Environment

Version: openharness 0.1.9
Contributor: ohmo (personal agent on OpenHarness)
Date: 2026-06-17

Relevant logs or screenshots