Sub-Agents

Sub-agents are child agent instances spawned by the harness to run a scoped task with a restricted toolset. Each runs in its own Zellij pane and communicates with the parent through files on disk.

Source: crates/core/src/subagent.rs, crates/core/src/spawn.rs, crates/core/src/subagent_config.rs.

How spawning works

The parent calls the built-in spawn_subagent tool. The harness then:

1. Writes the task to prompt.md and the filtered tool manifest to tools.json in a new directory under <cowboy_dir>/subagents/.
2. Spawns a new plugin instance via Zellij’s load_new_plugin() (a visible pane, load_in_background: false, skip_plugin_cache: true), passing a JSON-encoded SubagentConfig under the subagent_config key.
3. The child, on its first heartbeat tick, writes a lock file and its pane_id, reads prompt.md + tools.json, and processes the prompt as a user message.
4. When the child finishes, it writes response.md and removes lock.
5. The parent detects completion on its heartbeat poll and injects the response back into its own conversation.

WASM cannot write files directly, so all disk I/O is funneled through shell commands the harness emits and Zellij executes.

Directory layout

Each sub-agent gets a directory named <type>-<short_uuid>:

<cowboy_dir>/subagents/<type>-<id>/
  prompt.md     # task + metadata, written by parent
  tools.json    # filtered tool manifest, written by parent
  lock          # present while running, written by child
  pane_id       # Zellij pane id, written by child
  response.md   # final output, written by child on completion

<cowboy_dir> is $HOME on a ranch install and $XDG_DATA_HOME/cowboy (default ~/.local/share/cowboy) in lite mode.

Sub-agent types

Three types are defined in the SubAgentType enum. Each restricts the tools the child may call:

Research and Review are read-only with respect to the filesystem; only Code gets write and the hashline edit tool.

Models

SubagentConfig::cheap_defaults() picks an inexpensive model so sub-agents are cheap to run. The default per provider:

The selection falls back to the main harness provider/model, then to the first available keyed provider.

Status

The parent tracks each child with the SubAgentStatus enum:

• Starting — directory created, pane spawning
• Running — lock present
• Completed — response.md present, lock removed
• Failed(String) — lock removed without a response.md

Polling happens on the heartbeat timer.