feat(cli): child handoff wiring — role/consumes, handoff_submit and the poll gate (#383, 2/3)

[ajianaz]

What

Part 2 of 3 of the child-agent handoff: the wiring. Builds on the schema and gate merged in #396. (The real-binary E2E test follows in part 3 to keep each Cora review under its limit.)

Why

#383. The schema alone changes nothing: a child must be able to submit a handoff, downstream children must be able to read artifacts by reference, and a failed or missing verification must not be closed silently.

Changes

• agents.rs agent_start: optional role (explore/implement/verify/fix) and consumes (artifact references, validated: workspace-relative paths, option-safe refs, at most 32). The child's mission is the requested prompt preceded by a role brief and followed by the artifacts to read, rendered with control characters escaped; with neither input the prompt is unchanged. The role is stored in meta.json; TOLE_AGENT_ROLE / TOLE_AGENT_HANDOFF are set for the child.
• handoff.rs: HandoffSubmitTool (child-side, Write-tier) validates the input and writes <agent dir>/handoff.json atomically; the role is fixed by the parent, never taken from the model. agent_start adds exactly this tool name to the child's allowlist: it can only write that one validated, bounded file, so it does not widen what the child may do. Role briefs and the "closed without a handoff" fix prompt.
• agent_poll: for a settled role child it adds role, gate (closed / unverified / verify_failed / no_handoff for ungated roles), the handoff and, whenever the work is not closed, a fix_prompt. A gated child that submitted nothing, or an invalid document, is unverified.
• tole-cli: handoff.rs registers handoff_submit only for a process that has both env vars and a parseable role; compiles in the bare profile.
• docs/child-agents-handoff.md, docs/threat-model.md, README, CHANGELOG.

Deliberate deviation from the issue text

The issue says a failed verify "spawns a fix child". Nothing is spawned automatically: agent_poll surfaces the failed gate with a ready-made fix_prompt and the parent decides to start the fix child. Auto-spawning would bypass the parent's approval, allowlist and budget, and the design's own anti-goal is no scheduler.

Testing

• 4 new agents unit tests with a dump-script child: role brief, artifacts, env, allowlist and meta.role; no role means no change (prompt, allowlist, env); bad role / bad or oversized consumes refused before anything is spawned; the poll gate matrix (none, no verification, failed, passed, invalid JSON, ungated roles, role-less agents). 3 submit-tool tests, 1 env-wiring test.
• fmt, clippy -D warnings, cargo test --workspace and cargo check --no-default-features pass; cora review --staged clean.
• The multi-child real-binary E2E (implement fails verification, the fix child reads the artifact by reference, a silent implement child is blocked) passes locally and lands in part 3.
• Not done: a live run with real agents on a real provider; feat(child-agents): typed handoff + mandatory verify gate for child agents #383 stays open for that.

Refs #383

[github-actions]

🔍 Cora AI Code Review

✅ No issues found. Code looks good!

---

Review powered by cora-code · BYOK · MIT