# Tool Lifecycle Runtime

The tool lifecycle runtime orchestrates the four-stage lifecycle
(`discover`/`activate`/`execute`/`deactivate`) for all tool sources
(MCP, Agent Skills, built-ins, custom, wrapped).

## Architecture

```
ToolRuntime
  ├── ToolLifecycleCache     (per-plan activation reuse)
  ├── ToolInstance (Protocol) (concrete tool implementations)
  ├── ToolExecutionContext    (plan metadata + resources + cancellation)
  └── schema_validator        (JSON Schema input/output validation)
```

## Four-Stage Lifecycle

### 1. Discover

Returns lightweight `ToolDescriptor` metadata without activating the tool.
Used during registration and tool enumeration.

### 2. Activate

Prepares the tool for execution within a plan context. Called at most once
per plan via the lifecycle cache. May start external processes (MCP), load
instructions (Agent Skills), or no-op (built-ins).

### 3. Execute

Runs the tool with validated parameters. The runtime:
1. Checks cancellation
2. Auto-activates if not yet activated for the plan
3. Enforces capability flags (read-only, checkpoint requirements)
4. Validates inputs against JSON Schema
5. Executes the tool with tracing
6. Validates outputs against JSON Schema
7. Records changes into the execution context

### 4. Deactivate

Cleans up after all executions. Called once per plan on completion, failure,
or cancellation. Must be idempotent and must not raise.

## Capability Enforcement

| Constraint | Condition | Error |
|-----------|-----------|-------|
| Read-only plan | Tool has `writes=True` | `ToolAccessDeniedError` |
| Checkpoint required | Tool has `checkpointable=False` | `ToolCheckpointRequiredError` |

## Per-Plan Activation Cache

The `ToolLifecycleCache` ensures:
- Each tool is activated at most once per plan
- `deactivate()` is guaranteed for every activated tool when the plan ends
- Thread-safe via `RLock` for concurrent plan execution

## Cancellation

The `CancellationToken` propagates cancellation from the plan lifecycle:
- Set via `cancel()` when `agents plan cancel` is invoked
- Tools check `ctx.cancellation_token.is_cancelled` for long-running ops
- `ctx.cancellation_token.check()` raises `ToolCancelledError` immediately

## JSON Schema Validation

Uses JSON Schema draft 2020-12 via `jsonschema.Draft202012Validator`:
- `input_schema`: validated before execution; failures return error result
- `output_schema`: validated after execution; failures logged as warning

## Execution Tracing

Every execution produces a `ToolExecutionTrace` with:
- `started_at` / `ended_at` (ISO-8601)
- `duration_ms`
- `result_size_bytes`
- `success` / `error`

## Error Hierarchy

```
ToolRuntimeError
  ├── ToolAccessDeniedError
  ├── ToolCheckpointRequiredError
  ├── ToolNotActivatedError
  ├── ToolActivationError
  ├── ToolExecutionError
  └── ToolDeactivationError

ToolCancelledError  (standalone, not ToolRuntimeError)
ToolSchemaValidationError  (standalone)
```

## Key Files

| File | Purpose |
|------|---------|
| `src/cleveragents/tool/__init__.py` | Package exports |
| `src/cleveragents/tool/context.py` | `ToolExecutionContext`, `BoundResource`, `Change`, `CancellationToken`, `ToolExecutionTrace` |
| `src/cleveragents/tool/lifecycle.py` | `ToolRuntime`, `ToolInstance`, `ToolLifecycleCache`, `ToolDescriptor`, `ToolResult` |
| `src/cleveragents/tool/schema_validator.py` | JSON Schema validation for inputs/outputs |
| `src/cleveragents/domain/models/core/tool.py` | `Tool`, `Validation`, `ToolCapability` domain models |