Expose Wright semantic capabilities as native coding-agent tools

[Teakowa]

Goal

Expose Wright's existing structured agent capabilities as native coding-agent tools, so an agent can invoke semantic operations directly instead of routing every request through shell commands and JSON stdout.

The initial outcome is a reviewed architecture for this tool surface and a bounded implementation plan. Do not introduce a second semantic API: native tools must adapt the existing wright-agent/v1 / ToolService contract.

Context

Wright already has a stable structured agent backend:

• ToolService is the executable operation layer.
• wright-agent/v1 defines versioned requests and responses.
• wright serve exposes the contract over newline-delimited JSON and JSON-RPC.
• Existing operations include semantic queries, lint/findings, cost, call graph, diagnostics, and validated edits.

Today a coding agent can use these capabilities through shell + JSON or by implementing a client for the session protocol. That still leaves an avoidable integration gap: harnesses that support native tools should be able to discover and invoke Wright operations directly as structured tool calls.

This is particularly relevant to the agent-efficiency work: semantic queries should replace unnecessary grep/search/read work, while source reads remain the final mile for judgment and modification.

Scope

• Define the native coding-agent tool surface over the existing Wright agent contract.
• Determine the appropriate transport/adapter boundary for common harnesses; MCP is a candidate, not a pre-decided architecture requirement.
• Define how tool discovery maps from capabilities.operations.
• Define tool names, descriptions, input schemas, structured results, refusals/errors, and session/project lifecycle.
• Identify the smallest high-value initial tool set for agent workflows, with semantic navigation and validation prioritized over exhaustive exposure.
• Preserve the same operation semantics across CLI, wright serve, embedding, and native-tool surfaces.
• Add verification that native-tool calls and direct ToolService calls are behaviorally equivalent for exposed operations.
• Extend the agent benchmark so the native-tool condition can be compared with shell/JSON usage for task success and search/read/tool-call efficiency.

Design constraints

• ToolService / wright-agent/v1 remain the semantic authority for Wright-owned agent operations.
• The adapter must not reimplement symbols, references, lint, cost, rename, provider behavior, or other language/tooling semantics.
• Do not add Wright-only source-language semantics to make a tool easier to expose.
• Do not require every wright-agent/v1 operation to become a native tool in the first version.
• Prefer a thin adapter that can be removed or replaced without changing the underlying agent contract.
• Unsupported provider capabilities and semantic refusals must remain explicit; no textual or grep-based fallback belongs in the adapter.

Architecture questions

Resolve before implementation:

1. Which transport should be the first native-tool integration: MCP, harness-specific adapters, or another thin mapping?
2. Should Wright expose one generic request tool or multiple operation-specific tools? Evaluate tool discoverability, schema quality, model selection cost, and compatibility with the existing contract.
3. Which operations form the minimum useful initial set for semantic navigation and validated work?
4. How should project/session startup and lifetime map onto stateless-looking tool calls?
5. How should capability negotiation hide unsupported tools or represent dynamic provider capabilities?
6. What result shapes can be passed through unchanged, and where is a presentation-only wrapper justified?
7. How should native-tool use be measured against shell + JSON in the existing agent benchmark?

Non-goals

• Designing a new agent framework, planner, or model runtime.
• Replacing wright-agent/v1.
• Creating a parallel semantic contract specifically for MCP or one vendor.
• Reimplementing language semantics in the adapter.
• Exposing every existing operation before benchmark or workflow evidence shows it is useful.
• Changing OPY, DEL/OSTW, or Workshop ownership as part of this issue.
• Solving the broader provider/upstream architecture reevaluation in this task.

Acceptance criteria

• A reviewed architecture defines the native-tool adapter boundary without duplicating ToolService semantics.
• The first transport/integration target is chosen with rationale and alternatives recorded.
• A minimum initial tool set is defined from real agent workflows rather than mirroring every operation mechanically.
• Tool schemas, capability discovery, session lifecycle, structured errors/refusals, and provider capability behavior are specified.
• The design defines behavioral-equivalence tests against direct ToolService / wright-agent/v1 requests.
• The benchmark plan compares native tools with the existing shell/JSON path using task outcome plus search/read/tool-call/token metrics.
• Implementation work can proceed without changing the meaning of existing CLI, session, or embedding operations.

Dependencies / ownership

• Owner: Wright for agent-facing product surfaces, ToolService, and native-tool integration.
• Existing contract: wright-agent/v1 and its committed schema.
• Language semantics remain owned by their language implementations/providers.
• Related: Roadmap to v1.0: stable Workshop tooling platform #134 (Wright 1.0 roadmap), Add a first-party agent guide installer #415 (agent guide), Establish a product-level coding-agent benchmark for Workshop workflows #414/Establish a Wright effectiveness benchmark against docs and skills #466 (agent benchmark/effectiveness work).

This issue intentionally stops at the architecture boundary first. Implementation details should follow the approved design rather than being inferred from a preferred transport.