# Helper agents > Let a supported live agent session start helper agents in local harnesses, steer them, and collect their results. Identified agent sessions with Hansard tools can start helper agents in supported harnesses on your machine, give each one a task, and collect the results. Use helpers to get a second opinion from another model or to split a large task into parallel parts. Helpers work in the same project as the session that started them, and helper launches are on by default. Run `hansard integrations sync` to refresh existing integrations, then restart open clients. Explicit off settings are preserved. - App: **Settings → Handoff & helpers → Helper agents** - CLI: `hansard agents` ## Coordinate a project Open a project's overview to keep a continuing coordinator conversation in Codex or Claude Code; **Settings → Coordinator** chooses the harness, model, effort, and helper budget for every project. It receives updates about recent conversations, live peers, reported blockers, and delegated work. Setup instructions are retained across turns and viewer restarts; only changed context accompanies later messages. Use **Scratchpad** to save, edit, or delete preferences and decisions. A routing rule can specify the harness and model for a type of work. The coordinator can save an explicit preference from the conversation and flag a newer model for review. A suggestion leaves the saved rule unchanged until it is edited and saved. Use **Task plan** to set the objective, task owners, file scopes, dependencies, blockers, and acceptance criteria. The coordinator edits the same plan through `coordinator_plan` and assigns a task with `spawn_agent`'s `plan_task_id`. Overlapping assigned file scopes block another launch, including while a worker is queued. Tasks with unfinished dependencies cannot launch. A finished worker leaves its task in **Needs review**. Edit the task to record a successful command from a coordinator or worker run, identify the files checked, and explain which criterion it establishes. **Mark verified** requires evidence for every criterion. Changes to recorded files or the worker attempt invalidate verification. Provider summaries alone cannot verify a task. An interrupted worker offers **Inspect and resume**, including after Hansard restarts, since workers do not resume on their own. Select it to request an inspection of existing work before continuation. Reloading cannot launch the same recovery twice, and Hansard never replays previous commands automatically. Large provider output stays in private files. A tool card loads its full result from the saved copy when it opens, and a finished message shows its full text. There is no default cumulative output cutoff. Malformed frames and the emergency per-frame storage ceiling still fail the affected conversation; corrupted frames without a conversation identity close the shared transport. Oversized control requests fail without approving truncated commands. These changes require no reimport or archive rebuild. Workstreams link directly to worker conversations. **Threads** beside the coordinator chat show each helper's status and result, and open its conversation or live run. A completed worker still needs its evidence checked against the assignment. New helper conversations use task titles. After upgrading, restart the viewer. To refresh older inferred titles or Hansard prompt wrappers, run `hansard rebuild --since all`; explicit conversation names are preserved. ## Set up helper launches in the app 1. Open **Settings → Handoff & helpers**. 2. Turn on **Helper agents**. If the row shows **Set up**, select it to add the helper tools to detected supported agents. Turn the switch off to stop sessions from starting helpers. 3. Restart existing agent sessions once so they load the helper tools. Helpers use [agent messaging](https://www.hansard.dev/guides/session-messaging/) to ask questions and report back, so turning helper launches on also turns on messaging. ## Launch a helper from a terminal A helper belongs to the session that starts it, so the app does not launch helpers on a session's behalf. An agent starts one with `spawn_agent`; from a terminal, name the owning session with `--from`: ```sh hansard agents spawn codex "Review the parser tests" --from hansard agents list --from --descendants ``` `hansard agents message` changes a helper's task and `hansard agents cancel` stops it. If helper launches are off, turn on **Helper agents** in Settings, **Handoff & helpers**. See [Supported harnesses](https://www.hansard.dev/guides/agent-delegation/#supported-harnesses) for the harnesses you can choose. ## Ask an agent to use helpers Every managed integration installs these tools by default: | Tool | What it does | | -------------------- | ----------------------------------------------------------------------------------------------------------- | | `list_agent_targets` | Lists the harnesses available as helpers, with the models, efforts, and safe permission modes each accepts. | | `spawn_agent` | Starts a helper with a task. | | `list_agents` | Lists this session's helpers and their status. | | `wait_agents` | Waits for one or all of the listed helpers to finish and returns their results. | | `message_agent` | Sends a follow-up to a helper. | | `cancel_agent` | Stops a helper. | Helper lists and wait results include identity, state, and previews that fit an 8 KB response. `list_agents` with `agent_id`, `field`, and `offset_chars` reads a full task, result, or error in successive windows. An approval, sandbox escalation, or question reaches the parent as a notice. `list_agents` and `wait_agents` report it as `waiting_on`, and a pending wait returns when one appears. Only the person answers, in [Review](https://www.hansard.dev/guides/review/) or at the agent's own prompt. After `orchestrate.messaging.askTimeoutMs`, five minutes by default, Hansard declines an unanswered request and asks the helper to continue without it. Hansard MCP calls answer within 120 seconds, except `ask_session`, `ask_user`, and `wait_agents`, which answer within 30 minutes and 30 seconds. A call past its limit returns `tool_timeout`, though work already under way may still take effect. Ask in plain language. For example: "Use Fable to review the settings screen, and start another Codex session to check the tests." A helper with its managed integration has the same tools and can start helpers of its own, up to the depth limit. Codex and Claude Code sessions also get four tools for the project's visible agents, the ones on the [project page](https://www.hansard.dev/guides/projects/#start-and-message-the-projects-agents): | Tool | What it does | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | `start_agents` | Starts visible conversations in installed harnesses, in a new terminal tab or in Hansard, or resumes agents that stopped. | | `deliver_message` | Sends exact words to one agent or several and reports for each one whether they were read, delivered, queued, or failed. | | `roster` | Reads the project's agents, their state, and their tokens and estimated cost, and the events the watcher recorded. | | `ledger` | Keeps the project's workstreams, decisions and approvals, follow-ups, and watches. Only you answer a decision. | A helper belongs to the session that started it and returns its result to that session once. An agent started with `start_agents` is a visible conversation of its own, which you can open and steer like any other. ## Manage helpers from the CLI ```sh hansard agents status hansard agents targets hansard agents spawn fable "Review keyboard navigation in the settings screen." hansard agents list --descendants hansard agents message "Also check the narrow layout." hansard agents wait --return-when all hansard agents cancel ``` When the terminal is not running inside an agent session, add `--from ` to choose the session that owns the helpers. Every command accepts `--json`. | Command | What it does | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `hansard agents setup [same-project\|off]` | Turns helper launches on or off and updates every detected or existing managed integration. | | `hansard agents status` | Shows the mode, active and queued runs, and whether the tools are installed. | | `hansard agents targets` | Lists the helper harnesses available to the session. | | `hansard agents spawn ` | Starts a helper. See the options below. | | `hansard agents list` | Lists the session's helpers. `--descendants` includes helpers started by helpers. | | `hansard agents wait ...` | Waits for helpers to finish. `--return-when any` returns after the first one. `--timeout-ms` sets the wait, up to 30 minutes. | | `hansard agents message ` | Sends a follow-up. | | `hansard agents cancel ` | Stops a helper. | Options for `hansard agents spawn`: | Option | Effect | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | Names the helper. | | `--model ` | Chooses the helper's model. | | `--effort ` | Chooses the reasoning effort. | | `--permission-mode ` | Chooses a permission mode that still asks for review. See [Permissions](https://www.hansard.dev/guides/agent-delegation/#permissions). | | `--cwd ` | Runs the helper in another folder of the same project. | ## Supported harnesses | Harness | What starts | | ------------- | ------------------------------------------------------ | | `codex` | A new Codex session. | | `claude` | A new Claude Code session. | | `fable` | A new Claude Code session that uses the `fable` model. | | `grok` | A new Grok Build session. | | `antigravity` | A new Antigravity session. | | `opencode` | A new OpenCode session. | | `cursor` | A new Cursor CLI session over `cursor-agent acp`. | | `devin` | A new Devin session over ACP. | All managed integrations can start helpers, including sessions opened outside Hansard. Clients without native identity hooks must first use explicit session binding. See the [complete provider table](https://www.hansard.dev/reference/provider-support/). Only the targets above can be launched as new helpers; adding MCP to another client does not add a launch adapter. A helper harness must be installed on this device, and `hansard agents targets` lists the ones that are available. To limit which harnesses can be used, set `orchestrate.delegation.providers`, for example `hansard config set orchestrate.delegation.providers codex,claude_code`, or turn individual harnesses off with `orchestrate.delegation.disabledProviders`. Hansard records the harnesses turned off, so a newly supported harness becomes available to helpers once it is installed. ## How helpers run - Each helper belongs to the session that started it. Only that session, or a session above it in the tree, can message, wait for, or cancel it. - A follow-up reaches a running Codex or Claude Code helper during its current turn. Other harnesses receive it at the start of their next turn. - When a wait times out, the helpers keep running. - Independent conversations and helpers run concurrently without a run-count cap or elapsed-time deadline. Each native conversation keeps one active writer. The durable queue preserves launch ownership and paused project work across app and agent restarts. The former `orchestrate.maxActiveRuns` setting is ignored. Restart the viewer after upgrading; no reimport is needed. These settings control the limits: | Setting | Default | Allowed range | Limits | | --------------------------------------------- | -------------------- | ---------------- | ------------------------------------- | | `orchestrate.delegation.maxChildrenPerParent` | 12 | 1 to 100 | Helpers one session can start. | | `orchestrate.delegation.maxDepth` | 3 | 1 to 8 | Levels of helpers started by helpers. | | `orchestrate.delegation.maxQueued` | 32 | 1 to 500 | Helpers waiting to start. | | `orchestrate.delegation.waitTimeoutMs` | 1800000 (30 minutes) | 10000 to 1800000 | Longest wait for results. | Change a limit with `hansard config set`, for example `hansard config set orchestrate.delegation.maxDepth 2`. ## Permissions Helpers keep their harness's normal permission prompts. Hansard refuses any permission mode that skips review. | Harness | Allowed modes | Default | | --------------------- | ---------------------------------------- | ------------------------------------------------- | | Codex | `read-only`, `workspace-write` | `workspace-write` | | Claude Code and Fable | `default`, `plan`, `acceptEdits` | `acceptEdits` | | Grok Build | `default`, `plan`, `acceptEdits` | `acceptEdits` | | Antigravity | `request-review`, `plan`, `accept-edits` | `accept-edits` | | OpenCode | Uses OpenCode's own settings. | | | Cursor CLI | `agent`, `plan`, `ask` | `agent`, under the Cursor CLI's own approval mode | > **Caution:** A task from another agent is not your approval. A helper cannot use its > parent's task to approve tools, change configuration, or take actions outside > the project that its own permission settings would not allow. ## Turn off helper launches In the app, turn off **Helper agents** in **Settings → Handoff & helpers**. From the CLI: ```sh hansard agents setup off ``` Agent messaging stays on. Restart open sessions to remove the helper tools from their tool list. Sessions that still show them are refused. To turn off messaging and helpers together, run `hansard peers setup off`, or `hansard config setup --no-agent-collaboration`. ## Troubleshooting **"the selected helper harness is unavailable".** The harness is not installed or not found on this device. Run `hansard agents targets` to see what is available. **"the source session has reached its helper limit" or "the delegated-agent depth limit has been reached".** Raise `orchestrate.delegation.maxChildrenPerParent` or `orchestrate.delegation.maxDepth`, or reuse an existing helper with a follow-up. **"helper working directory must be in the source project".** `--cwd` points outside the session's project. Choose a folder that belongs to the same project. **"agent delegation is off".** Turn on **Helper agents** in **Settings → Handoff & helpers**, or run `hansard agents setup`. Then restart the session.