@kontextmind/kxm 0.7.7 → 0.7.9

package/plugins/kxm/dist/vnext-runtime-supervisor.js

@@ -15163,6 +15163,7 @@ function defaultSpawn(command, args, options) {
     let child;
     const finish = () => {
       if (finished) return;
+      if (stopping && !killSent) return;
       finished = true;
       for (const timer of [wallTimer, killTimer, drainTimer, reapTimer]) clearTimeout(timer);
       options.signal?.removeEventListener("abort", onAbort);
@@ -15172,7 +15173,18 @@ function defaultSpawn(command, args, options) {
       child?.unref();
       const started = Boolean(child?.pid);
       if (started && !observedChildExit) error ??= new Error("process_exit_unobserved");
-      resolve7({ stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), code, signal, started, observedChildExit, terminationRequested: stopping, ...error ? { error } : {} });
+      const unverifiedDescendants = stopping || started && !observedChildExit;
+      resolve7({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        code,
+        signal,
+        started,
+        observedChildExit,
+        terminationRequested: stopping,
+        ...unverifiedDescendants ? { unverifiedDescendants: true } : {},
+        ...error ? { error } : {}
+      });
     };
     const kill = (requested) => {
       killProcessTree(child, requested);
@@ -15203,7 +15215,7 @@ function defaultSpawn(command, args, options) {
         cwd: options.cwd,
         env: options.env ?? process.env,
         stdio: ["pipe", "pipe", "pipe"],
-        shell: false,
+        shell: options.shell === true,
         windowsHide: true,
         detached: process.platform !== "win32"
       });
@@ -15247,7 +15259,7 @@ function defaultSpawn(command, args, options) {
       closed = true;
       code = exitCode;
       signal = exitSignal;
-      if (!stopping || killSent) finish();
+      finish();
     });
     options.signal?.addEventListener("abort", onAbort, { once: true });
     if (options.signal?.aborted) onAbort();
@@ -15688,6 +15700,31 @@ function defaultRunner(env) {
     }
   };
 }
+function commandResultFromSpawn(result) {
+  const errno = result.error && "code" in result.error ? result.error.code : void 0;
+  const error = (typeof errno === "string" && errno ? errno : void 0) ?? result.error?.message ?? (result.observedChildExit !== true ? "auth_probe_exit_unobserved" : void 0);
+  return {
+    ok: result.code === 0 && !error,
+    code: result.code,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    ...error ? { error } : {}
+  };
+}
+function defaultAsyncRunner(env, signal) {
+  return async (command, args, timeoutMs) => {
+    try {
+      return commandResultFromSpawn(await defaultSpawn(command, args, {
+        env,
+        timeoutMs,
+        signal,
+        shell: harnessSpawnUsesShell(command)
+      }));
+    } catch (error) {
+      return { ok: false, code: null, stdout: "", stderr: "", error: error instanceof Error ? error.message : "spawn_failed" };
+    }
+  };
+}
 function firstLine(text) {
   const line = text.split(/\r?\n/).map((candidate) => candidate.trim()).find(Boolean);
   return line && line.length <= 200 ? line : void 0;
@@ -16103,35 +16140,31 @@ var PendingHarnessCommand = class {
     this.key = key;
   }
 };
