# ADR-0012: Capability-Based Tool Contract

## Status

Accepted

## Context

The manifest carried a `tools` list, but nothing stood behind it — the fourth
stable contract (tools) was named, not implemented.  Agents need to call tools
(image generation, retrieval, oracles), and "the Artist gets image-gen, the
Critic does not" must be enforced by the runtime, not by convention.

## Decision

Add `ToolRegistry` (`src/tools/registry.py`) as a capability-checked broker.
Agents never hold a tool; they ask the registry, which checks the calling agent's
`manifest.tools` grant before dispatching, raising `CapabilityViolation` on a
denied call.  Tools are `(name, description, run)` triples; `run(**params)`
returns a JSON-serialisable dict the agent folds into its event.

`ManifestAgent` exposes `call_tool()` (capability-checked) and injects granted
tool descriptions into the prompt.  A built-in deterministic `oracle` tool plus a
`fortune-teller` handler agent exercise the whole path end-to-end (scenario
`oracle-grove`), with its result recorded on the ledger.

Live MCP servers are deliberately **deferred**: the same `(name, description,
run)` interface fronts an in-process callable today and an MCP-server-backed tool
later, so swapping one for the other is invisible to agents.

## Consequences

- Least-privilege tool access is enforced at runtime and is testable.
- Tool output is first-class ledger data, not a side channel.
- The contract is stable across in-process tools and future MCP servers.
- A tool-using agent and a tool-less agent can sit in the same cast, scoped
  independently — demonstrated in `oracle-grove`.