Delegate to helper agents

Hansard lets a live Codex or Claude Code session launch and coordinate helper sessions in other local agent harnesses. New setup enables bounded same-project delegation by default, needs no skill or manual link, and keeps every helper attached to its parent.

Choose the setup default

The init and config-setup pickers preselect both live session messaging and same-project helper launches. Messaging is the master switch: unchecking it disables both surfaces, while unchecking only helper launches keeps messaging. For unattended setup, disable both with:

hansard init --yes --no-agent-collaboration

Use these controls to repair or change an existing installation:

Viewer
Terminal

Open Settings → General → Helper launches, then choose Same project. Restart existing Codex and Claude sessions once so their MCP tool lists include delegation and messaging.

hansard agents setup

Setup enables the same-project policy and updates Hansard’s existing Codex and Claude MCP entries. Use hansard agents setup off to disable only helper launches. Restart existing sessions after a tool-list change.

Delegation setup also enables live session messaging. Parents and children use that bounded channel for questions, answers, and dependency updates.

Choose a harness

Target	What starts
`codex`	A new Codex session.
`fable`	A Claude Code session with model `fable`.
`claude`	A new Claude Code session.
`grok`	A new Grok Build session.
`antigravity`	A new Antigravity session.
`opencode`	A new OpenCode session.

The target must be installed and available locally. Cursor CLI and Gemini CLI remain historical import sources rather than live helper targets.

Use the viewer

Select Agent sessions from the bottom of the viewer sidebar.
Choose the live Codex or Claude session that will own the helpers.
In Helpers, select a harness, give it one concrete task, and choose Launch.
Follow direct and nested helpers from their cards. Send a follow-up when a task changes, or cancel queued and running work that is no longer needed.
After provider history imports, choose Open transcript on a completed helper card.

The settings and mutation routes use the viewer’s normal authentication, loopback, and read-only boundaries.

Ask an agent to delegate

After setup, Codex and Claude receive these MCP tools:

list_agent_targets
spawn_agent
list_agents
wait_agents
message_agent
cancel_agent

Natural instructions such as “use Fable to review the interaction and another Codex to audit the tests” are enough. A helper receives the same tools and may launch a nested helper within the configured depth and fan-out limits.

Use the CLI

hansard agents targets
hansard agents spawn fable "Review the keyboard and narrow-screen paths."
hansard agents list --descendants
hansard agents message <agent-id> "Also check reduced motion."
hansard agents wait <agent-id> --return-when all
hansard agents cancel <agent-id>

When the terminal is not attached to an agent session, pass --from <session> to select the parent. Use --json for machine-readable output. Run hansard help agents for the complete command and flag list.

Scheduling, lineage, and recovery

Hansard records the parent session, parent helper, depth, native provider session, current run, eventual archived transcript, status, and final result. The native session identity is attached at session start, so a running Fable helper can launch a child without losing its place in the tree.

Provider work is capped by orchestrate.maxActiveRuns, which defaults to two. Overflow waits in a durable queue. Restarting the viewer or MCP process reconciles active runs and resumes the queue. Waiting can return on the first or all selected helpers; a timeout leaves the helpers running.

Follow-ups steer an active persistent Codex or Claude turn when supported. Other harnesses resume at the next turn boundary. Only the owning parent or an ancestor can inspect, message, wait for, or cancel a helper. Bounded local control requests carry steering and cancellation to the process that owns the run, so a root can still control a nested helper owned by Fable’s MCP process.

Herdr compatibility boundary

Delegation uses Hansard’s orchestrator, provider adapters, run ledger, queue, and archive reconciliation. No Herdr source is vendored or copied. A separately installed Herdr CLI may be used by the peer-messaging compatibility adapter for guarded discovery and text delivery; it does not launch, schedule, own, or recover delegated helpers.

Disable helper launches

Choose Off in Settings or run:

hansard agents setup off

Ordinary peer messaging can remain enabled. Existing sessions may display the tools until restarted, but the off policy rejects calls immediately. To disable messaging and helper launches together, use hansard config setup --no-agent-collaboration or choose Off for both General settings.

Example: Codex and Fable coordinate a helper tree

The ids and paths below are synthetic. The transcript is abbreviated but uses the shipped tool and result shapes.

User → Codex
Use Fable to review the agent panel and another Codex to audit its tests.
They may delegate further. Keep the work bounded.

Codex → spawn_agent
  harness: fable
  name: Interaction reviewer
  task: Review keyboard flow, narrow layouts, reduced motion, and status copy.
Tool → Codex
  agent_id: 00000000-0000-4000-8000-000000000001
  provider: claude_code
  model: fable
  depth: 1
  status: running

Codex → spawn_agent
  harness: codex
  name: Test auditor
  task: Audit API, ownership, queue, and viewer contract tests.
Tool → Codex
  agent_id: 00000000-0000-4000-8000-000000000002
  status: running

Fable → ask_session
  peer: codex:00000000-0000-4000-8000-000000000101
  question: Should the launch form expose dangerous permission modes?

Codex → reply_message
  message_id: 00000000-0000-4000-8000-000000000201
  reply: No. Show safe modes only, and reject bypass values on the server.
Tool → Fable
  answer: No. Show safe modes only, and reject bypass values on the server.

Fable → spawn_agent
  harness: codex
  name: Keyboard specialist
  task: Trace focus order and shortcuts in the compiled viewer.
Tool → Fable
  agent_id: 00000000-0000-4000-8000-000000000003
  parent_agent_id: 00000000-0000-4000-8000-000000000001
  depth: 2
  status: queued

Codex → message_agent
  agent_id: 00000000-0000-4000-8000-000000000001
  message: Also verify dark-theme status colors against shared tokens.
Tool → Codex
  steering: true

Codex → wait_agents
  agent_ids: [Interaction reviewer, Test auditor]
  return_when: all
Tool → Codex
  Interaction reviewer: complete — keep helpers inside Agent sessions and use
                        a dedicated General setting.
  Test auditor: complete — API, queue, ownership, and viewer guards pass.
  Keyboard specialist: complete — focus, shortcuts, and reduced motion pass.

Codex → User
Fable's interaction review and nested keyboard audit passed. The independent
Codex audit passed too. Completed helper transcripts are linked from the drawer.