subagent: add status tool, cut docs down to operator-facing + no cli flags

claude-plugins/plugins/base/skills/claude-subagents/SKILL.md

@@ -7,7 +7,7 @@ description: Spin up a short-lived headless `claude` sub-instance to grind throu
 
 A sub-instance you spawn inherits the same filesystem and credentials you
 have. This is a first-class tool for offloading a bounded, mechanical
-batch - not a hack.
+batch.
 
 ## When to use it
 
@@ -20,72 +20,26 @@ batch - not a hack.
 
 ## The `subagent` MCP tools
 
-Your container's `subagent` MCP server (`hive-subagent-daemon`) is this
-skill's recipe as MCP calls — no manual shell-wrapping, no hand-rolled
-backgrounding:
+Your container's `subagent` MCP server (`hive-subagent-daemon`) runs this
+skill's recipe for you:
 
 ```
 start(name, prompt_file, model?, trigger?)
 continue(name, prompt, model?)
+status(name)
 interrupt(name, force?)
 ```
 
-`name` ↔ `--name`, `model` ↔ `--model`, `prompt_file` ↔
-`--append-system-prompt-file`, `trigger`/`prompt` ↔ `-p`. `start` returns
-once the process is confirmed running, not once it finishes — a
-completion lands as a todo (`get_loose_ends`), same as any other producer.
-There's no `status` poll: check on a subagent by `continue`-ing it (refused
-while it's still running, which is itself the "still going" signal) or by
-reading its completion todo. `interrupt` genuinely stops a running turn
-(`force: true` for SIGKILL) — unlike bash tasks' `kill`, this isn't
-limited to a still-pending state.
+`start` and `continue` return as soon as the process is confirmed
+running, not once it finishes — a completion lands as a todo
+(`get_loose_ends`), same as any other producer. Use `status` for a
+zero-cost "is it still going" check; reach for `continue` only once you
+actually have a new instruction for it, since that spends a turn.
+`interrupt` genuinely stops a running turn (`force: true` for SIGKILL).
 
-Everything else in this skill (model choice, prompt hygiene, splitting
-big batches, verify-then-report) applies unchanged; only the launch
-mechanics differ from a raw shell invocation.
-
-No `subagent` MCP server on this container? Fall back to the manual
-command below — same recipe, you drive the backgrounding yourself.
-
-## The spawn command (manual fallback)
-
-Put the task recipe in a file and pass it as a path, with a short `-p`
-trigger:
-
-```bash
-claude --name <memorable> --model <cheaper-than-you> --dangerously-skip-permissions \
-       --append-system-prompt-file task-prompt.md \
-       -p "Carry out the task described in your instructions."
-```
-
-- **`--name <memorable>`** - names the session so you can `--resume` it
-  by name for follow-ups.
-- **`--model <cheaper-than-you>`** - think about which model the task
-  actually needs; don't spend a bigger model's tokens than your own on
-  mechanical work a cheaper one handles fine. Never use a _bigger_ model
-  than yourself for a sub-agent - if the task needs that much capability,
-  it's not the "mechanical batch" case this skill is for.
-- **`--dangerously-skip-permissions`** - required in headless (`-p`)
-  mode. Without it, tool calls that would normally prompt for approval
-  are auto-**denied** non-interactively, so the sub-agent silently does
-  nothing. Acceptable here because the sub-instance runs inside your
-  already-sandboxed environment, with your already-scoped credentials,
-  on a bounded task - don't reach for it when the task could touch
-  things outside its intended blast radius.
-- **`--append-system-prompt-file <path>`** - read the recipe from a
-  file rather than inlining it in `-p` (which is bounded by `ARG_MAX` -
-  a long recipe passed as `-p "$(cat …)"` can blow past it and the exec
-  fails). Keeps Claude Code's default scaffolding and adds your recipe
-  on top.
-- **`-p "<trigger>"`** - headless print mode. Keep this short: just
-  tell the sub-agent to act on its file-supplied instructions.
-
-## Run it in the background, don't babysit
-
-Wrap the launch in a background bash task and end your turn - your
-bash-task runner already captures stdout/stderr and hands you a
-completion pointer, and ending the turn keeps you reachable for other
-work while the sub-agent grinds.
+Model choice, prompt hygiene, splitting big batches, verify-then-report —
+everything else in this skill — applies exactly the same whether you're
+calling the tool or thinking through the recipe by hand.
 
 ## Prompt hygiene - this is where batches succeed or fail
 
@@ -121,10 +75,9 @@ running at once instead of handing the whole thing to one.
   different files never race on the same working tree or index. For a
   non-git batch (issue relabeling, API calls), independent items don't
   need filesystem isolation at all — just launch N in parallel.
-- **Launch all N in the background and don't babysit any single one** —
-  same as the one-subagent case, just N background bash tasks instead of
-  one. Check on them as a batch, not by polling each individually in a
-  loop.
+- **Launch all N and don't babysit any single one** — same as the
+  one-subagent case, just N `start` calls instead of one. Check on them
+  as a batch, not by polling each individually in a loop.
 - **Mind the container's memory cap before picking N.** Your whole
   container shares one `MemoryMax` (a few GB by default) with every
   subagent you spawn _and_ your own process. A `claude` process plus its
@@ -147,10 +100,10 @@ threaded — the coordination overhead isn't worth it below that size.
 
 ## Resume for follow-ups
 
-`claude --resume <name> -p "Now run the same procedure over the second batch."`
-reuses the same session, so the sub-agent keeps every constant and
-gotcha it already discovered instead of re-learning the surface from a
-cold prompt. Spawn a new `--name` only for a genuinely unrelated task.
+`continue` reuses the same session, so the sub-agent keeps every constant
+and gotcha it already discovered instead of re-learning the surface from
+a cold prompt. Reach for `start` under a new name only for a genuinely
+unrelated task.
 
 ## Verify, then report
 
@@ -160,14 +113,12 @@ anything the sub-agent left ambiguous or exempted for a human call.
 
 ## Pitfalls (all observed in practice)
 
-- No `--dangerously-skip-permissions` → headless tool calls denied, the
-  sub-agent burns a run doing nothing.
 - Using a model bigger than yourself → paying premium cost for
   mechanical work that didn't need it.
 - Skipping the one-item tuning pass → a systematic mistake smeared
   across the whole batch.
-- Spawning fresh instead of `--resume` for a follow-up → throws away
-  all the context the first pass earned.
+- `start`-ing fresh instead of `continue`-ing for a follow-up → throws
+  away all the context the first pass earned.
 - Baking an unverified assumption into the recipe - if a quick check
   suggests something "isn't possible" or "doesn't exist," confirm it
   before writing that conclusion into the prompt; a wrong assumption