feat(core): child-agent handoff schema, validation and verify gate (#383, 1/2)

[ajianaz]

What

Part 1 of 2 of the child-agent handoff: the typed document, its validation and the close gate. The child-side tool and the agent_poll enforcement follow in part 2.

Why

#383. A child's result reaches other agents only as the parent's retelling, and a child can finish without anyone checking its work.

Changes

• handoff.rs (new, ungated so embedders have it): Handoff { version, role, summary, artifacts, verify }; roles explore / implement / verify / fix; artifacts are references (workspace-relative path plus optional rev), read by downstream children themselves rather than relayed by the parent.
• Strict validation for model-authored input: unknown fields and roles are errors; all fields bounded; a path must be workspace-relative with no .., backslash, control characters or leading -; a rev must be a plain commit/ref name (alphanumeric start, safe charset, no ..), so neither can be parsed as an option or escape the workspace.
• Handoff::gate(): an implement/fix child without passing verification is Unverified / VerifyFailed, never closed silently. fix_prompt() builds the follow-up fix child's prompt from references and bounded evidence; text rendered for another model escapes control characters.
• docs/child-agents-handoff.md: design, role table, gate semantics, limits (verification evidence is self-reported), and the explicit anti-goal: no DAG scheduler or dependency engine, nothing is spawned automatically. README doc link, CHANGELOG.

Testing

• 6 unit tests: roundtrip and strictness, bad path/rev matrix (incl. option-looking refs), size bounds, the gate, the fix prompt by reference, no line break-out from model text.
• fmt, clippy -D warnings, cargo test --workspace and cargo check --no-default-features pass; cora review --staged clean.
• Not done: the multi-child integration and live E2E from the issue; they need part 2.

Refs #383

[github-actions]

🔍 Cora AI Code Review

✅ No issues found. Code looks good!

---

Review powered by cora-code · BYOK · MIT