Launch a subagent for complex multi-step tasks autonomously.

Available subagent types are listed below this description (the registry
appends them at request time per-agent).

# Script structure
#   - Multi-line: one command per non-blank line, set-e on first failure
#   - "double" quotes preserve literal LF and process \" \\ escapes
#   - 'single' quotes are verbatim
#   - <<EOF heredoc body is fully verbatim (no escape, no $vars)
#   - # starts a line comment to end-of-line (quoted # is literal text)
#   - $vars are preserved as literal text (no expansion)

# block until done, return the subagent's final message inline:
    actor run <subagent_type> "<description>" "<prompt>" [--model <ref>] [--actor <id>] [--timeout <ms>] [--command <cmd>] [--context none|state|full] [--output-schema '<json>']
    # bind it to one of your `task` tool tasks (TID from the `task` tool, e.g. T4):
    actor run <subagent_type> "<description>" "<prompt>" --task <TID>

# return actor_id immediately, run independently:
    actor spawn <subagent_type> "<description>" "<prompt>" [--model <ref>] [--actor <id>] [--command <cmd>] [--context none|state|full] [--output-schema '<json>']
    # bind it to one of your `task` tool tasks (TID from the `task` tool, e.g. T4):
    actor spawn <subagent_type> "<description>" "<prompt>" --task <TID>

# block on a previously-spawned actor's result:
    actor wait <actor_id> [--timeout <ms>]

# inspect / control:
    actor status <actor_id>     # current state without blocking
    actor cancel <actor_id>     # graceful stop

# deliver a message to another actor's inbox (fire-and-forget):
    actor send <to_actor_id> "<content>" [--session <id>] [--type <t>]
    # to_actor_id: 'main' for a session's main agent, or a subagent id like 'explore-1'
    # --session: target session id (defaults to current); --type: 'text' (default) or 'actor_notification'
    # (--task is NOT valid here — it applies only to run/spawn for tying a subagent to a task_id)

Examples:
    actor run explore "Find error recovery" "Scan src/parser.ts for catch blocks. Return file:line."

# pick a model/tier for this subagent (group name like ultra/standard/lite, or a literal provider/model):
    actor run explore "Quick scan" "find catch blocks" --model lite

# tie this subagent to a task — pass a TID the `task` tool returned this session
# (e.g. T1). On completion the postStop hook validates tasks/<TID>/progress.md.
# An unknown or malformed TID is ignored and the subagent runs ad-hoc:
    actor spawn general "Implement auth" "build the login flow" --task T1

# any multi-line prompt — heredoc body is verbatim (no escape needed for " \ $ #):
    actor run general "Type checker review" <<EOF
    Read docs/spec.md §3 then src/types.ts.
    Report missing implementations + coverage gaps.
    Regex check: /\bnew \w+Provider\b/  (paths like C:\Users\... are fine)
    Format: { missing_implementation: [...], coverage_gaps: [...] }.
    EOF

# parallel investigations: spawn three, then optionally wait or let notifications deliver:
    actor spawn explore "Q1" "search for catch blocks"
    actor spawn explore "Q2" "search for type narrowing"
    actor spawn explore "Q3" "search for test fixtures"

# fire-and-forget when you don't need the result inline:
    actor spawn general "Background log collection" "..."

# run/spawn flags: --actor resume a prior subagent (by actor_id); --timeout ms before
#   giving up (run only); --command the command that triggered this; --context none|state|full
#   (default none); --output-schema a JSON Schema STRING (single-quote it) — forces the
#   subagent to return a matching object instead of free text.

When to use what:
    run    — single delegation where the result drives your next step
    spawn  — fan-out for parallel work, OR fire-and-forget background tasks
    wait   — pick up a previously-spawned actor's result on demand
