jeo-code 0.12.9 → 0.12.11

package/src/agent/notify/topic-registry.ts

@@ -30,40 +30,127 @@ export interface TopicRecord {
 export interface TopicRegistryState {
   /** sessionId -> record. */
   topics: Record<string, TopicRecord>;
+  /** Bot account identity used to scope persisted topic ownership. */
+  botId?: string;
+  /** Paired Telegram chat identity used to scope persisted topic ownership. */
+  chatId?: string;
 }
 
 export function emptyTopicRegistryState(): TopicRegistryState {
   return { topics: {} };
 }
 
+/** Runtime guards for persisted topic state and API-created records. */
+function isRecordObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isValidTopicId(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && Number.isSafeInteger(value) && value > 0;
+}
+
+function isTopicRecord(value: unknown): value is TopicRecord {
+  if (!isRecordObject(value) || !isValidTopicId(value.topicId) ||
+      typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) return false;
+  return value.name === undefined || typeof value.name === "string";
+}
+
+function validateTopicRecord(sessionId: string, value: unknown): TopicRecord {
+  if (!isRecordObject(value)) throw new Error(`Invalid topic registry record for session '${sessionId}'`);
+  if (!isValidTopicId(value.topicId)) throw new Error(`Invalid topic ID for session '${sessionId}'`);
+  if (typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) {
+    throw new Error(`Invalid creation timestamp for session '${sessionId}'`);
+  }
+  if (value.name !== undefined && typeof value.name !== "string") {
+    throw new Error(`Invalid topic name for session '${sessionId}'`);
+  }
+  if (!isTopicRecord(value)) throw new Error(`Invalid topic registry record for session '${sessionId}'`);
+  return value;
+}
+
+interface TopicRegistryIdentity {
+  botId: string;
+  chatId: string;
+}
+
+function parseTopicRegistryIdentity(state: Record<string, unknown>): TopicRegistryIdentity | undefined {
+  const hasBotId = Object.hasOwn(state, "botId");
+  const hasChatId = Object.hasOwn(state, "chatId");
+  if (!hasBotId && !hasChatId) return undefined;
+  if (!hasBotId || !hasChatId || typeof state.botId !== "string" || !state.botId ||
+      typeof state.chatId !== "string" || !state.chatId) {
+    throw new Error("Invalid topic registry identity: botId and chatId must be non-empty strings");
+  }
+  return { botId: state.botId, chatId: state.chatId };
+}
+
+function sameTopicRegistryIdentity(a: TopicRegistryIdentity, b: TopicRegistryIdentity | undefined): boolean {
+  return b !== undefined && a.botId === b.botId && a.chatId === b.chatId;
+}
+
 /**
  * In-memory registry over a serializable state. Topic creation is injected via
  * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
  * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
  */
 export class TopicRegistry {
-  private readonly topics: Map<string, TopicRecord>;
+  private topics: Map<string, TopicRecord>;
   /** Maps topicId -> sessionId for fast inbound routing. */
-  private readonly byTopic = new Map<number, string>();
+  private byTopic = new Map<number, string>();
   /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
   private readonly inflight = new Map<string, Promise<TopicRecord>>();
+  /** Invalidates in-flight creates when a validated state replaces the indexes. */
+  private revision = 0;
+  /** Identity of the persisted Telegram destination currently loaded. */
+  private identity: TopicRegistryIdentity | undefined;
 
   constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
-    this.topics = new Map(Object.entries(state.topics ?? {}));
-    for (const [sessionId, record] of this.topics) this.byTopic.set(record.topicId, sessionId);
+    this.topics = new Map();
+    this.load(state);
   }
-
-  /** Merge a serialized state into this registry, preserving all persisted fields. */
+  /** Merge a serialized state, replacing indexes atomically within its identity. */
   load(state: TopicRegistryState): void {
-    for (const [sessionId, record] of Object.entries(state.topics ?? {})) {
-      this.topics.set(sessionId, record);
-      this.byTopic.set(record.topicId, sessionId);
+    if (!isRecordObject(state) || !isRecordObject(state.topics)) {
+      throw new Error("Invalid topic registry state: topics must be an object");
+    }
+
+    const incomingIdentity = parseTopicRegistryIdentity(state);
+    const resetForIdentity = this.identity !== undefined
+      ? !sameTopicRegistryIdentity(this.identity, incomingIdentity)
+      : incomingIdentity !== undefined && this.topics.size > 0;
+    const nextTopics = resetForIdentity ? new Map<string, TopicRecord>() : new Map(this.topics);
+    for (const [sessionId, rawRecord] of Object.entries(state.topics)) {
+      nextTopics.set(sessionId, validateTopicRecord(sessionId, rawRecord));
     }
+
+    const nextByTopic = new Map<number, string>();
+    for (const [sessionId, rawRecord] of nextTopics) {
+      const record = validateTopicRecord(sessionId, rawRecord);
+      const owner = nextByTopic.get(record.topicId);
+      if (owner !== undefined) {
+        throw new Error(`Duplicate topic ID ${record.topicId} for sessions '${owner}' and '${sessionId}'`);
+      }
+      nextByTopic.set(record.topicId, sessionId);
+    }
+
+    this.topics = nextTopics;
+    this.byTopic = nextByTopic;
+    this.identity = incomingIdentity ?? (resetForIdentity ? undefined : this.identity);
+    this.revision++;
+    this.inflight.clear();
   }
 
   /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
   sessionForTopic(topicId: number): string | undefined {
-    return this.byTopic.get(topicId);
+    if (!isValidTopicId(topicId)) return undefined;
+    const sessionId = this.byTopic.get(topicId);
+    if (sessionId === undefined) return undefined;
+    const record = this.topics.get(sessionId);
+    if (!record || !isTopicRecord(record) || record.topicId !== topicId) {
+      this.byTopic.delete(topicId);
+      return undefined;
+    }
+    return sessionId;
   }
 
   /** All session ids with a persisted topic record. */
@@ -87,16 +174,29 @@ export class TopicRegistry {
     name?: string,
   ): Promise<TopicRecord> {
     const existing = this.topics.get(sessionId);
-    if (existing) return existing;
+    if (existing) {
+      if (!isTopicRecord(existing)) throw new Error(`Invalid topic registry record for session '${sessionId}'`);
+      if (this.byTopic.get(existing.topicId) !== sessionId) {
+        throw new Error(`Topic registry mapping for session '${sessionId}' is invalid`);
+      }
+      return existing;
+    }
     // Concurrency guard: many session frames (identity/idle/turn/ask) can race
     // to first-use the same session. Without this, each call passes the
     // `existing` check before `create()` resolves and creates a DUPLICATE
     // forum topic. Share a single in-flight create per session id.
     const pending = this.inflight.get(sessionId);
     if (pending) return pending;
+    const revision = this.revision;
     const promise = (async () => {
       const topicId = await create();
-      const record: TopicRecord = { topicId, name, createdAt: now() };
+      if (revision !== this.revision) throw new Error("Topic registry changed while creating a topic");
+      if (!isValidTopicId(topicId)) throw new Error("Invalid topic ID returned by topic creation");
+      const owner = this.byTopic.get(topicId);
+      if (owner !== undefined && owner !== sessionId) {
+        throw new Error(`Duplicate topic ID ${topicId} already belongs to session '${owner}'`);
+      }
+      const record = validateTopicRecord(sessionId, { topicId, name, createdAt: now() });
       this.topics.set(sessionId, record);
       this.byTopic.set(topicId, sessionId);
       return record;
@@ -105,7 +205,7 @@ export class TopicRegistry {
     try {
       return await promise;
     } finally {
-      this.inflight.delete(sessionId);
+      if (this.inflight.get(sessionId) === promise) this.inflight.delete(sessionId);
     }
   }
 
@@ -141,12 +241,15 @@ export class TopicRegistry {
     const record = this.topics.get(sessionId);
     if (!record) return false;
     this.topics.delete(sessionId);
-    this.byTopic.delete(record.topicId);
+    for (const [topicId, owner] of this.byTopic) {
+      if (owner === sessionId) this.byTopic.delete(topicId);
+    }
     return true;
   }
 
   /** Serialize for atomic persistence beside the daemon state. */
   serialize(): TopicRegistryState {
-    return { topics: Object.fromEntries(this.topics) };
+    const topics = Object.fromEntries(this.topics);
+    return this.identity ? { topics, ...this.identity } : { topics };
   }
 }

package/src/agent/skill-router.ts

@@ -43,9 +43,28 @@ export interface SkillRouteSelection {
   /** Advisory only — never an install or model instruction. */
   routing: string;
 }
-
 const TOKEN_RE = /[a-z0-9][a-z0-9._-]*/gi;
 
+interface CachedSkillTokens {
+  textTokens: Set<string>;
+  nameTokens: Set<string>;
+}
+
+const skillTokenCache = new WeakMap<SkillDoc, CachedSkillTokens>();
+
+function getSkillTokens(skill: SkillDoc): CachedSkillTokens {
+  let cached = skillTokenCache.get(skill);
+  if (!cached) {
+    const text = skillText(skill);
+    cached = {
+      textTokens: tokens(text),
+      nameTokens: tokens(skill.name.replace(/[:/]/g, " ")),
+    };
+    skillTokenCache.set(skill, cached);
+  }
+  return cached;
+}
+
 /** Closed-class / low-signal words excluded from routing overlap — without
  *  this, chit-chat ("how are you") spuriously matches every long skill doc. */
 const STOPWORDS = new Set([
@@ -78,8 +97,11 @@ function skillText(s: SkillDoc): string {
 export function scoreSkillForTask(task: string, skill: SkillDoc): { score: number; reasons: string[] } {
   const taskTokens = tokens(task);
   if (taskTokens.size === 0) return { score: 0, reasons: [] };
-  const text = skillText(skill);
-  const textTokens = tokens(text);
+  return scoreSkillWithTaskTokens(taskTokens, skill);
+}
+
+function scoreSkillWithTaskTokens(taskTokens: Set<string>, skill: SkillDoc): { score: number; reasons: string[] } {
+  const { textTokens, nameTokens } = getSkillTokens(skill);
   let overlap = 0;
   const reasons: string[] = [];
   for (const t of taskTokens) {
@@ -88,7 +110,6 @@ export function scoreSkillForTask(task: string, skill: SkillDoc): { score: numbe
       if (reasons.length < 5) reasons.push(t);
     }
   }
-  const nameTokens = tokens(skill.name.replace(/[:/]/g, " "));
   let nameHits = 0;
   for (const t of taskTokens) if (nameTokens.has(t)) nameHits++;
   // Overlap ratio over task vocabulary + a decisive name bonus: an explicit
@@ -98,6 +119,7 @@ export function scoreSkillForTask(task: string, skill: SkillDoc): { score: numbe
   return { score, reasons };
 }
 
+
 /**
  * Jev-style `route-skills`: heuristic top-k skill selection for one task.
  * Never throws; empty input yields explicit none with reason "gate".
@@ -109,8 +131,12 @@ export function routeSkillsForTask(task: string, skills: SkillDoc[], topK = SKIL
   if (!trimmed) {
     return { topK: [], reason: "gate", strategy, routing: "No task text — no skill suggested. Answer directly." };
   }
+  const taskTokens = tokens(trimmed);
+  if (taskTokens.size === 0) {
+    return { topK: [], reason: "gate", strategy, routing: "No skill cleared the gate — answer directly without a workflow skill." };
+  }
   const scored = skills.map(s => {
-    const { score, reasons } = scoreSkillForTask(trimmed, s);
+    const { score, reasons } = scoreSkillWithTaskTokens(taskTokens, s);
     return { name: s.name, score, reasons };
   });
   scored.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : 1));

package/src/agent/subagent-registry.ts

@@ -57,7 +57,7 @@ export function truncateDetachedResult(s: string, maxBytes = MAX_DETACHED_RESULT
   return headSlice + marker + tailSlice;
 }
 
-export type SubagentStatus = "running" | "completed" | "failed" | "cancelled";
+export type SubagentStatus = "running" | "paused" | "completed" | "failed" | "cancelled";
 
 export interface SubagentRecord {
   /** Stable id, e.g. "executor-1". */
@@ -72,12 +72,22 @@ export interface SubagentRecord {
   success?: boolean;
   /** Final subagent report/output, set once the run settles. */
   result?: string;
+  /** True when delegated execution may have changed workspace state. */
+  mutationMayHaveOccurred?: boolean;
+  /** Live or last known activity description (e.g. current tool being run). */
+  activity?: string;
+  /** True when the subagent can be resumed with follow-up instructions. */
+  resumable?: boolean;
+
 }
 
+
 interface Entry {
   record: SubagentRecord;
   promise: Promise<void>;
   abort: AbortController;
+  readOnly: boolean;
+  settled: boolean;
 }
 
 /** A detached run: receives its own AbortSignal and its own registry id, and
@@ -87,13 +97,18 @@ interface Entry {
  *  streaming live events itself. */
 export type DetachedRunner = (signal: AbortSignal, id: string) => Promise<ToolResult>;
 
+export const DEFAULT_PAUSE_DIRECTIVE =
+  "Stop at the next safe boundary and yield. You can be resumed later with more instructions.";
+export const DEFAULT_RESUME_MESSAGE = "Continue from where you left off.";
+
 export class SubagentRegistry {
   private readonly entries = new Map<string, Entry>();
   private readonly seq = new Map<string, number>();
   private readonly steerInboxes = new Map<string, string[]>();
+  private readonly pausedIds = new Set<string>();
 
   /** Register and START a detached run; returns the (running) record immediately. */
-  launch(role: string, task: string, runner: DetachedRunner): SubagentRecord {
+  launch(role: string, task: string, runner: DetachedRunner, options: { readOnly?: boolean } = {}): SubagentRecord {
     const n = (this.seq.get(role) ?? 0) + 1;
     this.seq.set(role, n);
     const id = `${role}-${n}`;
@@ -106,24 +121,35 @@ export class SubagentRegistry {
       startedAt: Date.now(),
     };
     this.steerInboxes.set(id, []);
-    const promise = (async () => {
+    const entry: Entry = { record, promise: Promise.resolve(), abort, readOnly: options.readOnly ?? false, settled: false };
+    this.entries.set(id, entry);
+    entry.promise = (async () => {
       try {
         const res = await runner(abort.signal, id);
+        // Preserve structured mutation evidence even when cancellation already fired;
+        // the runner may have completed work before its promise settled.
+        record.mutationMayHaveOccurred = res.mutationMayHaveOccurred;
         // A cancel that already fired wins — don't overwrite the terminal state.
         if (record.status === "cancelled") return;
         record.status = res.success ? "completed" : "failed";
         record.success = res.success;
+        record.resumable = true;
         record.result = truncateDetachedResult(res.output || res.error || "");
       } catch (err) {
+        // A mutating runner may throw after a partial workspace change; retain
+        // conservative evidence before cancellation can hide the late failure.
+        if (!entry.readOnly) record.mutationMayHaveOccurred = true;
         if (record.status === "cancelled") return;
         record.status = "failed";
+        record.resumable = true;
         record.result = truncateDetachedResult(err instanceof Error ? err.message : String(err));
       } finally {
+        entry.settled = true;
         if (record.finishedAt === undefined) record.finishedAt = Date.now();
         this.steerInboxes.delete(id);
       }
+
     })();
-    this.entries.set(id, { record, promise, abort });
     return record;
   }
 
@@ -139,6 +165,11 @@ export class SubagentRegistry {
     return this.list().filter(r => r.status === "running");
   }
 
+  /** Return mutating runs whose runner has not settled, including cancelled runs. */
+  inFlightMutators(): SubagentRecord[] {
+    return [...this.entries.values()].filter(entry => !entry.settled && !entry.readOnly).map(entry => entry.record);
+  }
+
   /** Wait for the given ids (or all running, when empty). With `timeoutMs` the wait
    *  is bounded — unfinished runs simply stay "running" in the returned snapshot. */
   async awaitIds(ids: string[], timeoutMs?: number): Promise<SubagentRecord[]> {
@@ -184,16 +215,67 @@ export class SubagentRegistry {
     };
   }
 
+
+  /** Record an active step or tool description for a subagent id. */
+  setActivity(id: string, activity: string | undefined): void {
+    const rec = this.get(id);
+    if (rec) {
+      rec.activity = activity;
+    }
+  }
+
+  /** Request that one or more running subagents pause at their next safe boundary. */
+  pause(ids: string[], directive = DEFAULT_PAUSE_DIRECTIVE): SubagentRecord[] {
+    const out: SubagentRecord[] = [];
+    const targets = ids.length ? ids : this.running().map(r => r.id);
+    for (const id of targets) {
+      const rec = this.get(id);
+      if (!rec) continue;
+      if (rec.status === "running") {
+        this.steer(id, directive);
+        this.pausedIds.add(id);
+        rec.status = "paused";
+        rec.resumable = true;
+      }
+      out.push(rec);
+
+    }
+    return out;
+  }
+
+  /** Resume a paused (or resumable completed) subagent with follow-up instructions. */
+  resume(id: string, message = DEFAULT_RESUME_MESSAGE): { success: boolean; record?: SubagentRecord; error?: string } {
+    const rec = this.get(id);
+    if (!rec) return { success: false, error: `No subagent matches ${id}.` };
+    this.pausedIds.delete(id);
+    if (rec.status === "paused") {
+      rec.status = "running";
+      this.steer(id, message);
+      return { success: true, record: rec };
+    }
+    if (rec.status === "running") {
+      this.steer(id, message);
+      return { success: true, record: rec };
+    }
+    // If completed or failed, steer queues message for any attached listener
+    rec.status = "running";
+    rec.resumable = true;
+    this.steer(id, message);
+    return { success: true, record: rec };
+  }
+
   /** Cancel the given ids (or all running, when empty): aborts the run and marks the
    *  record cancelled. Already-terminal records are returned unchanged. */
   cancel(ids: string[]): SubagentRecord[] {
     const out: SubagentRecord[] = [];
     for (const id of ids) {
+      this.pausedIds.delete(id);
       const e = this.entries.get(id);
       if (!e) continue;
-      if (e.record.status === "running") {
+      if (e.record.status === "running" || e.record.status === "paused") {
         e.record.status = "cancelled";
         e.record.finishedAt = Date.now();
+        e.record.resumable = false;
         e.abort.abort();
       }
       out.push(e.record);

package/src/agent/subagent-tool.ts

@@ -13,12 +13,31 @@ import type { ToolHandler } from "./engine";
 import type { ToolResult } from "./tools";
 import type { SubagentRegistry, SubagentRecord } from "./subagent-registry";
 
+function mutationEvidence(recs: readonly SubagentRecord[]): boolean | undefined {
+  return recs.some(rec => rec.mutationMayHaveOccurred === true) ? true : undefined;
+}
+
+export type SubagentVerbosity = "receipt" | "preview" | "full";
+
+const DEFAULT_VERBOSITY: SubagentVerbosity = "preview";
+const DEFAULT_LIST_LIMIT = 10;
+const MAX_LIST_LIMIT = 50;
+const PREVIEW_CHARS = 2_000;
+const FULL_CHARS = 12_000;
+
+
 /** One-line protocol description appended to the launch system prompt. */
 export const SUBAGENT_TOOL_PROTOCOL_LINE =
-  `subagent {action:"list"|"inspect"|"await"|"cancel"|"steer", ids?, id?, message?, timeoutMs?} — control DETACHED ` +
-  `subagents started with task{detached:true}. 'await' blocks (optionally up to timeoutMs ms) and ` +
-  `returns their reports; 'inspect' shows status + result; 'cancel' aborts them; 'steer' sends {id, message} ` +
-  `to inject a live instruction into that ONE running subagent, picked up before its next step. Omit ids to target all running (list/inspect/await/cancel).`;
+  `subagent {action:"list"|"inspect"|"await"|"cancel"|"steer"|"pause"|"resume", ids?, id?, message?, verbosity?:"receipt"|"preview"|"full", limit?:number, timeoutMs?} — control DETACHED ` +
+  `subagents started with task{detached:true}. 'await' blocks and returns reports; 'inspect' shows status + result; 'cancel' aborts; 'steer' injects live instructions into running subagents; ` +
+  `'pause' asks running subagents to wrap up safely; 'resume' wakes or redirects a paused/completed subagent. ` +
+  `'verbosity' controls result length ('receipt' status-only, 'preview' <=2000 chars, 'full' <=12000 chars); 'limit' caps listings.`;
+
+const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+function isValidId(id: string): boolean {
+  return SAFE_ID_RE.test(id);
+}
 
 function elapsed(rec: SubagentRecord): string {
   const end = rec.finishedAt ?? Date.now();
@@ -26,44 +45,93 @@ function elapsed(rec: SubagentRecord): string {
 }
 
 function rowLine(rec: SubagentRecord): string {
-  return `- ${rec.id} [${rec.status.toUpperCase()}] ${elapsed(rec)} · ${rec.task}`;
+  const parts = [`- ${rec.id} [${rec.status.toUpperCase()}] ${elapsed(rec)} · ${rec.task}`];
+  if (rec.activity) parts.push(`(${rec.activity})`);
+  return parts.join(" ");
 }
 
-function detailBlock(rec: SubagentRecord): string {
+function detailBlock(rec: SubagentRecord, verbosity?: SubagentVerbosity): string {
   const head = rowLine(rec);
-  if (rec.status === "running" || !rec.result) return head;
-  return `${head}\n${rec.result}`;
+  if (rec.status === "running" && !rec.result) return head;
+  if (verbosity === "receipt") return head;
+  const rawResult = rec.result ?? "";
+  if (verbosity === "preview" && rawResult.length > PREVIEW_CHARS) {
+    const text = `${rawResult.slice(0, PREVIEW_CHARS - 1)}… [truncated, use verbosity:"full"]`;
+    return `${head}\n${text}`;
+  }
+  return rawResult ? `${head}\n${rawResult}` : head;
 }
 
+
 function idsOf(args: Record<string, any>): string[] {
-  if (Array.isArray(args.ids)) return args.ids.map((x: unknown) => String(x));
-  if (args.id !== undefined) return [String(args.id)];
+  if (Array.isArray(args.ids)) return args.ids.map((x: unknown) => String(x)).filter(isValidId);
+  if (args.id !== undefined) {
+    const s = String(args.id);
+    return isValidId(s) ? [s] : [];
+  }
   return [];
 }
 
+function clampLimit(value: unknown): number {
+  if (typeof value !== "number" || Number.isNaN(value)) return DEFAULT_LIST_LIMIT;
+  return Math.max(1, Math.min(MAX_LIST_LIMIT, Math.floor(value)));
+}
+
 export function createSubagentTool(registry: SubagentRegistry): ToolHandler {
   return async (args: Record<string, any>, _cwd: string): Promise<ToolResult> => {
     const action = String(args.action ?? "list").trim().toLowerCase();
     const ids = idsOf(args);
+    const verbosity: SubagentVerbosity | undefined = ["receipt", "preview", "full"].includes(args.verbosity) ? args.verbosity : undefined;
+
+    if (verbosity === "full" && action === "list") {
+      return {
+        success: false,
+        output: "",
+        error: "verbosity='full' is not permitted with action='list' to protect context budget. Use action='inspect' with explicit id(s).",
+      };
+    }
+
 
     if (action === "list") {
       const rows = registry.list();
       if (rows.length === 0) {
         return { success: true, output: "No detached subagents in this session. Launch one with task {detached:true}." };
       }
+      const limit = clampLimit(args.limit);
+      const sorted = [...rows].reverse(); // newest first
+      const visible = sorted.slice(0, limit);
       const running = rows.filter(r => r.status === "running").length;
-      return { success: true, output: `${rows.length} subagent(s), ${running} running:\n${rows.map(rowLine).join("\n")}` };
+      const paused = rows.filter(r => r.status === "paused").length;
+      const truncatedMsg = rows.length > limit ? `\n(… ${rows.length - limit} older subagent(s) omitted; specify limit or explicit ids)` : "";
+      return {
+        success: true,
+        output: `${rows.length} subagent(s) (${running} running, ${paused} paused):\n${visible.map(rowLine).join("\n")}${truncatedMsg}`,
+        mutationMayHaveOccurred: mutationEvidence(rows),
+      };
+
     }
 
     if (action === "inspect") {
       const targets = (ids.length ? ids.map(id => registry.get(id)) : registry.list())
         .filter((r): r is SubagentRecord => r !== undefined);
       if (targets.length === 0) {
-        return { success: false, output: "", error: ids.length ? `No subagent matches ${ids.join(", ")}.` : "No detached subagents in this session." };
+        return {
+          success: false,
+          output: "",
+          error: ids.length ? `No subagent matches ${ids.join(", ")}.` : "No detached subagents in this session.",
+        };
       }
-      return { success: true, output: targets.map(detailBlock).join("\n\n") };
+      const limit = ids.length ? targets.length : clampLimit(args.limit);
+      const visible = targets.slice(0, limit);
+
+      return {
+        success: true,
+        output: visible.map(r => detailBlock(r, verbosity)).join("\n\n"),
+        mutationMayHaveOccurred: mutationEvidence(targets),
+      };
     }
 
+
     if (action === "await") {
       const targets = ids.length ? ids : registry.running().map(r => r.id);
       if (targets.length === 0) {
@@ -73,9 +141,41 @@ export function createSubagentTool(registry: SubagentRegistry): ToolHandler {
       const recs = await registry.awaitIds(targets, timeoutMs);
       const stillRunning = recs.filter(r => r.status === "running").length;
       const head = stillRunning > 0
-        ? `Awaited ${recs.length} subagent(s); ${stillRunning} still running after the ${timeoutMs}ms timeout — await again or cancel.`
+        ? `Awaited ${recs.length} subagent(s); ${stillRunning} still running after the ${timeoutMs}ms timeout — await again, pause, or cancel.`
         : `Awaited ${recs.length} subagent(s); all settled.`;
-      return { success: stillRunning === 0, output: `${head}\n\n${recs.map(detailBlock).join("\n\n")}` };
+      return {
+        success: stillRunning === 0,
+        output: `${head}\n\n${recs.map(r => detailBlock(r, verbosity)).join("\n\n")}`,
+        mutationMayHaveOccurred: mutationEvidence(recs),
+      };
+    }
+
+
+    if (action === "pause") {
+      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      if (targets.length === 0) {
+        return { success: true, output: "No running subagents to pause." };
+      }
+      const message = typeof args.message === "string" && args.message.trim() ? args.message.trim() : undefined;
+      const paused = registry.pause(targets, message);
+      return { success: true, output: `Paused ${paused.length} subagent(s):\n${paused.map(rowLine).join("\n")}` };
+    }
+
+    if (action === "resume") {
+      if (ids.length !== 1) {
+        return {
+          success: false,
+          output: "",
+          error: `subagent 'resume' requires exactly one target id (e.g. {action:"resume", id:"executor-1"}). Got: ${JSON.stringify(args.id || args.ids)}.`,
+        };
+      }
+      const id = ids[0]!;
+      const message = typeof args.message === "string" && args.message.trim() ? args.message.trim() : undefined;
+      const res = registry.resume(id, message);
+      if (!res.success) {
+        return { success: false, output: "", error: res.error || `Failed to resume subagent '${id}'.` };
+      }
+      return { success: true, output: `Resumed subagent '${id}' (${res.record?.status}): ${message ?? "resumed with default message"}` };
     }
 
     if (action === "cancel") {
@@ -84,16 +184,27 @@ export function createSubagentTool(registry: SubagentRegistry): ToolHandler {
         return { success: true, output: "No running subagents to cancel." };
       }
       const recs = registry.cancel(targets);
-      return { success: true, output: `Cancelled ${recs.length} subagent(s):\n${recs.map(rowLine).join("\n")}` };
+      return {
+        success: true,
+        output: `Cancelled ${recs.length} subagent(s):\n${recs.map(rowLine).join("\n")}`,
+        mutationMayHaveOccurred: mutationEvidence(recs),
+      };
     }
 
     if (action === "steer") {
       const targetIds = Array.isArray(args.id) ? [] : args.id !== undefined ? [String(args.id)] : [];
       const message = typeof args.message === "string" ? args.message : typeof args.text === "string" ? args.text : "";
       if (targetIds.length !== 1) {
-        return { success: false, output: "", error: `subagent 'steer' requires exactly one target 'id' (a single string, not 'ids'). Got: ${JSON.stringify(args.id)}.` };
+        return {
+          success: false,
+          output: "",
+          error: `subagent 'steer' requires exactly one target 'id' (a single string, not 'ids'). Got: ${JSON.stringify(args.id)}.`,
+        };
       }
       const id = targetIds[0]!;
+      if (!isValidId(id)) {
+        return { success: false, output: "", error: `Invalid subagent id '${id}'.` };
+      }
       if (!message.trim()) {
         return { success: false, output: "", error: "subagent 'steer' requires a non-empty 'message' (or 'text')." };
       }
@@ -104,6 +215,10 @@ export function createSubagentTool(registry: SubagentRegistry): ToolHandler {
       return { success: true, output: `Steered ${id}: ${message.trim()}` };
     }
 
-    return { success: false, output: "", error: `Unknown subagent action '${action}'. Use list | inspect | await | cancel | steer.` };
+    return {
+      success: false,
+      output: "",
+      error: `Unknown subagent action '${action}'. Use list | inspect | await | cancel | steer | pause | resume.`,
+    };
   };
 }