cleveragents-core/docs/reference/skills_inline.md

Inline Tool Executor

Safe execution of inline (anonymous) tool code within skills.

Overview

The InlineToolExecutor runs Python code strings defined directly in skill YAML. Execution is bounded by configurable timeout and output-size limits, with write-guard enforcement delegated to the SkillContext.

InlineToolResult

Frozen Pydantic model returned from every execution.

Field	Type	Description
success	bool	Whether the execution succeeded
output	Any	Captured stdout/stderr output
error_message	str | None	Error description on failure
duration_ms	float	Wall-clock execution time in milliseconds
truncated	bool	Whether output was truncated due to size limits

InlineToolExecutor

Constructor

InlineToolExecutor(
    max_runtime_seconds: float = 30.0,
    max_output_bytes: int = 1_048_576,
)

Parameter	Default	Description
max_runtime_seconds	30.0	Maximum wall-clock seconds for execution
max_output_bytes	1_048_576	Maximum captured output before truncation (1 MiB)

execute(tool, context, input_data) -> InlineToolResult

Run an inline tool's code with safety guards.

1. Validation -- Checks the tool has code and uses a supported source.
2. Write guard -- If tool.capability.writes is True, calls context.enforce_write_guard(). In a read-only context this returns an error result without executing.
3. Path restriction -- File-path keys in input_data (keys ending with _path, _file, or equal to path) are validated against context.get_sandbox_path().
4. Threaded execution -- Code runs in a daemon thread with max_runtime_seconds timeout.
5. Output capture -- stdout and stderr are captured. If the combined output exceeds max_output_bytes, it is truncated and truncated=True is set on the result.
6. Change tracking -- The invocation is recorded in the context's change tracker regardless of success/failure.

validate_tool(tool) -> list[str]

Return a list of validation errors (empty means valid).

Checks:

• Tool has non-empty code.
• Tool's source is custom (Python). Other source types are not supported for MVP.

Safety Constraints

Timeout

Execution uses threading.Thread with a join timeout. If the thread does not complete within max_runtime_seconds, the result reports:

Execution timed out after {max_runtime_seconds}s

The daemon thread is abandoned (not forcibly killed). For MVP this is acceptable; future versions may use process isolation.

Output Size

Combined stdout + stderr is capped at max_output_bytes. When exceeded the output is byte-truncated and InlineToolResult.truncated is set to True.

Write Guard

Tools declaring capability.writes = True trigger a write-guard check via SkillContext.enforce_write_guard(). In a read-only context the executor returns an error result without executing any code.

Path Restriction

Input data keys matching *_path, *_file, or path are resolved and checked against the sandbox root. Paths that escape the sandbox are rejected before execution.

Language / Source Support

Only source = custom (Python) is supported for MVP. Other source types (mcp, agent_skill, builtin, wrapped) are rejected by validate_tool.

Network Access

For MVP, inline tools run in the host process and no network sandboxing is enforced. Tools should be treated as local-only. Future milestones will introduce process-level or container-level isolation for network restrictions.