Subagents and coding jobs

Subagents and coding jobs

The agent can delegate work: spawn child agent runs it supervises, and hand coding tasks to headless Claude Code or Codex CLIs — either attended (streaming into your chat) or as fire-and-forget background jobs. You watch and control all of it from the Agents tab of the web interface.

The Agents tab

Open Agents (Ctrl+5 by default) to see every delegated child run under the persistent host. For each run you can:

• Approve or deny its parked actions — a child hitting the approval gate waits for you, exactly like an unattended run (see Autonomy and approvals).
• Answer questions — when a child calls ask_operator, only that run pauses; siblings and the lead keep going. Runs waiting for text show the question and an answer box.
• Steer — queue a directive for an active run. It is appended to the run's transcript as an operator directive at the next turn boundary; it never interrupts a tool call already executing.
• Cancel the run.
• Inspect events — drill into each run's recorded event stream.

The same controls exist from the terminal:

holaryn status                     # host + task overview
holaryn question list              # pending questions
holaryn question answer <id> "Use README.md"
holaryn steer <session-id> "Focus on the approval failure"

Child agent runs

When the lead agent runs inside holaryn serve, it has a delegate tool that spawns child runs (one task or a tasks array). Each child runs under a session id like {parent}/sub:{n}. Children inherit the parent's autonomy posture and policy but can never become more permissive, delegation depth is capped at 1, and concurrency at 4. Child approvals land in the same parked-approval store, labelled by child session id. Live child runs are resumed from the run journal after a host restart.

Coding delegation: delegate_coding_task

The agent can conduct Claude Code and OpenAI Codex as subordinate coding agents. Tell it something like "write this code in D:\projects\photo-tools — use Claude Code" and it hands the task to the headless CLI, streams the coder's progress live into your chat, and reports back with the result and a session id for follow-up rounds. The agent's own model is the dispatcher; the coding CLI burns its own subscription or API usage.

Setup

Install and sign in to each CLI separately, on the machine running Holaryn:

In Settings → Configuration, pick the default Coding agent (HOLARYN_CODING_AGENT) and, if the CLIs are not on PATH, set the Claude Code CLI path / Codex CLI path (HOLARYN_CLAUDE_BIN / HOLARYN_CODEX_BIN). The tool is always registered; if the CLI is missing you get an error with install instructions, not a silent failure.

Using it

• "Delegate to Claude Code: add input validation to the signup form. Work in D:\apps\web."
• "Use codex for this: profile the slow test and fix it."
• Every result includes session: <id> — say "tell it to also add tests" and the same coding session continues with full context.

Permissions

Two gates stack. First, delegate_coding_task is irreversible (category coding.delegate), so it is ask-first at the default posture. Second, the permission_level argument maps onto the child CLI's own permission system:

full disables the child's own gate, so it is only allowed under the unrestricted posture in an attended session. Delegations default to 900 seconds (max 3600); on timeout the whole child process tree is killed.

Background coding jobs

Under holaryn serve, extra tools turn delegation into fire-and-forget:

• start_coding_task — same arguments as delegate_coding_task, but returns a job id (cj_...) immediately. When the job finishes, a notice is posted back to the chat that started it (web chats get a live bubble or a stored notice; Telegram-origin jobs get a bot message). permission_level: full is never allowed here — background jobs are unattended by definition.
• check_coding_job — status, progress tail, and result for one job or a list of recent jobs. Always the source of truth for a job's outcome.
• steer_coding_job — redirect a running claude-code job mid-run (see Steering a running job).

Steering a running job

A running claude-code job can be redirected without cancelling it: the steering message is delivered to the coder as its next instruction, with the session's full context. The coder's current step may finish first; each delivered steer shows up as a steer: … line in the job's progress.

Three ways to steer:

• The steer_coding_job tool (ask-first at the default posture, same as starting a job).
• The web Agents page → Coding jobs card's Steer… action (shown only on steerable jobs).
• The CLI: holaryn coding-jobs steer <cj_id> "skip the refactor, just fix the test".

Codex jobs cannot be steered — the Codex CLI accepts no mid-run input. Use the cancel-and-resume recipe instead: cancel_coding_job, then start a new job with session_id set to the cancelled job's child session and the corrected instructions.

Cancelling jobs

Three ways to cancel a running job:

• The cancel_coding_job tool (ask-first at the default posture — uncommitted work may be lost). The child session id survives, so a follow-up job can resume where the coder left off.
• The web Agents page → Coding jobs section — one card per job with status and progress, and a confirm-gated Cancel on running jobs.
• The CLI:

holaryn coding-jobs list             # recent jobs, straight from the state dir
holaryn coding-jobs steer <cj_id> "<message>"   # redirect a running claude-code job
holaryn coding-jobs cancel <cj_id>   # cancels through the running host

The JSON API mirrors these: GET /api/operator/coding-jobs, POST /api/operator/coding-jobs/steer, and POST /api/operator/coding-jobs/cancel.

Concurrency

At most Max concurrent coding jobs run at a time (HOLARYN_CODING_MAX_CONCURRENT, default 2, applied on host restart); further jobs queue.

Mutating background jobs default to a unique, durable isolated Git worktree; safe jobs default
to read_only. The start result and completion notice include the retained worktree_id. Review
and integrate it with the Code Workspace panel or holaryn worktree; a successful coding job
does not silently merge or delete its checkout. Advanced callers can select current, existing,
or read_only, resume a retained worktree_id, set a target branch, or provide explicit named
repository-root mappings. See Isolated coding worktrees.

Restarts

The host cannot reattach a headless CLI that was running when it stopped — such jobs are marked orphaned, but the record keeps the child session id so you can continue with session_id=... in a new job.

Recurring coding jobs can be scheduled — see Scheduler and automation.

Related pages

• Agent Teams — named agents collaborating over a durable bus, including coding-CLI team members.
• Autonomy and approvals — how the approval gate applies to delegated work.