Design: define portable agent adapter and execution substrate contracts

[devkade]

Design: define portable agent adapter and execution substrate contracts

Parent: #167
Related: #169, #170

Summary

Define the portable boundary that lets Ilchul run Codex, Pi, Claude Code, and future agent CLIs through common worker protocols without making core runtime depend on one agent implementation.

Scope

Define:

• AgentAdapter contract;
• ExecutionSubstrate contract;
• worker capability model;
• launch/send/capture/interrupt/health behavior;
• readiness nonce requirements;
• adapter-specific prompt/report constraints;
• tmux/worktree/process ownership split;
• failure and timeout behavior.

Non-goals

• No adapter implementation in this slice.
• No remote/cloud runner protocol.
• No CLI-specific semantics in RunContract core.

Acceptance criteria

• AgentAdapter interface is specified.
• ExecutionSubstrate interface is specified.
• Worker capability matching rules are described.
• Readiness and health-check expectations are defined.
• Structured worker report contract is defined.
• Codex/Pi/Claude Code compatibility notes are documented.

Verification

• Design review against current worker substrate code.
• Example adapter matrix for Codex, Pi, and Claude Code.

[devkade]

Design decision

needs-design is resolved by #167's Development Order.

Decisions:

• Split the boundary into AgentAdapter and ExecutionSubstrate.
• AgentAdapter owns launch/send/capture/interrupt/report parsing semantics for Codex, Pi, Claude Code, and future agents.
• ExecutionSubstrate owns local execution mechanics such as tmux, process, native-subagent, and future substrates.
• Core runtime depends only on the contracts, never on CLI-specific behavior.
• MVP must include a fake adapter/substrate so Sub-roadmap: DAG runtime phase 3 — worker execution, heartbeat, and evidence-gated completion #196 can be tested without tmux or a real agent.
• Worker readiness requires an explicit readiness nonce or equivalent proof.
• Worker completion requires a structured report that can produce EvidenceRef records.

Implementation can proceed as Step 2 of #167. Remote/cloud runners remain out of scope.