Ship a versioned agent contract over the shared tool service

[e54-bot]

Readiness: ready-for-implementation for the contract decisions below. Sequencing: after the OPY × workshop-rs real-project validation (OWBastion/Bastion#214, wrightkit/opy-rs#319) and the workshop-rs 1.0 candidate (wrightkit/workshop-rs#252).

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 it over stdio and JSON-RPC 2.0 ([M9] Add thin transport adapters for structured tool consumers #60, Make wright-serve JSON-RPC responses match the declared JSON-RPC 2.0 contract #357), but the release workflow builds and distributes only wright and wright-lsp, so agents cannot rely on it.
• wrightkit/workshop-agent tools pin Wright 0.1.0, implement find_symbol / find_references with rg/grep, and fall back to upstream OverPy; the curated skills live outside Wright's domain-intelligence contract (ADR-0017).
• The goal requires structured, deterministic agent access to semantic analysis, diagnostics, queries, and validated edits, without Wright becoming a generic agent framework.

Decisions (settled)

1. One contract. The ToolService request/response model is the single 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: existing CLI --format json. Session: wright serve (stdio / JSON-RPC 2.0) shipped in every release archive and package channel. MCP: a thin adapter over the same contract, owned and released by Wright.
3. workshop-agent role. Skills, installation, and version pinning only. Its deterministic tools become thin callers of the Wright contract; textual symbol/reference tools are retired; the OverPy path remains only as an explicit, labeled compatibility route.

Scope

• Declare the versioned agent contract (operations, request/response schemas, error model, capability negotiation) under docs/.
• Ship wright serve in release artifacts and installers.
• Provide the MCP adapter as a transport over the same service.
• Keep source-language results truthful: until the source-mapping contract (Decide the canonical source-mapping contract across the provider boundary workshop-rs#271) lands, OPY-derived Workshop evidence stays explicitly unmapped.

Non-goals

• New analysis, lint rules, or domain-intelligence content.
• A generic agent framework, planner, or model integration.
• Implementing OPY source mapping (tracked by Decide the canonical source-mapping contract across the provider boundary workshop-rs#271).
• Changing workshop-agent in this issue (follow-up in that repository).

Acceptance criteria

• The contract document lists every supported operation with schema and version; the CLI JSON, wright serve, and MCP transports return identical results for the same request (tested).
• Release archives and supported package channels install wright serve; the installer smoke test exercises it.
• An agent can, for a raw Workshop project, query findings, validate an edit transaction, and re-check through one session without reading terminal text.
• For an OPY project, results distinguish owner diagnostics from Wright findings and mark unmapped evidence explicitly.
• Contract changes are gated like wright-result/v1 (breaking change requires a new contract version).

Dependencies / ownership

• Owner: Wright.
• Depends on: Freeze the workshop-rs public API for 1.0 workshop-rs#252 (1.0 API), ci: integrate Wright real-project validation OWBastion/Bastion#214 and Converge Bastion compilation structurally on pinned OverPy opy-rs#319 (sequencing, not a technical block for raw Workshop).
• 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).
• Follow-ups: workshop-agent migration to the contract; .github routing table entry for workshop-agent / agent-lab ownership.