cayu.approvals.tools

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`PendingToolApproval`

from cayu.approvals import PendingToolApproval

Durable checkpoint state for a tool call waiting on caller approval.

max_steps, limits, budget_limits, and retry_policy persist the original run’s configuration across the approval pause so resolving the approval resumes with the same config instead of fresh defaults. A resolution request may restate those values only when they preserve the invocation’s frozen execution profile. They are optional so checkpoints written before this state existed still load. Loop policies are runtime callables and cannot be checkpointed; they must be re-supplied on the resolution request when needed.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`approval_id`	`str`	`required`
`tool_round_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`arguments`	`dict[str, Any]`	`Field(default_factory=dict)`
`agent_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`workspace_id`	`str \| None`	`None`
`task_id`	`str \| None`	`None`
`execution_profile_fingerprint`	`str \| None`	`Field(default=None, min_length=64, max_length=64, pattern='^[0-9a-f]{64}$')`
`publish_arguments`	`SkipJsonSchema[StrictBool]`	`required`
`secret_resolution_scope`	`Literal['static', 'dynamic', 'unknown']`	`'unknown'`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`tool_calls`	`list[PendingToolCallApproval]`	`required`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`run_limit_accounting`	`RunLimitAccountingContext \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`expires_at`	`datetime \| None`	`None`

validate_expires_at (method)

PendingToolApproval.validate_expires_at(value: datetime | None) -> datetime | None

from_event (method)

PendingToolApproval.from_event(event: Event) -> PendingToolApproval

Parse a legacy approval event that retains complete arguments.

Current quarantined events must be parsed as PendingToolApprovalEventView; they cannot produce executable checkpoint state with fabricated empty arguments.

validate_nonblank_fields (method)

PendingToolApproval.validate_nonblank_fields(value: str, info) -> str

validate_tool_round_identity (method)

PendingToolApproval.validate_tool_round_identity() -> PendingToolApproval

validate_optional_nonblank_fields (method)

PendingToolApproval.validate_optional_nonblank_fields(value: str | None, info) -> str | None

copy_json_fields (method)

PendingToolApproval.copy_json_fields(value: dict[str, Any], info) -> dict[str, Any]

copy_structured_output (method)

PendingToolApproval.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_tool_calls (method)

PendingToolApproval.copy_tool_calls(value: list[PendingToolCallApproval]) -> list[PendingToolCallApproval]

copy_limits (method)

PendingToolApproval.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

PendingToolApproval.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_retry (method)

PendingToolApproval.copy_retry(value: RetryPolicy | None) -> RetryPolicy | None

Release source · Runtime guarantees · Capability guides

`PendingToolApprovalEventView`

from cayu.approvals import PendingToolApprovalEventView

Typed approval-event projection with explicit argument availability.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`approval_id`	`str`	`required`
`tool_round_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`arguments_state`	`Literal['finalized', 'quarantined']`	`required`
`arguments`	`dict[str, Any] \| None`	`required`
`agent_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`workspace_id`	`str \| None`	`None`
`task_id`	`str \| None`	`None`
`execution_profile_fingerprint`	`str \| None`	`Field(default=None, min_length=64, max_length=64, pattern='^[0-9a-f]{64}$')`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`tool_calls`	`list[PendingToolCallApprovalEventView]`	`required`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`expires_at`	`datetime \| None`	`None`

copy_json_fields (method)

PendingToolApprovalEventView.copy_json_fields(value: dict[str, Any] | None, info)

copy_tool_calls (method)

PendingToolApprovalEventView.copy_tool_calls(value: list[PendingToolCallApprovalEventView]) -> list[PendingToolCallApprovalEventView]

copy_structured_output (method)

PendingToolApprovalEventView.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_limits (method)

PendingToolApprovalEventView.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

PendingToolApprovalEventView.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_thinking (method)

PendingToolApprovalEventView.copy_thinking(value: ThinkingConfig | None) -> ThinkingConfig | None

copy_retry (method)

PendingToolApprovalEventView.copy_retry(value: RetryPolicy | None) -> RetryPolicy | None

validate_argument_projection (method)

PendingToolApprovalEventView.validate_argument_projection() -> PendingToolApprovalEventView

from_event (method)

PendingToolApprovalEventView.from_event(event: Event) -> PendingToolApprovalEventView

Parse a complete legacy or quarantined current approval event.

Release source · Runtime guarantees · Capability guides

`PendingToolCallApproval`

from cayu.approvals import PendingToolCallApproval

One tool call captured inside a pending approval round.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`arguments`	`dict[str, Any]`	`Field(default_factory=dict)`
`targeted_tool_grant_id`	`str \| None`	`Field(default=None, pattern=TARGETED_TOOL_DIGEST_PATTERN, exclude_if=lambda value: value is None)`
`model_tool_name`	`str \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`targeted_tool_invocation`	`ResolvedTargetedToolInvocation \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`targeted_tool_rejection`	`RejectedTargetedToolInvocation \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`policy_evidence`	`ToolPolicyEvidence \| None`	`None`
`policy_decision`	`str \| None`	`None`
`command_denial_code`	`CommandDenialCode \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`active_taint_labels`	`list[str]`	`Field(default_factory=list)`

validate_nonblank_fields (method)

PendingToolCallApproval.validate_nonblank_fields(value: str, info) -> str

validate_model_tool_name (method)

PendingToolCallApproval.validate_model_tool_name(value: str | None) -> str | None

copy_targeted_tool_invocation (method)

PendingToolCallApproval.copy_targeted_tool_invocation(value: object) -> object

copy_targeted_tool_rejection (method)

PendingToolCallApproval.copy_targeted_tool_rejection(value: object) -> object

validate_active_taint_labels (method)

PendingToolCallApproval.validate_active_taint_labels(value: Any) -> list[str]

validate_optional_nonblank_fields (method)

PendingToolCallApproval.validate_optional_nonblank_fields(value: str | None, info) -> str | None

copy_json_fields (method)

PendingToolCallApproval.copy_json_fields(value: dict[str, Any], info) -> dict[str, Any]

validate_policy_evidence (method)

PendingToolCallApproval.validate_policy_evidence() -> PendingToolCallApproval

transcript_arguments (property)

PendingToolCallApproval.transcript_arguments() -> dict[str, Any]

Return the non-authoritative provider-history argument projection.

Release source · Runtime guarantees · Capability guides

`PendingToolCallApprovalEventView`

from cayu.approvals import PendingToolCallApprovalEventView

Non-executable projection of one call in an approval event.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`arguments_state`	`Literal['finalized', 'quarantined']`	`required`
`arguments`	`dict[str, Any] \| None`	`required`
`policy_evidence`	`ToolPolicyEvidence \| None`	`None`
`policy_decision`	`str \| None`	`None`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`active_taint_labels`	`list[str]`	`Field(default_factory=list)`

copy_json_fields (method)

PendingToolCallApprovalEventView.copy_json_fields(value: dict[str, Any] | None, info)

copy_active_taint_labels (method)

PendingToolCallApprovalEventView.copy_active_taint_labels(value: list[str]) -> list[str]

validate_argument_projection (method)

PendingToolCallApprovalEventView.validate_argument_projection() -> PendingToolCallApprovalEventView

Release source · Runtime guarantees · Capability guides

`ToolApprovalDecision`

from cayu.approvals import ToolApprovalDecision

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`APPROVE`	`class attribute`	`'approve'`
`DENY`	`class attribute`	`'deny'`

Release source · Runtime guarantees · Capability guides

`ToolApprovalRecoveryOutcome`

from cayu.approvals import ToolApprovalRecoveryOutcome

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`

