Task Agent → CLI Child Agent Pattern: Autonomous multi-turn CLI orchestration in Chamber

cli-child-agent-pattern.md

Task Agent → CLI Child Agent Pattern

A pattern for autonomous multi-turn CLI work in Chamber, using the task tool to orchestrate a cli_delegate session without manual polling.

The Problem

cli_delegate in safe mode runs a real CLI session with approval gates on every command. But it's multi-turn — it goes idle or awaits approval, and someone needs to keep checking on it, approving commands, and sending follow-ups. In a normal conversation, that means the user has to keep prompting the agent to check status. Terrible UX.

The Solution: Nest It

Use the task tool (background, general-purpose) as an autonomous orchestrator that manages the cli_delegate loop internally.

User (one prompt)
  → Agent (launches background task)
    → Task Agent (loops autonomously)
      → cli_delegate (safe mode, does the actual work)

What Each Layer Does

Layer	Role
User	States the goal once
Agent	Launches a background task agent with full context
Task Agent	Runs the orchestration loop: delegate → poll → approve → respond → repeat
CLI Child Agent	Investigates, writes code, runs commands, reports back

The Orchestration Loop

The task agent executes this cycle:

1. cli_delegate — spawn the CLI child agent with the problem statement and working directory
2. cli_status — poll for status (running / idle / awaiting_approval)
3. cli_approve — if awaiting approval, review the pending command and approve (allow_once) if safe
4. cli_respond — if idle, read the result; send follow-up instructions if more work is needed
5. Repeat until success criteria are met

Prompt Template

The prompt given to the background task agent needs five things:

1. **Context** — repo path, branch, what's broken, what you've already discovered
2. **Instruction to use cli_delegate** — specify cwd and permission_mode ("safe")
3. **The loop workflow** — delegate → poll → approve → respond → repeat
4. **Success criteria** — e.g., "keep going until the test is green"
5. **Reporting** — "report back with what you did and the final status"

Example Prompt

You're working in C:\src\my-repo on branch `feature/fix-tests`.

There's a failing test at `tests/e2e/smoke.spec.ts`. It fails because [description of the problem].

Your job: use cli_delegate (with safe mode, cwd: "C:\src\my-repo") to investigate and fix this.

Workflow:
1. cli_delegate to the child agent with instructions to investigate and fix
2. Poll with cli_status until it's idle or awaiting_approval
3. If awaiting_approval: review the pending command, approve with cli_approve
   (allow_once) if it's safe, reject if it's off-track
4. If idle: read the result, send follow-up with cli_respond if more work needed
5. Repeat until the test passes

Report back with the final status and what was done.

Launching It

# From the main agent conversation:
task(
    agent_type="general-purpose",
    mode="background",
    name="descriptive-name",
    description="Short description",
    prompt="<the full prompt above>"
)

The agent gets one notification when the task agent finishes. No polling, no manual prompts.

Why This Works

• Task agent is a full general-purpose agent with access to cli_delegate, cli_status, cli_approve, cli_respond
• Background mode means it runs to completion autonomously
• Safe mode is preserved — the task agent reviews and approves each command
• User interacts twice: once to request, once to review results

When to Use This

• Fixing tests, builds, or lint errors in a repo
• Investigating and resolving CI failures
• Refactoring tasks with validation
• Any multi-step CLI work where you want human-reviewable approval logic but don't want to be the human in the loop

Portability

Any agent on any machine with access to task and cli_delegate tools can run this pattern. The only things that change per-use:

• Working directory (cwd)
• Problem description and context
• Success criteria