Epic: Migrate ADF Claude agents to Agent SDK
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
Research direction
Start with cto-executive-system/knowledge/claude-agent-sdk-reference.md and cto-executive-system/plans/adf-architecture-improvements.md, then inspect crates/terraphim_spawner/src/lib.rs and dependency #688. The first deliverable is a spike comparing the three bridge options while preserving the Rust orchestrator; document the selected approach and split implementation work into the listed sub-issues.
Written by the indexing model from the issue text.
Description
Context
ADF spawns Claude agents as claude -p subprocesses with stdout/stderr capture. This causes SIGPIPE bugs, fragile output parsing, cold-start waste, and no native cost tracking. The Claude Agent SDK (renamed from Claude Code SDK) provides query() async iterator with typed hooks, native session resume/fork, and in-process cost tracking.
Proposal
Replace subprocess spawning for Claude-based agents with Agent SDK query() calls. Codex agents remain as subprocesses (no SDK equivalent).
Migration Strategy
- Create thin Python wrapper per agent that calls Agent SDK
query()and forwards typed JSONL events to stdout using the RPC envelope (#688) - Migrate one agent at a time: product-development first (lowest risk), then security-sentinel
- Preserve orchestrator reconciliation loop, Safety/Core/Growth layers, NightwatchMonitor
What This Eliminates
- SIGPIPE bug (async iterator, no pipes)
- Stdout/stderr parsing fragility (typed message stream)
- Cold-start waste (native
resume=session_id) - Cost tracking complexity (hooks on every API call vs output parsing)
- Session management complexity (
ClaudeSDKClienthandles state)
Open Question: Bridge Architecture
- Option A: Rust orchestrator -> thin Python wrapper (subprocess) -> Agent SDK
- Option B: Rust orchestrator -> local HTTP server running Agent SDK -> typed responses
- Option C: Implement Agent SDK protocol directly in Rust (high effort, fragile)
- Spike needed to determine which approach best preserves Rust orchestrator while gaining SDK benefits
Sub-issues (to be created during design phase)
- Spike: validate Agent SDK wrapper bridge pattern
- Migrate product-development agent to Agent SDK
- Implement cost tracking via Agent SDK hooks (supersedes #638 approach)
- Implement session resume via Agent SDK (supersedes #639 approach)
- Migrate security-sentinel agent to Agent SDK
References
- Agent SDK reference:
cto-executive-system/knowledge/claude-agent-sdk-reference.md - Current ADF subprocess model:
crates/terraphim_spawner/src/lib.rs - Comparison table: Agent SDK reference, "Comparison with Current ADF Setup" section
- Plan:
cto-executive-system/plans/adf-architecture-improvements.md(item 2.1) - Depends on: #688 (RPC envelope)
- Related: #637 (Paperclip epic), #638, #639
- Dominant language
- Rust
- Stars
- 62
- Forks
- 5
- Avg merge
- 2h 27m
- Merged PRs (30d)
- 1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from terraphim/terraphim-ai
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
terraphim/terraphim-ai#885 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 55/100
terraphim/terraphim-ai#871 ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 25/100
terraphim/terraphim-ai#810 · 2 comments ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 35/100
terraphim/terraphim-ai#729 ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 35/100
terraphim/terraphim-ai#728 ·
All issues in terraphim/terraphim-ai
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
kwakseongjae/auto-hwp#319 ·
-
area:cli bug filter-quality good first issue priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
bevyengine/bevy#25861 ·
-
comp-datalake
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
ClickHouse/ClickHouse#121222 ·
-
enhancement remote
Difficulty 2/5 1-3 hours Newbie friendliness 68/100