cayu.tools.subagents

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.

BackgroundSubagentTaskRegistry

from cayu.tools import BackgroundSubagentTaskRegistry

Strong-reference registry for background subagent drain tasks.

asyncio only keeps weak references to running tasks, so background subagent drains must be pinned here until they finish or the parent is torn down (cancel_parent). Drain failures are logged and recorded so subagent_result can report them instead of the error being silently swallowed.

init (method)

BackgroundSubagentTaskRegistry.__init__() -> None

register (method)

BackgroundSubagentTaskRegistry.register(task: asyncio.Task[None], *, parent_session_id: str, child_session_id: str) -> None

active_tasks (method)

BackgroundSubagentTaskRegistry.active_tasks(parent_session_id: str) -> tuple[asyncio.Task[None], ...]

failure (method)

BackgroundSubagentTaskRegistry.failure(child_session_id: str) -> dict[str, Any] | None

drain (method)

async BackgroundSubagentTaskRegistry.drain(*, timeout_s: float=10.0) -> bool

Observe registry-wide stream settlement without cancelling children.

Callers must first stop external dispatch. This does not seal the registry or prove remote-effect/environment cleanup; Runtime cleanup drains still apply after streams settle. A timeout or cancelled waiter retains owners for a later call. Failed streams count as settled, not successful.

cancel_parent (method)

async BackgroundSubagentTaskRegistry.cancel_parent(parent_session_id: str) -> None

Cancel and drain every background subagent task for a parent session.

Release source · Runtime guarantees · Capability guides

default_background_subagent_registry

from cayu.tools import default_background_subagent_registry

Shared registry used when subagent tools are not given an explicit one.

default_background_subagent_registry() -> BackgroundSubagentTaskRegistry

Release source · Runtime guarantees · Capability guides

project_terminal_subagent_result

from cayu.tools import project_terminal_subagent_result

Project one bounded child result after domain authorization.

This read-only primitive deliberately does not decide whether an application caller may inspect child_session_id. Applications must establish that authorization from their own durable state before calling it. Cayu still validates the child/session/task authority and returns the same bounded result semantics used by SubagentResultTool.

async project_terminal_subagent_result(session_store: SessionStore, child_session_id: str, *, task_store: TaskStore | None=None, expected_task_id: str | None=None, max_chars: int=DEFAULT_SUBAGENT_RESULT_MAX_CHARS) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

SubagentContextMode

from cayu.tools import SubagentContextMode

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
TASK_ONLY	class attribute	'task_only'

Release source · Runtime guarantees · Capability guides

SubagentExecutionMode

from cayu.tools import SubagentExecutionMode

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
FOREGROUND	class attribute	'foreground'
BACKGROUND	class attribute	'background'
DURABLE	class attribute	'durable'

Release source · Runtime guarantees · Capability guides

SubagentResultTool

from cayu.tools import SubagentResultTool

Fetch or wait for asynchronous subagent results from durable child sessions.

Bases: Tool.

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
spec	ToolSpec	required

init (method)

SubagentResultTool.__init__(session_store: SessionStore, *, name: str='subagent_result', description: str | None=None, default_timeout_s: float=DEFAULT_SUBAGENT_RESULT_WAIT_TIMEOUT_S, background_registry: BackgroundSubagentTaskRegistry | None=None, task_store: TaskStore | None=None, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None) -> None

name (property)

SubagentResultTool.name() -> str

execution_profile_identity (property)

SubagentResultTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

SubagentResultTool.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)

SubagentResultTool.description() -> str

schema (property)

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

run (method)

async SubagentResultTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

Release source · Runtime guarantees · Capability guides

SubagentSpec

from cayu.tools import SubagentSpec

Model-facing subagent target backed by a Cayu agent registration.

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
agent_name	str	required
description	str	''
context_mode	SubagentContextMode	SubagentContextMode.TASK_ONLY
mode	SubagentExecutionMode	SubagentExecutionMode.FOREGROUND
max_steps	StrictInt	Field(default=DEFAULT_MAX_STEPS, ge=1, le=MAX_STEPS)
result_max_chars	StrictInt	Field(default=DEFAULT_SUBAGENT_RESULT_MAX_CHARS, ge=1, le=MAX_SUBAGENT_RESULT_MAX_CHARS)
limits	RunLimits	Field(default_factory=RunLimits)
metadata	dict[str, Any]	Field(default_factory=dict)

validate_agent_name (method)

SubagentSpec.validate_agent_name(value: str, info) -> str

validate_description (method)

SubagentSpec.validate_description(value: str, info) -> str

copy_metadata (method)

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

copy_limits (method)

SubagentSpec.copy_limits(value: RunLimits) -> RunLimits

Release source · Runtime guarantees · Capability guides

SubagentTool

from cayu.tools import SubagentTool

Model-facing delegation tool backed by normal Cayu child sessions.

Bases: Tool, ChildSessionRecoveryMatcher.

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
spec	ToolSpec	required

init (method)

SubagentTool.__init__(runtime: SubagentRuntime, *, agents: Mapping[str, SubagentSpec | str], name: str='subagent', description: str | None=None, background_registry: BackgroundSubagentTaskRegistry | None=None, session_store: SessionStore | None=None, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None) -> None

name (property)

SubagentTool.name() -> str

execution_profile_identity (property)

SubagentTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

SubagentTool.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)

SubagentTool.description() -> str

schema (property)

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

run (method)

async SubagentTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

matches_recoverable_child (method)

SubagentTool.matches_recoverable_child(child: Session, *, parent_invocation: SessionInvocation, parent_session_id: str, causal_budget_id: str, environment_name: str | None, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any], require_fingerprint: bool) -> bool

matches_recoverable_submission (method)

SubagentTool.matches_recoverable_submission(*, parent_session: Session, tool_name: str, tool_round_id: str, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any], spawn_fingerprint: str) -> bool

reconcile_recoverable_child (method)

async SubagentTool.reconcile_recoverable_child(child: Session | None, *, parent_session: Session, tool_name: str, tool_round_id: str, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any]) -> Session | ToolResult | None

project_recoverable_child (method)

async SubagentTool.project_recoverable_child(child: Session) -> ToolResult | None

background_task_registry (property)

SubagentTool.background_task_registry() -> BackgroundSubagentTaskRegistry

Existing process-local owner; default registries may span applications.

Release source · Runtime guarantees · Capability guides