PRD 0011: teach the herd the agent protocol — hooks-first state, a task ledger, and an A2A surface - #415
Merged
Merged
Conversation
The herd read paint instead of speaking protocol. Three symptoms, one cause: state came from regex against a screen capture, a prompt left no evidence it was ever submitted, and the roster stopped at the edge of the box. Phase 1 — believe the engine. `herd hooks install claude` writes Claude Code's own lifecycle hooks so state comes from the engine (`authority: hook`), merging into the user's settings file rather than clobbering it. Sessions are launched with MOSHCODE_HERD_NAME/DIR so a hook can name what it is reporting for, and a hook fired outside a herd session does nothing and exits 0. `herd doctor` checks substrate, manifest drift, stale reports, and — for the first time — says what is wrong with rules.json instead of ignoring it. blocked gains sub-kinds (permission/question/menu) that ride in --json and notifications. Phase 2 — the ledger. Every prompt mints a task: id, transitions with timestamps, and the output captured as a screen delta, in 0600 JSONL capped at 500 tasks per session. `herd tasks`, `herd task`, `herd log`, `herd stats` read it back; blocked time is reported as what it is, human latency. The write goes where the watcher's notification decision already happens, not in a second poller. `wait --any/--all` replaces the polling loop every fan-out script had. Phase 3 — the protocol. `herd serve` exposes the herd over A2A v0.3.0 (discovery, message/send, tasks/get, tasks/cancel) behind the moshcode login, with no unauthenticated mode, loopback included, and --agent sessions withheld unless --expose-autonomous. `herd remote add` puts a deployed agent on the roster — a2a or a bare POST endpoint — and prompt/read/wait/kill work on it unchanged, with auth from MOSHCODE_REMOTE_<NAME>_TOKEN and never in the manifest. Phase 4 — `herd eval` runs a dataset across engines with either the dataset's own patterns or an engine as judge, exiting 0/4/5 so CI can tell a worse agent from a broken box. gradient joins the tool table with its own runtime check. 119 new tests. Decisions taken while building are recorded at the end of the PRD rather than edited into its requirements. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ThreatCrush Security Scan3 finding(s) in the 24 file(s) this pull request changes. MEDIUM: 3
52 pre-existing finding(s) elsewhere in the repository — **HIGH/CRITICAL**: 5 | **MEDIUM**: 41 | **LOW**: 6Not introduced by this pull request. The full set is in the Security tab.
…and 32 more. Full results in the Security tab. Snippets are redacted; ThreatCrush never prints matched credential material. |
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
1 participant
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.
Implements PRD 0011, which is added in this branch.
PRD 0009 built the herd; three limits were the daily friction, and all three were the same one: the herd read paint instead of speaking protocol.
Phase 1 — believe the engine, not the paint
moshcode herd hooks install claude|all(remove,status,--dry-run,--json) writes Claude Code's own lifecycle hooks so state comes from the engine.psreadshookin its new last column instead ofscreen.removetakes out only what moshcode put in; a settings file that will not parse is refused rather than overwritten.moshcodeon PATH, it does nothing and exits 0. Screen rules stay as the fallback, so a broken hook degrades to today and never below it.MOSHCODE_HERD_NAME/MOSHCODE_HERD_DIRthrough the oneenvprefix both substrates share.herd doctorchecks substrate, manifest drift, stale reports, an unwritable status dir, and finally says what is wrong withrules.jsoninstead of ignoring it.blockedgains sub-kinds (permission/question/menu), in--jsonand in notifications so an--askreply can be aimed correctly.Phase 2 — the task ledger
0600JSONL, capped at 500 tasks per session.herd tasks,herd task <id>,herd log,herd statsread it back. Blocked time is reported as what it is — human latency.herd tasks,tasks/get) also closes a task whose session has stopped.wait --any/--all— one loop over all members, not N waits raced, so--anyreturns and exits. moshscript:herdWait([names], { any: true }),herdTasks(),herdTask().Phase 3 — the A2A surface
herd servespeaks A2A v0.3.0: herd card, per-member cards,message/send,tasks/get,tasks/cancel. Streaming and push notifications are declared off in the capability flags.console.mjs's token discipline reused, a loud warning past loopback, and--agentsessions withheld unless--expose-autonomous.herd remote add <name> <url> --kind a2a|runputs a deployed agent on the roster.prompt/read/wait/killwork unchanged on it — the acceptance test is a fan-out with noif (remote)in it. Auth comes fromMOSHCODE_REMOTE_<NAME>_TOKEN, never the manifest.Phase 4 — evals and the DO toolchain
herd eval --dataset --engines --judge --thresholdscores engines against your dataset, exiting0pass /4below threshold /5harness failure.evals/moshcode.jsonlplus a hand-written (not fleet-managed) workflow that turns itself on when a credential secret exists.gradientjoins the tool table with a Python 3.10+ check that names the requirement, plus screen rules and a template pointer.Verification
herd serveexercised against a fake A2A agent and a barePOSTendpoint: discover → send → get → cancel, including the 401 on every unauthenticated path.Deliberate deviations
Recorded at the end of the PRD under Decisions taken while building, not edited into its requirements. The two worth reading before review:
tasks/cancelinterrupts but stops one rung short of killing the member, and a closed task reportscompletedrather than inheriting the session'sidle— without that, an A2A client polls a finished job forever.Draft: the PRD is
status: Draftand these are its decisions to accept or send back.🤖 Generated with Claude Code