killeros 1.5.3 → 1.5.5

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [1.5.5] - 2026-08-05
+
+### Added
+
+- Added live background subagent progress with queued, running, and completed states plus per-child and batch usage.
+- Added inline subagent roles for single, parallel, and chain spawns, bounded their tools to those active for the parent, and kept them scoped to one non-resumable spawn.
+- Added `message` as a single-spawn task alias and visible fallback to `worker` for unknown named roles.
+
+### Changed
+
+- Replaced default deterministic context compaction with model-backed summaries at 40% remaining context, preserved manual focus prompts, and disclosed deterministic fallback after model retries fail.
+
+### Fixed
+
+- Warned when a settled or failed background subagent handoff cannot reach the parent and pointed users to `list` and `collect` for recovery.
+- Overrode vulnerable transitive `brace-expansion` and `undici` versions with patched releases in the development and CI install tree.
+
+## [1.5.4] - 2026-08-04
+
+### Added
+
+- Added named child sessions with `wait` and `resume`, persisted lifecycle records, real `/subagents` controls, empty-response failure, a 30-minute default wall time, bounded process-exit cleanup, and serialized shared-worktree writers.
+
+### Fixed
+
+- Added guarded automatic context compaction at 30% remaining, with structured summaries and goal continuation after the compaction is saved.
+- Kept the parent-facing cancellation reason when a steer was already in flight: aborting the parent turn after a steer now reports `abort` on the settled thread and result and no longer triggers a replacement follow-up turn for the cancelled batch.
+- Isolated host update callbacks in child-process and tool telemetry paths so a throwing callback cannot crash the host, strand the result promise, or fail a settled batch.
+- Rejected steering explicitly once 20 messages are pending for a thread instead of silently dropping the oldest steers; task-size overflow is also rejected before mutation, and bounded steering history keeps the earliest messages.
+- `interrupt all` now also stops queued children of the batch, matching `interrupt` on one thread and parent-turn abort, so queued writers cannot run after a stop command.
+- Recreated the subagent thread registry on `session_start`, stopped old children, and fenced old callbacks so embedding hosts that keep the extension instance between sessions can still spawn children without stale follow-ups.
+
 ## [1.5.3] - 2026-08-03
 
 ### Fixed

package/Killeros.ts

@@ -1,18 +1,27 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerSubagentTool } from "./killeros/subagents.ts";
-import { registerAliases, registerSlashAutocomplete } from "./killeros/commands.ts";
+import {
+  createSubagentControlApi,
+  registerAliases,
+  registerSlashAutocomplete,
+  registerSubagentCommand,
+  type SubagentControlApi,
+  type SubagentToolLike,
+} from "./killeros/commands.ts";
 import { registerConcisePrompt } from "./killeros/concise.ts";
+import { registerContextCompaction } from "./killeros/context-compaction.ts";
 import { registerFooter } from "./killeros/footer.ts";
 import { registerGoal, registerGoalSettlement } from "./killeros/goals.ts";
 import { registerLifecycleHooks } from "./killeros/hooks.ts";
 import { registerInitCommand, registerInitSettlement } from "./killeros/init.ts";
 import { registerPersonalInstructions } from "./killeros/personal-instructions.ts";
 import { registerQuestionTool } from "./killeros/question.ts";
-import { createGoalRuntime, createInitRuntime } from "./killeros/runtime.ts";
+import { createCompactionRuntime, createGoalRuntime, createInitRuntime } from "./killeros/runtime.ts";
 import { registerShellUi } from "./killeros/shell-ui.ts";
 import { registerVariants } from "./killeros/variants.ts";
 
 export { CONCISE_SYSTEM_PROMPT, isConcisedEnabled } from "./killeros/concise.ts";
+export { contextPercentRemaining } from "./killeros/context-compaction.ts";
 export { formatCost, formatContextProgress } from "./killeros/footer.ts";
 export { executeHook } from "./killeros/hooks.ts";
 export { INIT_WORKFLOW_PROMPT, writeInitAgentsFile } from "./killeros/init.ts";
