cleveragents-core/docs/reference/tool_runtime.md

# Tool Runtime

The tool runtime provides the execution layer that sits on top of the
domain `Tool` model.  It is responsible for registering, discovering,
activating, executing, and deactivating tools at runtime.

## Modules

| Module | Purpose |
|--------|---------|
| `cleveragents.tool.runtime` | Data models: `ToolSpec`, `ToolResult`, `ToolError` |
| `cleveragents.tool.registry` | In-memory `ToolRegistry` with thread-safe operations |
| `cleveragents.tool.runner` | `ToolRunner` implementing the four-stage lifecycle |

## Tool Lifecycle

Every tool execution follows a strict four-stage lifecycle:

```
discover -> activate -> execute -> deactivate
```

### 1. Discover

`ToolRunner.discover(registry?)` queries the registry for all available
tools.  An alternate registry may be passed for dynamic discovery.

### 2. Activate

`ToolRunner.activate(tool_name)` validates that the tool exists and marks
it as ready for execution.  Raises `ToolError` with type
`ActivationError` if the tool is not found.

### 3. Execute

`ToolRunner.execute(tool_name, inputs)` runs the tool handler with the
provided inputs.  Key guarantees:

- **JSON-serialisable IO**: Both inputs and outputs are validated to be
  JSON-serialisable.  Non-serialisable data causes a `ToolResult` with
  `success=False`.
- **Error normalisation**: Any exception raised by the handler is caught
  and returned as a `ToolResult(success=False, error=...)`.  The caller
  never sees raw exceptions from tool handlers.
- **Duration tracking**: Wall-clock execution time is recorded in
  `ToolResult.duration_ms`.

### 4. Deactivate

`ToolRunner.deactivate(tool_name)` cleans up after execution.  Returns
`True` if the tool was active, `False` otherwise.

## Capability Flags

`ToolSpec.capabilities` carries a `ToolCapability` instance (from the
domain model) with the following flags:

| Flag | Description |
|------|-------------|
| `read_only` | Tool only reads; never writes |
| `writes` | Tool can write to resources |
| `checkpointable` | Tool supports checkpoint/rollback |
| `idempotent` | Safe to re-run without side effects |
| `unsafe` | Requires extra safety checks |
| `human_approval_required` | Needs explicit human approval |

A `read_only` tool cannot have `writes=True` or `checkpointable=True`.

## Error Semantics

### ToolResult

| Field | Type | Description |
|-------|------|-------------|
| `success` | `bool` | Whether execution succeeded |
| `output` | `dict` | JSON-serialisable output payload |
| `error` | `str \| None` | Error message on failure |
| `duration_ms` | `float` | Execution wall-clock time (ms) |
| `metadata` | `dict` | Arbitrary execution metadata |

### ToolError

`ToolError` is an exception class for structured tool failures:

| Attribute | Type | Description |
|-----------|------|-------------|
| `tool_name` | `str` | Namespaced tool name |
| `error_type` | `str` | Category (e.g. `RegistrationError`) |
| `details` | `str` | Human-readable explanation |

## Registry

`ToolRegistry` is an in-memory, thread-safe registry:

- **`register(spec)`** -- adds a tool; raises `ToolError` on name
  collision.
- **`get(name)`** -- lookup by namespaced name; returns `None` if not
  found.
- **`list_tools(namespace?, tool_type?)`** -- list with optional filters.
- **`remove(name)`** -- unregister; returns `bool`.

All mutating operations are protected by `threading.RLock`.