feat(validation): implement tool wrapping runtime (wraps + transform delegation) #555

2026-03-04T03:36:57Z

freemo commented

2026-03-04 03:36:57 +00:00

Summary

Implements the runtime execution engine for validation tool wrapping as specified in docs/specification.md § Core Concepts > Validation > Tool Wrapping. This adds the missing runtime layer that actually performs delegation when a validation has wraps set.

Changes

WrappedToolExecutor — Resolves wraps references and delegates execution to the wrapped tool. Supports composable wrapping chains (wrapper wraps another wrapper) with cycle detection and depth limiting (max 10 levels).
ArgumentMapper — Applies argument_mapping configuration to translate arguments between the wrapper's schema and the wrapped tool's schema. Supports forwarded parameter names and literal fixed values.
TransformExecutor — Runs the user-supplied transform function in a sandboxed Python environment with restricted builtins (no imports, no filesystem, no network). Validates that transforms return proper validation-format dicts with a passed boolean.
Error types — WrappedToolNotFoundError, WrappingCycleError, WrappingDepthExceededError, TransformExecutionError with clear diagnostic messages.
Package exports — All new types exported via cleveragents.tool.__init__.

Testing

20 Behave scenarios (features/tool_wrapping_runtime.feature): argument mapping (identity, configured, literal values, error cases), transform execution (valid, sandbox, missing function, invalid return), wrapping delegation (simple, chained, missing tool, cycle detection, context inheritance, type validation).
8 Robot Framework integration tests (robot/tool_wrapping_runtime.robot): end-to-end smoke tests for imports, mapping, transform, delegation, and error handling.
ASV benchmarks (benchmarks/tool_wrapping_bench.py): delegation overhead for identity mapping, configured mapping, transform execution, single and chained delegation.

Quality Gates

nox -s lint — passes
nox -s typecheck — 0 errors, 0 warnings (Pyright strict, no # type: ignore)
nox -s unit_tests — 8154 scenarios passed (including 20 new)

Closes #543

## Summary Implements the runtime execution engine for validation tool wrapping as specified in `docs/specification.md` § Core Concepts > Validation > Tool Wrapping. This adds the missing runtime layer that actually performs delegation when a validation has `wraps` set. ### Changes - **`WrappedToolExecutor`** — Resolves `wraps` references and delegates execution to the wrapped tool. Supports composable wrapping chains (wrapper wraps another wrapper) with cycle detection and depth limiting (max 10 levels). - **`ArgumentMapper`** — Applies `argument_mapping` configuration to translate arguments between the wrapper's schema and the wrapped tool's schema. Supports forwarded parameter names and literal fixed values. - **`TransformExecutor`** — Runs the user-supplied `transform` function in a sandboxed Python environment with restricted builtins (no imports, no filesystem, no network). Validates that transforms return proper validation-format dicts with a `passed` boolean. - **Error types** — `WrappedToolNotFoundError`, `WrappingCycleError`, `WrappingDepthExceededError`, `TransformExecutionError` with clear diagnostic messages. - **Package exports** — All new types exported via `cleveragents.tool.__init__`. ### Testing - **20 Behave scenarios** (`features/tool_wrapping_runtime.feature`): argument mapping (identity, configured, literal values, error cases), transform execution (valid, sandbox, missing function, invalid return), wrapping delegation (simple, chained, missing tool, cycle detection, context inheritance, type validation). - **8 Robot Framework integration tests** (`robot/tool_wrapping_runtime.robot`): end-to-end smoke tests for imports, mapping, transform, delegation, and error handling. - **ASV benchmarks** (`benchmarks/tool_wrapping_bench.py`): delegation overhead for identity mapping, configured mapping, transform execution, single and chained delegation. ### Quality Gates - `nox -s lint` — passes - `nox -s typecheck` — 0 errors, 0 warnings (Pyright strict, no `# type: ignore`) - `nox -s unit_tests` — 8154 scenarios passed (including 20 new) Closes #543

freemo added this to the v3.4.0 milestone 2026-03-04 03:37:05 +00:00

freemo added the

Type

Feature

label 2026-03-04 03:37:11 +00:00

freemo referenced this pull request

2026-03-04 03:40:00 +00:00

feat(validation): implement tool wrapping runtime (wraps + transform delegation) #543

freemo force-pushed feature/m5-tool-wrapping-runtime from 85603ae5a9 to 9a7795a5e9

2026-03-04 16:55:09 +00:00

Compare

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-04 17:28:36 +00:00