---
name: dispatch-background
description: Dispatches a long-running task to a maxv-* subagent in background via Claude Code's Agent View (`claude --bg`). Routes the task through `route-task` to pick the right agent, then forwards to `bin/maxv-dispatch run`. Use when the task is long-running and you want to keep the main session unblocked. The session appears as a row in `claude agents`.
when_to_use: |
  Trigger phrases: "/maxvision-orchestration:dispatch-background",
  "run this in background", "fire and check later",
  "execute this phase async", "dispatch to claude agents",
  "queue this work for later".
disable-model-invocation: true
argument-hint: <task description>
arguments: task
allowed-tools: Read Grep Glob Bash(test *) Bash(claude --version) Bash(claude --help) Bash(which claude) Bash(${CLAUDE_PLUGIN_ROOT}/bin/maxv-dispatch *) Skill(route-task)
---

# Dispatch background

Argument: `$task` (or `$ARGUMENTS`) — the task description. Forwarded
verbatim to `claude --bg --agent <chosen-agent>` after routing.

## Hard rules

1. **Manual confirmation required.** The skill picks an agent and shows
   the full `claude --bg` command line. The user must reply `sim` before
   anything is dispatched.
2. **One agent per invocation.** This skill dispatches ONE background
   session. For parallel fan-out across multiple agents, use `orchestrate`
   (which dispatches synchronously via Agent tool) or invoke this skill
   multiple times.
3. **Refuse when CC < 2.1.139.** Agent View requires Claude Code v2.1.139+
   (research preview). Abort with a structured error on older versions.
4. **Refuse interactive tasks.** Tasks that need turn-by-turn user
   input should run in the main session, not in background. If the task
   description starts with "ask me", "interactive", "step by step
   together", abort and recommend running in the main session.
5. **Never bypass `route-task`.** The skill always invokes `route-task`
   first to pick the agent, even when the user names one explicitly —
   `route-task` validates that the named agent matches the task.

## Render-time preflight

- claude binary present:     !`which claude >/dev/null 2>&1 && echo "OK" || echo "MISSING"`
- claude version:            !`claude --version 2>/dev/null | head -1 || echo "unknown"`
- maxv-dispatch present:     !`test -f "${CLAUDE_PLUGIN_ROOT:-/missing}/bin/maxv-dispatch" && echo "OK" || echo "MISSING"`

## Workflow

### 1. Honor preflight

Abort with structured error if any preflight check fails:

```json
{"status":"aborted","reason":"claude_missing|maxv_dispatch_missing|version_too_old","next_step":"<remediation>"}
```

### 2. Version gate

Parse the version string from the preflight output above. The format is
`<major>.<minor>.<patch> (Claude Code)`. Reject any version below
2.1.139 with:

```json
{"status":"aborted","reason":"agent_view_unavailable","version":"<observed>","required":"2.1.139+","next_step":"Run `claude update` and retry."}
```

### 3. Route the task

Invoke `Skill(route-task)` with `$task` as the input. Wait for the
JSON result. It returns a primary subagent recommendation plus
secondary agents.

For this skill, ONLY the primary agent is used. Secondary agents are
ignored — the user can fan out by invoking this skill again with a
different task framing.

### 4. Decide worktree isolation

Read the chosen agent's frontmatter from
`~/.claude/plugins/cache/maxvision-orchestration/*/agents/<name>.md`.
If the frontmatter declares `isolation: worktree`, no `--worktree`
CLI flag is needed (CC honors the frontmatter). Otherwise:

- If the task touches source files (Write/Edit-class work):
  recommend `--worktree`.
- If the task is purely read-only research/audit, no worktree.

### 5. Show dispatch plan + confirmation

```
About to dispatch a background session:

  Agent:        <primary-from-route-task>
  Task:         "$task"
  Worktree:     <yes-from-frontmatter|yes-recommended|no>
  Display name: <auto-generated from task first 5 words>
  Model:        <agent default | sonnet | opus | haiku>
  Permission:   <inherits cwd settings>

Equivalent shell:
  maxv-dispatch run <agent> "<task>" [--worktree] [--name=<short>]

This session will appear in `claude agents`. Token usage is per-session.

Proceed? [sim/skip]
```

Wait for explicit `sim`. On `skip`, exit 0 with `{"status":"skipped"}`.

### 6. Dispatch

Invoke `bin/maxv-dispatch run <agent> "<task>" [flags]` via the
`${CLAUDE_PLUGIN_ROOT}/bin/maxv-dispatch run ...` permission already
declared in `allowed-tools`. Capture the output — `claude --bg` prints
the session ID + management commands.

### 7. Report

Append a single log line to
`~/.claude/projects/<workspace>/maxv-orchestration.log`:

```
2026-05-16T21:00:00Z  dispatch-background  <agent>  <session-id>  task=<short>
```

Then report to the user:

```
✓ Dispatched. Session ID: <id>
  Watch:  maxv-dispatch status   (or `claude agents`)
  Attach: maxv-dispatch attach <id>
  Logs:   maxv-dispatch logs <id>
  Stop:   maxv-dispatch stop <id>
```

## Output JSON

```json
{
  "status": "dispatched",
  "agent": "<primary>",
  "session_id": "<short-id>",
  "worktree": <true|false>,
  "next_step": "Monitor via `maxv-dispatch status` or `claude agents`"
}
```

## Comparison with `orchestrate`

| | `orchestrate` | `dispatch-background` |
| --- | --- | --- |
| Coordination | Main thread (Skill body) | User via Agent View UI |
| Sync vs Async | Synchronous — returns after agents complete | Asynchronous — main thread continues immediately |
| Multi-agent | Wave-of-4 paralelo | One agent per invocation |
| Best for | Reports / recon / multi-domain analysis | Long-running plan execution, PR review, debug investigation |
| Token cost | Within parent session quota | Independent session quota |

Use `dispatch-background` when you would otherwise type `claude --bg
--agent <name> ...` manually. The skill validates the agent name,
applies route-task's selection logic, and surfaces the management
commands.