[KM-627] Canonical ToolSpec + ToolOutput

Move ToolSpec/ToolRegistry/ToolOutput to src/tools/contracts.py as the single
source of truth (owned by the tool team, KM-465). planner/contracts.py now
re-exports them so the planner/slow_path importers are unchanged; shapes are
identical to the prior stubs (zero field change).

Records the data-flow decision: Pattern A (analyze_* take data="${t<id>}"
placeholder, not self-fetch by source_id) and analyze_comparison.output_kind =
"stats", aligning with the planner registry.

Verified: imports OK, ruff + mypy strict clean, 72 analytics tests green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/agents/planner/contracts.py

@@ -1,32 +1,35 @@
-"""STUB contracts the planner consumes from other teams.
+"""Contracts the planner consumes from other teams.
 
-These models are LOCAL STUBS so the planner is buildable and testable now.
-They must be reconciled with their owners before integration:
+`BusinessContext` (+ KeyTerm / DataTableNote / DataColumnNote) is still a LOCAL
+STUB owned by the lead (interview / Business Understanding); shape mirrors
+AGENT_ARCHITECTURE_CONTEXT_new.md §7.1 and must be reconciled before integration.
 
-  - `BusinessContext` (+ KeyTerm / DataTableNote / DataColumnNote)
-      Owner: the lead (interview / Business Understanding).
-      Shape mirrors AGENT_ARCHITECTURE_CONTEXT_new.md §7.1.
-
-  - `ToolSpec` / `ToolRegistry`
-      Owner: the tool team (KM-608).
-      Shape mirrors §9.2. The concrete v1 P0 registry instance lives in
-      `registry.py`; this file only defines the contract types.
-
-  - `ToolOutput`
-      The tool -> agent output envelope (§8.1). Not produced by the planner
-      (tools return it at TaskRunner time); defined here so the planner layer
-      owns one definition of the contract it plans against.
-
-When the real modules land, delete the corresponding stub here and import from
-the shared location instead.
+`ToolSpec` / `ToolRegistry` / `ToolOutput` are NO LONGER defined here — the tool
+team owns them (KM-465). They now live in `src.tools.contracts` and are
+re-exported below so existing importers (`registry.py`, the slow-path
+`invoker.py` / `schemas.py`) keep working against one shared definition.
 """
 
 from __future__ import annotations
 
-from typing import Any, Literal
+from typing import Literal
 
 from pydantic import BaseModel, Field
 
+# Canonical tool contracts now owned by the tool team (KM-465). Re-exported here
+# for backwards-compatible imports; the definitions live in src.tools.contracts.
+from src.tools.contracts import ToolOutput, ToolRegistry, ToolSpec
+
+__all__ = [
+    "KeyTerm",
+    "DataTableNote",
+    "DataColumnNote",
+    "BusinessContext",
+    "ToolSpec",
+    "ToolRegistry",
+    "ToolOutput",
+]
+
 # --------------------------------------------------------------------------- #
 # BusinessContext (lead's contract — §7.1)
 # --------------------------------------------------------------------------- #
@@ -60,45 +63,3 @@ class BusinessContext(BaseModel):
     recent_events: str = ""
     things_to_watch_for: str = ""
     open_questions: list[str] = Field(default_factory=list)
-
-
-# --------------------------------------------------------------------------- #
-# Tool registry (tool team's contract — §9.2)
-# --------------------------------------------------------------------------- #
-
-
-class ToolSpec(BaseModel):
-    name: str
-    category: str  # analytics.query | .aggregation | .timeseries | ...
-    input_schema: dict[str, Any]  # validates ToolCall.args
-    output_kind: str  # the ToolOutput.kind it returns
-    description: str  # prompt-style: what it does, edge cases, what NOT to use it for
-    phase: Literal["P0", "P1", "P2"] = "P0"
-
-
-class ToolRegistry(BaseModel):
-    tools: list[ToolSpec] = Field(default_factory=list)
-
-    def names(self) -> set[str]:
-        return {t.name for t in self.tools}
-
-    def get(self, name: str) -> ToolSpec | None:
-        for t in self.tools:
-            if t.name == name:
-                return t
-        return None
-
-
-# --------------------------------------------------------------------------- #
-# Tool output envelope (tool -> agent contract — §8.1)
-# --------------------------------------------------------------------------- #
-
-
-class ToolOutput(BaseModel):
-    tool: str
-    kind: Literal["scalar", "table", "stats", "series", "documents", "error"]
-    value: Any | None = None
-    columns: list[str] | None = None
-    rows: list[list[Any]] | None = None
-    meta: dict[str, Any] = Field(default_factory=dict)
-    error: str | None = None

src/tools/contracts.py

@@ -0,0 +1,70 @@
+"""Canonical tool contracts (KM-465 — owned by the tool team).
+
+These are the single source of truth for the tool <-> agent interface:
+
+  - `ToolSpec` / `ToolRegistry` — the registry contract (§9.2). The concrete v1
+    analytics registry instance is built on top of these.
+  - `ToolOutput` — the tool -> agent output envelope (§8.1). Tools return this at
+    TaskRunner time; the agent layer plans and degrades against it.
+
+Ownership note (2026-06-08): the tool team owns these definitions outright; the
+agent team's earlier copies in `src/agents/planner/contracts.py` are now thin
+re-exports of this module so there is exactly ONE definition across the codebase.
+The shapes here are kept byte-for-byte identical to those original stubs so the
+already-landed planner / TaskRunner / Assembler keep working unchanged.
+
+Data-flow decision (KM-465, agreed with the agent team): the analytics tools use
+**Pattern A** — `analyze_*` tools do NOT self-fetch by `source_id`; each takes a
+`data` argument that is a `"${t<id>}"` placeholder resolved to a DataFrame at
+execution time. `analyze_comparison.output_kind` is `"stats"` (a labelled-metric
+dict), aligning with the planner registry.
+
+See AGENT_ARCHITECTURE_CONTEXT_new.md §8.1 / §9.2.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+# --------------------------------------------------------------------------- #
+# Tool registry (§9.2)
+# --------------------------------------------------------------------------- #
+
+
+class ToolSpec(BaseModel):
+    name: str
+    category: str  # analytics.query | .aggregation | .timeseries | ...
+    input_schema: dict[str, Any]  # validates ToolCall.args
+    output_kind: str  # the ToolOutput.kind it returns
+    description: str  # prompt-style: what it does, edge cases, what NOT to use it for
+    phase: Literal["P0", "P1", "P2"] = "P0"
+
+
+class ToolRegistry(BaseModel):
+    tools: list[ToolSpec] = Field(default_factory=list)
+
+    def names(self) -> set[str]:
+        return {t.name for t in self.tools}
+
+    def get(self, name: str) -> ToolSpec | None:
+        for t in self.tools:
+            if t.name == name:
+                return t
+        return None
+
+
+# --------------------------------------------------------------------------- #
+# Tool output envelope (§8.1)
+# --------------------------------------------------------------------------- #
+
+
+class ToolOutput(BaseModel):
+    tool: str
+    kind: Literal["scalar", "table", "stats", "series", "documents", "error"]
+    value: Any | None = None
+    columns: list[str] | None = None
+    rows: list[list[Any]] | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None