jeo-code 0.8.42 → 0.8.43

package/src/agent/monitor-tool.ts

@@ -0,0 +1,51 @@
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import type { JobRegistry, MonitorCategory } from "./job-registry";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const MONITOR_TOOL_PROTOCOL_LINE =
+  "monitor {command, kind, description, timeout?, persistent?} starts a turn-scoped stdout monitor. " +
+  "Each newline-terminated stdout line is a notification; non-persistent monitors stop after the first line. " +
+  "Use job {action:\"list\"|\"tail\"|\"await\"|\"cancel\", ids?} with its returned job id to inspect or cancel it.";
+
+const MONITOR_CATEGORIES: readonly MonitorCategory[] = ["log", "poll", "watch", "other"];
+
+export function createMonitorTool(registry: JobRegistry): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const command = typeof args.command === "string" ? args.command.trim() : "";
+    if (!command) {
+      return { success: false, output: "", error: "monitor requires a non-empty 'command'." };
+    }
+
+    const description = typeof args.description === "string" ? args.description.trim() : "";
+    if (!description) {
+      return { success: false, output: "", error: "monitor requires a non-empty 'description'." };
+    }
+
+    const kind = args.kind;
+    if (typeof kind !== "string" || !MONITOR_CATEGORIES.includes(kind as MonitorCategory)) {
+      return { success: false, output: "", error: "monitor requires 'kind' to be exactly log, poll, watch, or other." };
+    }
+
+    if (args.timeout !== undefined && (typeof args.timeout !== "number" || !Number.isFinite(args.timeout) || args.timeout <= 0)) {
+      return { success: false, output: "", error: "monitor 'timeout' must be a finite positive number of seconds." };
+    }
+
+    if (args.persistent !== undefined && typeof args.persistent !== "boolean") {
+      return { success: false, output: "", error: "monitor 'persistent' must be a boolean." };
+    }
+
+    const resolvedCwd = typeof args.cwd === "string" && args.cwd.trim() ? args.cwd : cwd;
+    const record = registry.startMonitor(command, resolvedCwd, {
+      category: kind as MonitorCategory,
+      description,
+      persistent: args.persistent ?? false,
+      timeout: args.timeout,
+    });
+    return {
+      success: true,
+      output: `[monitor] started '${record.id}' (persistent: ${record.persistent}). ` +
+        "Use the job tool to inspect, await, or cancel it.",
+    };
+  };
+}

package/src/agent/subagent-registry.ts

@@ -11,8 +11,8 @@
  * can push a message into a running detached subagent's inbox; the subagent's own
  * agent loop drains it between steps, same mechanism as ordinary task steering.
  *
- * Lifecycle is bounded to the turn that created the registry — `cancelAll()` on
- * turn teardown guarantees no background promise leaks into the next turn.
+ * Lifecycle is bounded to the originating turn: `cancelAll()` requests cooperative
+ * abort on teardown. A filesystem operation already committing cannot be rolled back.
  */
 import type { ToolResult } from "./tools";
 

package/src/agent/subagent-tool.ts

