@akagilnc/pi-workflow-roles 0.1.2091 → 0.1.2096

package/resources/engines/opus.md

@@ -14,18 +14,25 @@ The machine entrypoint is `claude`. Run from the role project root. Non-interact
 print mode (`-p` / `--print`) is verified available on this host:
 
 ```bash
-claude -p "YOUR_LABOR_PROMPT"
+claude -p --output-format=stream-json "YOUR_LABOR_PROMPT"
 ```
 
 Pin the Opus model explicitly (`--model opus` verified accepted on this host):
 
 ```bash
-claude -p --model opus "YOUR_LABOR_PROMPT"
+claude -p --model opus --output-format=stream-json "YOUR_LABOR_PROMPT"
 ```
 
+Use `--output-format=stream-json` (verified present on this host) so the package
+idle clock can see subprocess activity while the engine works; take the labor body
+from the final `result` event, not from intermediate stream rows.
+
 Prefer `claude --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.
 
-When the package detour tool is available, start exactly one subprocess through
-it with argv assembled from this material and the local CLI; return the stdout
-labor content to the same session for the existing typed submission path.
+When the package detour tool is available, start exactly one subprocess per
+labor invocation through it with argv assembled from this material and the
+local CLI; return the stdout labor content to the same session for the existing
+typed submission path. One labor turn = one process (not one process for the
+whole role run). If the detour fails, continue labor in-session on the seat main
+road and still submit via the existing typed path.

package/src/engine-detour-tool.ts

@@ -1,7 +1,10 @@
 /**
- * Package-owned engine detour tool (#357 T2 / #378).
+ * Package-owned engine detour tool (#357 T2 / #378 / #380).
  * Registered by shared role-runtime when Judge|Reviewer + engine activation signal is present.
  * Evidence-child legs install the same definition via customTools (no spawn in role modules).
+ * #380: engine process failure soft-returns so the seat rejoins the main road; declaration
+ * is recorded once via engine-labor-fallback (no fail-closed reject-leg).
+ * Caller AbortSignal cancel propagates without fallback; package-owned idle abort soft-fails.
  */
 import type {
   AgentToolResult,
@@ -19,7 +22,16 @@ import {
   isEngineDetourFailure,
   runEngineDetourOnce,
 } from "./engine-detour.ts";
-import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
+import {
+  activationEngineLaborFallbackLatch,
+  recordEngineLaborFallback,
+  type EngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
+import {
+  isPackageOwnedToolIdleTimeoutError,
+  pokePackageOwnedToolIdle,
+  wrapPackageOwnedToolDefinition,
+} from "./package-owned-tool-idle.ts";
 
 const engineDetourArgsSchema = Type.Object(
   {
@@ -49,10 +61,55 @@ export type EngineDetourToolRegistration = {
 
 type EngineDetourLatch = { used: boolean };
 
+function seatFallbackToolResult(
+  field: EngineLaborFallbackField,
+  failure: string,
+): AgentToolResult<unknown> {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text:
+          `Engine detour failed: ${failure}. Perform the labor in this session (seat main road) and submit via the existing typed path. A mechanical fallback declaration will attach to the typed receipt.`,
+      },
+    ],
+    details: {
+      tool: ENGINE_DETOUR_TOOL_NAME,
+      detourFailed: true,
+      ...field,
+    },
+  };
+}
+
+/** Caller/upper-layer cancel must propagate; idle backstop is seat-fallback, not cancel. */
+function isCallerCancellation(
+  error: unknown,
+  signal: AbortSignal | undefined,
+): boolean {
+  if (isPackageOwnedToolIdleTimeoutError(error)) return false;
+  if (
+    signal !== undefined &&
+    isPackageOwnedToolIdleTimeoutError(signal.reason)
+  ) {
+    return false;
+  }
+  if (signal?.aborted === true) return true;
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: unknown }).name === "AbortError"
+  ) {
+    return true;
+  }
+  return false;
+}
+
 /**
  * Build one once-latch detour tool definition for a configured engine name.
  * `latch` is shared so parent registration can reset between activations.
- * `fail` owns host abort (parent) vs throw (evidence child).
+ * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
+ * Engine process failure (nonzero/empty/spawn/idle-timeout) soft-returns seat fallback (#380).
+ * Caller AbortSignal cancel propagates without writing fallback.
  */
 export function createEngineDetourToolDefinition(input: {
   engineName: string;
@@ -71,6 +128,7 @@ export function createEngineDetourToolDefinition(input: {
       `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once for the configured engine (${engineName}). Optional packaged notes are guidance when present; a bare engine name alone is also a valid call path.`,
       "Pass argv for the host CLI of this engine name — first element is the executable name on PATH. Follow optional packaged notes when delivered; otherwise act from the engine name and the host CLI actual interface. Do not invent package flags.",
       "On success, use the returned stdout as labor content for the existing typed submission / report path.",
+      "On engine failure the tool returns a soft failure: continue labor in this session and submit via the existing typed path. Do not treat engine failure as a reason to withhold the typed receipt.",
     ],
     parameters: engineDetourArgsSchema,
     async execute(
@@ -99,27 +157,39 @@ export function createEngineDetourToolDefinition(input: {
         );
       }
 
+      const softFail = (failure: string): AgentToolResult<unknown> => {
+        // Activation-scoped latch is the sole shared recorder (parent seat + legs).
+        const fallbackLatch =
+          activationEngineLaborFallbackLatch() ?? { field: undefined };
+        const field = recordEngineLaborFallback(fallbackLatch, {
+          engine: engineName,
+          failure,
+        });
+        return seatFallbackToolResult(field, failure);
+      };
+
       let result: Awaited<ReturnType<typeof runEngineDetourOnce>>;
       try {
+        // Byte activity on stdout/stderr touches the outer package-owned idle clock
+        // (183s silence law unchanged). True hangs still die; slow streaming engines live.
         result = await runEngineDetourOnce({
           argv,
           cwd: ctx.cwd,
           ...(signal === undefined ? {} : { signal }),
+          onOutputActivity: pokePackageOwnedToolIdle,
         });
       } catch (error) {
-        input.fail(
-          error instanceof Error ? error : new Error(String(error)),
-          toolCallId,
-          ctx,
-        );
+        // Caller cancel: propagate. Idle backstop + spawn/engine failure: seat fallback.
+        if (isCallerCancellation(error, signal)) {
+          throw error;
+        }
+        const failure =
+          error instanceof Error ? error.message : String(error);
+        return softFail(failure.trim() === "" ? "engine detour spawn failed" : failure);
       }
 
       if (isEngineDetourFailure(result)) {
-        input.fail(
-          new Error(engineDetourFailureDiagnostic(result)),
-          toolCallId,
-          ctx,
-        );
+        return softFail(engineDetourFailureDiagnostic(result));
       }
 
       return {

package/src/engine-detour.ts

@@ -28,11 +28,28 @@ export type EngineDetourRunInput = Readonly<{
   cwd: string;
   env?: NodeJS.ProcessEnv;
   signal?: AbortSignal;
+  /**
+   * Called when the child emits at least one byte on stdout or stderr.
+   * Host wires this to the package-owned idle clock (activity = touch); no timer here.
+   */
+  onOutputActivity?: () => void;
 }>;
 
+function abortReasonError(signal: AbortSignal): Error {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason;
+  if (typeof reason === "string" && reason.trim() !== "") {
+    return new Error(reason);
+  }
+  const error = new Error("aborted");
+  error.name = "AbortError";
+  return error;
+}
+
 /**
  * Run one engine subprocess. First argv element is the executable (PATH lookup).
  * stdio: ignore stdin, pipe stdout+stderr. No shell, no retry, no hang timer.
+ * AbortSignal cancels the child immediately via an explicit listener (reason preserved).
  */
 export async function runEngineDetourOnce(
   input: EngineDetourRunInput,
@@ -44,30 +61,64 @@ export async function runEngineDetourOnce(
   const args = input.argv.slice(1);
   return await new Promise<EngineDetourResult>((resolve, reject) => {
     let settled = false;
+    const signal = input.signal;
+    // Own abort→kill explicitly so rejection preserves signal.reason (caller cancel
+    // vs package-owned idle). Do not pass `signal` to spawn (Node replaces reason).
     const child = spawn(command, args, {
       cwd: input.cwd,
       env: input.env ?? process.env,
       stdio: ["ignore", "pipe", "pipe"],
-      ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     let stdout = "";
     let stderr = "";
+    const noteActivity = (chunk: string): void => {
+      if (chunk.length === 0) return;
+      input.onOutputActivity?.();
+    };
     child.stdout.setEncoding("utf8").on("data", (chunk: string) => {
       stdout += chunk;
+      noteActivity(chunk);
     });
     child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
       stderr += chunk;
+      noteActivity(chunk);
     });
     const fail = (error: unknown): void => {
       if (settled) return;
       settled = true;
+      if (signal !== undefined) {
+        signal.removeEventListener("abort", onAbort);
+      }
       reject(error instanceof Error ? error : new Error(String(error)));
     };
-    child.on("error", (error) => fail(error));
-    child.on("close", (code) => {
+    const succeed = (result: EngineDetourResult): void => {
       if (settled) return;
       settled = true;
-      resolve({ code: code ?? 1, stdout, stderr });
+      if (signal !== undefined) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve(result);
+    };
+    const onAbort = (): void => {
+      // Fail synchronously so cooperative idle/cancel paths can soft-settle
+      // before the outer package-owned idle hard-reject drain.
+      fail(signal !== undefined ? abortReasonError(signal) : new Error("aborted"));
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // already exited
+      }
+    };
+    if (signal !== undefined) {
+      if (signal.aborted) {
+        onAbort();
+      } else {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+    child.on("error", (error) => fail(error));
+    child.on("close", (code) => {
+      succeed({ code: code ?? 1, stdout, stderr });
     });
   });
 }

package/src/engine-labor-fallback.ts

@@ -0,0 +1,172 @@
+/**
+ * #380 — sole shared seat-fallback declaration after engine detour failure.
+ * Detour rejoins the main road (ADR 0069); silence is the only crime.
+ * Construction of the typed receipt field lives in exactly one site (S1).
+ */
+
+export type EngineLaborFallback = Readonly<{
+  engine: string;
+  failure: string;
+  laborBy: "seat";
+}>;
+
+/** Activation-scoped latch holder (one parent seat activation at a time). */
+let activationLatch: EngineLaborFallbackLatch | undefined;
+
+/** Sole construction site for typed receipt field `engineLaborFallback` (#380 S1). */
+export function buildEngineLaborFallbackField(input: {
+  readonly engine: string;
+  readonly failure: string;
+}) {
+  return Object.freeze({
+    engineLaborFallback: Object.freeze({
+      engine: input.engine,
+      failure: input.failure,
+      laborBy: "seat" as const,
+    }),
+  });
+}
+
+/** Frozen field bag produced by the sole construction site. */
+export type EngineLaborFallbackField = ReturnType<
+  typeof buildEngineLaborFallbackField
+>;
+
+export type EngineLaborFallbackLatch = {
+  field: EngineLaborFallbackField | undefined;
+};
+
+export function createEngineLaborFallbackLatch(): EngineLaborFallbackLatch {
+  return { field: undefined };
+}
+
+/**
+ * Record first detour failure for this latch (first wins; parallel legs share one field).
+ * Always returns the latched first-wins value so tool details and receipt projection match.
+ */
+export function recordEngineLaborFallback(
+  latch: EngineLaborFallbackLatch,
+  input: { readonly engine: string; readonly failure: string },
+): EngineLaborFallbackField {
+  const field = buildEngineLaborFallbackField(input);
+  if (latch.field === undefined) latch.field = field;
+  return latch.field;
+}
+
+export function readEngineLaborFallbackField(
+  latch: EngineLaborFallbackLatch | undefined,
+): EngineLaborFallbackField | undefined {
+  return latch?.field;
+}
+
+/**
+ * Merge sole-built field into typed receipt details.
+ * Spread only — must not construct the field key again (S1).
+ * Without a mechanical latch, strip any model-injected reserved key (no forged declaration).
+ */
+export function withEngineLaborFallbackField<T extends object>(
+  receipt: T,
+  field: EngineLaborFallbackField | undefined,
+): T {
+  if (field !== undefined) {
+    return { ...receipt, ...field };
+  }
+  if (
+    !Object.prototype.hasOwnProperty.call(receipt, "engineLaborFallback")
+  ) {
+    return receipt;
+  }
+  const { engineLaborFallback: _forged, ...rest } = receipt as T & {
+    engineLaborFallback?: unknown;
+  };
+  return rest as T;
+}
+
+/** Install the activation-scoped latch (Judge/Reviewer session_start). */
+export function installActivationEngineLaborFallbackLatch(
+  latch: EngineLaborFallbackLatch,
+): void {
+  activationLatch = latch;
+}
+
+/** Clear activation latch (session end / next activation). */
+export function clearActivationEngineLaborFallbackLatch(): void {
+  activationLatch = undefined;
+}
+
+/** Active activation latch, if any (legs inherit parent seat activation). */
+export function activationEngineLaborFallbackLatch():
+  | EngineLaborFallbackLatch
+  | undefined {
+  return activationLatch;
+}
+
+/** Read fallback field from the active activation latch. */
+export function readActivationEngineLaborFallbackField():
+  | EngineLaborFallbackField
+  | undefined {
+  return readEngineLaborFallbackField(activationLatch);
+}
+
+/**
+ * Read a previously attached declaration from a typed receipt / details object.
+ * Rebuilds via the sole construction site — callers must spread, never re-key.
+ */
+export function readEngineLaborFallbackFieldFrom(
+  source: unknown,
+): EngineLaborFallbackField | undefined {
+  if (typeof source !== "object" || source === null || Array.isArray(source)) {
+    return undefined;
+  }
+  let raw: unknown;
+  try {
+    raw = (source as Record<string, unknown>).engineLaborFallback;
+  } catch {
+    return undefined;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const rec = raw as Record<string, unknown>;
+  if (
+    typeof rec.engine !== "string" ||
+    typeof rec.failure !== "string" ||
+    rec.laborBy !== "seat"
+  ) {
+    return undefined;
+  }
+  return buildEngineLaborFallbackField({
+    engine: rec.engine,
+    failure: rec.failure,
+  });
+}
+
+/**
+ * Restore activation latch from durable session tool results (#380 resume).
+ * Scans existing same-session detour tool results only — no sidecar / new entry type.
+ * Replays through recordEngineLaborFallback so first-wins + sole producer stay intact.
+ */
+export function restoreEngineLaborFallbackFromSessionEntries(
+  latch: EngineLaborFallbackLatch,
+  entries: readonly unknown[],
+  toolName: string,
+): void {
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const row = entry as { type?: unknown; message?: unknown };
+    if (row.type !== "message") continue;
+    const message = row.message;
+    if (typeof message !== "object" || message === null) continue;
+    const msg = message as {
+      role?: unknown;
+      toolName?: unknown;
+      details?: unknown;
+    };
+    if (msg.role !== "toolResult") continue;
+    if (msg.toolName !== toolName) continue;
+    const field = readEngineLaborFallbackFieldFrom(msg.details);
+    if (field === undefined) continue;
+    recordEngineLaborFallback(latch, {
+      engine: field.engineLaborFallback.engine,
+      failure: field.engineLaborFallback.failure,
+    });
+  }
+}

package/src/evidence-child-executor.ts

@@ -596,17 +596,15 @@ export async function executeEvidenceChild(
                 engine: engineName,
                 packageRoot: options.packageRoot,
               });
-      // #378: detour failure is durable for this leg — later assistant reports cannot wash it.
-      let engineDetourFailure: Error | undefined;
+      // #378/#380: same detour tool as parent seat. Engine process failure soft-returns
+      // seat main-road fallback (ADR 0069 detour-rejoins-main-road); tool misuse still throws.
       const engineDetourTool =
         engineName === undefined
           ? undefined
           : createEngineDetourToolDefinition({
               engineName,
               fail(error) {
-                const failure = error instanceof Error ? error : new Error(String(error));
-                engineDetourFailure = failure;
-                throw failure;
+                throw error instanceof Error ? error : new Error(String(error));
               },
             });
       // No tools allowlist — Pi defaults + unrestricted evidence surface (ADR 0064).
@@ -642,18 +640,8 @@ export async function executeEvidenceChild(
         try {
           await session.prompt(delivered);
         } catch (error) {
-          // Engine detour fail becomes isError toolResult and must outrank a later
-          // provider-shaped throw from the same prompt turn (#378).
-          if (engineDetourFailure !== undefined) {
-            throw classifiedError(engineDetourFailure, "child");
-          }
           throw classifiedError(error, "provider");
         }
-        // Launched-leg detour non-zero / empty stdout / spawn failure is infrastructure:
-        // reject the leg even when the model still emits a non-blank report afterward.
-        if (engineDetourFailure !== undefined) {
-          throw classifiedError(engineDetourFailure, "child");
-        }
         if (signal?.aborted) throw new Error("Evidence child was cancelled");
         const lastAssistant = [...session.messages]
           .reverse()

package/src/judge-role.ts

@@ -8,6 +8,10 @@ import { Type, type Static } from "typebox";
 
 import { disposeComplianceDecision } from "./audit-escalation.ts";
 import type { ComplianceDecision } from "./compliance-transport.ts";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 
 import {
   JUDGE_OUTPUT_TOOL_NAME,
@@ -126,18 +130,21 @@ export function createJudgeRoleRuntime(
             } catch (error) {
               hostActions.failInfrastructure(error, ctx, toolCallId);
             }
+            // #380: attach sole-built engineLaborFallback when detour fell back to seat labor.
+            const laborFallback = readActivationEngineLaborFallbackField();
+            const acceptedDetails = withEngineLaborFallbackField(verdict, laborFallback);
             return disposeComplianceDecision<AgentToolResult<unknown>>(
               audit,
               {
                 pass: (usage) => ({
                   content: [{ type: "text" as const, text: "Judge verdict accepted" }],
-                  details: verdict,
+                  details: acceptedDetails,
                   terminate: true as const,
                   ...(usage === undefined ? {} : { usage }),
                 }),
                 noReceipt: (auditNoReceipt, usageProjection) => ({
                   content: [{ type: "text" as const, text: "Judge verdict accepted; compliance audit produced no receipt" }],
-                  details: { ...verdict, auditNoReceipt },
+                  details: { ...acceptedDetails, auditNoReceipt },
                   terminate: true as const,
                   ...usageProjection,
                 }),
@@ -149,7 +156,8 @@ export function createJudgeRoleRuntime(
                 escalate: (result) => result,
                 auditIncomplete: (result) => result,
               },
-              verdict,
+              // #380: escalate deliveredOutput must carry the same mechanical projection.
+              acceptedDetails,
             );
           },
         });

package/src/package-owned-tool-idle.ts

@@ -4,11 +4,16 @@
  * Fixed 183000ms silence clock on package-owned tool execute only.
  * Real producing onUpdate resets; final resolve/reject clears; timeout throws so
  * Pi settles the current call as an LLM-visible isError tool result. No retry,
- * role failure, process termination, signal abort, config, or Pi built-in coverage.
+ * role failure, process termination, config, or Pi built-in coverage.
  *
  * #339: do not name-exempt whole terminating tools. Outer idle stays armed for
  * pre/post-audit work. Only the real compliance-audit await suspends this single
  * layer (ADR 0059 owns that interval); resume re-arms the same outer backstop.
+ *
+ * #380: on idle, abort a derived tool signal (not the caller signal) so detour
+ * spawn cleanup and softFail can run through the existing AbortSignal path.
+ * Cooperative soft-settle may win; non-listeners still hard-reject after a
+ * microtask drain (no second timer).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
@@ -28,6 +33,8 @@ const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
 type PackageOwnedToolIdleSuspension = {
   suspend(): void;
   resume(): void;
+  /** Reset the silence window (byte/activity signal from the active execute). */
+  poke(): void;
 };
 
 /**
@@ -46,6 +53,20 @@ export class PackageOwnedToolIdleTimeoutError extends Error {
   }
 }
 
+export function isPackageOwnedToolIdleTimeoutError(
+  value: unknown,
+): value is PackageOwnedToolIdleTimeoutError {
+  return (
+    value instanceof PackageOwnedToolIdleTimeoutError ||
+    (
+      typeof value === "object" &&
+      value !== null &&
+      (value as { name?: unknown }).name === "PackageOwnedToolIdleTimeoutError" &&
+      (value as { code?: unknown }).code === PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE
+    )
+  );
+}
+
 /** Minimal executable tool shape accepted by the shared idle wrapper. */
 export type PackageOwnedToolLike = {
   readonly name: string;
@@ -87,6 +108,15 @@ export async function withPackageOwnedToolIdleSuspended<T>(
   }
 }
 
+/**
+ * Touch the active package-owned execute idle clock (reuse stream-idle-guard poke).
+ * No-op outside a wrapped package-owned execute or while that layer is suspended.
+ * Used by long-running tools (engine detour) that see real subprocess output bytes.
+ */
+export function pokePackageOwnedToolIdle(): void {
+  packageOwnedToolIdleScope.getStore()?.poke();
+}
+
 /**
  * Single shared execute wrapper for package-owned tool definitions.
  * Idempotent: wrapping twice returns the same protected definition.
@@ -103,7 +133,7 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
   const wrappedExecute = function packageOwnedToolIdleExecute(
     ...args: unknown[]
   ): Promise<unknown> {
-    const signal = args[2] as AbortSignal | undefined;
+    const parentSignal = args[2] as AbortSignal | undefined;
     const onUpdate = args[3] as ((partialResult: unknown) => void) | undefined;
     return new Promise((resolve, reject) => {
       let settled = false;
@@ -112,15 +142,46 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
         idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
       });
 
+      // Derived tool signal: caller cancel forwards; idle aborts this only (not parent).
+      const toolController = new AbortController();
+      const onParentAbort = (): void => {
+        if (toolController.signal.aborted) return;
+        toolController.abort(parentSignal?.reason);
+      };
+      if (parentSignal !== undefined) {
+        if (parentSignal.aborted) {
+          toolController.abort(parentSignal.reason);
+        } else {
+          parentSignal.addEventListener("abort", onParentAbort);
+        }
+      }
+
+      const cleanup = (): void => {
+        idle.signal.removeEventListener("abort", onIdle);
+        idle.dispose();
+        parentSignal?.removeEventListener("abort", onParentAbort);
+      };
+
       const settle = (deliver: () => void): void => {
         if (settled) return;
         settled = true;
-        idle.signal.removeEventListener("abort", onIdle);
-        idle.dispose();
+        cleanup();
         deliver();
       };
       const onIdle = (): void => {
-        settle(() => reject(new PackageOwnedToolIdleTimeoutError()));
+        const idleError = new PackageOwnedToolIdleTimeoutError();
+        if (!toolController.signal.aborted) {
+          toolController.abort(idleError);
+        }
+        // Cooperative tools (detour) soft-settle via the aborted signal in the
+        // next microtasks. Non-listeners still hard-reject after a short drain
+        // of those microtasks — no second wall-clock timer.
+        void Promise.resolve()
+          .then(() => {})
+          .then(() => {})
+          .then(() => {
+            settle(() => reject(idleError));
+          });
       };
       idle.signal.addEventListener("abort", onIdle, { once: true });
 
@@ -141,6 +202,10 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
           });
           idle.signal.addEventListener("abort", onIdle, { once: true });
         },
+        poke(): void {
+          if (settled || suspended) return;
+          idle.poke();
+        },
       };
 
       const guardedOnUpdate = onUpdate === undefined
@@ -152,8 +217,9 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
           };
 
       const callArgs = args.slice();
-      // Preserve the original signal at args[2]; timeout must not abort it.
-      callArgs[2] = signal;
+      // Pass derived signal so idle/cancel can clean up subprocesses without
+      // aborting the caller/parent agent signal identity.
+      callArgs[2] = toolController.signal;
       callArgs[3] = guardedOnUpdate;
 
       void packageOwnedToolIdleScope.run(suspension, async () => {