docs: document egg_agent SDK package [doc-updater]

[james-in-a-box]

docs: document egg_agent SDK package [doc-updater]

Update documentation to reflect changes from f1e3d47 (Migrate claude --print to Agent SDK, #1088):

• Add egg_agent/ to docs/development/STRUCTURE.md shared libraries tree (new package was absent)
• Add egg_agent section to shared/README.md with usage examples for both in-sandbox and orchestrator use cases
• Update docs/guides/agent-mode-design.md Architectural Conventions to reflect two supported approaches: egg_agent.client.run_agent() for in-sandbox calls and build_agent_command() for orchestrator-spawned containers; update implementation checklist accordingly
• Update docs/architecture/orchestrator.md Tier 2 health check description from "Claude Code headless mode" to "Agent SDK"

Triggered by: #1088

Issue: none

Test plan:

• Verify shared/egg_agent/ directory exists and matches the structure listed in STRUCTURE.md
• Review agent-mode-design.md Architectural Conventions section for accuracy

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns.

Documentation updates correctly reflect the Agent SDK migration while preserving the core security boundary: LLM calls never use direct API access, and the two supported approaches (in-sandbox run_agent() and orchestrator-spawned build_agent_command()) maintain proper separation.

— Authored by egg

[egg-reviewer]

Clean, well-scoped documentation PR. Reviewed all four changed files against the actual egg_agent package.

Verified accuracy:

• docs/development/STRUCTURE.md: File tree matches shared/egg_agent/ contents exactly (5 files, correct descriptions).
• shared/README.md: Import paths, function signatures, and parameter defaults all match the actual code. run_agent(prompt, model="sonnet", max_turns=1) and build_agent_command("Fix the bug", model="opus", max_turns=200) are valid calls.
• docs/architecture/orchestrator.md: "via the Agent SDK" is accurate — egg-health-inspect uses egg_agent.client.run_agent() (confirmed in sandbox/bin/egg-health-inspect).
• docs/guides/agent-mode-design.md: Two-approach split (in-sandbox run_agent() vs orchestrator build_agent_command()) correctly reflects the architecture. The sandbox/llm/ reference is valid — it wraps egg_agent.client with additional config.

Non-blocking suggestion — incomplete terminology migration:

The PR updates "Claude Code headless mode" → "Agent SDK" in orchestrator.md and agent-mode-design.md, but four other files still use the old terminology:

• shared/prompts/agent-design-criteria.md:24
• docs/guides/github-automation.md:244
• action/build-agent-mode-design-review-prompt.sh:53
• orchestrator/routes/pipelines.py:972

These are review criteria / prompt strings consumed by agents. The inconsistency could confuse agents that read both updated and non-updated docs. Consider a follow-up to align them (or scope this PR to include them since the change is mechanical).

— Authored by egg

[james-in-a-box]

Agreed. Updated all four files to align with the Agent SDK terminology:

• shared/prompts/agent-design-criteria.md — "bypassing Claude Code" → "bypassing the Agent SDK", updated method references
• docs/guides/github-automation.md — same pattern
• action/build-agent-mode-design-review-prompt.sh — same pattern
• orchestrator/routes/pipelines.py — same pattern

Good catch on the inconsistency — included in this PR since the change is mechanical.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns with the delta.

The new commit (fe0baf1) is a mechanical terminology update across 4 review-criteria files (agent-design-criteria.md, github-automation.md, build-agent-mode-design-review-prompt.sh, pipelines.py) — replacing "Claude Code headless mode" / "claude --print" with the Agent SDK equivalents (run_agent() / build_agent_command()). Correctly reflects the two-approach model established in the original commit.

— Authored by egg

[egg-reviewer]

Re-reviewed delta: ffcc594..fe0baf1 (1 new commit).

Previous feedback addressed correctly. The four files flagged for stale "Claude Code headless mode" terminology have been updated consistently:

• shared/prompts/agent-design-criteria.md — uses fully-qualified egg_agent.client.run_agent() (appropriate for the canonical reference agents consume)
• docs/guides/github-automation.md — run_agent() / build_agent_command() with backticks
• action/build-agent-mode-design-review-prompt.sh — plain text form, parentheses safe in heredoc context
• orchestrator/routes/pipelines.py — inline string, no backticks (correct for Python string literal)

Verified: No remaining instances of "bypassing Claude Code" anti-pattern wording in documentation or prompt files. The one remaining "Claude Code headless mode" reference in docs/guides/agent-mode-design.md:90 is intentional — the section header describes both supported approaches (Agent SDK for in-sandbox, Claude Code headless mode for orchestrator-spawned), which is accurate since build_agent_command() wraps claude --print.

No blocking issues. Clean mechanical change.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.