ACP for Agent-to-Agent Supervision: Investigation & Solution

acp-agent-supervision-writeup.md

ACP for Agent-to-Agent Supervision: Investigation & Solution

Use Case

Agent-supervises-agent workflow:

1. User tells supervisor agent (Haku): "Build me X"
2. Haku spawns Claude Code to do the work
3. Claude Code completes, Haku verifies output
4. Haku reports filtered assessment to user

The user shouldn't babysit—Haku should automatically continue when Claude Code finishes.

What We Tried

Attempt 1: sessions_spawn with thread: true

{
  "task": "Build feature X",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session"
}

Result: thread: true creates a new Discord thread instead of using the current one. If user asks in thread A, Claude Code posts to thread B.

Attempt 2: sessions_spawn with mode: "run" (no thread binding)

{
  "task": "Say hello",
  "runtime": "acp",
  "agentId": "claude",
  "mode": "run"
}

Result: Output still posted to Discord as a chat message, not returned programmatically to the spawning agent. The supervisor agent wasn't woken—it had to poll or the user had to intervene.

Root Cause: Architectural Mismatch

ACP's design assumptions:

1. Human watches the thread
2. Human is the supervisor
3. Human will respond when agent posts
4. Agent output as "chat messages" is sufficient

Our use case requires:

1. Agent supervises agent (not human)
2. Supervisor needs automatic wake signal on completion
3. Supervisor needs programmatic output access, not chat messages
4. Supervisor verifies before reporting to user

OpenClaw's ACP runtime routes all output to Discord chat, assuming a human will read it. There's no "wake the spawning agent session" callback.

Solution: Direct acpx via Bash

Bypassing OpenClaw's ACP runtime entirely and calling acpx directly works perfectly:

# One-shot execution - result returns synchronously
acpx --format quiet --approve-all claude exec "task here"

# Persistent sessions
acpx claude sessions new --name my-session
acpx claude -s my-session "first task"
acpx claude -s my-session "follow-up task"  # remembers context
acpx claude sessions close my-session

Why this works:

• --format quiet → just the final answer (or --format json for full NDJSON event stream)
• Synchronous execution → result returns in same shell call
• Named sessions (-s name) → persistent multi-turn conversations
• No Discord posting → supervisor controls what/when to relay
• --approve-all → equivalent to Claude Code's --dangerously-skip-permissions

Comparison

Aspect	tmux + Stop hooks	OpenClaw ACP runtime	Direct acpx
Completion signal	Hook wakes supervisor	None (must poll)	Sync return
Output format	Terminal capture	Discord messages	Structured (quiet/json)
Session persistence	tmux sessions	Managed by OpenClaw	~/.acpx/sessions/
Result destination	Supervisor captures	Discord thread	Supervisor's stdout
Supervisor control	Full	Limited	Full

Equivalence Table

tmux approach	acpx equivalent
claude_code_create("proj-t<id>", cwd)	acpx claude sessions new --name t<id> --cwd <path>
claude_code_send(session, task)	acpx claude -s t<id> "task"
claude_code_capture(session)	--format json or sessions history
claude_code_status(session)	acpx claude status -s t<id>
claude_code_kill(session)	acpx claude sessions close t<id>

Feature Request for OpenClaw ACP Runtime

If OpenClaw's sessions_spawn(..., runtime: "acp") is to support agent-to-agent supervision, it would need:

1. Option to bind to existing thread instead of always creating new
2. Completion callback to wake the spawning agent session
3. Programmatic result return (like subagent mode: "run") instead of Discord posting

Until then, direct acpx via bash is the recommended approach for agent-supervised coding workflows.

---

Tested with OpenClaw 2026.3.2 and acpx 0.1.15