cayu.tools.policy

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.

AllowAllToolPolicy

from cayu.tools import AllowAllToolPolicy

Bases: ToolPolicy.

execution_profile_identity (property)

AllowAllToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async AllowAllToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

Release source · Runtime guarantees · Capability guides

AllowlistRule

from cayu.tools import AllowlistRule

Allow a present argument only when it matches an allowed string.

A missing argument is intentionally allowed. Use RequiredAllowlistRule when omission must fail closed.

Bases: ParameterRule.

parameter (property)

AllowlistRule.parameter() -> str

check (method)

AllowlistRule.check(arguments: dict[str, Any]) -> str | None

violation_metadata (method)

AllowlistRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

Return safe structured details for a rejected argument.

Custom rules remain source-compatible: rules that do not override this hook continue to emit the standard policy, tool, parameter, rule, and rule-index metadata.

is_validity_violation (method)

AllowlistRule.is_validity_violation(arguments: dict[str, Any]) -> bool

init (method)

AllowlistRule.__init__(parameter: str, *, values: Iterable[str]) -> None

Release source · Runtime guarantees · Capability guides

AlwaysRequireApprovalToolPolicy

from cayu.tools import AlwaysRequireApprovalToolPolicy

Require caller approval for specific tools (or for every tool).

When tools is given, only those tool names require approval and the rest are allowed; when omitted, every tool call requires approval. Use this to gate side-effecting tools (post a PR comment, send an email) behind resolve_tool_approval without hand-writing a policy — instead of abusing a deny-everything rule. expires_in_seconds bounds how long the resulting pending approval stays resolvable before it deterministically denies.

Bases: ToolPolicy.

execution_profile_identity (property)

AlwaysRequireApprovalToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async AlwaysRequireApprovalToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

AlwaysRequireApprovalToolPolicy.__init__(*, tools: Iterable[str] | None=None, expires_in_seconds: float | None=None) -> None

Release source · Runtime guarantees · Capability guides

ANY_TAINT_LABEL

from cayu.tools import ANY_TAINT_LABEL

ANY_TAINT_LABEL = '*'

Release source · Runtime guarantees · Capability guides

DenyPatternRule

from cayu.tools import DenyPatternRule

Reject a string argument when it matches one of the denied regex patterns.

Bases: ParameterRule.

parameter (property)

DenyPatternRule.parameter() -> str

check (method)

DenyPatternRule.check(arguments: dict[str, Any]) -> str | None

violation_metadata (method)

DenyPatternRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

Return safe structured details for a rejected argument.

Custom rules remain source-compatible: rules that do not override this hook continue to emit the standard policy, tool, parameter, rule, and rule-index metadata.

is_validity_violation (method)

DenyPatternRule.is_validity_violation(arguments: dict[str, Any]) -> bool

init (method)

DenyPatternRule.__init__(parameter: str, *, patterns: Iterable[str]) -> None

Release source · Runtime guarantees · Capability guides

EnvironmentScopedToolPolicy

from cayu.tools import EnvironmentScopedToolPolicy

Pre-authorize explicit tools in named execution environments.

allow maps tool names to exact environment names (no wildcards). Unlisted tools, empty scopes, and missing or unmatched environments deny. Only trusted request context is checked, never model-provided arguments. Names are public application identifiers, not credentials. Authorization does not establish containment or bypass environment execution admission.

Bases: ToolPolicy.

execution_profile_identity (property)

EnvironmentScopedToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async EnvironmentScopedToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

EnvironmentScopedToolPolicy.__init__(*, allow: Mapping[str, Iterable[str]]) -> None

allow (property)

EnvironmentScopedToolPolicy.allow() -> Mapping[str, frozenset[str]]

Release source · Runtime guarantees · Capability guides

EveryCallRule

from cayu.tools import EveryCallRule

Match every call so the policy’s decision applies to the whole tool.

With ParameterConstrainedToolPolicy(..., decision=REQUIRE_APPROVAL) each call to the tool pauses for human approval; with DENY it is blocked. Use it for tools whose every invocation is consequential, such as sending a message or writing an external record.

Bases: ParameterRule.

parameter (property)

EveryCallRule.parameter() -> str

check (method)

EveryCallRule.check(arguments: dict[str, Any]) -> str | None

violation_metadata (method)

EveryCallRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

Return safe structured details for a rejected argument.

Custom rules remain source-compatible: rules that do not override this hook continue to emit the standard policy, tool, parameter, rule, and rule-index metadata.

is_validity_violation (method)

EveryCallRule.is_validity_violation(arguments: dict[str, Any]) -> bool

Whether approval cannot repair this violation; custom rules default to authority.

Release source · Runtime guarantees · Capability guides

GuardedToolPolicy

from cayu.tools import GuardedToolPolicy

