cayu.tools.commands

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.

`CommandPolicy`

from cayu.tools import CommandPolicy

Authorizes exec_command requests before they reach the runner.

With a policy, ExecCommandTool resolves the requested cwd through the active runner and runs the selected backend’s side-effect-free preflight before evaluation, then supplies both the requested and canonical forms. An allowed command executes with that same canonical value. Without a policy the model-controlled command, cwd, and env pass straight to the runner. Hosts that need an allow/deny/approval seam attach a policy via ExecCommandTool(policy=...).

Bases: ABC.

process_capabilities (property)

CommandPolicy.process_capabilities() -> ProcessCommandCapabilities | None

Optional public capability snapshot; discovery never grants authority.

allowed_environment_names (property)

CommandPolicy.allowed_environment_names() -> tuple[str, ...] | None

Optional name-only discovery; None means this policy does not declare a list.

execution_profile_identity (property)

CommandPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

evaluate (method)

async CommandPolicy.evaluate(ctx: ToolContext, request: CommandRequest) -> CommandPolicyResult

Return whether this command may execute.

Release source · Runtime guarantees · Capability guides

`CommandPolicyDecision`

from cayu.tools import CommandPolicyDecision

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_COMMAND_APPROVAL`	`class attribute`	`'require_command_approval'`

Release source · Runtime guarantees · Capability guides

`CommandPolicyResult`

from cayu.tools import CommandPolicyResult

Authorization decision for one exec_command invocation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`decision`	`CommandPolicyDecision`	`required`
`reason`	`str \| None`	`None`
`process_diagnostic`	`ProcessCommandDiagnostic \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`denied_env_name`	`str \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`allowed_env_names`	`tuple[str, ...] \| None`	`Field(default=None, max_length=64, exclude_if=lambda value: value is None)`
`allowed_env_names_truncated`	`bool`	`Field(default=False, exclude_if=lambda value: not value)`

validate_denied_env_name (method)

CommandPolicyResult.validate_denied_env_name(value: str | None) -> str | None

validate_allowed_env_names (method)

CommandPolicyResult.validate_allowed_env_names(value: tuple[str, ...] | None) -> tuple[str, ...] | None

validate_optional_reason (method)

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

Release source · Runtime guarantees · Capability guides

`CommandRequest`

from cayu.tools import CommandRequest

Exec request evaluated by a CommandPolicy.

cwd preserves the original requested value for audit and backward compatibility. canonical_cwd is the active runner’s resolved working directory and is the value execution will receive. The canonical field is optional only so policy metadata serialized before it was introduced can still be loaded; ExecCommandTool always supplies it.

Bases: _CommandValidationModel.

Fields and attributes

Name	Type	Default
`command`	`ExecCommand`	`required`
`cwd`	`str \| None`	`None`
`canonical_cwd`	`str \| None`	`None`
`env`	`dict[str, str] \| None`	`None`
`timeout_s`	`int`	`required`
`stdin`	`str \| None`	`None`

model_validate (method)

CommandRequest.model_validate(obj: Any, *, strict: bool | None=None, extra: Any=None, from_attributes: bool | None=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

model_validate_json (method)

CommandRequest.model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None=None, extra: Any=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

model_validate_strings (method)

CommandRequest.model_validate_strings(obj: Any, *, strict: bool | None=None, extra: Any=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

init (method)

CommandRequest.__init__(**data: Any) -> None

copy_command (method)

CommandRequest.copy_command(value: ExecCommand) -> ExecCommand

Release source · Runtime guarantees · Capability guides

`ExecCommandTool`

from cayu.tools import ExecCommandTool

Bases: Tool.

init (method)

ExecCommandTool.__init__(spec: ToolSpec | None=None, *, policy: CommandPolicy | None=None, default_timeout_seconds: int=DEFAULT_TIMEOUT_SECONDS) -> None

name (property)

ExecCommandTool.name() -> str

execution_profile_identity (property)

ExecCommandTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

ExecCommandTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

ExecCommandTool.description() -> str

schema (property)

ExecCommandTool.schema() -> dict[str, Any]

run (method)

async ExecCommandTool.run(ctx: ToolContext, args: dict) -> ToolResult

command_policy (property)

ExecCommandTool.command_policy() -> CommandPolicy | None

Return the enforcing command policy, if one is configured.

Release source · Runtime guarantees · Capability guides