Release source · Runtime guarantees · Capability guides

`ToolApprovalRecoveryRequest`

from cayu.approvals import ToolApprovalRecoveryRequest

Caller-supplied terminal outcome for an approved tool with unknown result.

max_steps, limits, budget_limits, and retry_policy default to None, which means “inherit the original run’s configuration” as persisted on the pending approval checkpoint. An explicit value is accepted only when it preserves the invocation’s frozen execution profile.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`review_reference`	`HumanReviewReference \| None`	`Field(default=None, repr=False, exclude_if=lambda value: value is None)`
`session_id`	`str`	`required`
`task_worker_id`	`str \| None`	`None`
`task_handoff_id`	`str \| None`	`None`
`approval_id`	`str`	`required`
`tool_round_id`	`str`	`required`
`tool_call_id`	`str`	`required`
`outcome`	`ToolApprovalRecoveryOutcome`	`required`
`message`	`str`	`required`
`structured`	`dict[str, Any] \| None`	`None`
`artifacts`	`list[dict[str, Any]]`	`Field(default_factory=list)`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`resolved_by`	`ResolutionActor \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`loop_policies`	`SkipJsonSchema[tuple[LoopPolicy, ...]]`	`Field(default_factory=tuple, exclude=True)`

validate_nonblank_ids (method)

ToolApprovalRecoveryRequest.validate_nonblank_ids(value: str, info) -> str

validate_task_worker_id (method)

ToolApprovalRecoveryRequest.validate_task_worker_id(value: str | None) -> str | None

validate_task_handoff_authority (method)

ToolApprovalRecoveryRequest.validate_task_handoff_authority() -> ToolApprovalRecoveryRequest

validate_message (method)

ToolApprovalRecoveryRequest.validate_message(value: str, info) -> str

validate_optional_reason (method)

ToolApprovalRecoveryRequest.validate_optional_reason(value: str | None, info) -> str | None

copy_json_fields (method)

ToolApprovalRecoveryRequest.copy_json_fields(value, info)

copy_resolved_by (method)

ToolApprovalRecoveryRequest.copy_resolved_by(value: ResolutionActor | None) -> ResolutionActor | None

copy_structured_output (method)

ToolApprovalRecoveryRequest.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_limits (method)

ToolApprovalRecoveryRequest.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

ToolApprovalRecoveryRequest.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_loop_policies (method)

ToolApprovalRecoveryRequest.copy_loop_policies(value) -> tuple[LoopPolicy, ...]

Release source · Runtime guarantees · Capability guides

`ToolApprovalRequest`

from cayu.approvals import ToolApprovalRequest

Caller decision for a pending tool approval.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`review_reference`	`HumanReviewReference \| None`	`Field(default=None, repr=False, exclude_if=lambda value: value is None)`
`session_id`	`str`	`required`
`task_worker_id`	`str \| None`	`None`
`task_handoff_id`	`str \| None`	`None`
`approval_id`	`str`	`required`
`tool_round_id`	`str`	`required`
`tool_call_id`	`str`	`required`
`decision`	`ToolApprovalDecision`	`required`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`resolved_by`	`ResolutionActor \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`loop_policies`	`SkipJsonSchema[tuple[LoopPolicy, ...]]`	`Field(default_factory=tuple, exclude=True)`