@@ -20,18 +29,35 @@ export { INIT_WORKFLOW_PROMPT, writeInitAgentsFile } from "./killeros/init.ts";
 export default function Killeros(pi: ExtensionAPI): void {
   const initRuntime = createInitRuntime();
   const goalRuntime = createGoalRuntime();
+  const compactionRuntime = createCompactionRuntime();
   registerShellUi(pi);
   registerConcisePrompt(pi);
   registerGoal(pi, goalRuntime, initRuntime);
   registerPersonalInstructions(pi, initRuntime);
   registerQuestionTool(pi);
-  registerSubagentTool(pi);
+  let subagentTool: SubagentToolLike | undefined;
+  const registrationPi = new Proxy(pi, {
+    get(target, property, receiver) {
+      if (property === "registerTool") {
+        return (tool: Parameters<ExtensionAPI["registerTool"]>[0]) => {
+          if (tool.name === "subagent") subagentTool = tool as unknown as SubagentToolLike;
+          return target.registerTool(tool);
+        };
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+  const subagents = registerSubagentTool(registrationPi);
+  const subagentControl = (subagents as unknown as SubagentControlApi | undefined)
+    ?? (subagentTool ? createSubagentControlApi(subagentTool) : undefined);
+  registerSubagentCommand(pi, subagentControl);
   registerAliases(pi);
   registerSlashAutocomplete(pi);
   registerFooter(pi, goalRuntime);
   registerVariants(pi);
   registerInitCommand(pi, initRuntime, goalRuntime);
   registerLifecycleHooks(pi);
-  registerGoalSettlement(pi, goalRuntime, initRuntime);
+  registerContextCompaction(pi, compactionRuntime, goalRuntime);
+  registerGoalSettlement(pi, goalRuntime, initRuntime, compactionRuntime);
   registerInitSettlement(pi, initRuntime);
 }

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.5.3
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.5.4
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -45,6 +45,7 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - Coral Spark activity indicator with Claude-adjacent verbs that advance between agent runs and a quiet hidden-thinking label
 - Framed multiline editor with Shift+Enter support
 - Responsive footer with polished model/provider identity, plain-language context, and active goal state remaining; reasoning, Git branch, elapsed time, cost, and path cut down by available width
+- Automatic model-backed context compaction at 40% remaining; active goals continue after the saved summary
 - `/variants` selector and direct reasoning-level arguments
 - Codex-style `/goal` for durable long-running objectives with pause, resume, edit, clear, automatic continuation, and explicit completion
 - Pi-native `subagent` tool with named, inspectable child threads, Markdown roles, explicit read/write boundaries, parent controls, natural completion, and cancellation propagation
@@ -66,6 +67,7 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 /goal clear               Remove the current goal
 /variants                 Open the reasoning-level selector
 /variants high            Set a reasoning level directly
+/subagents                Open child-thread selectors in TUI mode
 /clear                    Start a new session after confirmation
 /exit                     Quit Pi gracefully
 ```
@@ -97,48 +99,66 @@ KillerOS ships `planner`, `reviewer`, `scout`, and `security` as read-only roles
 
 The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
 
-The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles use one shared slot by default; set `writerConcurrency` above `1` only after proving path ownership in the shared worktree. Reader-only batches reject `writerConcurrency` because it does not apply. All children share the parent worktree, so concurrent writers must avoid file conflicts. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model.
+The tool supports a single `agent` plus `task` or its `message` alias, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. `agent` may be a role name or an inline `{name, description, access, tools}` role for one spawn. Inline tools must be active for the parent, and inline role settings are not saved or resumable. Each task may set a `name`; names are unique within the parent session without regard to case and are passed to child Pi as `--name`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles are serialized in the shared worktree with one shared slot. Reader-only batches reject `writerConcurrency` because it does not apply. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model.
 
 | Action | Required fields | Allowed optional fields |
 |---|---|---|
-| omitted / `spawn` single | `agent`, `task` | `model`, `thinking`, `agentScope` |
-| omitted / `spawn` parallel | `tasks` | `writerConcurrency`, `model`, `thinking`, `agentScope` |
-| omitted / `spawn` chain | `chain` | `model`, `thinking`, `agentScope` |
+| omitted / `spawn` single | `agent`, one of `task` or `message` | `name`, `model`, `thinking`, `agentScope` |
+| omitted / `spawn` parallel | `tasks` | per-task `name`, `writerConcurrency`, `model`, `thinking`, `agentScope` |
+| omitted / `spawn` chain | `chain` | per-task `name`, `model`, `thinking`, `agentScope` |
 | `list` | none | none |
 | `inspect` | `threadId` | none |
+| `wait` | none | `threadId`, `all: true`, `timeoutMs` |
 | `steer` | `threadId`, `message` | none |
 | `interrupt` one | `threadId` | none |
 | `interrupt` all | `all: true` | none |
 | `collect` | `threadId` | none |
+| `resume` | `threadId` | `task` |
 | `close` | `threadId` | none |
 
-The three spawn shapes cannot be mixed. The `message` field is only valid with `action: "steer"`, and lifecycle actions reject spawn fields. KillerOS rejects malformed requests before role discovery, project confirmation, thread creation, or child launch. The TUI shows a parallel or shared-pool schedule only after shape validation; malformed calls show `invalid request` instead of queued work. For example:
+The three spawn shapes cannot be mixed. On a single spawn, `message` aliases `task`; supplying both is invalid. With `action: "steer"`, `message` remains required, and other lifecycle actions reject it. An unknown role name falls back to `worker` on a new spawn and reports that choice in the tool output. The `wait` action defaults to all queued or active children, waits up to 30 seconds by default, and never stops a child when it times out. The `resume` action keeps the same thread ID, name, session ID, and session directory and increments `attempt`; it requires the original named role and rejects inline roles. KillerOS rejects malformed requests before role discovery, project confirmation, thread creation, or child launch. The TUI shows a parallel or shared-pool schedule only after shape validation; malformed calls show `invalid request` instead of queued work. For example:
 
 ```json
-{"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
+{"agent":"reviewer","task":"Review the change","name":"auth-audit","model":"provider/model","thinking":"high"}
 ```
 
-Spawn returns the generated thread IDs immediately while the children continue in the background. This lets the parent use `list`, `inspect`, `steer`, `interrupt`, `collect`, and `close` in later tool calls. When the batch settles, KillerOS delivers its bounded handoff as a Pi follow-up and triggers the parent turn. A batch cancelled by parent Escape remains inspectable but does not trigger a replacement turn.
+Spawn returns the generated thread IDs immediately while the children continue in the background. This lets the parent use `list`, `inspect`, `wait`, `steer`, `interrupt`, `collect`, `resume`, and `close` in later tool calls. Compact thread records persist through Pi custom session entries. On parent restart, an active record restores as `orphaned`; `close` removes the child session only after confirmed process exit. When the batch settles, KillerOS delivers its bounded handoff as a Pi follow-up and triggers the parent turn. A batch cancelled by parent Escape remains inspectable but does not trigger a replacement turn.
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, trace, stderr, or returned-output execution quota; each JSONL record still has a bounded 8 MiB parser ceiling. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Aborting the originating parent turn stops its queued and active children; explicit `interrupt` actions and session shutdown also terminate active children and escalate after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. An empty final assistant response is a failure. The default child wall time is 30 minutes; token and dollar quotas remain opt-in. Each JSONL record still has a bounded 8 MiB parser ceiling. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Aborting the originating parent turn stops its queued and active children; explicit `interrupt` actions and session shutdown also terminate active children and use a bounded 10-second process-exit wait.
+
+The command grammar is:
+
+```text
+/subagents
+/subagents list
+/subagents inspect <id-or-name>
+/subagents wait [<id-or-name>] [timeout-ms]
+/subagents steer <id-or-name> <message>
+/subagents interrupt <id-or-name|all>
+/subagents collect <id-or-name>
+/subagents resume <id-or-name> [task]
+/subagents close <id-or-name>
+```
+
+Bare `/subagents` opens TUI selectors. RPC, JSON, and print modes require an explicit verb and never open a UI prompt.
 
 ### Thread lifecycle
 
 Each delegated task creates a named child thread. Its contract records the parent ID, child ID, role, prompt, model, requested capability boundary, trace, usage, and result state. Roles define the child’s access and tools; they do not own lifecycle controls or grant new filesystem powers. The parent owns scope, waits, inspection, steering, collection, and closure.
 
-Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `closed`. The parent renders separate **Active** and **Done** lists. Active threads show their name, task, model, usage, and direct controls. Done threads keep their handoff and trace available until the parent closes them.
+Threads move through `queued`, `active`, `done`, `failed`, `stopped`, `orphaned`, and `closed`. The parent renders separate **Active** and **Done** lists. Active threads show their name, task, model, usage, and direct controls. Done threads keep their handoff and trace available until the parent closes them.
 
-The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful. Closing removes a thread from the active workspace; heavy trace and result payloads are evicted as needed under the bounded retention budget, leaving a small inspectable tombstone.
+The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; wait for one named or ID child or all queued and active children; steer an active or queued thread with a bounded follow-up (at most 20 pending messages; further steering is rejected explicitly until the child restarts or drains the queue); interrupt one child or all active and queued children; collect a concise handoff into parent context; resume a terminal or orphaned child; and close a finished, stopped, or orphaned thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful. Closing removes a thread from the active workspace; heavy trace and result payloads are evicted as needed under the bounded retention budget, leaving a small inspectable tombstone.
 
-A child completes naturally when it returns a final answer. The default path has no per-child execution quota, while every JSONL record has an 8 MiB parser ceiling. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Aborting the originating parent turn settles queued work as cancelled and terminates active children; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown also terminates active children and escalates after five seconds.
+A child completes only when it returns usable final assistant text. The default wall time is 30 minutes; token and dollar quotas remain opt-in, while every JSONL record has an 8 MiB parser ceiling. Explicit embedding options can add output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Aborting the originating parent turn settles queued work as cancelled and terminates active children; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown also terminates active children and waits up to 10 seconds for confirmed process exit.
 
 The replacement lifecycle has nine phases:
 
 1. **Dispatch:** create a named thread and store its contract before launch.
 2. **Track:** maintain lifecycle states and Active/Done visibility.
 3. **Inspect:** keep the trace in the child thread, not the parent context.
-4. **Steer:** append a bounded parent follow-up to an active thread.
-5. **Interrupt:** stop one or all active children while preserving partial work.
+4. **Steer:** append a bounded parent follow-up to an active or queued thread.
+5. **Interrupt:** stop one or all active or queued children while preserving partial work.
 6. **Collect:** return a concise handoff while retaining the expanded trace.
 7. **Guard:** honor only explicitly configured child resource guards; do not impose a routine turn stop.
 8. **Close:** remove a finished or stopped thread from the workspace while retaining a small inspectable tombstone; heavy payloads may be evicted under the retention budget.
@@ -150,6 +170,8 @@ KillerOS activates its packaged `killeros` theme when a TUI session starts. Tool
 
 KillerOS displays session costs in USD. The footer uses Pi's human-readable model name when available, keeps the provider visually secondary, and renders context as `percent left (tokens)` without a progress bar. When a goal exists, the footer adds its active time or terminal state; at narrow widths, context pressure and goal state take priority.
 
+KillerOS checks context after each agent turn. At 40% remaining, it starts Pi's model-backed compaction after the current run settles, so the active turn is not aborted. Manual `/compact` uses the same model path and keeps custom focus instructions. If model compaction is unavailable or exhausts its retries, KillerOS uses the disclosed deterministic fallback and warns that repeated compaction can reduce accuracy.
+
 For trusted projects, KillerOS loads `AGENTS.local.md` after Pi's shared repository context. A one-line `@path` or `@~/path` file imports personal guidance from another location.
 
 Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`; matchers are JavaScript regular expressions over Pi tool names. Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. Failed `tool_call` hooks block the tool, while later-event failures notify the user.
@@ -180,7 +202,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For release `1.5.0`, publish after the validation checks pass:
+For a release, publish after the validation checks pass:
 
 ```bash
 npm login

package/killeros/commands.ts

@@ -1,5 +1,76 @@
-import { type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { formatThreadControls, type ThreadStatus } from "./subagent-ui.ts";
+
+export type SubagentControlAction = "list" | "inspect" | "wait" | "steer" | "interrupt" | "collect" | "resume" | "close";
+
+export interface SubagentControlRequest {
+  action: SubagentControlAction;
+  threadId?: string;
+  all?: true;
+  message?: string;
+  task?: string;
+  timeoutMs?: number;
+}
+
+interface SubagentControlThread {
+  id: string;
+  displayName?: string;
+  name?: string;
+  agent?: string;
+  role?: string;
+  task?: string;
+  prompt?: string;
+  status?: string;
+  state?: string;
+}
+
+export interface SubagentControlDetails {
+  results?: readonly SubagentControlThread[];
+  threads?: readonly SubagentControlThread[];
+}
+
+export interface SubagentControlResult {
+  text: string;
+  details?: SubagentControlDetails;
+  usage?: unknown;
+}
+
+export interface SubagentControlApi {
+  execute(request: SubagentControlRequest, ctx: ExtensionContext): Promise<SubagentControlResult>;
+}
+
+export interface SubagentToolLike {
+  name: string;
+  execute(
+    toolCallId: string,
+    params: unknown,
+    signal: AbortSignal | undefined,
+    onUpdate: undefined,
+    ctx: ExtensionContext,
+  ): Promise<{
+    content?: readonly { type: string; text?: string }[];
+    details?: unknown;
+    usage?: unknown;
+  }>;
+}
+
+export function createSubagentControlApi(tool: SubagentToolLike): SubagentControlApi {
+  return {
+    async execute(request, ctx) {
+      const toolRequest = request.action === "interrupt" && request.threadId === "all"
+        ? { action: "interrupt", all: true }
+        : request;
+      const result = await tool.execute("subagents-command", toolRequest, ctx.signal, undefined, ctx);
+      const text = result.content?.find((item) => item.type === "text")?.text ?? "";
+      return {
+        text,
+        details: result.details as SubagentControlDetails | undefined,
+        usage: result.usage,
+      };
+    },
+  };
+}
 
 async function confirmNewSession(ctx: ExtensionCommandContext): Promise<boolean> {
   if (!ctx.hasUI) return true;
@@ -57,6 +128,7 @@ const BUILTIN_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
 const COMMAND_SYNTAX_HINTS: Readonly<Record<string, string>> = {
   goal: "/goal [objective|clear|edit|pause|resume]",
   variants: "/variants [level]",
+  subagents: "/subagents [list|inspect|wait|steer|interrupt|collect|resume|close] [thread]",
   model: "/model [provider/model]",
   "scoped-models": "/scoped-models",
   login: "/login [provider]",
@@ -79,6 +151,162 @@ function scoreCommandMatch(name: string, prefix: string): number {
   return 0;
 }
 
+const SUBAGENT_COMMAND_USAGE = "/subagents [list|inspect|wait|steer|interrupt|collect|resume|close] [thread]";
+
+function subagentCommandError(message: string): Error {
+  return new Error(`${message} Usage: ${SUBAGENT_COMMAND_USAGE}`);
+}
+
+function parseThreadReference(action: SubagentControlAction, tail: string): string {
+  const reference = tail.match(/^(\S+)(?:\s+([\s\S]*))?$/u)?.[1];
+  if (!reference) throw subagentCommandError(`/subagents ${action} requires a thread reference.`);
+  return reference;
+}
+
+function parseExplicitSubagentCommand(args: string): SubagentControlRequest {
+  const trimmed = args.trim();
+  const match = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/u);
+  if (!match) throw subagentCommandError("/subagents requires an explicit verb outside TUI.");
+  const action = match[1]!.toLocaleLowerCase() as SubagentControlAction;
+  const tail = match[2]?.trim() ?? "";
+
+  if (action === "list") {
+    if (tail) throw subagentCommandError("/subagents list does not accept arguments.");
+    return { action };
+  }
+  if (action === "wait") {
+    if (!tail) return { action };
+    const parts = tail.split(/\s+/u);
+    if (parts.length > 2) throw subagentCommandError("/subagents wait accepts one thread reference and one timeout-ms value.");
+    if (parts.length === 1 && /^\d+$/u.test(parts[0]!)) {
+      return { action, timeoutMs: parseTimeout(parts[0]!) };
+    }
+    const request: SubagentControlRequest = { action, threadId: parts[0] };
+    if (parts[1] !== undefined) request.timeoutMs = parseTimeout(parts[1]);
+    return request;
+  }
+  if (action === "steer") {
+    const referenceAndMessage = tail.match(/^(\S+)(?:\s+([\s\S]+))?$/u);
+    if (!referenceAndMessage?.[1]) throw subagentCommandError("/subagents steer requires a thread reference.");
+    if (!referenceAndMessage[2]?.trim()) throw subagentCommandError("/subagents steer requires a message.");
+    return { action, threadId: referenceAndMessage[1], message: referenceAndMessage[2] };
+  }
+  if (action === "resume") {
+    const referenceAndTask = tail.match(/^(\S+)(?:\s+([\s\S]+))?$/u);
+    if (!referenceAndTask?.[1]) throw subagentCommandError("/subagents resume requires a thread reference.");
+    return {
+      action,
+      threadId: referenceAndTask[1],
+      ...(referenceAndTask[2] ? { task: referenceAndTask[2] } : {}),
+    };
+  }
+  if (action === "inspect" || action === "interrupt" || action === "collect" || action === "close") {
+    const threadId = parseThreadReference(action, tail);
+    if (tail.slice(threadId.length).trim()) throw subagentCommandError(`/subagents ${action} accepts one thread reference.`);
+    return { action, threadId };
+  }
+  throw subagentCommandError(`Unknown /subagents action ${JSON.stringify(match[1])}.`);
+}
+
+function parseTimeout(value: string): number {
+  const timeoutMs = Number(value);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0) {
+    throw subagentCommandError("/subagents wait timeout-ms must be a non-negative integer.");
+  }
+  return timeoutMs;
+}
+
+function controlThreads(result: SubagentControlResult): SubagentControlThread[] {
+  const details = result.details;
+  if (!details) return [];
+  const results = [...(details.results ?? [])];
+  const threads = [...(details.threads ?? [])];
+  const candidates = results.length ? results : threads;
+  return candidates.filter((thread) => thread && typeof thread.id === "string" && thread.state !== "closed" && thread.status !== "closed");
+}
+
+function threadStatus(thread: SubagentControlThread): ThreadStatus {
+  const status = (thread.status ?? thread.state ?? "queued").toLocaleLowerCase();
+  if (status === "active" || status === "running") return "running";
+  if (status === "done" || status === "complete" || status === "closed") return "complete";
+  if (status === "stopped" || status === "cancelled") return "cancelled";
+  if (status === "limited") return "limited";
+  if (status === "orphaned") return "orphaned";
+  if (status === "failed") return "failed";
+  return "queued";
+}
+
+function threadLabel(thread: SubagentControlThread): string {
+  const name = thread.displayName ?? thread.name ?? thread.agent ?? thread.role ?? thread.id;
+  return `${name} · ${thread.id} · ${threadStatus(thread)}`;
+}
+
+function selectedThread(threads: readonly SubagentControlThread[], labels: readonly string[], choice: string): SubagentControlThread | undefined {
+  const index = labels.indexOf(choice);
+  if (index >= 0) return threads[index];
+  return threads.find((thread) => thread.id === choice || thread.displayName === choice || thread.name === choice);
+}
+
+async function executeSubagentControl(
+  control: SubagentControlApi | undefined,
+  request: SubagentControlRequest,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  if (!control) throw new Error("Subagent control API is not available.");
+  const result = await control.execute(request, ctx);
+  if (result?.text) ctx.ui.notify(result.text, "info");
+}
+
+async function runTuiSubagentCommand(control: SubagentControlApi | undefined, ctx: ExtensionCommandContext): Promise<void> {
+  if (!control) throw new Error("Subagent control API is not available.");
+  const listed = await control.execute({ action: "list" }, ctx);
+  const threads = controlThreads(listed);
+  if (!threads.length) {
+    ctx.ui.notify("No child threads.", "info");
+    return;
+  }
+
+  const labels = threads.map(threadLabel);
+  const selected = await ctx.ui.select("Select a thread", labels);
+  if (selected === undefined) return;
+  const thread = selectedThread(threads, labels, selected);
+  if (!thread) return;
+
+  const controls = formatThreadControls(threadStatus(thread)).filter((item) => item.enabled);
+  const controlLabels = controls.map((item) => item.label);
+  const selectedControl = await ctx.ui.select("Select a control", controlLabels);
+  if (selectedControl === undefined) return;
+  const chosen = controls.find((item) => item.label === selectedControl || item.id === selectedControl);
+  if (!chosen) return;
+
+  const request: SubagentControlRequest = { action: chosen.id, threadId: thread.id };
+  if (chosen.id === "steer") {
+    const message = await ctx.ui.input("Steer child thread", "Message");
+    if (message === undefined || !message.trim()) return;
+    request.message = message;
+  } else if (chosen.id === "resume") {
+    const task = await ctx.ui.input("Resume child thread", "Optional task");
+    if (task === undefined) return;
+    if (task) request.task = task;
+  }
+  await executeSubagentControl(control, request, ctx);
+}
+
+export function registerSubagentCommand(pi: ExtensionAPI, control?: SubagentControlApi | void): void {
+  const api = control && typeof control.execute === "function" ? control : undefined;
+  pi.registerCommand("subagents", {
+    description: "Inspect and control child threads",
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        if (ctx.mode !== "tui") throw subagentCommandError("/subagents requires an explicit verb outside TUI.");
+        await runTuiSubagentCommand(api, ctx);
+        return;
+      }
+      await executeSubagentControl(api, parseExplicitSubagentCommand(args), ctx);
+    },
+  });
+}
+
 export function registerSlashAutocomplete(pi: ExtensionAPI): void {
   const usage = new Map<string, number>();
   pi.on("session_start", (_event, ctx) => {
@@ -121,6 +349,15 @@ export function registerSlashAutocomplete(pi: ExtensionAPI): void {
           }
         }
 
+        if (!commands.has("subagents")) {
+          commands.set("subagents", {
+            name: "subagents",
+            description: "Inspect and control child threads",
+            category: "Extension",
+            syntaxHint: COMMAND_SYNTAX_HINTS.subagents,
+          });
+        }
+
         const ranked = [...commands.values()]
           .map((command) => ({
             command,