pi-famulus 0.1.9 → 0.2.1

package/src/subagent/hosted-session.ts

@@ -0,0 +1,314 @@
+/**
+ * ChildSessionAdapter over a daemon-hosted `pi --mode rpc` process.
+ * The runner's timers stay; only the session lives in another process.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ManagerClient, ManagerEvent } from "../manager-client";
+import { parentResourceArgs, resolvePiArgv } from "../pi-command";
+import { resolveChildModel, type PiRuntimeDeps } from "./pi-runtime";
+import type {
+  ChildRunRequest,
+  ChildSessionAdapter,
+  ChildSessionEvent,
+  ChildTokenUsage,
+  CreateSessionFn,
+} from "./types";
+
+export interface HostedSessionDeps extends PiRuntimeDeps {
+  getClient: () => ManagerClient | null;
+  getHome: () => string;
+  /** This extension's entry file, passed to the child with -e. */
+  extensionEntry: string;
+  piCommand?: string | null;
+  trustProject?: boolean;
+}
+
+interface HostingView {
+  residency: string;
+  activity: string;
+  driver: string;
+  cacheExpiresAt?: number;
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn {
+  return async (req) => {
+    const client = deps.getClient();
+    if (!client || !client.isAvailable()) {
+      throw new Error("pi-famulus daemon is not connected; a subagent needs it to run pi --mode rpc.");
+    }
+    client.requireHostedProtocol();
+    const pi = resolvePiArgv(deps.piCommand);
+    if ("error" in pi) throw new Error(pi.error);
+    const model = resolveChildModel(deps, req);
+    const thinking =
+      model.thinkingOverride ?? req.agent.thinking ?? deps.getParentThinkingLevel() ?? "off";
+    const cwd = deps.getCwd();
+    const promptPath = join(deps.getHome(), "agents", "prompts");
+    mkdirSync(promptPath, { recursive: true });
+    const promptFile = join(promptPath, `${req.childId}.md`);
+    writeFileSync(promptFile, req.agent.systemPrompt);
+    const inherited = parentResourceArgs();
+    const extensionPaths = inherited.filter((_, i) => inherited[i - 1] === "-e");
+    const alreadyLoadsUs = extensionPaths.some((path) => path === deps.extensionEntry);
+    const trustInherited = inherited.some((arg) => arg === "-a" || arg === "--approve" || arg === "-na" || arg === "--no-approve");
+    const argv = [
+      ...pi.argv,
+      "--mode", "rpc",
+      "--session-id", req.childId,
+      "--name", `${req.agent.name}: ${req.name}`,
+      ...inherited,
+      ...(alreadyLoadsUs ? [] : ["-e", deps.extensionEntry]),
+      ...(model.model ? ["--model", `${model.model.provider}/${model.model.id}`] : []),
+      "--thinking", String(thinking),
+      "--append-system-prompt", promptFile,
+      ...(trustInherited ? [] : [deps.getProjectTrusted?.() ? "-a" : "-na"]),
+      ...(req.agent.tools ? ["--tools", hostedChildTools(req.agent.tools).join(",")] : []),
+    ];
+    const env = { ...process.env } as Record<string, string>;
+    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = hostedChildTools(req.agent.tools).join(",");
+    env.PI_FAMULUS_CHILD_RUN = req.runId;
+    env.PI_FAMULUS_CHILD_NAME = req.name;
+    const spawned = await client.agentSpawn({
+      childId: req.childId,
+      runId: req.runId,
+      name: req.name,
+      argv,
+      cwd,
+      env,
+    });
+    const warning = model.warning;
+    await client.agentWatch(req.childId);
+    const session = new HostedRpcSession(client, req.childId, {
+      warning,
+      resolvedModel: model.model ? `${model.model.provider}/${model.model.id}` : undefined,
+      effectiveThinkingLevel: typeof thinking === "string" ? thinking : undefined,
+      sessionFile: typeof spawned.session_file === "string" ? spawned.session_file : undefined,
+      sessionId: typeof spawned.session_id === "string" ? spawned.session_id : req.childId,
+    });
+    return session;
+  };
+}
+
+class HostedRpcSession implements ChildSessionAdapter {
+  readonly warning?: string;
+  readonly resolvedModel?: string;
+  readonly effectiveThinkingLevel?: string;
+  private readonly listeners = new Set<(event: ChildSessionEvent) => void>();
+  private readonly unsubscribe: () => void;
+  private streaming = false;
+  private lastText = "";
+  private lastFailure: { stopReason: "error" | "aborted"; errorMessage?: string } | undefined;
+  private turns: { role: string; text: string }[] = [];
+  private usage: ChildTokenUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  private settle: (() => void) | null = null;
+  private hostingView: HostingView;
+  private disposed = false;
+
+  constructor(
+    private readonly client: ManagerClient,
+    private readonly childId: string,
+    init: { warning?: string; resolvedModel?: string; effectiveThinkingLevel?: string; sessionFile?: string; sessionId?: string },
+  ) {
+    this.warning = init.warning;
+    this.resolvedModel = init.resolvedModel;
+    this.effectiveThinkingLevel = init.effectiveThinkingLevel;
+    this.hostingView = {
+      residency: "warm",
+      activity: "starting",
+      driver: "parent",
+      sessionFile: init.sessionFile,
+      sessionId: init.sessionId,
+    };
+    this.unsubscribe = this.client.onEvent((event) => this.onManagerEvent(event as ManagerEvent & Record<string, unknown>));
+  }
+
+  hosting(): HostingView {
+    return { ...this.hostingView };
+  }
+
+  async prompt(text: string): Promise<void> {
+    const done = this.armSettle();
+    const op = this.streaming ? "prompt_steer" : "prompt";
+    await this.client.agentInput(this.childId, op, text, "parent");
+    if (!this.streaming) await done;
+  }
+
+  async steer(text: string): Promise<void> {
+    await this.client.agentInput(this.childId, "prompt_steer", text, "parent");
+  }
+
+  async followUp(text: string): Promise<void> {
+    await this.client.agentInput(this.childId, "prompt_follow", text, "parent");
+  }
+
+  async abort(): Promise<void> {
+    await this.client.agentInput(this.childId, "abort", "", "parent");
+    this.streaming = false;
+    this.settle?.();
+    this.settle = null;
+  }
+
+  async park(): Promise<void> {
+    await this.client.agentPark(this.childId);
+    this.hostingView.residency = "parked";
+  }
+
+  async waitForIdle(): Promise<void> {
+    if (!this.streaming) return;
+    await this.armSettle();
+  }
+
+  getLastAssistantText(): string | undefined {
+    return this.lastText || undefined;
+  }
+
+  getLastAssistantFailure(): { stopReason: "error" | "aborted"; errorMessage?: string } | undefined {
+    return this.lastFailure;
+  }
+
+  getConversation() {
+    return this.turns.map((turn) => ({ ...turn }));
+  }
+
+  tokenUsage(): ChildTokenUsage {
+    return { ...this.usage };
+  }
+
+  isStreaming(): boolean {
+    return this.streaming;
+  }
+
+  subscribe(listener: (event: ChildSessionEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribe();
+    this.settle?.();
+    this.settle = null;
+  }
+
+  private armSettle(): Promise<void> {
+    return new Promise((resolve) => {
+      this.settle = resolve;
+    });
+  }
+
+  private onManagerEvent(event: ManagerEvent & Record<string, unknown>): void {
+    if (event.child_id !== this.childId) return;
+    if (event.event === "agent_state") {
+      this.hostingView = {
+        residency: String(event.residency ?? this.hostingView.residency),
+        activity: String(event.activity ?? this.hostingView.activity),
+        driver: String(event.driver ?? this.hostingView.driver),
+        cacheExpiresAt: typeof event.cache_expires_at === "number" ? event.cache_expires_at : this.hostingView.cacheExpiresAt,
+        sessionFile: typeof event.session_file === "string" ? event.session_file : this.hostingView.sessionFile,
+        sessionId: typeof event.session_id === "string" ? event.session_id : this.hostingView.sessionId,
+      };
+      if (event.activity === "running") this.streaming = true;
+      if (event.activity === "idle" || event.activity === "failed") {
+        if (event.activity === "failed" && !this.lastFailure) {
+          this.lastFailure = { stopReason: "error", errorMessage: "hosted child process failed" };
+        }
+        this.streaming = false;
+        this.settle?.();
+        this.settle = null;
+      }
+      return;
+    }
+    if (event.event !== "agent_rpc" || !event.record || typeof event.record !== "object") return;
+    const record = event.record as {
+      type?: string;
+      message?: {
+        role?: string;
+        content?: { type?: string; text?: string }[];
+        usage?: Record<string, unknown>;
+        stopReason?: string;
+        errorMessage?: string;
+      };
+      toolCallId?: string;
+      toolName?: string;
+      args?: unknown;
+      isError?: boolean;
+    };
+    const type = record.type ?? "";
+    if (type === "agent_start") this.streaming = true;
+    if (type === "agent_settled") {
+      this.streaming = false;
+      this.settle?.();
+      this.settle = null;
+    }
+    if (type === "message_end" && record.message?.role === "assistant") {
+      const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
+      if (text) {
+        this.lastText = text;
+        this.turns.push({ role: "assistant", text });
+      }
+      const stopReason = record.message.stopReason;
+      if (stopReason === "error" || stopReason === "aborted") {
+        this.lastFailure = {
+          stopReason,
+          ...(record.message.errorMessage ? { errorMessage: record.message.errorMessage } : {}),
+        };
+        if (record.message.errorMessage) {
+          this.turns.push({ role: "assistant error", text: record.message.errorMessage });
+        }
+      } else {
+        this.lastFailure = undefined;
+      }
+      const usage = record.message.usage;
+      if (usage) {
+        this.usage.input += num(usage.input);
+        this.usage.output += num(usage.output);
+        this.usage.cacheRead += num(usage.cacheRead);
+        this.usage.cacheWrite += num(usage.cacheWrite);
+      }
+    }
+    if (type === "message_end" && record.message?.role === "user") {
+      const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
+      if (text) this.turns.push({ role: "user", text });
+    }
+    if (type === "tool_execution_end") {
+      const name = record.toolName ?? "tool";
+      const text = record.args === undefined ? name : `${name} ${JSON.stringify(record.args)}`;
+      this.turns.push({
+        role: record.isError ? `tool ${name} error` : `tool ${name}`,
+        text,
+      });
+    }
+    const adapted: ChildSessionEvent = {
+      type,
+      ...(record.message?.role ? { role: record.message.role } : {}),
+      ...(record.toolCallId ? { toolCallId: record.toolCallId } : {}),
+      ...(record.toolName ? { toolName: record.toolName } : {}),
+      ...(record.args !== undefined ? { args: record.args } : {}),
+      ...(record.isError !== undefined ? { isError: record.isError } : {}),
+    };
+    for (const listener of this.listeners) listener(adapted);
+  }
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+const SUPERVISOR_TOOLS = ["contact_supervisor", "agent_message"];
+
+/** Agent allowlists still keep the two supervisor tools. */
+export function hostedChildTools(tools: string[]): string[] {
+  const kept = new Set(tools);
+  for (const name of SUPERVISOR_TOOLS) kept.add(name);
+  return [...kept];
+}
+
+/** Request id for a child→parent decision. */
+export function newCommsRequestId(): string {
+  return `rq_${randomUUID().slice(0, 8)}`;
+}

package/src/subagent/overrun.ts

@@ -38,6 +38,17 @@ export class ChildShellTracker {
     this.sizes.delete(taskId);
   }
 
+  /** A hosted child's shell is observed from the parent session's task_exited. */
+  endByTask(taskId: string): void {
+    for (const [childId, shell] of this.shells) {
+      if (shell.taskId === taskId) {
+        this.shells.delete(childId);
+        this.sizes.delete(taskId);
+        return;
+      }
+    }
+  }
+
   current(childId: string): ChildShell | undefined {
     return this.shells.get(childId);
   }

package/src/subagent/pi-runtime.ts

@@ -157,6 +157,10 @@ interface ResolvedModel {
  * falls back to the parent model with a warning (user-authored files must not
  * hard-fail across machines).
  */
+export function resolveChildModel(deps: PiRuntimeDeps, req: ChildRunRequest): ResolvedModel {
+  return resolveModel(deps, req);
+}
+
 function resolveModel(deps: PiRuntimeDeps, req: ChildRunRequest): ResolvedModel {
   const candidates = modelCandidates(deps);
   const findModel = (provider: string, id: string): Model | undefined =>

package/src/subagent/registry.ts

@@ -342,6 +342,84 @@ export class SubagentRegistry implements RunRegistry {
   // M3 extensions beyond Appendix B
   // -------------------------------------------------------------------------
 
+  /**
+   * Reconstruct a run/child the previous parent process wrote to disk
+   * so resume can reattach by child_id.
+   */
+  adoptExisting(info: {
+    runId: string;
+    childId: string;
+    name: string;
+    agent: string;
+    workKind?: string;
+    startedAt?: number;
+    prompt?: string;
+  }): void {
+    if (this.children.has(info.childId)) return;
+    let run = this.runs.get(info.runId);
+    if (!run) {
+      run = {
+        runId: info.runId,
+        kind: "tasks",
+        status: "interrupted",
+        createdAt: info.startedAt ?? this.now(),
+        children: [],
+      };
+      this.runs.set(info.runId, run);
+    }
+    const child: InternalChild = {
+      childId: info.childId,
+      runId: info.runId,
+      name: info.name,
+      agent: info.agent,
+      workKind: info.workKind ?? "other",
+      status: "interrupted",
+      startedAt: info.startedAt ?? this.now(),
+      endedAt: this.now(),
+      turn: 1,
+      queueMs: 0,
+      prompt: info.prompt,
+    };
+    run.children.push(child);
+    this.children.set(child.childId, child);
+    this.emit(run);
+  }
+
+  /** Bind a live hosted session to an adopted child without sending its first prompt. */
+  async attachChild(req: ChildRunRequest): Promise<ChildHandle> {
+    const child = this.children.get(req.childId);
+    if (!child) throw new Error(`unknown child ${req.childId} (adoptExisting first)`);
+    const runner = this.runner;
+    if (!runner?.attach) {
+      throw new Error(`subagent ${req.childId} has no live session to resume`);
+    }
+    child.prompt = req.taskPrompt ?? req.prompt;
+    child.preamble = req.agent.systemPrompt || undefined;
+    child.model = req.model ?? req.agent.model;
+    let handle: ChildHandle;
+    try {
+      handle = await runner.attach(req, (startingHandle) => {
+        child.handle = startingHandle;
+      });
+    } catch (error) {
+      const failed = child.handle as DisposableChildHandle | undefined;
+      child.handle = undefined;
+      await failed?.dispose?.();
+      throw error;
+    }
+    if (!this.children.has(child.childId)) return handle;
+    child.handle = handle;
+    handle.result.then((result) => this.settleChild(child.childId, result));
+    const resolved = handle.resolvedModel();
+    if (resolved) {
+      const thinking = handle.effectiveThinkingLevel?.();
+      child.model = `${resolved}${thinking ? `:${thinking}` : ""}`;
+    }
+    const run = this.runs.get(child.runId);
+    if (run) this.emit(run);
+    return handle;
+  }
+
   /** Allocate a pending child inside a run. Returns the child id. */
   addChild(runId: string, info: { name: string; agent: string; workKind?: string }): string {
     const run = this.runs.get(runId);

package/src/subagent/runner.ts

@@ -87,6 +87,8 @@ export interface InProcessRunnerOptions {
   stallRetryDelayMs?: number;
   /** Called on every stall detection (before any retry), with the 1-based attempt. */
   onStall?: (childId: string, attempt: number) => void;
+  /** Same tool name and arguments three times in a row. */
+  onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
   /** Overrun reminder interval (ms). Default 10 minutes. */
   overrunRepeatMs?: number;
   /** Abort ceiling per user turn (ms). 0/absent = off: the soft deadline never aborts. */
@@ -99,10 +101,10 @@ export interface InProcessRunnerOptions {
   /** Shared time source and scheduler. */
   clock?: Clock;
   /**
-   * Per-generation admission hook. Awaited before each (re)start; the
-   * releaser gets terminal=false for a resumable interruption so its local
-   * slot can be returned while the child-owned machine permit is retained.
-   * Rejecting cancels the generation as {status:"interrupted", error}.
+   * Per-generation admission hook. Awaited before each (re)start. The
+   * releaser is called with terminal=true when the turn settles, including
+   * an interrupted turn: the machine permit is released and the next turn
+   * acquires again. Rejecting cancels the generation as {status:"interrupted", error}.
    */
   acquire?: (req: ChildRunRequest, ticket: AdmissionTicket) => Promise<(terminal?: boolean) => void>;
   /**
@@ -116,6 +118,20 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** 429 / rate-limit text is recorded separately from other model errors. */
+export function classifyModelFailure(message: string): {
+  endReason: "model-error" | "rate-limit";
+  retryAfter?: number;
+} {
+  const rateLimited = /\b429\b|rate[\s-]?limit|too many requests/i.test(message);
+  if (!rateLimited) return { endReason: "model-error" };
+  const retry = /retry[\s-]?after[:\s]+(\d+)/i.exec(message);
+  return {
+    endReason: "rate-limit",
+    ...(retry ? { retryAfter: Number(retry[1]) } : {}),
+  };
+}
+
 export class InProcessRunner implements ChildRunner {
   private readonly opts: InProcessRunnerOptions;
 
@@ -129,6 +145,13 @@ export class InProcessRunner implements ChildRunner {
     await handle.launch();
     return handle;
   }
+
+  async attach(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<DisposableChildHandle> {
+    const handle = new InProcessChildHandle(req, this.opts);
+    onHandle?.(handle);
+    await handle.attachIdle();
+    return handle;
+  }
 }
 
 class InProcessChildHandle implements DisposableChildHandle {
@@ -138,6 +161,9 @@ class InProcessChildHandle implements DisposableChildHandle {
   private readonly stallRetries: number;
   private readonly stallRetryDelayMs: number;
   private readonly onStall?: (childId: string, attempt: number) => void;
+  private readonly onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
+  private lastToolKey: string | null = null;
+  private lastToolCount = 0;
   private readonly overrunRepeatMs: number;
   private readonly hardTimeoutMs: number;
   private readonly onOverrun?: (tick: OverrunTick) => void;
@@ -233,6 +259,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       ? Math.max(0, Math.floor(rawDelay))
       : DEFAULT_STALL_RETRY_DELAY_MS;
     this.onStall = opts.onStall;
+    this.onToolLoop = opts.onToolLoop;
     const rawRepeat = opts.overrunRepeatMs ?? DEFAULT_OVERRUN_REPEAT_MS;
     this.overrunRepeatMs =
       Number.isFinite(rawRepeat) && rawRepeat > 0
@@ -331,6 +358,27 @@ class InProcessChildHandle implements DisposableChildHandle {
     await this.beginGeneration(this.req.prompt, true);
   }
 
+  /**
+   * Bind an already-hosted session so resume() can send the next turn.
+   * The previous parent died; this generation is interrupted, not prompted.
+   */
+  async attachIdle(): Promise<void> {
+    this.sessionCreation = this.createSession(this.req);
+    const created =
+      await this.sessionCreation;
+    this.sessionCreation = null;
+    if (this.disposed) return;
+    this.session = created;
+    this.resolvedModel_ = created.resolvedModel;
+    this.unsubscribe = this.session.subscribe((event) => this.handleSessionEvent(event));
+    this.settle(this.generation, {
+      status: "interrupted",
+      text: this.session.getLastAssistantText() ?? "",
+      error: "parent session ended",
+      durationMs: 0,
+    });
+  }
+
   async steer(message: string): Promise<void> {
     if (this.status_ !== "running" || !this.session) {
       throw new Error(`subagent ${this.req.childId} is not running (status: ${this.status_})`);
@@ -462,8 +510,17 @@ class InProcessChildHandle implements DisposableChildHandle {
     await this.beginGeneration(message, false, false, gen);
   }
 
+  hosting(): { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } | undefined {
+    const session = this.session as { hosting?: () => { residency?: string; driver?: string; cacheExpiresAt?: number; sessionFile?: string; sessionId?: string } } | null;
+    return session?.hosting?.();
+  }
+
   async interrupt(): Promise<void> {
-    if (this.status_ !== "running" && this.status_ !== "pending") return;
+    if (this.status_ !== "running" && this.status_ !== "pending") {
+      const session = this.session as { park?: () => Promise<void> } | null;
+      if (session?.park) await session.park();
+      return;
+    }
     this.settle(this.generation, {
       status: "interrupted",
       // A pending turn has produced nothing yet; the last assistant text
@@ -471,11 +528,10 @@ class InProcessChildHandle implements DisposableChildHandle {
       text: this.status_ === "pending" ? "" : this.partialText(),
       durationMs: this.now() - this.startedAt,
     });
-    try {
-      await this.session?.abort();
-    } catch {
-      // abort is best-effort; the result is already settled
-    }
+    // Resume may be accepted as soon as the interrupted result is visible.
+    // Drain this abort just like a timeout/stall abort before prompting again.
+    this.abortPromise = this.session ? this.session.abort().catch(() => {}) : null;
+    await this.abortPromise;
   }
 
   dispose(): void | Promise<void> {
@@ -563,8 +619,8 @@ class InProcessChildHandle implements DisposableChildHandle {
           signal: admissionAbort.signal,
         });
         if (this.disposed || this.isSettled(gen)) {
-          // A queued interruption is resumable; only disposal is terminal.
-          release(this.disposed);
+          // The turn is over (interrupted or disposed). The next turn acquires again.
+          release(true);
           return;
         }
         this.releaseSlot = release;
@@ -681,11 +737,14 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (!this.isCurrent(gen)) return;
     const failure = session?.getLastAssistantFailure?.();
     if (failure) {
+      const error = failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`;
+      const classified = classifyModelFailure(error);
       this.settle(gen, {
         status: "failed",
         text: this.partialText(),
-        error: failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`,
-        endReason: "model-error",
+        error,
+        endReason: classified.endReason,
+        ...(classified.retryAfter !== undefined ? { retryAfter: classified.retryAfter } : {}),
         durationMs: this.now() - this.startedAt,
       });
       return;
@@ -756,8 +815,9 @@ class InProcessChildHandle implements DisposableChildHandle {
       result.warning = this.session.warning;
     }
     this.status_ = result.status;
-    this.terminalSettle = result.status !== "interrupted" || result.error === "disposed";
-    this.release(this.terminalSettle);
+    // Every settled turn releases its machine permit, including an
+    // interrupted one. The next turn (resume, send, user input) acquires again.
+    this.release(true);
     this.notifyActivity();
     this.resolveResult(result);
   }
@@ -861,7 +921,7 @@ class InProcessChildHandle implements DisposableChildHandle {
     this.toolStartedAt = null;
   }
 
-  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; usage?: { input: number; output: number } }): void {
+  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; toolName?: string; args?: unknown; usage?: { input: number; output: number } }): void {
     const now = this.now();
     const active = this.status_ === "running";
     let currentToolEvent = false;
@@ -905,6 +965,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       if (currentToolEvent) {
         this.toolDepth++;
         this.clearStall();
+        this.noteToolCall(event.toolName, event.args);
       }
       return;
     }
@@ -921,6 +982,22 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
   }
 
+  private noteToolCall(toolName: string | undefined, args: unknown): void {
+    const name = toolName ?? "";
+    const key = `${name}\0${JSON.stringify(args ?? null)}`;
+    if (this.lastToolKey === key) this.lastToolCount += 1;
+    else {
+      this.lastToolKey = key;
+      this.lastToolCount = 1;
+    }
+    if (this.lastToolCount !== 3 || !name) return;
+    try {
+      this.onToolLoop?.(this.req.childId, name, args);
+    } catch {
+      // loop observers must not break the child
+    }
+  }
+
   private release(terminal = true): void {
     const release = this.releaseSlot;
     if (terminal) this.releaseSlot = null;