docs(adr): 0002 — Tool contract (v1)

[EmersonBraun]

Summary

Second ADR of Phase 0 — formalizes the Tool contract implicit in packages/core/src/types/tool.ts and packages/tools/src/*.

Builds on ADR 0001 (Adapter).

What's included

• docs/architecture/adrs/0002-tool-contract.md — 3 core types, 12 invariants (T1-T12), stability tier stable, rationale, trade-offs, alternatives considered, open questions.
• ADR index updated.

Why now

Before Fase 3 adds dozens of tools (GitHub, Linear, Slack, Google Workspace, Stripe, Supabase, browser, etc.) and before the MCP bridge (#167) publishes/consumes tools across ecosystems, we need a contract that:

• Aligns cleanly with MCP spec (execute-optional tools)
• Supports static discovery, bundling, and a future marketplace
• Makes schema-first type inference ([F1] #17 — Honest comparison vs competitors #130) sound
• Makes human-in-the-loop ([F2] #45 — Human-in-the-loop primitives #158) trustworthy (no timeout auto-approve)

Key invariants (the important ones)

• T1 Name is identity — strict regex, unique within registry
• T2 Schema is the contract — JSON Schema 7, authoritative for inputs
• T3 Validate at boundary — runtime validates before calling execute
• T4 Execute optional — declaration-only tools are first-class (MCP-friendly)
• T6 AsyncIterable streaming — mirrors Adapter contract for progressive tools
• T9 Confirmation explicit — no timeout auto-approve; security-critical
• T10 No side effects at definition time — enables static discovery and tree-shaking

Trade-offs made explicit

• JSON-only arguments (T5) — Buffer/Date must be serialized; matches wire format
• No per-invocation auth in v1 — deferred to future ADR if strong case emerges
• Typed return values via generics deferred — a future ADR will add ToolDefinition<TArgs, TResult>

Unlocks

• MCP bridge ([F3] #54 — Bidirectional MCP bridge #167) as thin mapping
• Tool composer ([F3] #55 — Tool composer (chaining) #168) — macro tools as ToolDefinitions
• Self-debug tool ([F3] #64 — Memory adapters (pgvector, Pinecone, Qdrant, etc.) #177) — agent retrying tool calls with the schema as ground truth
• Tool sandbox ([F2] #50 — Rate limiting by user/IP/key #163) — wraps execute, leaves schema/init/dispose alone

Test plan

• Doc renders on GitHub
• ADR index updated
• No code changes — pure documentation
• Reviewer: T1-T12 match current tools in packages/tools/src/?
• Reviewer: any invariant that blocks a real use case?

Refs #214 #211