-async function probeHarnessAssignmentAsync(options) {
+async function replayHarnessProbe(run, execute, limit) {
   const observed = /* @__PURE__ */ new Map();
-  const run = options.runCommand ?? (async (command, args, timeoutMs) => {
-    const result = await defaultSpawn(command, args, { env: options.env, timeoutMs, signal: options.signal });
-    const error = result.error?.message ?? (result.observedChildExit !== true ? "auth_probe_exit_unobserved" : void 0);
-    return {
-      ok: result.code === 0 && !error,
-      code: result.code,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      ...error ? { error } : {}
-    };
-  });
-  for (let commands = 0; commands <= 32; commands++) {
+  for (let commands = 0; commands <= limit; commands++) {
     try {
-      return probeHarnessAssignment({ ...options, runCommand(command, args, timeoutMs) {
+      return execute((command, args, timeoutMs) => {
         const key = JSON.stringify([command, args, timeoutMs]);
         const result = observed.get(key);
         if (result) return result;
         throw new PendingHarnessCommand(command, args, timeoutMs, key);
-      } });
+      });
     } catch (pending) {
       if (!(pending instanceof PendingHarnessCommand)) throw pending;
-      if (commands === 32) throw new Error("auth_probe_command_limit");
+      if (commands === limit) throw new Error("auth_probe_command_limit");
       observed.set(pending.key, await run(pending.command, pending.args, pending.timeoutMs));
     }
   }
   throw new Error("auth_probe_command_limit");
 }
+async function probeHarnessAssignmentAsync(options) {
+  return replayHarnessProbe(
+    options.runCommand ?? defaultAsyncRunner(options.env ?? process.env, options.signal),
+    (runCommand) => probeHarnessAssignment({ ...options, runCommand }),
+    32
+  );
+}
 
 // plugins/kxm/src/vnext-config.ts
 var VnextConfigError = class extends Error {
@@ -21904,9 +21937,28 @@ import { join as join11 } from "node:path";
 import { createHash as createHash6, randomUUID as randomUUID3 } from "node:crypto";
 import { lstat, mkdir, open, rename } from "node:fs/promises";
 import { join as join6 } from "node:path";
+var ONESHOT_EVIDENCE_SCHEMA = "kxm.oneshot-evidence.v2";
+var RETIRED_ONESHOT_EVIDENCE_SCHEMAS = /* @__PURE__ */ new Set(["kxm.oneshot-evidence.v1"]);
 var TEXT_LIMIT = 4 * 1024 * 1024;
+var ARGV_LIMIT = 64 * 1024;
 var RECORD_LIMIT = 16 * 1024 * 1024;
 var digest = (value) => `sha256:${createHash6("sha256").update(value).digest("hex")}`;
+function parseOneShotEvidenceRecord(bytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes);
+  } catch {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  const schema = parsed.schema;
+  if (typeof schema !== "string") throw new Error("oneshot_evidence_record_invalid");
+  if (RETIRED_ONESHOT_EVIDENCE_SCHEMAS.has(schema)) throw new Error("oneshot_evidence_schema_retired");
+  if (schema !== ONESHOT_EVIDENCE_SCHEMA) throw new Error("oneshot_evidence_schema_unknown");
+  return parsed;
+}
 async function beginOneShotEvidence(root, intent, sensitive) {
   await mkdir(root, { recursive: true, mode: 448 });
   const stat = await lstat(root);
@@ -21920,11 +21972,11 @@ async function beginOneShotEvidence(root, intent, sensitive) {
   const redact = (value) => {
     let text = value;
     for (const secret of secrets) text = text.replaceAll(secret, "[REDACTED]");
-    return text.replace(/(\b(?:authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)\b["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^\s"',;}]+/gi, "$1[REDACTED]");
+    return text.replace(/(\b(?:authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)\b["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^\s"',;}]+/gi, "$1[REDACTED]").replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
   };
-  const bounded = (value) => {
+  const bounded = (value, max = TEXT_LIMIT) => {
     const bytes = Buffer.from(redact(value));
-    return { text: bytes.subarray(0, TEXT_LIMIT).toString("utf8"), truncated: bytes.length > TEXT_LIMIT, sha256: digest(value) };
+    return { text: bytes.subarray(0, max).toString("utf8"), truncated: bytes.length > max, sha256: digest(redact(value)) };
   };
   const write = async (name, value) => {
     const current = await lstat(dir);
@@ -21933,6 +21985,7 @@ async function beginOneShotEvidence(root, intent, sensitive) {
     }
     const bytes = JSON.stringify(value);
     if (Buffer.byteLength(bytes) > RECORD_LIMIT) throw new Error("oneshot_evidence_record_limit");
+    parseOneShotEvidenceRecord(bytes);
     const target = join6(dir, name);
     const partial = `${target}.partial`;
     const file = await open(partial, "wx", 384);
@@ -21954,7 +22007,7 @@ async function beginOneShotEvidence(root, intent, sensitive) {
     return digest(bytes);
   };
   await write("intent.json", {
-    schema: "kxm.oneshot-evidence.v1",
+    schema: ONESHOT_EVIDENCE_SCHEMA,
     id,
     recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
     runId: intent.runId,
@@ -21965,9 +22018,10 @@ async function beginOneShotEvidence(root, intent, sensitive) {
     provider: intent.provider,
     requestedModel: intent.model,
     cwd: intent.cwd,
-    command: intent.command,
-    argv: bounded(JSON.stringify(intent.args)),
+    command: redact(intent.command),
+    argv: bounded(JSON.stringify(intent.args), ARGV_LIMIT),
     stdin: intent.input === void 0 ? null : bounded(intent.input),
+    env: null,
     acceptance: false
   });
   let finished = false;
@@ -21977,7 +22031,7 @@ async function beginOneShotEvidence(root, intent, sensitive) {
       if (finished) throw new Error("oneshot_evidence_already_finished");
       finished = true;
       return write("result.json", {
-        schema: "kxm.oneshot-evidence.v1",
+        schema: ONESHOT_EVIDENCE_SCHEMA,
         id,
         recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
         stdout: bounded(result.stdout),
@@ -21987,6 +22041,7 @@ async function beginOneShotEvidence(root, intent, sensitive) {
         started: result.started ?? null,
         observedChildExit: result.observedChildExit ?? null,
         terminationRequested: result.terminationRequested ?? null,
+        unverifiedDescendants: result.unverifiedDescendants ?? null,
         error: result.error ? bounded(result.error.message) : null,
         observation: bounded(JSON.stringify(observation)),
         acceptance: false
@@ -25648,7 +25703,8 @@ Return a final JSON object with an "outcome" field chosen from ${JSON.stringify(
       parsed = { text: "", isError: true };
     }
     const aborted = request.signal.aborted || procResult.error?.message === "process_aborted";
-    const effectUncertain = procResult.terminationRequested === true || Boolean(procResult.signal) || procResult.error?.message === "process_exit_unobserved" || procResult.observedChildExit === false && procResult.started !== false;
+    const unverifiedDescendants = procResult.unverifiedDescendants === true || procResult.terminationRequested === true || procResult.error?.message === "process_exit_unobserved" || procResult.observedChildExit === false && procResult.started !== false;
+    const effectUncertain = unverifiedDescendants || Boolean(procResult.signal);
     const transportFailed = procResult.code !== 0 || Boolean(procResult.error) || effectUncertain;
     const outcome = aborted ? "cancelled" : transportFailed || parsed.isError ? "failed" : determineOutcome(parsed.text, request.allowedOutcomes);
     const providerMetadata = {
@@ -25660,6 +25716,7 @@ Return a final JSON object with an "outcome" field chosen from ${JSON.stringify(
     if (procResult.observedChildExit !== void 0) providerMetadata.observedChildExit = procResult.observedChildExit;
     if (procResult.started !== void 0) providerMetadata.processStarted = procResult.started;
     if (procResult.terminationRequested !== void 0) providerMetadata.terminationRequested = procResult.terminationRequested;
+    if (unverifiedDescendants) providerMetadata.descendantEffects = "unverified";
     if (procResult.error) {
       const reason = procResult.error.message;
       providerMetadata.processError = /^process_(aborted|timeout|output_limit|stdin_error|stdio_error|stdio_unclosed|exit_unobserved)$/.test(reason) ? reason : "process_error";
@@ -26140,7 +26197,6 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
               });
             } catch (err) {
               earlyError = err;
-              drivePromise = Promise.reject(err);
             }
             await Promise.resolve();
             if (earlyError) {
@@ -26166,6 +26222,7 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
                 } catch {
                 }
               }
+            }).catch(() => {
             });
             sendJson(response, 202, {
               ok: true,

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxm-claude-plugin",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/system.ts

@@ -81,7 +81,7 @@ import { loadKxmUpdateConfig } from "../kxm-update-config.ts";
 import {
   formatHarnessUpdate,
   planHarnessUpdate,
-  probeHarnesses,
+  probeHarnessesAsync,
   runHarnessUpdate,
   type HarnessUpdateScope,
 } from "../vnext-harness.ts";
@@ -399,7 +399,7 @@ export async function cmdUpdate(runtime: Runtime, harness: string | undefined, o
     return kxmApply?.ok === false ? 1 : 0;
   }
   const scope: HarnessUpdateScope = options.self ? "self" : options.extensions ? "extensions" : options.models ? "models" : "all";
-  const inventory = probeHarnesses({ env: runtime.env });
+  const inventory = await probeHarnessesAsync({ env: runtime.env });
   const planned = planHarnessUpdate(inventory, { ...(harness ? { harness } : {}), scope });
   const steps = runHarnessUpdate(planned, { env: runtime.env, dryRun: runtime.dryRun });
   const failed = steps.some((step) => step.outcome === "failed") || kxmApply?.ok === false;
@@ -755,7 +755,7 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
   if (runtime.env[GUIDE_SETUP_OPT_OUT_ENV]?.trim()) return;
   let inventory;
   try {
-    inventory = probeHarnesses({ env: runtime.env });
+    inventory = await probeHarnessesAsync({ env: runtime.env });
   } catch {
     return;
   }

package/plugins/kxm/src/cli/tasks.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { probeHarnesses } from "../vnext-harness.ts";
+import { probeHarnessesAsync } from "../vnext-harness.ts";
 import { suggestWorkflowAndRoles } from "../suggest.ts";
 import {
   createGoal,
@@ -32,7 +32,7 @@ export async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promi
       runtime.io.stderr("prompt must be non-empty\n");
       return 2;
     }
-    const inventory = probeHarnesses({ env: runtime.env });
+    const inventory = await probeHarnessesAsync({ env: runtime.env });
     const availableHarnesses = inventory.harnesses.map((h) => ({
       harness: h.id,
       auth: h.authenticated === true ? "authenticated" : "unauthenticated",

package/plugins/kxm/src/cli/vnext.ts

@@ -25,7 +25,7 @@ import {
 import { vnextRuntimePaths } from "../vnext-runtime-store.ts";
 import {
   formatHarnessInventory,
-  probeHarnesses,
+  probeHarnessesAsync,
 } from "../vnext-harness.ts";
 import {
   fetchLatestKxmVersion,
@@ -580,7 +580,7 @@ export async function cmdVnextRunList(runtime: Runtime): Promise<number> {
 }
 
 export async function cmdHarnessList(runtime: Runtime): Promise<number> {
-  const inventory = probeHarnesses({ env: runtime.env });
+  const inventory = await probeHarnessesAsync({ env: runtime.env });
   print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
   return 0;
 }

package/plugins/kxm/src/mcp-server.ts

@@ -7,7 +7,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.7";
+const VERSION = "0.7.9";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/model-inventory.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { stringify } from "yaml";
+import { defaultSpawn } from "./vnext-oneshot-process.ts";
 
 export interface InventoryPrice {
   inputPerMillion: number | null;
@@ -95,10 +95,10 @@ export async function refreshModelInventory(options: { outputRoot: string; env?:
     if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
     byId.set(key, current);
   };
-  const native = (command: string, args: string[], source: string) => {
-    const result = spawnSync(command, args, { encoding: "utf8", timeout: 20_000, shell: false });
-    const ok = result.status === 0;
-    sources[source] = { url: `${command} ${args.join(" ")}`, ok, ...(ok ? {} : { error: (result.stderr || "command failed").trim().slice(0, 240) }) };
+  const native = async (command: string, args: string[], source: string) => {
+    const result = await defaultSpawn(command, args, { env, timeoutMs: 20_000 });
+    const ok = result.code === 0 && !result.error;
+    sources[source] = { url: `${command} ${args.join(" ")}`, ok, ...(ok ? {} : { error: (result.stderr || result.error?.message || "command failed").trim().slice(0, 240) }) };
     if (!ok) return;
     for (const line of (result.stdout || "").split(/\r?\n/)) {
       const parts = line.trim().split(/\s+/);
@@ -109,9 +109,9 @@ export async function refreshModelInventory(options: { outputRoot: string; env?:
       }
     }
   };
-  native("pi", ["--list-models"], "pi");
-  native("grok", ["models"], "grok");
-  native("agy", ["models"], "agy");
+  await native("pi", ["--list-models"], "pi");
+  await native("grok", ["models"], "grok");
+  await native("agy", ["models"], "agy");
   const openrouter = await fetchModels(env.KXM_OPENROUTER_MODELS_URL?.trim() || OR_URL, env.OPENROUTER_API_KEY);
   const openrouterUrl = env.KXM_OPENROUTER_MODELS_URL?.trim() || OR_URL;
   sources.openrouter = { url: openrouterUrl, ok: !openrouter.error, ...(openrouter.error ? { error: openrouter.error } : {}) };

package/plugins/kxm/src/runtime.ts

@@ -10,3 +10,4 @@ export * from "./improve.ts";
 export * from "./browser.ts";
 export * from "./modes.ts";
 export * from "./ssh-remote.ts";
+export * from "./subagent-control.ts";

package/plugins/kxm/src/subagent-control.ts

@@ -0,0 +1,312 @@
+/**
+ * Supervisory agent control, in-process real-time steering, and work-splitting.
+ *
+ * Implements:
+ * - Dual-tool control plane: `agent` (spawn) and `agent_control` (manage, poll, steer, stop).
+ * - Strict capability narrowing via `allowed_tools[]` allowlists.
+ * - Mid-flight steering instruction injection.
+ * - Subagent state lifecycle management (working, blocked, idle, done, error).
+ */
+
+import { randomUUID } from "node:crypto";
+import { assertCommandSeatbelt } from "./safety-integrity.ts";
+
+export type SubagentType = "general" | "Explore" | "Plan" | "Reviewer" | "Auditor";
+export type SubagentStatus = "pending" | "running" | "blocked" | "completed" | "stopped" | "failed";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high";
+
+export interface AgentSpawnParams {
+  prompt: string;
+  description: string;
+  type?: SubagentType | undefined;
+  model?: string | undefined;
+  thinking?: ThinkingLevel | undefined;
+  allowed_tools?: string[] | undefined;
+  turns?: number | undefined;
+  background?: boolean | undefined;
+  parent_tools?: readonly string[] | undefined;
+}
+
+export interface AgentControlParams {
+  action: "info" | "result" | "steer" | "stop";
+  kind?: "types" | "models" | "active" | undefined;
+  agent_id?: string | undefined;
+  message?: string | undefined;
+  turns?: number | undefined;
+  verbose?: boolean | undefined;
+}
+
+export interface SubagentRecord {
+  id: string;
+  description: string;
+  type: SubagentType;
+  model: string;
+  thinking: ThinkingLevel;
+  allowedTools: string[];
+  status: SubagentStatus;
+  turnsMax: number;
+  turnsCompleted: number;
+  prompt: string;
+  createdAt: string;
+  updatedAt: string;
+  steeringMessages: Array<{ text: string; injectedAt: string; processed: boolean }>;
+  output?: string | undefined;
+  error?: string | undefined;
+}
+
+export interface SubagentExecutionReceipt {
+  ok: boolean;
+  action: string;
+  agent_id?: string | undefined;
+  status?: SubagentStatus | undefined;
+  activeAgents?: Array<{ id: string; description: string; type: SubagentType; status: SubagentStatus }> | undefined;
+  types?: readonly SubagentType[] | undefined;
+  result?: string | undefined;
+  steered?: boolean | undefined;
+  stopped?: boolean | undefined;
+  error?: string | undefined;
+}
+
+export const SUBAGENT_TYPES: readonly SubagentType[] = Object.freeze([
+  "general",
+  "Explore",
+  "Plan",
+  "Reviewer",
+  "Auditor",
+]);
+
+export const DEFAULT_SUBAGENT_MODELS: Readonly<Record<SubagentType, string>> = Object.freeze({
+  general: "grok/grok-4.6",
+  Explore: "openrouter/qwen/qwen3-coder-plus",
+  Plan: "claude/fable",
+  Reviewer: "openai/gpt-5.6-sol",
+  Auditor: "claude/fable",
+});
+
+/**
+ * Validates and intersects child allowed tools against the parent tool surface.
+ * Enforces the safety invariant that a child can only narrow, never expand authority.
+ */
+export function narrowSubagentTools(
+  requestedTools: readonly string[] | undefined,
+  parentTools?: readonly string[] | undefined,
+): string[] {
+  if (!requestedTools || requestedTools.length === 0) {
+    return parentTools ? [...parentTools] : ["read", "grep", "find"];
+  }
+
+  if (!parentTools || parentTools.length === 0) {
+    return [...requestedTools];
+  }
+
+  const parentSet = new Set(parentTools);
+  const narrowed: string[] = [];
+
+  for (const tool of requestedTools) {
+    if (parentSet.has(tool)) {
+      narrowed.push(tool);
+    }
+  }
+
+  if (narrowed.length === 0 && requestedTools.length > 0) {
+    throw new Error(
+      `Cannot spawn subagent: requested tools [${requestedTools.join(", ")}] expand beyond parent capabilities.`,
+    );
+  }
+
+  return narrowed;
+}
+
+/**
+ * In-Process Subagent Manager.
+ */
+export class SubagentManager {
+  private readonly subagents = new Map<string, SubagentRecord>();
+
+  /**
+   * Spawns a new managed subagent with strict capability boundaries.
+   */
+  spawn(params: AgentSpawnParams): SubagentRecord {
+    if (!params.prompt || !params.prompt.trim()) {
+      throw new Error('Subagent "prompt" is required.');
+    }
+    if (!params.description || !params.description.trim()) {
+      throw new Error('Subagent "description" is required.');
+    }
+
+    const type = params.type ?? "general";
+    const model = params.model ?? DEFAULT_SUBAGENT_MODELS[type] ?? "grok/grok-4.6";
+    const thinking = params.thinking ?? "low";
+    const allowedTools = narrowSubagentTools(params.allowed_tools, params.parent_tools);
+    const id = `ag_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+    const now = new Date().toISOString();
+
+    const record: SubagentRecord = {
+      id,
+      description: params.description.trim(),
+      type,
+      model,
+      thinking,
+      allowedTools,
+      status: params.background === false ? "completed" : "running",
+      turnsMax: params.turns ?? 10,
+      turnsCompleted: 0,
+      prompt: params.prompt.trim(),
+      createdAt: now,
+      updatedAt: now,
+      steeringMessages: [],
+    };
+
+    this.subagents.set(id, record);
+    return record;
+  }
+
+  /**
+   * Dispatches an action from the `agent_control` tool.
+   */
+  control(params: AgentControlParams): SubagentExecutionReceipt {
+    const action = params.action;
+
+    // 1. Action: "info"
+    if (action === "info") {
+      const kind = params.kind ?? "active";
+      if (kind === "types") {
+        return {
+          ok: true,
+          action: "info",
+          types: SUBAGENT_TYPES,
+        };
+      }
+      if (kind === "models") {
+        return {
+          ok: true,
+          action: "info",
+          result: JSON.stringify(DEFAULT_SUBAGENT_MODELS),
+        };
+      }
+      const active = Array.from(this.subagents.values()).map((ag) => ({
+        id: ag.id,
+        description: ag.description,
+        type: ag.type,
+        status: ag.status,
+      }));
+      return {
+        ok: true,
+        action: "info",
+        activeAgents: active,
+      };
+    }
+
+    if (!params.agent_id) {
+      return {
+        ok: false,
+        action,
+        error: 'Parameter "agent_id" is required for result, steer, and stop actions.',
+      };
+    }
+
+    const agent = this.subagents.get(params.agent_id);
+    if (!agent) {
+      return {
+        ok: false,
+        action,
+        agent_id: params.agent_id,
+        error: `Subagent "${params.agent_id}" not found.`,
+      };
+    }
+
+    // 2. Action: "result"
+    if (action === "result") {
+      return {
+        ok: true,
+        action: "result",
+        agent_id: agent.id,
+        status: agent.status,
+        result: agent.output ?? `[Subagent is currently ${agent.status}]`,
+      };
+    }
+
+    // 3. Action: "steer"
+    if (action === "steer") {
+      if (!params.message || !params.message.trim()) {
+        return {
+          ok: false,
+          action: "steer",
+          agent_id: agent.id,
+          error: 'Parameter "message" is required for steer action.',
+        };
+      }
+
+      if (agent.status === "completed" || agent.status === "stopped" || agent.status === "failed") {
+        return {
+          ok: false,
+          action: "steer",
+          agent_id: agent.id,
+          error: `Cannot steer subagent "${agent.id}" because it is already ${agent.status}.`,
+        };
+      }
+
+      agent.steeringMessages.push({
+        text: params.message.trim(),
+        injectedAt: new Date().toISOString(),
+        processed: false,
+      });
+      agent.updatedAt = new Date().toISOString();
+
+      return {
+        ok: true,
+        action: "steer",
+        agent_id: agent.id,
+        status: agent.status,
+        steered: true,
+      };
+    }
+
+    // 4. Action: "stop"
+    if (action === "stop") {
+      agent.status = "stopped";
+      agent.updatedAt = new Date().toISOString();
+      return {
+        ok: true,
+        action: "stop",
+        agent_id: agent.id,
+        status: "stopped",
+        stopped: true,
+      };
+    }
+
+    return {
+      ok: false,
+      action,
+      error: `Unknown control action "${action}".`,
+    };
+  }
+
+  /**
+   * Retrieves an agent record by ID.
+   */
+  get(agentId: string): SubagentRecord | undefined {
+    return this.subagents.get(agentId);
+  }
+
+  /**
+   * Marks a subagent as completed with output.
+   */
+  complete(agentId: string, output: string): void {
+    const agent = this.subagents.get(agentId);
+    if (agent) {
+      agent.status = "completed";
+      agent.output = output;
+      agent.updatedAt = new Date().toISOString();
+    }
+  }
+
+  /**
+   * Returns all active running subagents.
+   */
+  listActive(): SubagentRecord[] {
+    return Array.from(this.subagents.values()).filter(
+      (ag) => ag.status === "running" || ag.status === "pending" || ag.status === "blocked",
+    );
+  }
+}