@@ -75,7 +75,7 @@ export function createSubagentTool(registry: SubagentRegistry): ToolHandler {
       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); all settled.`;
-      return { success: stillRunning === 0, output: `${head}\n\n${recs.map(detailBlock).join("\n\n")}` };
+      return { success: true, output: `${head}\n\n${recs.map(detailBlock).join("\n\n")}` };
     }
 
     if (action === "cancel") {

package/src/agent/subagents.ts

@@ -302,7 +302,7 @@ export function subagentToolset(role: SubagentRole): Record<string, ToolHandler>
   if (prefixes && prefixes.length > 0) {
     const inner = DEFAULT_TOOLS.bash;
     const guarded: Record<string, ToolHandler> = { ...DEFAULT_TOOLS };
-    guarded.bash = async (a, cwd) => {
+    guarded.bash = async (a, cwd, onProgress, signal) => {
       const command = String(a.command ?? a.cmd ?? "");
       if (!bashCommandAllowed(command, prefixes)) {
         return {
@@ -313,7 +313,7 @@ export function subagentToolset(role: SubagentRole): Record<string, ToolHandler>
             `Received: ${command.trim().slice(0, 120)}`,
         };
       }
-      return inner(a, cwd);
+      return inner(a, cwd, onProgress, signal);
     };
     return guarded;
   }

package/src/agent/task-tool.ts

@@ -52,6 +52,10 @@ export type SubagentTaskConfig = RoutingConfig & Pick<Config, "subagents" | "thi
 /** Lifecycle event emitted while a delegated subagent runs. */
 export interface TaskSubEvent {
   role: string;
+  /** Stable registry id for a detached run; absent for synchronous work. */
+  id?: string;
+  /** True when this event belongs to a detached registry run. */
+  detached?: boolean;
   /** `"thinking"` streams the subagent's live reasoning/thought text (native
    *  extended-thinking models) — a transient live-preview beat, not persisted to
    *  the ledger (mirrors the main turn's dimmed "Thinking" block, scoped per
@@ -108,6 +112,9 @@ export interface TaskToolOptions {
  *  should either run sequentially (separate `task` calls) or coordinate — jeo has
  *  no in-batch peer channel yet, so overlapping-scope tasks MUST be sequential. */
 export const MAX_FANOUT = 4;
+/** Task-tool policy: cap independently launched detached runs at four per turn.
+ * The registry remains reusable by other execution paths with their own limits. */
+const MAX_ACTIVE_DETACHED_SUBAGENTS = 4;
 
 /** Small bounded reroute budget for a SUBAGENT's own 429 (distinct from
  *  launch.ts's `ROUTE_FALLBACK_MAX_ATTEMPTS`, default 3): a subagent is already
@@ -182,7 +189,7 @@ function createSteerHub(drain?: () => string[]) {
  *  across the board, not just for the JSON-in-prose fallback providers. */
 export function taskToolProtocolLine(config?: Pick<Config, "subagents">): string {
   return (
-    `task   single: {role?, task, context?}  —  fan-out: {role?, tasks:["task 1", "task 2", ...]} ` +
+    `task   single: {role?, task, context?, detached?:true}  —  fan-out: {role?, tasks:["task 1", "task 2", ...]} (fan-out cannot be detached) ` +
     `— delegate to a subagent (role: ${subagentRoleIds(config).join("|")}; executor can edit, planner/architect/critic are read-only). ` +
     `'tasks' MUST be a real JSON array (of strings, or {task, context?} objects) — NEVER a JSON-stringified array, NEVER a single task string. ` +
     `All items in 'tasks' run concurrently (bounded); scope each executor task to disjoint files (no shared-file coordination channel between concurrent tasks — use sequential task calls if scopes overlap). Integrate the findings yourself.`
@@ -234,6 +241,8 @@ export interface RunSubagentOptions {
   steer?: () => string[];
   /** 1-based position within a fan-out/parallel batch, for event tagging. */
   slot?: { index: number; total: number };
+  /** Stable registry id for a detached run's lifecycle events. */
+  detachedId?: string;
   /** Pre-loaded project context to avoid re-scanning AGENTS.md per batch item. */
   projectContext?: ProjectContextFile[];
   /** BATCH-scoped (not per-call) credential scopes already known exhausted this
@@ -301,11 +310,14 @@ export async function runSubagentOnce(
   cwd: string,
   opts: RunSubagentOptions,
 ): Promise<SubagentRunResult> {
-  const { steer, slot, projectContext: preloadedContext, signal } = opts;
-  // Tag every live event with its fan-out slot so a parent monitor can tell
-  // task 1 from task 3 when several same-role subagents stream concurrently.
+  const { steer, slot, detachedId, projectContext: preloadedContext, signal } = opts;
+  // Tag live events with their fan-out slot and/or detached registry identity.
   const emit = (ev: TaskSubEvent) =>
-    opts.onEvent?.(slot ? { ...ev, index: slot.index, total: slot.total } : ev);
+    opts.onEvent?.({
+      ...ev,
+      ...(slot ? { index: slot.index, total: slot.total } : {}),
+      ...(detachedId ? { id: detachedId, detached: true } : {}),
+    });
   const initialModel = opts.modelOverride || resolveSubagentModel(role.id, opts.config);
   const maxSteps = resolveSubagentMaxSteps(role.id, opts.config);
   // gjc parity: a role may pin its own reasoning budget; absent = inherit the
@@ -537,6 +549,8 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
     extra: {
       steer?: () => string[];
       slot?: { index: number; total: number };
+      /** Stable registry id for detached-run lifecycle events. */
+      detachedId?: string;
       projectContext?: ProjectContextFile[];
       /** Overrides opts.signal — a detached run uses its own registry signal so it
        *  is cancellable independently of the parent turn. */
@@ -554,6 +568,7 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
       onEvent: opts.onEvent,
       steer: extra.steer,
       slot: extra.slot,
+      detachedId: extra.detachedId,
       projectContext: extra.projectContext,
       excludedCredentialScopes: extra.excludedCredentialScopes,
       modelOverride: extra.modelOverride,
@@ -567,6 +582,13 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
     }
     const ctx = (c: unknown) => (typeof c === "string" && c.trim() ? `\n\nContext:\n${c.trim()}` : "");
 
+    // Native/function-call adapters normally preserve boolean values, but the prose-only
+    // protocol can still yield the exact string "true" from otherwise valid model JSON.
+    // This is an unambiguous serialization mistake; treating it as synchronous defeats
+    // detached dispatch while the parent waits for the very task it intended to background.
+    const detached = args.detached === true
+      || (typeof args.detached === "string" && args.detached.trim().toLowerCase() === "true");
+
     // Fan-out form: `tasks: [ "assignment" | {task|assignment|prompt, context?} ]`.
     // Live-reproduced (v0.8.42, multiple real models across two different providers,
     // including a native-tool-calling-capable one): even with an explicit, example-driven
@@ -578,6 +600,13 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
       ? (() => { try { const p = JSON.parse(args.tasks as string); return Array.isArray(p) ? p : args.tasks; } catch { return args.tasks; } })()
       : args.tasks;
     if (Array.isArray(tasksArg)) {
+      if (detached) {
+        return {
+          success: false,
+          output: "",
+          error: "Detached task fan-out is not supported. Launch each independent task with detached:true so each has its own lifecycle id and control handle.",
+        };
+      }
       const items = (tasksArg as unknown[])
         .map(entry => {
           if (typeof entry === "string") return { task: entry.trim(), context: "" };
@@ -683,9 +712,20 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
     // parent can keep working, then list/inspect/await/cancel via the `subagent`
     // tool. Live peer messaging (steer/irc) DOES reach a detached run — it drains
     // its own registry inbox (registry.steerDrainFor(id)) between its own steps.
-    if (args.detached === true && opts.registry) {
+    if (detached && opts.registry) {
+      if (opts.registry.running().length >= MAX_ACTIVE_DETACHED_SUBAGENTS) {
+        return {
+          success: false,
+          output: "",
+          error: `Detached subagent limit reached (${MAX_ACTIVE_DETACHED_SUBAGENTS} running). Await or cancel a running subagent before launching another.`,
+        };
+      }
       const rec = opts.registry.launch(role.id, taskText, (signal, id) =>
-        runOne(role, taskText, ctx(args.context), cwd, { signal, steer: opts.registry!.steerDrainFor(id) }),
+        runOne(role, taskText, ctx(args.context), cwd, {
+          signal,
+          steer: opts.registry!.steerDrainFor(id),
+          detachedId: id,
+        }),
       );
       // Remote subagent visibility/control over Telegram (gjc daemon parity, see
       // `src/agent/notify/`): best-effort, no-op unless `notifications.enabled`.

package/src/agent/tool-schemas.ts

@@ -116,6 +116,22 @@ const SCHEMAS: Record<string, NativeToolSchema> = {
       required: ["calculations"],
     },
   },
+  monitor: {
+    name: "monitor",
+    description: "Start a bounded background stdout monitor. Non-persistent monitors stop after their first output line; control the returned job id with the job tool.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: STRING,
+        kind: { type: "string", enum: ["log", "poll", "watch", "other"] },
+        description: STRING,
+        timeout: { type: "number" },
+        persistent: { type: "boolean" },
+        cwd: STRING,
+      },
+      required: ["command", "kind", "description"],
+    },
+  },
   done: {
     name: "done",
     description: "Call when the task is fully implemented AND verified. The reason is shown to the user as your message.",

package/src/agent/tools.ts

@@ -111,6 +111,10 @@ export async function assertBashAllowed(
   }
 }
 
+function cancelledMutationResult(signal?: AbortSignal): ToolResult | undefined {
+  return signal?.aborted ? { success: false, output: "", error: "Operation cancelled" } : undefined;
+}
+
 /**
  * Parse a read line selector into sorted, merged, inclusive [start,end] ranges.
  * Segments are comma-separated; each is one of: "a-b" (range), "a-" (a→EOF),
@@ -312,15 +316,22 @@ export async function readTool(
 export async function writeTool(
   filePath: string,
   content: string,
-  cwd: string = process.cwd()
+  cwd: string = process.cwd(),
+  signal?: AbortSignal,
 ): Promise<ToolResult> {
   try {
+    const aborted = cancelledMutationResult(signal);
+    if (aborted) return aborted;
     if (typeof filePath !== "string" || filePath.trim() === "") {
       return { success: false, output: "", error: 'write requires a non-empty "filePath".' };
     }
     await assertMutationAllowed(filePath, cwd);
+    const abortedAfterGuard = cancelledMutationResult(signal);
+    if (abortedAfterGuard) return abortedAfterGuard;
     const absPath = path.resolve(cwd, filePath);
     await fs.mkdir(path.dirname(absPath), { recursive: true });
+    const abortedBeforeWrite = cancelledMutationResult(signal);
+    if (abortedBeforeWrite) return abortedBeforeWrite;
     await fs.writeFile(absPath, content, "utf-8");
     markRead(absPath); // own change counts as having seen the file
     return { success: true, output: `Successfully wrote ${content.length} characters to ${filePath}` };
@@ -360,9 +371,12 @@ export function parseEditHunks(block: string): { search: string; replace: string
 export async function editTool(
   filePath: string,
   editBlock: string,
-  cwd: string = process.cwd()
+  cwd: string = process.cwd(),
+  signal?: AbortSignal,
 ): Promise<ToolResult> {
   try {
+    const aborted = cancelledMutationResult(signal);
+    if (aborted) return aborted;
     if (typeof filePath !== "string" || filePath.trim() === "") {
       return { success: false, output: "", error: 'edit requires a non-empty "filePath".' };
     }
@@ -370,6 +384,8 @@ export async function editTool(
       return { success: false, output: "", error: 'edit requires a non-empty "editBlock" (≔ directive or <<<<<<< SEARCH block).' };
     }
     await assertMutationAllowed(filePath, cwd);
+    const abortedAfterGuard = cancelledMutationResult(signal);
+    if (abortedAfterGuard) return abortedAfterGuard;
     const absPath = path.resolve(cwd, filePath);
     let content = await fs.readFile(absPath, "utf-8");
 
@@ -581,6 +597,8 @@ export async function editTool(
       };
     }
 
+    const abortedBeforeWrite = cancelledMutationResult(signal);
+    if (abortedBeforeWrite) return abortedBeforeWrite;
     await fs.writeFile(absPath, content, "utf-8");
     markRead(absPath); // own change counts as having seen the file
     return { success: true, output: `Successfully updated ${filePath}` };
@@ -1076,18 +1094,25 @@ export async function lsTool(
  */
 export async function mkdirTool(
   dirPath: string,
-  cwd: string = process.cwd()
+  cwd: string = process.cwd(),
+  signal?: AbortSignal,
 ): Promise<ToolResult> {
   try {
+    const aborted = cancelledMutationResult(signal);
+    if (aborted) return aborted;
     if (typeof dirPath !== "string" || dirPath.trim() === "") {
       return { success: false, output: "", error: 'mkdir requires a non-empty "dirPath".' };
     }
     await assertMutationAllowed(dirPath, cwd);
+    const abortedAfterGuard = cancelledMutationResult(signal);
+    if (abortedAfterGuard) return abortedAfterGuard;
     const abs = path.resolve(cwd, dirPath);
     const existing = await fs.stat(abs).catch(() => null);
     if (existing && !existing.isDirectory()) {
       return { success: false, output: "", error: `Path exists and is not a directory: ${dirPath}` };
     }
+    const abortedBeforeMkdir = cancelledMutationResult(signal);
+    if (abortedBeforeMkdir) return abortedBeforeMkdir;
     await fs.mkdir(abs, { recursive: true });
     return { success: true, output: `Directory ready: ${dirPath}` };
   } catch (err: any) {
@@ -1105,13 +1130,18 @@ export async function mkdirTool(
 export async function deleteTool(
   targetPath: string,
   cwd: string = process.cwd(),
-  recursive: boolean = false
+  recursive: boolean = false,
+  signal?: AbortSignal,
 ): Promise<ToolResult> {
   try {
+    const aborted = cancelledMutationResult(signal);
+    if (aborted) return aborted;
     if (typeof targetPath !== "string" || targetPath.trim() === "") {
       return { success: false, output: "", error: 'delete requires a non-empty "path".' };
     }
     await assertMutationAllowed(targetPath, cwd);
+    const abortedAfterGuard = cancelledMutationResult(signal);
+    if (abortedAfterGuard) return abortedAfterGuard;
     const abs = path.resolve(cwd, targetPath);
     if (abs === path.resolve(cwd)) {
       return { success: false, output: "", error: "Refusing to delete the working directory itself." };
@@ -1123,6 +1153,8 @@ export async function deleteTool(
     if (st.isDirectory() && !recursive) {
       return { success: false, output: "", error: `${targetPath} is a directory — pass recursive:true to remove it and its contents.` };
     }
+    const abortedBeforeDelete = cancelledMutationResult(signal);
+    if (abortedBeforeDelete) return abortedBeforeDelete;
     await fs.rm(abs, { recursive, force: false });
     readThisSession.delete(abs); // a future edit against this path must read it again first
     return { success: true, output: `Deleted ${st.isDirectory() ? "directory" : "file"}: ${targetPath}` };

package/src/commands/launch/slash-handlers.ts

@@ -10,6 +10,7 @@ import { taskToolProtocolLine } from "../../agent/task-tool";
 import { TODO_TOOL_PROTOCOL_LINE } from "../../agent/todo-tool";
 import { SUBAGENT_TOOL_PROTOCOL_LINE } from "../../agent/subagent-tool";
 import { JOB_TOOL_PROTOCOL_LINE } from "../../agent/job-tool";
+import { MONITOR_TOOL_PROTOCOL_LINE } from "../../agent/monitor-tool";
 import { IRC_TOOL_PROTOCOL_LINE } from "../../agent/irc-tool";
 import { GOAL_TOOL_PROTOCOL_LINE } from "../../agent/goal-tool";
 import { hotkeysLines, contextUsageLines } from "./slash-views";
@@ -50,6 +51,7 @@ export async function handleTools(ctx: SlashContext): Promise<SlashResult> {
   lines.push(`  ${TODO_TOOL_PROTOCOL_LINE}`);
   lines.push(`  ${SUBAGENT_TOOL_PROTOCOL_LINE}`);
   lines.push(`  ${JOB_TOOL_PROTOCOL_LINE}`);
+  lines.push(`  ${MONITOR_TOOL_PROTOCOL_LINE}`);
   lines.push(`  ${IRC_TOOL_PROTOCOL_LINE}`);
   lines.push(`  ${GOAL_TOOL_PROTOCOL_LINE}`);
   return { lines };

package/src/commands/launch/stream.ts

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { type AgentLoopEvents } from "../../agent/engine";
 import { type TaskSubEvent } from "../../agent/task-tool";
+import { type MonitorJobEvent } from "../../agent/job-registry";
 import { categoryBadge } from "../../tui/components/category-index";
 import { summarizeForgeInvocation } from "../../tui/components/forge";
 import { formatDuration, formatUsage } from "../../tui/components/duration";
@@ -44,7 +45,8 @@ function streamResultSuffix(tool: string, ok: boolean, output: string | undefine
 
 export function formatTaskSubEvent(e: TaskSubEvent): string {
   const role = e.role || "subagent";
-  const roleLabel = e.index && e.total ? `${role.toUpperCase()}[${e.index}/${e.total}]` : role.toUpperCase();
+  const detachedLabel = e.detached && e.id ? ` [${e.id}]` : "";
+  const roleLabel = `${e.index && e.total ? `${role.toUpperCase()}[${e.index}/${e.total}]` : role.toUpperCase()}${detachedLabel}`;
   const tokTag = e.tokens ? ` (${e.tokens.input + e.tokens.output} tok)` : "";
   const detail = firstOutputLine(e.detail);
   const summary = e.summary ? ` — ${e.summary}` : "";
@@ -66,6 +68,19 @@ export function logTaskSubEvent(e: TaskSubEvent, log: (line: string) => void = (
   const line = formatTaskSubEvent(e);
   if (line) log(line);
 }
+export function formatMonitorJobEvent(e: MonitorJobEvent): string {
+  const label = `${e.record.id} · ${e.record.category} · ${e.record.description}`;
+  if (e.type === "start") return `${categoryBadge("progress")} ${chalk.cyan("monitor ▸")} ${label}`.slice(0, 240);
+  if (e.type === "line") {
+    const line = firstOutputLine(e.line);
+    return `${categoryBadge("progress")} ${chalk.cyan("monitor │")} ${label}${line ? ` — ${line}` : ""}`.slice(0, 240);
+  }
+  return `${categoryBadge("progress")} ${chalk.cyan("monitor └")} ${label} ${chalk.dim("done")}`.slice(0, 240);
+}
+
+export function logMonitorJobEvent(e: MonitorJobEvent, log: (line: string) => void = (s: string) => console.log(s)): void {
+  log(formatMonitorJobEvent(e));
+}
 
 export function createStreamEvents(
   _maxSteps: number,

package/src/commands/launch.ts

@@ -19,7 +19,8 @@ import { parseInThreadConfigCommand } from "../agent/notify/config-commands";
 
 import { createTodoTool, TODO_TOOL_PROTOCOL_LINE } from "../agent/todo-tool";
 import { createJobTool, JOB_TOOL_PROTOCOL_LINE } from "../agent/job-tool";
-import { JobRegistry } from "../agent/job-registry";
+import { JobRegistry, type MonitorJobEvent } from "../agent/job-registry";
+import { createMonitorTool, MONITOR_TOOL_PROTOCOL_LINE } from "../agent/monitor-tool";
 import { createIrcTool, IRC_TOOL_PROTOCOL_LINE } from "../agent/irc-tool";
 import { createGoalTool, GOAL_TOOL_PROTOCOL_LINE } from "../agent/goal-tool";
 import { createApproveTool, APPROVE_TOOL_PROTOCOL_LINE } from "../agent/approve-tool";
@@ -185,6 +186,7 @@ import {
   gatedStdout,
   formatTaskSubEvent,
   logTaskSubEvent,
+  formatMonitorJobEvent,
   createStreamEvents,
   shouldUseOneShotTui,
 } from "./launch/stream";
@@ -560,7 +562,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // pi-style: load project context (JEO.md / AGENTS.md / .jeo/context.md / CLAUDE.md) into the prompt.
   const contextFiles = await loadProjectContext(cwd);
 
-  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "eval", "todo", "subagent", "job", "irc", "goal", "approve", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug", "browser"]);
+  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "eval", "todo", "subagent", "job", "monitor", "irc", "goal", "approve", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug", "browser"]);
   let allowedTools = new Set(KNOWN_TOOLS);
 
   if (flags.noTools) {
@@ -633,6 +635,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     (allowedTools.has("subagent") ? "\n\nDetached subagents: " + SUBAGENT_TOOL_PROTOCOL_LINE +
     " Launch background work with task {\"detached\": true, \"role\": <role>, \"task\": <assignment>}; it returns a subagent id immediately so you can keep working and collect the result later." : "") +
     (allowedTools.has("job") ? "\n\nBackground jobs: " + JOB_TOOL_PROTOCOL_LINE : "") +
+    (allowedTools.has("monitor") ? "\n\nBackground monitors: " + MONITOR_TOOL_PROTOCOL_LINE : "") +
     (allowedTools.has("irc") ? "\n\nPeer messaging: " + IRC_TOOL_PROTOCOL_LINE : "") +
     (allowedTools.has("goal") ? "\n\nGoal tracking: " + GOAL_TOOL_PROTOCOL_LINE : "") +
     (allowedTools.has("approve") ? "\n\nPlan approval: " + APPROVE_TOOL_PROTOCOL_LINE : "") +
@@ -1422,7 +1425,32 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       // #9: per-turn registry for DETACHED subagents (task{detached:true}); the
       // `subagent` tool controls them and cancelAll() in finally prevents orphans.
       const subagentRegistry = new SubagentRegistry();
+      // TUI callbacks are scoped to this registry. cancelAll() may trigger a detached
+      // run's final event after the turn is complete; do not let it paint a freshly
+      // reset later TUI. Non-TUI streams retain direct event logging.
+      let acceptingTuiSubagentEvents = true;
+      const onSubagentEvent = useTui
+        ? (e: TaskSubEvent) => {
+            if (acceptingTuiSubagentEvents) tui?.onSubagentEvent(e);
+          }
+        : (e: TaskSubEvent) => logTaskSubEvent(e);
       const jobRegistry = new JobRegistry();
+      // Monitor output stays bounded and turn-scoped. It deliberately feeds the
+      // engine's observational inbox rather than the steering inbox.
+      const monitorInbox: string[] = [];
+      const MONITOR_INBOX_CAP = 32;
+      let acceptingMonitorEvents = true;
+      const onMonitorEvent = (e: MonitorJobEvent) => {
+        if (!acceptingMonitorEvents) return;
+        if (useTui) tui?.onMonitorEvent(e);
+        else console.log(formatMonitorJobEvent(e));
+        if (e.type !== "line" || monitorInbox.length >= MONITOR_INBOX_CAP) return;
+        const description = e.record.description.replace(/\s+/g, " ").trim().slice(0, 240);
+        const line = e.line.slice(0, 2_000);
+        monitorInbox.push(`[monitor ${e.record.id} · ${e.record.category} · ${description}]\n${line}`);
+      };
+      const unsubscribeMonitor = jobRegistry.subscribeMonitor(onMonitorEvent);
+      const drainMonitor = () => monitorInbox.splice(0, monitorInbox.length);
       sessionNotifyEndpoint?.attachRegistry(subagentRegistry);
       currentTurnSteer = { push: line => steerInbox.push(line), flushCard: line => tui?.flushSteerCard(line) };
       if (sessionNotifyEndpoint && !notifyRedact) {
@@ -1495,21 +1523,18 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             steer: drainSteer,
             registry: subagentRegistry,
             sessionEndpoint: sessionNotifyEndpoint,
-            onEvent: useTui
-              ? (e => tui?.onSubagentEvent(e))
-              : (e => logTaskSubEvent(e)),
+            onEvent: onSubagentEvent,
           }),
           eval: createEvalTool({
             config: { ...turnConfig, defaultModel: activeModel },
             signal: ac.signal,
             steer: drainSteer,
-            onEvent: useTui
-              ? (e => tui?.onSubagentEvent(e))
-              : (e => logTaskSubEvent(e)),
+            onEvent: onSubagentEvent,
           }),
           todo: createTodoTool({ onChange: items => { turnTodos = items; tui?.setTodos(items); } }),
           subagent: createSubagentTool(subagentRegistry),
           job: createJobTool(jobRegistry),
+          monitor: createMonitorTool(jobRegistry),
           irc: createIrcTool(subagentRegistry),
           goal: createGoalTool(),
           approve: createApproveTool(),
@@ -1615,6 +1640,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           signal: ac.signal,
           sessionKey: cacheKey,
           steer: drainSteer,
+          monitor: drainMonitor,
           rateLimitFallbackAvailable,
           safetyFallbackAvailable,
           events: wrapEvents(withStepPersistence({ ...withToolDetailCapture(tui ? tui.events() : streamEvents), onBeforeDone }, persistTurnTail), opik),
@@ -1748,6 +1774,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             signal: ac.signal,
             sessionKey: turnSessionKey,
             steer: drainSteer,
+            monitor: drainMonitor,
             // Deliberately NOT wiring rateLimitFallbackAvailable here: this repair
             // retry has no reroute loop around it (unlike runLoopWithModel's
             // routeFallbackAttempt loop) — bailing the retry ladder early on a 429
@@ -1772,11 +1799,14 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         await opik.endTurn({ done: result.done, steps: result.steps, output: result.doneReason });
       } finally {
         harness.dispose();
+        acceptingTuiSubagentEvents = false;
+        acceptingMonitorEvents = false;
         subagentRegistry.cancelAll(); // #9: no detached run leaks past the turn
         sessionNotifyEndpoint?.detachRegistry(); // this turn's registry is gone — subagent frames stop applying to it
         currentTurnSteer = undefined; // a remote message after this point queues instead of steering a dead turn
         await stopSessionNotifyEndpoint(subagentRegistry); // tear down the FALLBACK lazy endpoint, if one was started (no-op when sessionNotifyEndpoint owns the registry)
         jobRegistry.cancelAll(); // background jobs are turn-scoped too — no orphaned processes
+        unsubscribeMonitor();
 
         // Steering typed but never drained (e.g. entered just after the final step)
         // must not be lost — fold it into the next prompt draft so it runs next.