Ship a versioned agent contract over the shared tool service

[e54-bot]

Goal

Ship one versioned, deterministic agent contract so coding agents use Wright's semantic services (diagnostics, queries, cost, validated edits) as a released product surface instead of scraping CLI text, reimplementing parsers, or falling back to textual search.

Context

• wright_driver::service::ToolService already implements capabilities, project, rules, symbols, references, usage, CFG, findings, persistent objects, lint, lint rules, call graph, cost estimate, target metadata, validate edit, semantic rename, and provider rename/edit validation.
• wright-serve exposes the shared service over stdio and JSON-RPC 2.0, but the released agent surface must be explicit and stable before external agents can depend on it.
• The separate wrightkit/skills repository is only an optional distributable guidance layer. It must not carry independent semantic tools, fallback/version machinery, or a second Workshop knowledge system.
• The goal requires structured, deterministic agent access to semantic analysis, diagnostics, queries, and validated edits without Wright becoming a generic agent framework.

Decisions

1. One contract. The ToolService request/response model is the single executable agent contract, versioned like wright-result/v1 and negotiated through capabilities. CLI JSON, wright serve, and any MCP adapter are transports over it and must not add or alter semantics.
2. Transports. One-shot workflows use CLI structured output. Session workflows use wright serve over stdio / JSON-RPC 2.0. MCP, when shipped, is a thin Wright-owned adapter over the same contract.
3. Agent guidance is not another runtime. wrightkit/skills may distribute one optional Wright capability guide. It does not own deterministic tools, semantic fallbacks, backend/version pinning, reference routing, or source-language semantics.
4. Installation is a Wright product surface. A first-party Wright command installs the canonical guide for users who want agent-specific guidance; manual installation remains possible. The guide teaches capability discovery and correct use of Wright rather than hardcoding a parallel command/semantic contract.

Scope

• Declare the versioned agent contract (operations, request/response schemas, error model, capability negotiation) under docs/.
• Ship wright serve in release artifacts and supported install paths.
• Provide the MCP adapter as a transport over the same service when that transport is part of the supported product surface.
• Keep source-language results truthful; unavailable source mapping or owner capability must be represented explicitly rather than guessed.
• Keep the agent contract reusable by CLI, embedding, agent guidance, and benchmark consumers.

Non-goals

• New analysis, lint rules, or domain-intelligence content.
• A generic agent framework, planner, or model integration.
• Maintaining separate semantic/tool implementations in wrightkit/skills.
• Making a Workshop-specific prompt or skill pack required for Wright correctness.

Acceptance criteria

• The contract document lists every supported operation with schema and version; supported transports return equivalent service results for the same request.
• Released session tooling is installed and smoke-tested through supported distribution paths.
• An agent can query findings, validate an edit transaction, and re-check through the structured Wright surface without reading terminal prose.
• Source-language owner diagnostics, Wright findings, source mapping, and unsupported capabilities remain distinguishable.
• Contract changes are gated like wright-result/v1; breaking changes require a new contract version.
• The optional guidance layer can be removed entirely without changing Wright semantic behavior.

Dependencies / ownership

• Owner: Wright.
• Related: Avoid rebuilding full semantic analysis state for repeated ToolService queries #356 (session query performance), ADR-0017 / Define the Wright domain-intelligence contract for agent workflows #323 (domain intelligence), Decide the canonical source-mapping contract across the provider boundary workshop-rs#271 (source mapping), Establish a product-level coding-agent benchmark for Workshop workflows #414 (agent benchmark), Add a first-party agent guide installer #415 (agent guide installer), and the wrightkit/skills repository simplification.
• Language semantics remain owned by workshop-rs, opy-rs, and deltin-rs.