subagents extension on the generic host surfaces

The rock now owns all subagent policy on top of libpanto-lua's generic APIs:
children are ordinary panto.agent instances over rock-constructed stores,
started with agent:run_async and awaited by arming uv.new_poll on each job's
wake_fd from the tool handler's coroutine.

subagents/jobs.lua carries the session policy the host used to own: the
concurrency gate (4 running, FIFO queue, cancel-while-queued never starts),
the await contract (results in input order; "first" returns settled plus
remaining by identity), and settle-time shaping. subagents/spawn.lua seeds
new children (primary system context, child role, profile body with manifest
metadata), resolves model/reasoning through panto.ext.resolve_model, filters
subagents.* out of the inherited tool set via agent:set_tools, and reads
resume defaults back from stored message metadata. One-shot structured
workers are a null_store agent with a declaration-only output tool,
tool_choice forced, dispatch_tools=false. subagents/progress.lua renders
per-tool-entry cards through the component handle's invalidate seam;
turn_interrupt cancels live children, turn_end closes them.

Spec suite rewritten against fakes of the new surfaces (98 cases), including
gate/queue/cancel bounds, resume-default extraction, one-shot capture via
unresolved tool calls, tool filtering, and manifest seeding.

1 files changed, 39 insertions, 0 deletions

diff --git a/README.md b/README.md
index 8c24c36..713ea60 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,22 @@ rocks = ["panto-subagents"]
 
 For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead.
 
+### Dependencies
+
+Panto installs the rock's dependencies with it:
+
+- **lyaml** parses profile frontmatter. It binds the system libyaml, which
+  LuaRocks does not vendor — install it first (`brew install libyaml`, or
+  `apt install libyaml-dev`), otherwise the rock fails to build and panto
+  quietly starts without the `subagents.*` tools.
+- **toml2lua** reads TOML workflows. Pure Lua, nothing to install.
+- **luv** backs profile and workflow discovery. Panto already ships it.
+
+Structured workflow output is validated against its JSON Schema by a built-in
+validator covering the schema subset those results use. Installing the
+`jsonschema` rock switches validation over to it; that rock needs a system PCRE,
+so it is not a declared dependency.
+
 ## Agent profiles
 
 Agents are Markdown files with YAML frontmatter:
@@ -87,4 +103,27 @@ their structured result. Panto extensions can use this API directly, while
 `subagents.lua` runs model-authored one-off workflows in a restricted Lua
 environment.
 
+## Development
+
+[mise](https://mise.jdx.dev) provides Lua 5.4 and LuaRocks:
+
+```sh
+mise run deps    # install the rocks into ./.rocks (gitignored)
+mise run check   # run the specs against that tree
+```
+
+`mise run deps` passes Homebrew's libyaml prefix to lyaml when brew is
+available. Without mise, install the same rocks with any LuaRocks targeting Lua
+5.4 and run `lua spec/run.lua` from the repo root. `panto lua spec/run.lua` runs
+the suite inside panto's own interpreter and rocks tree, skipping whatever cases
+that tree has no rock for.
+
+The specs are plain Lua asserts — no framework. `spec/run.lua` loads every
+`spec/test_*.lua`, each of which returns an ordered array of `{ name, function }`
+cases. A case asserts and returns nothing to pass, or returns `"skip", reason`
+when an optional rock is missing; skips do not fail the run. `spec/fake_ext.lua`
+is a scriptable stand-in for the `panto.ext` host seam: it queues the result each
+spawned child settles with, records every spawn spec, tool, and command the
+extension produced, and settles awaits synchronously.
+
 See [DESIGN.md](DESIGN.md) for the runtime and persistence design.