validate_nonblank_ids (method)

ToolApprovalRequest.validate_nonblank_ids(value: str, info) -> str

validate_task_worker_id (method)

ToolApprovalRequest.validate_task_worker_id(value: str | None) -> str | None

validate_task_handoff_authority (method)

ToolApprovalRequest.validate_task_handoff_authority() -> ToolApprovalRequest

validate_optional_reason (method)

ToolApprovalRequest.validate_optional_reason(value: str | None, info) -> str | None

copy_metadata (method)

ToolApprovalRequest.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

copy_resolved_by (method)

ToolApprovalRequest.copy_resolved_by(value: ResolutionActor | None) -> ResolutionActor | None

copy_structured_output (method)

ToolApprovalRequest.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_limits (method)

ToolApprovalRequest.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

ToolApprovalRequest.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_loop_policies (method)

ToolApprovalRequest.copy_loop_policies(value) -> tuple[LoopPolicy, ...]

Release source · Runtime guarantees · Capability guides

`ToolPolicyEvidence`

from cayu.approvals import ToolPolicyEvidence

Durable authority state for one policy-planned tool call.

AUTHORITATIVE is the only state that may carry an executable policy decision. AMBIGUOUS means evaluation may have happened but its result was not durably published; operator acknowledgement cannot turn that missing evidence into authorization.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`UNPLANNED`	`class attribute`	`'unplanned'`
`AUTHORITATIVE`	`class attribute`	`'authoritative'`
`UNREGISTERED`	`class attribute`	`'unregistered'`
`UNEXPOSED`	`class attribute`	`'unexposed'`
`AMBIGUOUS`	`class attribute`	`'ambiguous'`

Release source · Runtime guarantees · Capability guides