tai/research/cap-protocol/cap-core-v1.md

CAP Core v1 specification

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	CAP CLI Agent Protocol (Core v1)
Source URL	https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/cap-v1.md
Source type	specification
Source date (published)	2026-05-18 (draft, public review)
Date researched	2026-10-18
Researched by	tai (agent), model: Muse Spark, on behalf of retoor
Research method	direct raw-file fetch, read in full (1036 lines)
Confidence	High
Status	Active

Summary

The normative core: PTY is the REQUIRED universal binding, four OPTIONAL fast-paths (stream-json, gRPC, ACP-stdio, A2A), 14 core event kinds, 3 core reverse-RPC methods, a lifecycle starting with cap.session.config then cap.session.ready, first-class multi-agent orchestration (§10), A2A interop both directions (§11), and a dual numeric/string error registry (§14.2).

Key findings

• Agent conformance = CLI-invokable + publishes Manifest + matches one binding contract; orchestrator conformance = reads manifests + PTY binding + §10 semantics + required reverse RPC.

• Manifest resolution order: in-package, user-local (~/.config/cap/agents/), system-wide (/usr/share/cap-agents/), --cap-manifest probe.

• Parse regexes use a POSIX ERE subset (no backrefs/lookaround); drivers MUST reject richer patterns. Note: the spec's own examples use (?P<tool>...) named groups, which are NOT in that subset.

• PTY details: ANSI/VT100 screen buffer, regexes against rendered text on line boundaries, idle = idle-regex on last line + 200ms silence, bracketed paste over 1KB, cancel graceful/hard/none, 10k scrollback SHOULD, pty_died error on unexpected exit.

• Orchestration: cap:// URNs, master plan with _meta.cap.assigned_to, no direct sub-agent contact (all mediated + audited), git worktrees SHOULD, orchestrator MUST aggregate usage and hard-cancel over budget, cooperative interruption pattern (cancel + preserve + resend).

• Reverse RPC has no defined wire encoding for stream-json/gRPC bindings; only the ACP binding gives it a native transport (JSON-RPC methods).

• Error registry: -32001..-32010 with string twins; cap.error string codes include rate_limit, pty_died, parse_failed, context_overflow.

• (added 2026-10-25, re-read for model handling) cap.session.config carries a model field (example claude-opus-4-7, allowed values undefined) and budget_usd; the driver applies model before spawning or after a binding-specific handshake (section 3.3). The manifest's only model field is startup.model_arg; there is no models list and no effort field.

• (added 2026-10-25) No method or event switches models mid-session and the spec defines no model-selection or routing strategy. cap.usage reports model_id, token counts and cost_usd_estimate; the orchestrator MUST aggregate usage and enforce budgets by cap.cancel ('Sub-agents MUST NOT be trusted to self-enforce budget', section 10.5). Errors: model_unavailable, -32004 cap_budget_exceeded.

Pros / strengths

• Complete contract in one file: events, lifecycle, orchestration, errors, and informative binding mappings (C.1-C.4) sufficient to implement drivers without guessing.
• PTY-required/fast-path-optional layering matches tai's stdlib-only reality: full conformance is reachable without gRPC or any dependency.
• The §10 orchestration semantics (URNs, mediated routing, budget aggregation) map directly onto tai's existing subagent + scheduler machinery.

Cons / limitations / caveats

• Draft status with real drift risk: A2A method names in §6.5/C.4 (message/send, tasks/cancel) do not match current A2A (PascalCase / colon-REST); see the naming-drift conclusion.
• Self-contradiction on regex flavor (§5.4 ERE-only vs (?P<>) in §5.1 examples); tai must decide what to accept.
• Reverse RPC over stream-json is unspecified, so tai-as-agent cannot offer fs/terminal mediation on its speak path without inventing framing.
• No conformance test suite ships with the spec; interop is validated against the reference Rust implementation only.

Relevance to tai

The build blueprint for both directions: tai-as-agent implements §3.1 via --cap-manifest + stream-json speak; tai-as-orchestrator implements §3.2 minus gRPC. The §7 event table and §14.2 error table become cap.md drift tables.

Changelog

Date	Change
2026-10-18	Initial dossier created.
2026-10-25	Forward correction: model-handling findings added from a re-read; the earlier note on routing strategies (static, llm, hybrid) comes from the quickstart, not from this document.