@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.20.11",
-  "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
+  "version": "0.21.0",
+  "description": "Agent runtime backed by the Pi SDK provider catalog",
   "type": "module",
   "license": "GPL-3.0-only",
   "repository": {
@@ -47,18 +47,6 @@
       "types": "./types/ai/runtime/registry.d.ts",
       "default": "./src/ai/runtime/registry.js"
     },
-    "./ai/runtime/context-windows.js": {
-      "types": "./types/ai/runtime/context-windows.d.ts",
-      "default": "./src/ai/runtime/context-windows.js"
-    },
-    "./ai/runtime/fast-mode.js": {
-      "types": "./types/ai/runtime/fast-mode.d.ts",
-      "default": "./src/ai/runtime/fast-mode.js"
-    },
-    "./ai/streaming/codex-events.js": {
-      "types": "./types/ai/streaming/codex-events.d.ts",
-      "default": "./src/ai/streaming/codex-events.js"
-    },
     "./ai/live-input-prompt.js": {
       "types": "./types/ai/live-input-prompt.d.ts",
       "default": "./src/ai/live-input-prompt.js"
@@ -67,29 +55,9 @@
       "types": "./types/ai/file-change-stats.d.ts",
       "default": "./src/ai/file-change-stats.js"
     },
-    "./ai/providers/claude-sdk.js": {
-      "types": "./types/ai/providers/claude-sdk.d.ts",
-      "default": "./src/ai/providers/claude-sdk.js"
-    },
-    "./ai/providers/claude-sdk-discovery.js": {
-      "types": "./types/ai/providers/claude-sdk-discovery.d.ts",
-      "default": "./src/ai/providers/claude-sdk-discovery.js"
-    },
-    "./ai/providers/claude-cli.js": {
-      "types": "./types/ai/providers/claude-cli.d.ts",
-      "default": "./src/ai/providers/claude-cli.js"
-    },
-    "./ai/providers/codex-app.js": {
-      "types": "./types/ai/providers/codex-app.d.ts",
-      "default": "./src/ai/providers/codex-app.js"
-    },
-    "./ai/providers/opencode-discovery.js": {
-      "types": "./types/ai/providers/opencode-discovery.d.ts",
-      "default": "./src/ai/providers/opencode-discovery.js"
-    },
-    "./ai/providers/acp.js": {
-      "types": "./types/ai/providers/acp.d.ts",
-      "default": "./src/ai/providers/acp.js"
+    "./ai/providers/codex/app-server-client.js": {
+      "types": "./types/ai/providers/codex/app-server-client.d.ts",
+      "default": "./src/ai/providers/codex/app-server-client.js"
     },
     "./agent/tools/index.js": {
       "types": "./types/agent/tools/index.d.ts",
@@ -132,26 +100,27 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.15.0"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.3.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.206",
-    "@anthropic-ai/sdk": "^0.110.0",
-    "@earendil-works/pi-agent-core": "0.83.0",
-    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-agent-core": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "0.6.0",
-    "@opencode-ai/sdk": "^1.15.13",
     "@vscode/ripgrep": "1.18.0",
     "bmp-ts": "1.0.9",
     "cross-spawn": "^7.0.6",
     "defuddle": "0.19.2",
+    "fast-xml-parser": "5.7.3",
     "linkedom": "0.18.13",
     "sharp": "0.35.3",
+    "turndown": "7.2.4",
     "unpdf": "1.8.0",
     "zod": "^4.3.6"
   },
+  "devDependencies": {
+    "@types/turndown": "5.0.6"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.types.json",
     "typecheck": "tsc -p tsconfig.types.json --noEmit",

package/src/agent/tool-bloat.js

@@ -6,9 +6,9 @@
 // still cite the artifact.
 //
 // Persistence is delegated to the host via a `persistArtifact({ filename, buffer,
-// toolName, toolUseId }) -> path | null` callback. Host output sinks
-// in src/core/tool-artifacts.js writes to {runArtifactDir}/tool-output/<file>.
-// Hosts that don't care can pass null and the truncated payload is dropped.
+// toolName, toolUseId }) -> path | null` callback. The app binds that callback
+// per run and stores payloads under its configured tool-output artifact root.
+// Hosts that don't provide a sink still receive bounded retained text.
 
 export const MAX_TOOL_RESULT_BYTES = 262144;
 
@@ -22,6 +22,11 @@ export const DEFAULT_TOOL_BLOAT_CONFIG = Object.freeze({
   binaryBloatTools: BINARY_BLOAT_TOOLS,
 });
 
+const RETAINED_UNTRUSTED_BEGIN = "[BEGIN RETAINED UNTRUSTED TOOL RESULT]";
+const RETAINED_UNTRUSTED_END = "[END RETAINED UNTRUSTED TOOL RESULT]";
+const RETAINED_MIDDLE_NOTICE = "[Omitted middle may contain additional source content; retained tail is not the source ending.]";
+const RETAINED_OMISSION_RE = /\[\.\.\. (\d+) source bytes omitted \.\.\.\]/gu;
+
 function blockBytes(block) {
   if (!block || typeof block !== "object") return 0;
   if (block.type === "text") return Buffer.byteLength(String(block.text || ""), "utf8");
@@ -74,17 +79,144 @@ function persistBlock(toolName, block, idx, idTag, persistArtifact) {
   }
 }
 
-function summaryText(toolName, originalBytes, maxBytes, savedPaths) {
+function controlFree(value) {
+  return String(value || "").replace(/[\u0000-\u001f\u007f]+/gu, " ").trim();
+}
+
+function persistenceSummary(savedPaths, includePath = true) {
+  if (savedPaths.length === 0) return "persistence unavailable";
+  if (!includePath) return `saved_files=${savedPaths.length}`;
+  if (savedPaths.length === 1) return `saved_to=${controlFree(savedPaths[0])}`;
+  return `saved_to=${controlFree(savedPaths[0])}; saved_files=${savedPaths.length}`;
+}
+
+function summaryText(toolName, originalBytes, retainedBytes, maxBytes, savedPaths, includePath = true) {
   const parts = [
     `[truncated tool_result: ${originalBytes} bytes exceeded ${maxBytes} byte cap`,
-    `tool=${toolName}`,
+    `retained=${retainedBytes} bytes`,
+    `tool=${controlFree(toolName)}`,
   ];
-  if (savedPaths.length === 1) parts.push(`saved_to=${savedPaths[0]}`);
-  else if (savedPaths.length > 1) parts.push(`saved_to=[${savedPaths.length} files]`);
-  else parts.push("persistence unavailable");
+  parts.push(persistenceSummary(savedPaths, includePath));
   return `${parts.join("; ")}]`;
 }
 
+function capSummary(text, maxBytes) {
+  for (const candidate of [text, "[truncated tool_result]", "[truncated]", "[]"]) {
+    if (Buffer.byteLength(candidate, "utf8") <= maxBytes) return candidate;
+  }
+  return "";
+}
+
+function summaryOnly(toolName, originalBytes, maxBytes, savedPaths) {
+  const parts = [
+    `[truncated tool_result: ${originalBytes} bytes exceeded ${maxBytes} byte cap`,
+    `tool=${controlFree(toolName)}`,
+  ];
+  parts.push(persistenceSummary(savedPaths));
+  return `${parts.join("; ")}]`;
+}
+
+function neutralizeRetainedFrames(value) {
+  return wellFormedText(value)
+    .replaceAll(RETAINED_UNTRUSTED_BEGIN, `(BEGIN RETAINED UNTRUSTED TOOL RESULT)`)
+    .replaceAll(RETAINED_UNTRUSTED_END, `(END RETAINED UNTRUSTED TOOL RESULT)`)
+    .replaceAll(RETAINED_MIDDLE_NOTICE, `(Omitted middle may contain additional source content; retained tail is not the source ending.)`)
+    .replace(RETAINED_OMISSION_RE, `(... $1 source bytes omitted ...)`);
+}
+
+function wellFormedText(value) {
+  let out = "";
+  for (const point of String(value || "")) {
+    const unit = point.charCodeAt(0);
+    out += point.length === 1 && unit >= 0xd800 && unit <= 0xdfff ? "\uFFFD" : point;
+  }
+  return out;
+}
+
+function utf8Head(segments, maxBytes) {
+  if (maxBytes <= 0) return { text: "", sourceBytes: 0 };
+  let bytes = 0;
+  let out = "";
+  let sourceBytes = 0;
+  outer: for (const segment of segments) {
+    for (const point of segment.text) {
+      const size = Buffer.byteLength(point, "utf8");
+      if (bytes + size > maxBytes) break outer;
+      out += point;
+      bytes += size;
+      if (segment.source) sourceBytes += size;
+    }
+  }
+  return { text: out, sourceBytes };
+}
+
+function utf8Tail(segments, maxBytes) {
+  if (maxBytes <= 0) return { text: "", sourceBytes: 0 };
+  let bytes = 0;
+  const out = [];
+  let sourceBytes = 0;
+  outer: for (const segment of [...segments].reverse()) {
+    for (const point of [...segment.text].reverse()) {
+      const size = Buffer.byteLength(point, "utf8");
+      if (bytes + size > maxBytes) break outer;
+      out.push(point);
+      bytes += size;
+      if (segment.source) sourceBytes += size;
+    }
+  }
+  return { text: out.reverse().join(""), sourceBytes };
+}
+
+function retainedTextPayload(toolName, blocks, originalBytes, maxBytes, savedPaths) {
+  const segments = blocks.flatMap((block, index) => [
+    ...(index === 0 ? [] : [{ text: "\n\n", source: false }]),
+    { text: neutralizeRetainedFrames(block.text), source: true },
+  ]);
+  const maximumDigits = String(originalBytes).length;
+  const retainedPlaceholder = "9".repeat(maximumDigits);
+  const omittedPlaceholder = "9".repeat(maximumDigits);
+  let summary = summaryText(toolName, originalBytes, Number(retainedPlaceholder), maxBytes, savedPaths, true);
+  const fixedBody = [
+    summary,
+    RETAINED_UNTRUSTED_BEGIN,
+    "",
+    `[... ${omittedPlaceholder} source bytes omitted ...]`,
+    RETAINED_MIDDLE_NOTICE,
+    "",
+    RETAINED_UNTRUSTED_END,
+  ].join("\n");
+  if (Buffer.byteLength(fixedBody, "utf8") > maxBytes) {
+    summary = summaryText(toolName, originalBytes, 0, maxBytes, savedPaths, false);
+    return capSummary(summary, maxBytes);
+  }
+
+  const sourceBudget = maxBytes - Buffer.byteLength(fixedBody, "utf8");
+  const head = utf8Head(segments, Math.floor(sourceBudget * 0.6));
+  const tail = utf8Tail(segments, sourceBudget - Buffer.byteLength(head.text, "utf8"));
+  const retainedBytes = head.sourceBytes + tail.sourceBytes;
+  const omittedBytes = Math.max(0, originalBytes - retainedBytes);
+  summary = summaryText(toolName, originalBytes, retainedBytes, maxBytes, savedPaths, true);
+  const rendered = [
+    summary,
+    RETAINED_UNTRUSTED_BEGIN,
+    head.text,
+    `[... ${omittedBytes} source bytes omitted ...]`,
+    RETAINED_MIDDLE_NOTICE,
+    tail.text,
+    RETAINED_UNTRUSTED_END,
+  ].join("\n");
+  if (Buffer.byteLength(rendered, "utf8") <= maxBytes) return rendered;
+
+  // A long saved path can make the exact-path summary larger than the reserved
+  // placeholder. Preserve the trust frame and source slices by falling back to
+  // the honest saved-file count, never by returning a partial path.
+  const countSummary = summaryText(toolName, originalBytes, retainedBytes, maxBytes, savedPaths, false);
+  const countRendered = [countSummary, ...rendered.split("\n").slice(1)].join("\n");
+  return Buffer.byteLength(countRendered, "utf8") <= maxBytes
+    ? countRendered
+    : capSummary(countSummary, maxBytes);
+}
+
 export function summarisePayload(toolName, contentBlocks, persistArtifact, options = {}) {
   const {
     maxBytes = MAX_TOOL_RESULT_BYTES,
@@ -109,8 +241,12 @@ export function summarisePayload(toolName, contentBlocks, persistArtifact, optio
     const path = persistBlock(toolName, block, idx, idTag, persistArtifact);
     if (path) savedPaths.push(path);
   });
+  const textOnly = blocks.length > 0 && blocks.every((block) => block?.type === "text");
+  const rewrittenText = textOnly && otherBytes > maxBytes && imageBytes === 0
+    ? retainedTextPayload(toolName, blocks, originalBytes, maxBytes, savedPaths)
+    : summaryOnly(toolName, originalBytes, maxBytes, savedPaths);
   return {
-    rewrittenBlocks: [{ type: "text", text: summaryText(toolName, originalBytes, maxBytes, savedPaths) }],
+    rewrittenBlocks: [{ type: "text", text: rewrittenText }],
     savedPaths,
     originalBytes,
     truncated: true,

package/src/agent/tools/agent-tool.js

@@ -203,7 +203,7 @@ function positiveInt(value, fallback) {
  * Build the `Agent` tool, or null when subagents are unavailable for this run.
  *
  * @param {RuntimeSubagentsOptions|null|undefined} subagents
- * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, onEvent?: (event: *) => void}} [context]
+ * @param {{model?: *, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, webSearchConfig?: *, webRequestCoordinator?: *, webFetchConfig?: *, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents, context = {}) {
@@ -291,9 +291,10 @@ export function createAgentTool(subagents, context = {}) {
     label: "Agent",
     description: toolDescription(subagents, definitions, ceiling),
     parameters,
-    // MUST stay undefined. pi-agent-core's agent loop makes the ENTIRE batch
-    // sequential when any tool in it declares executionMode "sequential"
-    // (dist/agent-loop.js:289), which would serialize every parallel Agent call.
+    // MUST stay undefined. Agent-only batches can overlap when the offered tool
+    // set contains no sequential tool. Pi 0.85 exposes only a global harness
+    // mode, however, so offering Bash/Write/MCP/etc. serializes Agent calls too;
+    // see the documented provider limitation rather than marking Agent itself.
     executionMode: undefined,
     /**
      * @param {string} toolCallId
@@ -398,7 +399,6 @@ export function createAgentTool(subagents, context = {}) {
           prompt: params.prompt,
           definition: profile,
           ...(context.model === undefined ? {} : { model: context.model }),
-          ...(context.executionMode === undefined ? {} : { executionMode: context.executionMode }),
           ...(context.cwd === undefined ? {} : { cwd: context.cwd }),
           ...(context.parentRunId === undefined ? {} : { parentRunId: context.parentRunId }),
           // Inherited, never widened: a profile cannot loosen confinement.
@@ -410,6 +410,9 @@ export function createAgentTool(subagents, context = {}) {
           ...(context.skills === undefined ? {} : { skills: context.skills }),
           ...(context.skillsRoot === undefined ? {} : { skillsRoot: context.skillsRoot }),
           ...(context.toolEnvironment === undefined ? {} : { toolEnvironment: context.toolEnvironment }),
+          ...(context.webSearchConfig === undefined ? {} : { webSearchConfig: context.webSearchConfig }),
+          ...(context.webRequestCoordinator === undefined ? {} : { webRequestCoordinator: context.webRequestCoordinator }),
+          ...(context.webFetchConfig === undefined ? {} : { webFetchConfig: context.webFetchConfig }),
           abortSignal: controller.signal,
           maxTurns,
           callId: toolCallId,
@@ -447,7 +450,7 @@ export function createAgentTool(subagents, context = {}) {
 
       const durationMs = Date.now() - startedAt;
       const outcome = classifyOutcome({ result, thrown, timedOut, abandoned });
-      collector.finished({ status: outcome.status, durationMs });
+      collector.finished({ status: outcome.status, durationMs, result });
       // Each result is individually capped, but the parent's context sees the
       // SUM. The description encourages parallel calls, so twenty valid results
       // would otherwise land ~480KB in one batch. Later calls get whatever
@@ -598,6 +601,22 @@ function normalizeProfile(definition) {
 
 /** Hard cap on any single forwarded payload, so the operator wire's binary-search reducer never has to run. */
 const WIRE_CONTENT_MAX_CHARS = 2_000;
+const ROUTE_HISTORY_MAX_ENTRIES = 32;
+
+function boundedRouteString(value, max = 256) {
+  return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+}
+
+function boundedRouteIndex(value) {
+  return Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+
+function appendRouteEntry(entries, entry, routeState) {
+  entries.push(entry);
+  if (entries.length <= ROUTE_HISTORY_MAX_ENTRIES) return;
+  entries.splice(1, entries.length - ROUTE_HISTORY_MAX_ENTRIES);
+  routeState.truncated = true;
+}
 
 /**
  * Translates the child's raw provider events into (a) a bounded per-tool-call
@@ -624,6 +643,7 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit,
   /** What the child reported spending, so the parent run can own it. */
   const usage = emptyUsage();
   const subagent = { id: callId, name: profileName, callIndex, ...(label === undefined ? {} : { label }) };
+  const routeState = { requested: {}, attempted: undefined, transitions: [], retries: [], truncated: false };
 
   /** @param {*} event */
   const publish = (event) => {
@@ -646,11 +666,32 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit,
         arguments: { name: profileName, ...(label === undefined ? {} : { description: label }) },
       });
     },
-    /** @param {{status: string, durationMs: number}} outcome */
-    finished({ status, durationMs }) {
+    /** @param {{status: string, durationMs: number, result?: *}} outcome */
+    finished({ status, durationMs, result }) {
       // Before the bookend, so the run's own usage report can already include
       // it, and so an abandoned child still hands over whatever it spent.
       recordUsage?.(usage);
+      const executed = status === "ok" && result && typeof result === "object"
+        ? {
+            ...(boundedRouteString(result.model) === undefined ? {} : { model: boundedRouteString(result.model) }),
+            ...(boundedRouteString(result.effort, 64) === undefined ? {} : { effort: boundedRouteString(result.effort, 64) }),
+            ...(boundedRouteString(result.effectiveEffort, 64) === undefined ? {} : { effectiveEffort: boundedRouteString(result.effectiveEffort, 64) }),
+          }
+        : undefined;
+      const requestedModel = routeState.requested.model;
+      const fallback = routeState.transitions.length > 0
+        || (executed?.model !== undefined && requestedModel !== undefined && executed.model !== requestedModel);
+      const attribution = requestedModel === undefined && routeState.attempted === undefined && executed === undefined
+        ? undefined
+        : {
+            requested: routeState.requested,
+            ...(routeState.attempted === undefined ? {} : { attempted: routeState.attempted }),
+            ...(executed === undefined ? {} : { executed }),
+            disposition: requestedModel === undefined ? "unknown" : fallback ? "fallback" : "requested",
+            transitions: routeState.transitions,
+            retries: routeState.retries,
+            ...(routeState.truncated ? { truncated: true } : {}),
+          };
       publish({
         phase: "agent_completed",
         id: `agent:${callId}`,
@@ -658,7 +699,13 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit,
         // The one place the child's price is knowable per delegation: operator
         // surfaces show it on the row so an expensive one is identifiable, not
         // just visible in the run total it disappears into.
-        ...(usage.costUsd > 0 ? { subagent: { ...subagent, costUsd: usage.costUsd } } : {}),
+        ...((usage.costUsd > 0 || attribution !== undefined)
+          ? { subagent: {
+              ...subagent,
+              ...(usage.costUsd > 0 ? { costUsd: usage.costUsd } : {}),
+              ...(attribution === undefined ? {} : { attribution }),
+            } }
+          : {}),
         isError: status !== "ok",
         executionMs: durationMs,
         content: `${status} · ${done.length} tool call${done.length === 1 ? "" : "s"}`,
@@ -681,6 +728,58 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit,
     /** @param {*} event */
     observe(event) {
       const type = event?.type;
+      if (type === "provider_execution_config") {
+        const model = boundedRouteString(event.model);
+        const effort = boundedRouteString(event.effort, 64);
+        const effectiveEffort = boundedRouteString(event.effectiveEffort, 64);
+        routeState.attempted = {
+          ...(model === undefined ? {} : { model }),
+          ...(effort === undefined ? {} : { effort }),
+          ...(effectiveEffort === undefined ? {} : { effectiveEffort }),
+        };
+        if (routeState.requested.model === undefined && routeState.transitions.length === 0) {
+          routeState.requested = {
+            ...(model === undefined ? {} : { model }),
+            ...(effort === undefined ? {} : { effort }),
+          };
+        }
+        return;
+      }
+      if (type === "provider_failover_started") {
+        const from = boundedRouteString(event.from);
+        const to = boundedRouteString(event.to);
+        if (from !== undefined && to !== undefined) {
+          if (routeState.requested.model === undefined) routeState.requested = { model: from };
+          const attemptIndex = boundedRouteIndex(event.attemptIndex);
+          const reason = boundedRouteString(event.reason, 128);
+          appendRouteEntry(routeState.transitions, {
+            from,
+            to,
+            ...(attemptIndex === undefined ? {} : { attemptIndex }),
+            ...(reason === undefined ? {} : { reason }),
+          }, routeState);
+          routeState.attempted = { model: to };
+        }
+        return;
+      }
+      if (type === "provider_retry_started") {
+        const model = boundedRouteString(event.model);
+        const retryIndex = boundedRouteIndex(event.retryIndex);
+        const attempts = boundedRouteIndex(event.attempts);
+        const reason = boundedRouteString(event.reason, 128);
+        appendRouteEntry(routeState.retries, {
+          ...(model === undefined ? {} : { model }),
+          ...(retryIndex === undefined ? {} : { retryIndex }),
+          ...(attempts === undefined ? {} : { attempts }),
+          ...(reason === undefined ? {} : { reason }),
+        }, routeState);
+        return;
+      }
+      if (type === "provider_failover_completed") {
+        const model = boundedRouteString(event.model);
+        if (model !== undefined) routeState.attempted = { ...(routeState.attempted || {}), model };
+        return;
+      }
       // Providers legitimately forward multiple blocks in one message; the
       // Claude bridges do routinely. Inspecting only content[0] dropped every
       // tool call after the first.

package/src/agent/tools/bash.js

@@ -14,22 +14,12 @@ import {
   DEFAULT_PROCESS_BUFFER_BYTES,
   runPreparedProcess,
 } from "./shared/process-runner.js";
+import { cleanBashEnvironment } from "./shared/bash-environment.js";
 import { handOffProcessJob } from "./shared/process-jobs.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_BASH_TIMEOUT_MS = 120_000;
-const BASH_STARTUP_ENV_KEYS = new Set([
-  "BASHOPTS",
-  "BASH_COMPAT",
-  "BASH_XTRACEFD",
-  "CDPATH",
-  "GLOBIGNORE",
-  "POSIXLY_CORRECT",
-  "PROMPT_COMMAND",
-  "PS4",
-  "SHELLOPTS",
-]);
 
 /**
  * Legacy Bash timeout normalization. Values up to 600 are seconds; larger
@@ -82,7 +72,7 @@ export function normalizeBackgroundBashTimeoutMs(value) {
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export async function bashToolImpl(params, options = {}) {
@@ -92,7 +82,7 @@ export async function bashToolImpl(params, options = {}) {
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export async function bashToolRun(
@@ -104,6 +94,7 @@ export async function bashToolRun(
     max_output_chars,
     workdir,
     background,
+    wake_on_completion,
   },
   {
     signal,
@@ -114,6 +105,12 @@ export async function bashToolRun(
   } = {},
 ) {
   const startedAt = Date.now();
+  if (wake_on_completion !== undefined && (background !== true || typeof wake_on_completion !== "boolean")) {
+    return failed("Error: wake_on_completion requires background=true and a boolean value.", "process_job_invalid", startedAt);
+  }
+  if (background === true && !processJobsController) {
+    return failed("Error: Background process jobs are unavailable for this request.", "background_unsupported", startedAt);
+  }
   if (typeof command !== "string") {
     return failed("Error: Bash command must be a string.", "invalid_command", startedAt);
   }
@@ -168,6 +165,7 @@ export async function bashToolRun(
       prepared,
       summary: `Bash command (${command.length} characters; content redacted)`,
       description,
+      wakeOnCompletion: wake_on_completion,
       timeoutMs: requestedTimeoutMs,
       maxOutputChars: max_output_chars === undefined ? undefined : maxChars,
       startedAt,
@@ -260,19 +258,6 @@ export async function bashToolRun(
   return completed(partial, baseOutcome, maxChars, "Bash", resolvedCtx);
 }
 
-function cleanBashEnvironment() {
-  const env = {
-    BASH_ENV: "/dev/null",
-    ENV: "/dev/null",
-  };
-  for (const key of Object.keys(process.env)) {
-    if (BASH_STARTUP_ENV_KEYS.has(key) || key.startsWith("BASH_FUNC_")) {
-      env[key] = undefined;
-    }
-  }
-  return env;
-}
-
 function finitePositiveInteger(value, fallback) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;