cleveragents-core/docs/reference/tool_lifecycle.md

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