temp/docs/reference/validation_model.md

Validation Domain Model

A Validation extends Tool with pass/fail semantics. Validations are always read-only (writes=False, checkpointable=False, read_only=True).

Validation-Specific Fields

Field	Type	Default	Description
mode	ValidationMode	required	Whether failure blocks execution
wraps	str | None	None	Name of existing tool to wrap
transform	str | None	None	Python code to transform wrapped output
argument_mapping	dict | None	None	Args for wrapped tool (only with wraps)

All fields from Tool are also available.

Forced Constraints

When constructing a Validation, the following are always enforced:

• tool_type is forced to ToolType.VALIDATION
• capability.read_only is forced to True
• capability.writes is forced to False
• capability.checkpointable is forced to False

Wraps Semantics

A Validation may wrap an existing Tool to reuse its implementation:

• When wraps is set, source must be wrapped
• When wraps is set, code must not be set (mutually exclusive)
• When wraps is set, transform is required
• argument_mapping is only valid when wraps is set

Modes

Mode	Behavior
required	Failure blocks the operation
informational	Failure is reported but does not block

Class Methods

• Validation.from_config(config: dict) -- Create from a YAML config dict (auto-detects source=wrapped when wraps is present)
• validation.as_cli_dict() -- Stable ordered dict with validation fields

CLI Management

agents validation add --config <file> [--update]
agents validation attach [--project <project>|--plan <plan_id>] <resource> <validation>
agents validation detach [--yes] <attachment_id>

Validations are listed and inspected via standard agents tool commands with --type validation filter.