Helper agents

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 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:

hansard agents spawn codex "Review the parser tests" --from <session>
hansard agents list --from <session> --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 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 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:

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

hansard agents status
hansard agents targets
hansard agents spawn fable "Review keyboard navigation in the settings screen."
hansard agents list --descendants
hansard agents message <agent-id> "Also check the narrow layout."
hansard agents wait <agent-id> --return-when all
hansard agents cancel <agent-id>

When the terminal is not running inside an agent session, add --from <session> 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 <harness> <task>	Starts a helper. See the options below.
hansard agents list	Lists the session’s helpers. --descendants includes helpers started by helpers.
hansard agents wait <agent-id>...	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 <agent-id> <message>	Sends a follow-up.
hansard agents cancel <agent-id>	Stops a helper.

Options for hansard agents spawn:

Option	Effect
--name <name>	Names the helper.
--model <model>	Chooses the helper’s model.
--effort <level>	Chooses the reasoning effort.
--permission-mode <mode>	Chooses a permission mode that still asks for review. See Permissions.
--cwd <path>	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. 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

Your sessionAsks Hansard for a helperhansard agents spawn

QueueRecords each helper before the runtime launches it

HelpersEach works in the same project

ResultsReturn once to the session that started them

• 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:

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.