Repository navigation
[Project Proposal] Weft Coordination Protocol (WCP) and Agent Hooks Core #53
Description
Project Name
Weft Coordination Protocol (WCP) and Agent Hooks Core
Project Description
What it does. Many coding agents now edit the same codebase at the same time, and today they find out they collided only at merge time. WCP moves coordination to edit time: every agent harness already has pre/post tool-call hooks, so each edit an agent makes is sent through a hook to a per-repository coordinator that keeps one strictly ordered event log. The coordinator answers each edit with diagnostics, like the red squiggles a human sees in an editor: "src/cart.ts#calcTotal changed on trunk 4 seconds ago by agent-a; update this call site." The agent sees the warning mid-run and adapts before it finishes, instead of producing a conflict for a human to untangle later.
The proposal has two layers, deliberately separated:
- Agent Hooks Core v0.1 (docs/protocol/hooks-core-v0.md): a small, vendor-neutral interoperability layer for coding-agent hooks. Common envelopes for tool-call events, allow/deny/ask decisions and diagnostics, plus a capability declaration so a hook knows what each host can actually do. Codecs map it to the native hook formats of Claude Code, Codex, Cursor, Gemini CLI and OpenCode. A conformance runner (
wcp-hook-conformance) with fixtures and published reports for five adapters ships with it. This layer needs no coordinator, network or vendor. - WCP v0 (docs/protocol/wcp-v0.md): a coordination extension on top of the core. It adds an ordered per-repo log with deterministic replay, read/write sets at symbol level, claims (soft/firm, short leases), arbitration in which exactly one party receives the error, and stop/commit gates so an agent cannot finish with open conflicts.
Why it is valuable. Hooks are the one integration point every major harness has converged on, but each defines them differently, and Agent Plugins 1.0 left hooks out. A common hook core makes guardrails, policy, observability and coordination portable across harnesses. Security WG issues aaif/wg-security-and-privacy#30 and #31 make the same argument from the security side: enforcement belongs at the in-loop pre-execution hook.
Origin and history. Started 2026-10-03 as an entry to Cloudflare's "next Git platform" competition (submitted). The reference implementation runs on Cloudflare Workers, Durable Objects and Artifacts, but the protocol is transport- and vendor-neutral. It has been dogfooded since day one: Weft was built by many concurrent agents coordinated by Weft itself. The live demo ran 18 agents (Claude Code, Codex, OpenCode) on one repo, and the maintainer's own agent fleet across about 95 repos reports to it. Demo video: https://weft-media.elier.ai/weft-demo.mp4
Alignment with AAIF Mission
AAIF exists to build open, neutral, interoperable infrastructure for agentic AI. Agents working together on shared state is the next interoperability problem after tools (MCP), instructions (AGENTS.md) and agent-to-agent messaging (A2A). WCP is a neutral protocol for that, and the Hooks Core is a neutral foundation that other projects (policy engines, security guardrails, observability) can build on without picking a vendor.
Relation to Existing AAIF Projects
- MCP: complementary. MCP standardizes how agents reach tools; the Hooks Core standardizes how a host lets a third party observe and gate those tool calls. MCP tool calls are covered by the same hook envelopes.
- AGENTS.md: WCP agents receive their coordination rules through AGENTS.md-style context, and the reference repo uses AGENTS.md.
- Agent Skills / Agent Plugins: the Hooks Core fills the hooks gap those formats leave open; a plugin could declare hooks in this format.
- A2A: A2A lets agents talk to each other. WCP coordinates agents that never talk to each other but edit the same thing, through a shared ordered log.
- Workflows & Process Integration WG: directly relevant to its multi-agent reference architecture work ([RA] draft first multi-agent RA proposal wg-workflows-and-process-integration#55, parallel agents then merge). WCP covers the "during the run" part of that problem.
Example Use Cases and Evidence of Adoption
Use cases: several coding agents (any mix of harnesses) working on one repository at once; agent fleets doing large refactors in parallel; portable policy hooks (deny or ask on dangerous calls) written once for every harness.
Adoption, stated honestly: this is early. It is used in production by its maintainer (8 agent profiles and about 95 repositories coordinated through it daily). Outside signal after one week public: 30 stars, 2 forks, an outside contributor with 4 open PRs and 17 issues, and the CTO of a YC company planning to integrate it with his own agent tooling. There are no independent production deployments yet. We know this is below the bar and are filing now to get on record and to learn exactly what the TC needs to see first.
Technical Committee Sponsor (if identified)
None yet. We'd welcome one.
GitHub Repository URL
https://github.com/celador/weft
License
MIT
Governance Model
Currently a single-maintainer project (BDFL) by John Nelson. Decisions are made in public GitHub issues and PRs. Protocol changes must update the spec first (CONTRIBUTING.md). We intend to adopt LF Minimum Viable Governance, add a GOVERNANCE.md, and add a second maintainer from another organization.
CI/CD & Release Workflow
GitHub Actions (.github/workflows/ci.yml) runs the full gate (pnpm -r typecheck && pnpm -r test, TypeScript strict and vitest including the Workers runtime pool) on every push and PR. Fork PRs need maintainer approval before CI runs. The reference gateway deploys to Cloudflare from main after the gate passes. There are no tagged releases yet; the first tagged spec release (v0.1 of the Hooks Core, v0 of WCP) is planned with the roadmap below.
Public-Facing Contribution Process for Specifications
https://github.com/celador/weft/blob/main/CONTRIBUTING.md. Spec-first: any change to the protocol, journal, diagnostics or agent-facing text updates the spec and explains why; replay must stay deterministic. Every PR needs a test that fails on main, a before/after recording, and security notes. The PR template enforces this. Discussion happens in GitHub Issues and Discussions.
Publicly Accessible Issue Tracker
https://github.com/celador/weft/issues
External Project Dependencies
- TypeScript (Apache-2.0), esbuild (MIT), @cloudflare/puppeteer (Apache-2.0); dev: vitest (MIT), wrangler and @cloudflare/workers-types (MIT OR Apache-2.0), @cloudflare/vitest-pool-workers (MIT)
- Optional: Mergiraf (GPL-3.0), invoked as a separate binary for structural merge in the sandbox; not linked.
- The reference implementation uses Cloudflare Workers/Durable Objects/Artifacts. The specs don't depend on Cloudflare.
Maintainers & Contributors
- John Nelson (@celador), independent (Elier). Sole maintainer.
- Outside contributors: @barnessomer (PRs under review).
We do not yet meet the 2-maintainer / 10-contributor bar.
Leadership Team & Decision Process
John Nelson leads. Decisions are made through public issues and PRs; spec changes require an issue and a spec diff first. We will move to a multi-maintainer, lazy-consensus model once a second maintainer joins.
Roadmap
Next 12 months:
- Q4 2026: tag Hooks Core v0.1 and WCP v0; short heartbeat-renewed claim leases (in progress); a GOVERNANCE.md; an OpenSSF Best Practices badge; working-group engagement (Workflows, Security).
- Q1 2027: a second independent implementation of the Hooks Core (target: a non-Cloudflare coordinator); the first outside organization in production; a second maintainer from another org; native hook adapters upstreamed or accepted by at least one harness.
- Q2–Q3 2027: Hooks Core v1.0 candidate with conformance tests run by several hosts; WCP v1 with multi-repo coordination and observer roles.
Security
SECURITY.md with GitHub private vulnerability reporting. Untrusted contributions are reviewed statically and never run on maintainer machines outside a sandbox; fork CI requires approval and workflows default to read-only tokens. Agent tokens are scoped (agent / observer / admin). The protocol threat model covers claim abuse (bounded leases), conflict bypass, and config discovery. No OpenSSF badge yet.
Website URL
Documented Governance Practices (if any)
CONTRIBUTING.md, SECURITY.md and AGENTS.md in the repo. GOVERNANCE.md to follow.
Links to Social Media Accounts
None yet.
Trademark and accounts
- If the project is accepted, I agree to donate all project trademarks and accounts to the AAIF.
Details of Existing Financial Sponsorship
None.
Infrastructure Needs or Requests
None today. Later: CI capacity for cross-harness conformance runs.
Additional Information
We expect "too early" today, and we're filing now on purpose: to put the Hooks Core and WCP on record and get the TC's concrete list of what to reach first. Requested stage: whichever entry stage the TC considers right (Sandbox if available, otherwise Growth). We'll report progress against that list in this issue and happily present to the TC or the Workflows WG at any time.
Application contact name(s) and email(s)
John Nelson, john.aaron.nelson@gmail.com
Contributing or sponsoring entity signatory information
Individual:
| Name | Country | Email address |
|---|---|---|
| John Nelson | United States | john.aaron.nelson@gmail.com |
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
docs: GOVERNANCE (MVG-based), MAINTAINERS, public ROADMAP for AAIF pr…
barka-bee commentedon Oct 12, 2026
A note on the evidence, since the proposal cites the Security WG issues aaif/wg-security-and-privacy#30 and aaif/wg-security-and-privacy#31. I opened both. They argue for enforcement at the runtime hook, and aaif/wg-security-and-privacy#31 names the OWASP Agent Control Standard (ACS) as the open wire format for hook decisions.
For the TC's view of related work: the Hooks Core layer overlaps with the Instrument pillar of ACS. ACS defines a JSON-RPC 2.0 envelope for hook events across the run (specification, hook taxonomy), five decisions (allow, deny, modify, ask, defer), conformance profiles the host declares at the handshake, and host shims for Claude Code and OpenCode, with Cursor and NAT adapters in an GenAI-Security-Project/agent-control-standard#22. The WCP coordination layer, the ordered per-repo log, claims and gates, is outside the scope of ACS and is the new part of this proposal.
A codec from the Hooks Core envelope to the ACS envelope, or the Codex and Gemini CLI adapters contributed upstream, would give WCP a standard hook layer and give ACS two more hosts. @celador I am glad to work on either with you.
Disclosure: I co-lead the ACS project under OWASP, listed as @bar-capsule in the ACS roster, and I work at Capsule Security, an AAIF member.
celador commentedon Oct 13, 2026
@bar-capsule thank you, that's a fair and useful read, and I agree with it: the coordination layer (ordered per-repo log, claims, gates) is the new part, and the hook layer should converge with ACS rather than compete with it.
Yes to working together. I'd start with the codec from the Hooks Core envelope to the ACS Instrument envelope (JSON-RPC 2.0, the five decisions, host profiles at the handshake), so WCP rides on ACS for the hook layer. The Codex and Gemini CLI adapters upstreamed as ACS hosts after that. I've opened nothing yet, so propose wherever suits you; an issue on celador/weft or on the ACS repo both work for me.
For the TC: we'll update the proposal to position WCP as a coordination extension on top of a standard hook layer (ACS), and keep the Hooks Core only as the mapping.
maniksurtani commentedon Nov 2, 2026
Hi @celador, thanks for your submission.
We've reviewed it against the AAIF Project Lifecycle Policy and are declining it for now. Building the hook layer on the OWASP Agent Control Standard, as you said you would, is the right call.
Further, the Workflows and Security working groups are a good place to keep building this in the meantime, discuss there, etc.