Epic: Migrate ADF Claude agents to Agent SDK

Open
#689 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
python, rust
Domain
ai, backend

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

enhancement

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
  1. Create thin Python wrapper per agent that calls Agent SDK query() and forwards typed JSONL events to stdout using the RPC envelope (#688)
  2. Migrate one agent at a time: product-development first (lowest risk), then security-sentinel
  3. 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 (ClaudeSDKClient handles 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from terraphim/terraphim-ai

All issues in terraphim/terraphim-ai

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.