feat: subagents — on-demand + scheduled spawning with lifecycle management (#15)

[mattmezza]

Summary

Implements issue #15 — Subagents: on-demand spawning, scheduling, and lifecycle management.

One execution primitive (AgentCore.run_subagent) reached by two trigger paths:

• On demand — the new spawn_subagent tool, called by the agent mid-turn.
• Scheduled — a subagent job fired by the scheduler.

A subagent runs the existing agent loop with system semantics (no goal
decomposition, memory extraction, reflection, or per-action approval prompts) —
the same path scheduled jobs already use — under a chosen persona, and returns a
structured result.

Execution model

• Sync (default): the tool blocks, runs the sub-loop to completion, returns { summary, result }; the parent continues in the same turn.
• Background (background: true): returns a run id immediately; the run executes off-turn and posts its result back to the originating chat.

Guardrails (config subagents)

• Inherit-never-widen scope: a child's tools/skills/secrets are the intersection of the caller's scope and the requested persona's (narrow_scope). NEVER permission rules still apply at any depth.
• Recursion depth cap (default 3).
• Per-run step + token budgets (default 12 steps / 100k tokens) — a hard stop on the otherwise-unbounded loop.
• Max concurrent background runs (default 3).

Lifecycle (list / status / cancel)

• Telegram: /jobs lists active runs with inline Cancel buttons — monitor/cancel a long task from the phone, no web UI needed.
• Admin UI: the Jobs tab gains a responsive subagent-runs card grid (persona, status, elapsed, current step, cancel), polled live; collapses to one column at phone width.
• Runs are tracked in an in-memory SubagentRegistry (ephemeral by design — a restart clears them).

Acceptance criteria

• The agent can spawn a subagent with a chosen persona and receive a structured result.
• Background spawns report back asynchronously to the correct chat.
• A background subagent can be monitored and cancelled from Telegram on mobile; the jobs view is usable at phone width.
• Recursion depth and budgets are enforced; scope cannot be widened by a child.

Changes

• core/subagents.py — SubagentRun, SubagentRegistry, narrow_scope.
• core/agent.py — spawn_subagent tool, run_subagent primitive, budgeted/depth-capped sub-loop, background delivery, request-state plumbing (depth/origin/persona).
• core/config.py — SubagentsConfig; SchedulerJob.persona.
• core/job_store.py — subagent type + persona column (additive migration).
• core/scheduler.py — run_subagent_task handler + routing.
• core/permissions.py — spawn_subagent is an ASK write-action.
• channels/telegram.py — /jobs command + cancel callback.
• api/admin.py + templates — subagent runs view, cancel route, subagent job type in the Jobs form, gateable per persona.
• Docs: subagents.mdx (+ nav), scheduler table row, README feature, config.yml.example.

Tests

tests/test_subagents.py (20 new; 470 total green): scope narrowing, registry lifecycle/trim, run_subagent (sync, disabled, depth cap, unknown persona, step-budget stop, background→origin delivery, concurrency cap), persona narrowing, JobStore persona persistence + column migration, scheduled-run delivery.

Notes / deliberate simplifications

• Subagents use channel="system", so writes inside a run are auto-approved — the trust boundary is the single ASK on spawn_subagent (same model as scheduled jobs). Scope is narrowed and NEVER rules still block.
• { summary } is a truncated preview of the result, not a separate LLM call.
• The runs registry is in-memory (ephemeral); background results post back on completion (start/result messages rather than an in-place edited "working…" message).

Closes #15

[mattmezza]

Rebased onto latest main (per-turn skills, #46/#48). Three additions since the last review:

• Caller-sized runs — spawn_subagent gains max_steps, token_budget, and thinking_effort. The two numeric caps default to the configured value and are clamped to it as a ceiling (the agent can dial a run down but never past the guardrail; token_budget floored at 1000); thinking_effort (off|low|medium|high) maps to a thinking level, omit to inherit the caller's.
• File handoff — subagents share the agent's cwd/filesystem, so a subagent now reports the absolute paths of any files it writes in its result, which the existing result-folding carries into the parent's history.
• Persona roster — the main turn shows the agent a compact name — role roster so delegating to a specialist is informed, not a guess; selection stays user-led (omit persona = run as yourself). Gated to when spawn_subagent is in scope. The "Persona not found" error now lists valid names.

512 tests pass, ruff clean. Each change was adversarially reviewed.

[mattmezza]

Pushed three more commits acting on real-world feedback:

• Hide raw from chat + synthesise → then refined: a finished background batch is now distilled by a dedicated subagent_summary inference into a one-line chat notification + a concise digest kept in the agent context. Raw subagent output reaches neither the user nor the context. Disabled/error → first-line truncation fallback. A barrier collapses parallel spawns into one delivery; cancelling a sibling no longer orphans a deferred reply.
• Persona default hardened (omit = run as yourself; only name a specialist on explicit request).
• Inference defaults (memory extraction/consolidation, goal decomposition, task reflection, compaction) switched from claude-haiku-4-5 to deepseek-v4-flash — better/cheaper and consistent with the main provider. Vision left on a multimodal model.
• Admin UI (Result-summary controls in the Subagents card), docs, README, and config example updated.

515 tests pass, ruff clean.