Delegation

Delegation lets Anyy split bounded work into child sessions. A child session has its own transcript, run state, role/workspace scope, and tool view, while the parent session keeps the user-facing conversation.

Use delegation for independent model work that can be summarized back to the parent: parallel research, comparing options, checking a repo section, or running a bounded analysis task.

Do not use it for ordinary follow-up questions, quick lookups, or long shell commands. Use the foreground turn for quick work, background_job for resident background work, and managed process jobs for long-running shell commands.

Delegate Task

The main model-visible tool is delegate_task in the subagents toolset. It starts one or more child Anyy sessions and waits for their final summaries before the parent continues.

Common arguments:

Argument	Meaning
task or goal	The bounded task for a single child session.
context	Extra background context appended to the child task.
label	Short display label for the delegated run.
child_role_id	Optional role id for the child session.
child_workspace_id	Optional workspace id for the child session.
timeout_seconds	Optional timeout for the child run.
requested_model_id	Optional model override for the child run.
tasks	Batch mode. Runs multiple child tasks in parallel.

Batch mode is capped by the subagent concurrency limit. The current built-in cap is three active child runs per parent session.

The tool returns structured JSON with per-child summaries, child session ids, and subagent run ids. The parent should use those summaries instead of exposing the child transcript directly unless the user asks for detail.

Child Session Isolation

A delegated child is an Anyy session with source subagent. It is stored and audited like other sessions, but it is scoped to its parent.

Important boundaries:

Boundary	Behavior
Transcript	The child has a separate transcript.
Depth	Child sessions cannot create another generation of child sessions.
Concurrency	A parent can have up to three active child runs.
Tools	Child tools are filtered by the parent-visible tool list and subagent deny rules.
Messaging	Messaging toolsets are denied in child sessions by default.
Memory and automation writes	High-impact child-side tools such as memory and automation mutation tools are denied by default.

delegate_task, background_job, subagent_list, subagent_history, and subagent_cancel are disabled inside subagent sessions.

Background Subagents

Use background_job when the user explicitly asks for work to continue in the background or to notify them when it finishes.

background_job starts an async child session and returns immediately with:

Field	Meaning
background_job_id	The gateway background job handle.
subagent_run_id	The child run id.
child_session_id	The child session id.
async	Always true for this path.

The runtime marks the job for completion notification. The user can keep using the parent session while the background child runs.

Admission Control

Anyy also has an admission path for natural-language requests that clearly ask for background or async agentic work.

The classifier keeps light lookups in the foreground. Mechanical long-running shell work is routed toward managed process jobs. Substantial async agentic work can become a background subagent.

This classifier is intentionally conservative. Asking "look up the weather" should not create a child session. Asking "research this in the background and notify me" can.

Control And History

The parent session can inspect and stop its child runs.

Surface	Entry points
Model tools	subagent_list, subagent_history, subagent_cancel
TUI	/background <prompt>, /agents
RPC	session.spawn, subagents.list, subagents.history, subagents.kill, subagents.steer

subagent_history returns a bounded transcript and status summary for one child run. subagent_cancel stops a running or accepted child run owned by the current session.

subagents.steer currently supports cancellation. Message and restart steering are recognized at the RPC boundary but return an unsupported-action conflict in this build.

Practical Guidance

• Delegate only tasks that are independent enough to run without constant parent interaction.
• Give each child a narrow deliverable: "summarize the migration tests" is better than "look around".
• Use background_job only when the user can continue without the result in the current reply.
• Keep sensitive or state-changing work in the parent unless the allowed tool policy and approval path are clear.

For job tracking, see Background Jobs. For the toolset that exposes delegation tools, see Toolsets.