Apply deny-or-continue guards, then one enforcing downstream policy.

A guard cannot authorize a call. Invalid returns and ordinary exceptions deny with fixed content-free text; cancellation still propagates.

Bases: ToolPolicy.

execution_profile_identity (property)

GuardedToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async GuardedToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

GuardedToolPolicy.__init__(*, guards: Iterable[ToolPolicyGuard], then: ToolPolicy) -> None

guards (property)

GuardedToolPolicy.guards() -> tuple[ToolPolicyGuard, ...]

then (property)

GuardedToolPolicy.then() -> ToolPolicy

Release source · Runtime guarantees · Capability guides

metadata_with_taint_labels

from cayu.tools import metadata_with_taint_labels

metadata_with_taint_labels(metadata: Mapping[str, Any], labels: Iterable[str]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

ParameterConstrainedToolPolicy

from cayu.tools import ParameterConstrainedToolPolicy

Validate tool-call arguments with per-tool parameter rules.

Tools not present in rules are allowed. For constrained tools, the first validity violation always denies: approval cannot repair missing, empty or wrongly typed arguments. Authority violations return decision with a structured metadata payload. Validity checks take precedence over authority violations, even when an authority rule appears first.

Bases: ToolPolicy.

execution_profile_identity (property)

ParameterConstrainedToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

authorize (method)

async ParameterConstrainedToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

ParameterConstrainedToolPolicy.__init__(rules: dict[str, Iterable[ParameterRule]], *, decision: ToolPolicyDecision=ToolPolicyDecision.DENY, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None) -> None

Release source · Runtime guarantees · Capability guides

ParameterRule

from cayu.tools import ParameterRule

Validates one argument path in a tool call.

A path can be a top-level argument name such as "to" or a dotted path such as "request.url" for nested JSON objects.

Bases: ABC.

parameter (property)

ParameterRule.parameter() -> str

Human-readable argument path this rule validates.

check (method)

ParameterRule.check(arguments: dict[str, Any]) -> str | None

Return a violation reason, or None when the arguments satisfy the rule.

violation_metadata (method)

ParameterRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

Return safe structured details for a rejected argument.

Custom rules remain source-compatible: rules that do not override this hook continue to emit the standard policy, tool, parameter, rule, and rule-index metadata.

is_validity_violation (method)

ParameterRule.is_validity_violation(arguments: dict[str, Any]) -> bool

Whether approval cannot repair this violation; custom rules default to authority.

Release source · Runtime guarantees · Capability guides

RequiredAllowlistRule

from cayu.tools import RequiredAllowlistRule

Require a non-empty string argument that matches an explicit allowlist.

Bases: ParameterRule.

parameter (property)

RequiredAllowlistRule.parameter() -> str

check (method)

RequiredAllowlistRule.check(arguments: dict[str, Any]) -> str | None

violation_metadata (method)

RequiredAllowlistRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

is_validity_violation (method)

RequiredAllowlistRule.is_validity_violation(arguments: dict[str, Any]) -> bool

init (method)

RequiredAllowlistRule.__init__(parameter: str, *, values: Iterable[str]) -> None

Release source · Runtime guarantees · Capability guides

RequiredArguments

from cayu.tools import RequiredArguments

Deny missing or empty argument paths before the downstream policy runs.

init (method)

RequiredArguments.__init__(rules: Mapping[str, Iterable[str]]) -> None

check (method)

async RequiredArguments.check(request: ToolPolicyRequest) -> ToolPolicyResult | None

Release source · Runtime guarantees · Capability guides

RequiredFieldRule

from cayu.tools import RequiredFieldRule

Require an argument path to be present and non-empty.

Bases: ParameterRule.

parameter (property)

RequiredFieldRule.parameter() -> str

check (method)

RequiredFieldRule.check(arguments: dict[str, Any]) -> str | None

violation_metadata (method)

RequiredFieldRule.violation_metadata(arguments: dict[str, Any]) -> dict[str, Any]

Return safe structured details for a rejected argument.

Custom rules remain source-compatible: rules that do not override this hook continue to emit the standard policy, tool, parameter, rule, and rule-index metadata.

is_validity_violation (method)

RequiredFieldRule.is_validity_violation(arguments: dict[str, Any]) -> bool

init (method)

RequiredFieldRule.__init__(parameter: str) -> None

Release source · Runtime guarantees · Capability guides

StaticToolPolicy

from cayu.tools import StaticToolPolicy

Simple allow/deny policy for static tool scopes.

Deny rules win over allow rules. When allow is omitted, all tools are allowed except explicitly denied tools. When allow is provided, only those tools are allowed.

Bases: ToolPolicy.

execution_profile_identity (property)

StaticToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async StaticToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

StaticToolPolicy.__init__(*, allow: Iterable[str] | None=None, deny: Iterable[str] | None=None) -> None

Release source · Runtime guarantees · Capability guides

taint_labels_from_metadata

from cayu.tools import taint_labels_from_metadata

taint_labels_from_metadata(metadata: Mapping[str, Any]) -> frozenset[str]

Release source · Runtime guarantees · Capability guides

TAINT_LABELS_METADATA_KEY

from cayu.tools import TAINT_LABELS_METADATA_KEY

TAINT_LABELS_METADATA_KEY = 'cayu:taint_labels'

Release source · Runtime guarantees · Capability guides

TaintAwareToolPolicy

from cayu.tools import TaintAwareToolPolicy

Protect sensitive tools after untrusted tool output enters a session.

This policy does not scan content for prompt-injection strings. Instead, apps classify tool boundaries:

• taint_sources maps inbound/untrusted tool names to taint labels.
• protected_tools maps sensitive outbound tools to labels that should deny or require approval once present in the session.

Cayu’s runtime supplies durable prior labels through request.metadata["cayu:taint_labels"] and adds same-round labels while planning a batch of tool calls.

Bases: ToolPolicy.

execution_profile_identity (property)

TaintAwareToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async TaintAwareToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

init (method)

TaintAwareToolPolicy.__init__(*, taint_sources: Mapping[str, Iterable[str]], protected_tools: Mapping[str, Iterable[str]], decision: ToolPolicyDecision=ToolPolicyDecision.REQUIRE_APPROVAL) -> None

labels_for_source_tool (method)

TaintAwareToolPolicy.labels_for_source_tool(tool_name: str) -> frozenset[str]

Return labels added when tool_name produces a terminal result.

protected_labels_for_tool (method)

TaintAwareToolPolicy.protected_labels_for_tool(tool_name: str) -> frozenset[str]

Return taint labels that protect tool_name.

Release source · Runtime guarantees · Capability guides

TOOL_POLICY_REAUTHORIZATION_METADATA_KEY

from cayu.tools import TOOL_POLICY_REAUTHORIZATION_METADATA_KEY

TOOL_POLICY_REAUTHORIZATION_METADATA_KEY = 'cayu:tool_policy_reauthorization'

Release source · Runtime guarantees · Capability guides

ToolPolicy

from cayu.tools import ToolPolicy

Authorizes registered tool calls before execution.

Bases: ABC.

execution_profile_identity (property)

ToolPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

authorize (method)

async ToolPolicy.authorize(request: ToolPolicyRequest) -> ToolPolicyResult

Return whether this tool call may execute.

Release source · Runtime guarantees · Capability guides

ToolPolicyDecision

from cayu.tools import ToolPolicyDecision

Bases: StrEnum.

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
ALLOW	class attribute	'allow'
DENY	class attribute	'deny'
REQUIRE_APPROVAL	class attribute	'require_approval'

Release source · Runtime guarantees · Capability guides

ToolPolicyGuard

from cayu.tools import ToolPolicyGuard

A narrowing guard: return None to continue or a DENY result.

Custom guards can declare execution_profile_identity for portable recovery. An undeclared guard keeps the composite process-local.

Bases: Protocol.

check (method)

async ToolPolicyGuard.check(request: ToolPolicyRequest) -> ToolPolicyResult | None

Release source · Runtime guarantees · Capability guides

ToolPolicyRequest

from cayu.tools import ToolPolicyRequest

Input passed to a tool policy before a registered tool executes.

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
session	Session	required
agent	AgentSpec	required
tool_name	str	required
tool_call_id	str	required
tool_effect	ToolEffect	ToolEffect.EXTERNAL
arguments	dict[str, Any]	Field(default_factory=dict)
environment_name	str | None	None
workspace_id	str | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

validate_nonblank_fields (method)

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

validate_optional_names (method)

ToolPolicyRequest.validate_optional_names(value: str | None, info) -> str | None

copy_json_fields (method)

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

Release source · Runtime guarantees · Capability guides

ToolPolicyResult

from cayu.tools import ToolPolicyResult

Authorization decision for one tool call.

approval_expires_in_seconds is honored only when decision is REQUIRE_APPROVAL: the runtime converts it to an absolute expires_at on the pending approval checkpoint, after which resolution deterministically denies the round. None means the approval never expires.

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
decision	ToolPolicyDecision	required
reason	str | None	None
metadata	dict[str, Any]	Field(default_factory=dict)
command_denial_code	CommandDenialCode | None	Field(default=None, exclude_if=lambda value: value is None)
approval_expires_in_seconds	float | None	None

validate_optional_reason (method)

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

copy_metadata (method)

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

validate_approval_expires_in_seconds (method)

ToolPolicyResult.validate_approval_expires_in_seconds(value: object) -> float | None

Release source · Runtime guarantees · Capability guides