Sub-agent Plugin

The bundled subagent plugin lets Chetty delegate work to child conversations, or run several child tasks as a workflow.

Agent types

Open Agents in the web interface to browse the built-in and custom agent types Chetty can delegate to. Built-in types cannot be edited; administrators can add, edit and delete custom ones, and every account can view the page.

Read Create a custom agent type for the fields, the tool modes and the per-account model choices.

The plugin adds no slash command. The /workflow prompt command is core behavior, described on Sub-agents & Workflows.

Delegation and workflow tools

Pass background: false to Delegate or WorkflowStart to wait for results. Otherwise the result arrives automatically before Chetty's next step if it is still working, or starts a new turn if it has finished. A child that has no conversation to deliver into waits by default.

A running tool finishes before its result is added, and a result never interrupts a tool. A follow-up to a running child steers its current work instead of starting a separate reply.

The result preserves the complete report and any later job or helper addenda in order. DelegateRead reads the latest answered task, including after a restart. DelegateResult with the original dlg-* handle keeps the original task's result even after a later continuation; with a session id it reads the latest task.

Do not poll for work that delivers its own result: use DelegateStatus for a one-time check, or DelegateResult if a delivery was missed.

Large child results and workflow summaries share the general tool-output limit. Above it, Chetty receives a short preview with the byte count and a file path, and reads the full answer from there. A failed save reports an explicit error with a DelegateRead hint rather than cutting the answer.

What a fresh child receives

A fresh child receives the assigned task, its role, the applicable account and project instructions, and the shared engineering guidance. It reports results and missing decisions to the parent conversation.

Include the background it needs in the task: a fresh child is given neither recalled memories nor this conversation. A fork keeps the parent's prompt, tools and history instead.

The built-in reviewer reports only concrete defects reachable through real callers, inputs or event sequences, and may return zero findings. It inherits tools so it can run permitted checks, while its instructions require it to leave the repository unchanged.

Limit a child’s access

A child cannot receive more access than the caller. Narrow it with read_only, tools or subagent_type, and choose a configured model or thinkingLevel.

• read_only removes the write and edit tools and restricts shell commands. Shell redirection can still write files, so it is a guardrail, not a security sandbox.
• The built-in explore and plan types are read-only: explore reports what it found, and plan returns a proposed implementation plan as its reply, which the caller writes into its own plan file. review inherits the caller's tools but changes nothing.
• An exact tools list from the caller's tools is accepted, and an empty list is refused.

The child inherits the caller's model, reasoning level and working directory unless the delegation selects otherwise.

An absolute cwd runs a child or a workflow node in another directory. A host-capable administrator may pick any readable directory, including another project or a linked Git worktree, while scoped callers stay inside their project and managed children inside their container. An unavailable directory is refused, and the permission ceiling still applies.

With fork: true the child inherits this conversation's prompt, tools and history. A fork cannot be combined with tools, read_only, subagent_type or cwd, and a different model gives up the shared prompt cache that makes a fork cheap.

Run a workflow

Write a JSON file before calling WorkflowStart, then pass its path. A workflow is either an array of nodes or an object with a nodes array and optional title, fork and background.

Every node needs a unique id and a self-contained task; the optional deps decide which handovers it receives, and independent nodes run in parallel. A node may also set its own model, thinkingLevel, tools, read_only, subagent_type, fork and absolute cwd.

A node should end with a ## Handover section, because each dependent receives only that short handover from each direct dependency, limited to 4,000 characters. Dependents of a failed node stay pending and never run.

If a workflow cannot prepare a complete dependency result or deliver its summary, it reports that problem separately. Resolve it, then use WorkflowResume, which keeps the completed node work.

Note: A workflow can have up to 128 nodes. Each task is limited to 16,000 characters and a longer one is rejected rather than cut; each id to 64 characters.

The workflow inspector

Open a workflow from the side panel of the conversation to see its inspector. Nodes appear as a graph in waves; select one to see its status, the nodes it depends on, its progress and its result or error, and to open its conversation. Stop workflow stops the workflow and its running nodes after you confirm.

Settings and limits

In Settings → Plugins, open the bundled subagent plugin to set:

Retention controls how long finished background results stay available, for workflows as well as for background delegations. The stall timeout interrupts a child with no tool or step activity, and DelegateContinue picks it up again; raise it for a long analysis that pauses without using tools.

Restart to apply

Saving these settings, or enabling or disabling the plugin, requests a Chetty restart. The screen reports that the change is saved and Chetty is restarting, and the new values apply after it.

Concurrency and recovery

The plugin can have up to 64 delegations in progress. When every sub-agent runner is busy, a background delegation waits in a queue and is reported as queued; stopping it removes it from the queue.

• A finished child can be continued after a daemon restart, but its live progress is no longer available.
• A workflow can add nodes only while it is running, and resume retries only unfinished nodes. Up to 16 workflows run at once.
• A daemon restart interrupts a workflow, and Chetty recovers it from its saved journal. Completed nodes stay complete and unfinished nodes are retried under current access checks.
• If recovery cannot verify access, or the journal is missing or invalid, Chetty reports that the workflow could not be resumed while other workflows still recover.
• A stored child error is clipped to 100,000 characters from the start. A long successful result stays readable through DelegateRead, which returns at most 50,000 characters per call, 8,000 by default.

Permissions

Enabling the plugin asks for consent for its workflow-dag capability. If consent is declined, the plugin stays installed but disabled.

Every account can choose its own model for a built-in agent; that choice is stored in the account's own settings and needs no administrator. Only administrators create, edit or delete custom agents, and every account can view the Agents page.

Normal account tool permissions and model restrictions still apply, and a workflow node inherits the adding caller's access without widening it.

Agents rail and sub-agent history

A conversation's side rail shows the delegated work it is waiting for. The Workflow section carries every running workflow with its finished and total node count; the Agents section carries the sub-agents whose results have not been collected yet.

Each row marks the model the child runs on and names the run with its elapsed time. A second line carries the child's latest status note beside the generation speed and the token count. Hover the name to read the delegation brief, and select the row to open the child's conversation.

The button on a running row stops that sub-agent together with everything it started. A collapsed rail shows a count whose popover carries the same rows.

The conversation's history offers a Sub-agents branch with the same runs as a tree of cards. Each card names the child or the workflow node, the model it ran on and its status; selecting a child's card opens its conversation, and Expand and Collapse show or hide the cards of the runs it started. A card whose branch was cut short says so.

Related guides

• Create a custom agent type
• Delegate a task to a sub-agent
• Dependent work in a workflow
• Sub-agents & Workflows