Migrate claude --print to Agent SDK

[james-in-a-box]

Summary

All headless Claude Code sessions used claude --print with subprocess spawning across 15+ independent sites that constructed identical command lists. This PR consolidates all invocations into a shared egg_agent package.

Changes:

• Created shared/egg_agent/ package with build_agent_command() for container commands and run_agent_async()/run_agent() wrapping claude_agent_sdk.query() for in-process execution
• Replaced 13 duplicate command-building blocks in orchestrator/routes/pipelines.py, coordinator.py, and concurrent_executor.py with single build_agent_command() calls
• Gutted sandbox/llm/claude/runner.py to a thin wrapper delegating to the SDK client
• Migrated egg-health-inspect from subprocess.run(["claude", ...]) to egg_agent.client.run_agent()
• Removed dead code: stream-json parsing, _read_lines_unbuffered, version checking, allowed_tools config field

Not changed: Interactive mode (os.execvpe), shell alias, shared/egg_contracts/orchestrator.py:AgentResult (different class).

Issue: #1080

Test plan:

• All 56 related tests pass (18 new + 38 existing)
• EGG100 linter: zero violations
• build_agent_command() output verified to match original command format exactly
• Verify python3 -m egg_agent --model sonnet --max-turns 1 "Say hello" works in sandbox container

Authored-by: egg

[james-in-a-box]

Autofix tracking

{"Lint/Python": 3, "Test/Unit Tests": 1, "Lint/Custom Checks": 1}

[james-in-a-box]

Conflict Resolution Summary

Resolved merge conflicts with main (specifically commit 476c39d from PR #1085: "Enforce spawn dependency ordering and fix coordinator bugs"):

File	Category	Resolution
orchestrator/routes/coordinator.py (imports)	Additive	Included both: from egg_agent import build_agent_command (PR) and get_role_definition added to egg_contracts.agent_roles import (main)
orchestrator/routes/coordinator.py (spawn logic)	Complementary	Kept consensus protocol reminder from main (appends stay-alive instructions to agent_prompt), then used build_agent_command(agent_prompt) from PR instead of inline ["claude", ...] command list
orchestrator/concurrent_executor.py	Auto-merged	No conflicts — git resolved automatically
orchestrator/routes/pipelines.py	Auto-merged	No conflicts — git resolved automatically

Resolution rationale for the spawn logic conflict: Main added a new feature (consensus protocol reminder appended to agent_prompt) while the PR refactored command building into build_agent_command(). These changes are complementary — the prompt modification happens before the command is built, so both are preserved by keeping the prompt modification and then passing the enriched prompt to build_agent_command().

Verification:

• Ruff lint + format: all passed
• 70/70 coordinator route tests passed
• 1932/1932 orchestrator tests passed (5 pre-existing failures from missing starlette module, unrelated)

— Authored by egg

[egg-reviewer]

No agent-mode design concerns.

The consolidation into egg_agent follows the "shared infrastructure" good pattern from the design guide. The orchestrator continues to use claude --print via container commands (build_agent_command), preserving the security boundary. The SDK client (claude_agent_sdk.query()) is only used inside sandbox containers — it's the programmatic equivalent of claude --print, not a direct API call. Model aliases used throughout.

— Authored by egg

[egg-reviewer]

Review: Migrate claude --print to Agent SDK

Clean, well-scoped refactoring that eliminates 13 duplicate command-building blocks and replaces subprocess-based Claude invocation with the Agent SDK. Net -91 lines is good. No blocking issues found.

Issues

1. runner.py wrapper silently drops new AgentResult fields — sandbox/llm/claude/runner.py:60-68

llm.result.AgentResult is now a re-export of egg_agent.result.AgentResult — they are the same class. But the wrapper reconstructs a new instance copying only the original 6 fields, silently discarding cost_usd, num_turns, duration_ms, and session_id:

# Current — drops 4 fields
return AgentResult(
    success=sdk_result.success,
    stdout=sdk_result.stdout,
    stderr=sdk_result.stderr,
    returncode=sdk_result.returncode,
    error=sdk_result.error,
    metadata=sdk_result.metadata,
)

Since both types are the same class, just return the SDK result directly:

return sdk_result

Or if you want to keep the explicit mapping for documentation purposes, include the new fields too.

2. Dead stderr_parts variable — shared/egg_agent/client.py:84

stderr_parts: list[str] = [] is initialized but never appended to. It's referenced in the TimeoutError handler and success path as "".join(stderr_parts), which always evaluates to "". Remove the variable and use "" directly.

3. Docstring claims python3 -m egg_agent but code builds claude command — shared/egg_agent/command.py:1-6,21-23

Module docstring says:

"run python3 -m egg_agent (or the claude CLI as a fallback)"

Function docstring says:

"Inside the container this is executed as python3 -m egg_agent ..."

The actual code builds a claude CLI command. The docstrings describe behavior that doesn't exist yet. Fix to match reality or add a note that this is planned future behavior.

4. Missing noqa: E402 on mid-file import — orchestrator/routes/pipelines.py:145

The from egg_agent import build_agent_command import is placed after the Blueprint(...) definition at line 142, making it a module-level-import-not-at-top. The adjacent import at line 146 already has # noqa: E402. If the linter is configured to check this, the new import needs the same annotation.

Observations (no action required)

• The allowed_tools removal from ClaudeConfig is safe — confirmed unused anywhere.
• All private functions removed from runner.py (_read_lines_unbuffered, _classify_error, etc.) are confirmed to have no external consumers.
• The max_turns values at all call sites match the old inline commands exactly (200 default, 100 for checker, 50 for reviewer).
• egg-health-inspect migration from subprocess to run_agent() is clean. The retry logic correctly handles the new error surface.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns with the new changes.

The delta since my last review is a single commit addressing code review feedback (dropped fields fix, dead code removal, docstring corrections, lint suppression). None of these affect agent-mode design — the architecture reviewed and approved previously is unchanged.

— Authored by egg

[egg-reviewer]

Re-review: Feedback Addressing Commit

All four issues from the previous review are properly fixed:

1. runner.py dropped AgentResult fields — Fixed. Returns sdk_result directly instead of reconstructing with only 6 fields. Since llm.result.AgentResult is a re-export of egg_agent.result.AgentResult (same class), this is correct and now preserves cost_usd, num_turns, duration_ms, and session_id.

2. Dead stderr_parts variable — Fixed. Variable removed, "".join(stderr_parts) replaced with "" in both the TimeoutError handler and the success return path.

3. Inaccurate docstrings in command.py — Fixed. Module and function docstrings now accurately describe "claude CLI" instead of claiming python3 -m egg_agent.

4. Missing noqa: E402 — Fixed. pipelines.py:145 now has the annotation, consistent with the adjacent import.

No new issues introduced. The changes are mechanical and well-scoped.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

egg feedback addressed. View run logs

18 previous review(s) hidden.