Repository navigation
Add the hand-off channel: a witnessed work tree with MCP tools - #87
Merged
Merged
Conversation
Agents hand work to each other through adapters/work_tree.py, an event-sourced work tree that lives beside the POODO cores rather than inside one (a core is per-domain and single-caller, with no parent or completion API). Ported and reworked from the feat/assignment-runtime draft. - One node per hand-off. Lineage (owner|routine|outside, owner message id) is set at the root and copied unchanged to children. Modes are work|consult|notify, replies resume|poll|none, and artifacts are typed references checked against an optional host table. - A requester waits on its children and is woken once when all its replying children settle. An overdue child chases its requester once. Two idle continuations fail a node. Owner holds cancel a domain and refuse new work there. Owner answers are returned, never recorded. - Typed refusals: loop (back up the branch), depth, unreachable (host reachable map), root_full (default 4 open nodes per root), busy (one live node per bot), shields, not_yours, state, mode, artifact, held, unknown. - Append-only, flock'd JSONL log. Reopening rebuilds the same state, a torn tail is set aside, and an event out of order is refused. Every event is also appended to the session ledger (stream <bot>.handoff, the witnessed node log when configured). - The MCP server lists handoff_create/start/status/wait/settle/park/ answer only when <state_root>/handoff.json exists. The requester is stamped from the session. Holds, releases, sweeps and owner answers are host-only. Docs: CS-REQ-087, SDD-C29, matrix row, ADAPTERS.json row handoff-work-tree, hand-off tools section in server-and-adapters, regenerated data dictionary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in #84 (Foundations MCP server), #85 (cstack init) and #86 (starter agents). Conflicts in docs/architecture/architecture.md and docs/requirements/requirements.md resolved by keeping both sides: component rows in SDD order (C26, C28, C29, C31) and requirements CS-REQ-084 to CS-REQ-086 before CS-REQ-087. EXPORT-MANIFEST.json regenerated with tools/build_export_manifest.py; data dictionary --check passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Akilleez-QA
marked this pull request as ready for review
November 17, 2026 08:48
Akilleez-QA
pushed a commit
that referenced
this pull request
Nov 17, 2026
Brings in #84 to #87. Conflicts resolved by keeping both sides: CHANGELOG.md entries; requirements and verification-matrix revision rows renumbered so main's 2.2 (cstack init) stays and this PR's CS-REQ-088 row becomes 2.3, with each document's Version set to 2.3. EXPORT-MANIFEST.json regenerated with tools/build_export_manifest.py; data dictionary --check passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change
This PR adds Wave 2G, the hand-off channel.
adapters/work_tree.pyis an event-sourced work tree that agents use to pass work to each other. It is ported from the unreviewedfeat/assignment-runtimedraft and reworked. The tree lives beside the POODO cores, not inside one, because a core is per-domain and single-caller and has no parent or completion API.poodo_core/is unchanged.owner|routine|outsideplus the owner message id) is set at the root and copied unchanged to every child.work|consult|notify; replies areresume|poll|none.artifact_namestable.loop: no hand-off back up the branch.depth: depth cap.unreachable: the hostreachablemap inhandoff.jsondecides who a sender can hand off to.root_full: at most 4 open nodes per root by default.busy: one live node per bot.shields,not_yours,state,mode,artifact,held,unknown.LedgerPort, on stream<bot>.handoff. That is the witnessed node log whenledger.jsonexists. The work tree file stays the queryable store; the ledger is the witness. A missed witness is reported and can be detected withwitness_gaps.handoff_create,handoff_start,handoff_status,handoff_wait(non-blocking),handoff_settle,handoff_parkandhandoff_answer.<state_root>/handoff.jsonexists. There is a golden fixture for them.adapters/mcp_stdio_server.py(+39), following the existingMAIL_TOOLSpattern. A separate server would have duplicated the session and the transport.bootstrap.py(+13) and anaor_session.pyattribute plus close (+3).Requirements, design and interface impact
contracts/ADAPTERS.json: new rowhandoff-work-tree.docs/guides/explanation/server-and-adapters.md, plus a §4 mention in the SRS.MAX_TEXTandMAX_ARTIFACTS.Verification
All runs were local on macOS with Python 3.13, using a throwaway venv in a scratch dir. No model calls were made and the Anthropic credential environment variables were unset.
python -B -m unittest discover -s tests: 770 tests, 76 failures, 4 errors, 8 skipped. The baseline onorigin/main(0a9703b) is 734 tests, 76 failures, 4 errors, 8 skipped, and the failing set is identical by test id. Those are the known workcell/forge environment failures on macOS. The 36 new tests all pass.python -B -O -m unittest discover -s tests: same counts as the plain run.python -B tools/check_trace.py: 78 requirements, 0 failures.python -B tools/check_links.py: 0 broken links.python -B tools/gen_data_dictionary.py --check: passes after regeneration.tests/test_work_tree.pycovers:Not done
WorkTree, so a host must callsweep()itself to make chases fire.agents/artifacts.jsonsingle-writer table. Workstream A has not landed that table, so the host passesartifact_namesinhandoff.json.hard_wired(ADR 005 item 11c).Peer review record
🤖 Generated with Claude Code