@mono-agent/agent-runtime 0.19.0 → 0.20.0

package/src/agent/tools/grep.js

@@ -9,9 +9,17 @@ import {
 import { boundedInt, safeStat } from "./shared/dedup.js";
 import {
   isPathAllowed,
+  isPathLexicallyAllowed,
+  protectedRelativePaths,
   resolveToolPath,
   workspaceRoot,
 } from "./shared/path-resolver.js";
+import {
+  normalizeProtectedSearchLine,
+  protectedFilesystemTargetPlan,
+  runProtectedFilesystemCommand,
+  scopeProtectedSearchGlob,
+} from "./shared/protected-filesystem.js";
 import {
   capLines,
   excludedGlobArgs,
@@ -24,7 +32,7 @@ const execFileAsync = promisify(execFile);
 
 /**
  * @param {{pattern: string, path?: string, glob?: string, type?: string, output_mode?: string, context?: number, case_insensitive?: boolean, multiline?: boolean, head_limit?: number, offset?: number, max_matches?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export async function grepToolImpl({
   pattern,
@@ -40,13 +48,27 @@ export async function grepToolImpl({
   max_matches,
   max_output_chars,
   workdir,
-}, { sandboxPolicy, ctx } = {}) {
+}, { sandboxPolicy, sandboxEngine, ctx } = {}) {
   const target = resolveToolPath(path || workspaceRoot(workdir, ctx), workdir, ctx);
-  if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${target}`;
-  const stat = safeStat(target);
-  if (!stat) return `Error: Path not found: ${target}`;
-  const cwd = stat.isDirectory() ? target : dirname(target);
-  const searchTarget = stat.isDirectory() ? "." : basename(target);
+  const protectedSearch = protectedFilesystemTargetPlan(target, { sandboxPolicy, ctx });
+  const protectedExecution = protectedSearch !== null;
+  if (protectedExecution) {
+    if (!isPathLexicallyAllowed(target, workdir, { sandboxPolicy, ctx })) {
+      return "Error: Protected filesystem search was denied.";
+    }
+  } else if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) {
+    return `Error: Path not allowed: ${target}`;
+  }
+  let cwd;
+  let searchTarget;
+  if (protectedExecution) {
+    ({ cwd, searchTarget } = protectedSearch);
+  } else {
+    const stat = safeStat(target);
+    if (!stat) return `Error: Path not found: ${target}`;
+    cwd = stat.isDirectory() ? target : dirname(target);
+    searchTarget = stat.isDirectory() ? "." : basename(target);
+  }
   const mode = ["content", "count", "files_with_matches"].includes(output_mode) ? output_mode : "files_with_matches";
   const args = ["--no-config", "--hidden", "--color=never"];
   if (mode === "files_with_matches") args.push("--files-with-matches");
@@ -55,15 +77,47 @@ export async function grepToolImpl({
   if (case_insensitive) args.push("-i");
   if (mode === "content" && context) args.push(`-C${boundedInt(context, 0, { min: 0, max: 20 })}`);
   if (multiline) args.push("-U", "--multiline-dotall");
-  if (glob) args.push("--glob", glob);
+  if (glob) args.push(
+    "--glob",
+    protectedExecution ? scopeProtectedSearchGlob(glob, searchTarget) : glob,
+  );
   if (type) args.push("--type", type);
-  args.push(...excludedGlobArgs(), "--", pattern, searchTarget);
+  args.push(...excludedGlobArgs());
+  const protectedPaths = protectedRelativePaths(cwd, { sandboxPolicy, ctx });
+  for (const protectedPath of protectedPaths) {
+    args.push("--glob", `!${protectedPath}`, "--glob", `!${protectedPath}/**`);
+  }
+  args.push("--", pattern, searchTarget);
   const resultLimit = boundedInt(head_limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
   const rgPath = resolveRgPath({ ctx });
   if (!rgPath) return ripgrepMissingMessage(ctx);
   try {
-    const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
-    const normalized = stdout.trim().split("\n").filter(Boolean).map((line) => line.replace(/^\.\//, ""));
+    let stdout;
+    if (!protectedExecution) {
+      ({ stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER }));
+    } else {
+      const protectedResult = await runProtectedFilesystemCommand({
+        command: rgPath,
+        args,
+        cwd,
+      }, { sandboxPolicy, sandboxEngine, ctx, maxBufferBytes: SEARCH_MAX_BUFFER });
+      if (protectedResult?.code === 1) return "No matches found.";
+      if (protectedResult === null
+        || protectedResult.code !== 0
+        || protectedResult.bufferExceeded
+        || protectedResult.timedOut) {
+        return "Error: Protected filesystem search was denied.";
+      }
+      stdout = protectedResult.stdout;
+    }
+    const normalized = stdout.trim().split("\n")
+      .filter(Boolean)
+      .filter((line) => !protectedPaths.some((path) => (
+        line === path || line.startsWith(`${path}/`) || line.startsWith(`${path}:`)
+      )))
+      .map((line) => protectedExecution
+        ? normalizeProtectedSearchLine(line, searchTarget)
+        : line.replace(/^\.\//, ""));
     const formatted = capLines(normalized.join("\n"), {
       label: "Grep",
       noMatches: "No matches found.",
@@ -74,6 +128,7 @@ export async function grepToolImpl({
     });
     return formatted === "No matches found." ? formatted : `${formatted}\n\n${excludedPathSummary()}`;
   } catch (err) {
+    if (protectedExecution) return "Error: Protected filesystem search was denied.";
     if (err.code === 1) return "No matches found.";
     if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" || /maxBuffer/i.test(err.message || "")) {
       return `${capLines(err.stdout || "", {

package/src/agent/tools/node-repl.js

@@ -254,9 +254,12 @@ async function terminateRecord(record) {
     await record.done;
     return;
   }
-  killProcessGroup(record.child, "SIGTERM");
+  killProcessGroup(record.child, "SIGTERM", { fallbackToChildPid: true });
   if (!record.killTimer) {
-    record.killTimer = setTimeout(() => killProcessGroup(record.child, "SIGKILL"), KILL_GRACE_MS);
+    record.killTimer = setTimeout(
+      () => killProcessGroup(record.child, "SIGKILL", { fallbackToChildPid: true }),
+      KILL_GRACE_MS,
+    );
     record.killTimer.unref?.();
   }
   await record.done;

package/src/agent/tools/pi-bridge.js

@@ -1,4 +1,5 @@
 import { Type } from "@earendil-works/pi-ai";
+import { randomUUID } from "node:crypto";
 import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
@@ -55,6 +56,11 @@ const DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS = 2_700_000;
 const MCP_RAW_DETAIL_LIMIT = 4_000;
 const MCP_IMAGE_INLINE_MAX_BYTES = 250_000;
 const DEFAULT_BASH_TIMEOUT_MS = 120_000;
+const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
+const MCP_APP_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+const MCP_APP_SUPPORTED_PROTOCOL_VERSIONS = ["2026-01-26", "2025-11-21"];
+const MCP_APP_RESOURCE_MAX_BYTES = 2 * 1024 * 1024;
+const PRIVATE_CAPABILITY_URL = Symbol.for("@mono-agent/private-capability-url");
 
 function objectSchema(properties, required = []) {
   return { type: "object", properties, required, additionalProperties: false };
@@ -261,7 +267,7 @@ function isStructuredToolRun(value) {
  * @param {any} description
  * @param {any} parameters
  * @param {any} execute
- * @param {{cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, forceSequential?: boolean}} [options]
+ * @param {{cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: any, forceSequential?: boolean}} [options]
  */
 function createBuiltinTool(name, label, description, parameters, execute, {
   cwd,
@@ -271,6 +277,7 @@ function createBuiltinTool(name, label, description, parameters, execute, {
   sandboxPolicy,
   sandboxEngine,
   ctx,
+  processJobsController,
   forceSequential = false,
 } = {}) {
   return {
@@ -282,12 +289,22 @@ function createBuiltinTool(name, label, description, parameters, execute, {
     async execute(toolCallId, params, signal) {
       if (signal?.aborted) throw new Error("tool execution aborted");
       const normalized = normalizePiBuiltinToolParams(name, params, { cwd, toolLimits, ctx });
+      if (processJobsController && params?.background === true && (name === "Bash" || name === "Exec")) {
+        // Foreground normalization always materializes the established default
+        // limits. A background omission instead belongs to the host's compiled
+        // process-job config, so preserve absence while still narrowing every
+        // explicitly supplied per-call value through the ordinary tool caps.
+        if (params.max_output_chars === undefined) delete normalized.max_output_chars;
+        if (params.timeout_ms === undefined && (name !== "Bash" || params.timeout === undefined)) {
+          delete normalized.timeout_ms;
+        }
+      }
       if (name === "Bash" && toolPolicy?.bashReadOnly && !isReadOnlyShellCommand(normalized.command)) {
         throw new Error("Error: Planning shell policy allows only read-only inspection commands.");
       }
       const shouldTrackWrite = name === "Write" && typeof normalized.file_path === "string" && normalized.file_path.length > 0;
       const beforeWrite = shouldTrackWrite ? readFileChangeSnapshot(normalized.file_path) : null;
-      const raw = await execute(normalized, { signal, sandboxPolicy, sandboxEngine, ctx });
+      const raw = await execute(normalized, { signal, sandboxPolicy, sandboxEngine, ctx, processJobsController });
       // Image reads (e.g. Read on a .png) come back as a structured image
       // result so vision models see pixels; emit an image content block and let
       // the shared bloat guard cap oversize payloads.
@@ -417,7 +434,7 @@ export function createStructuredOutputTool(outputSchema, onStructuredOutput) {
 
 /**
  * @param {any} allowedTools
- * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
+ * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, processJobsController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
  */
 export function getPiBuiltinTools(allowedTools, {
   disallowedTools = [],
@@ -439,6 +456,7 @@ export function getPiBuiltinTools(allowedTools, {
   approvalModel = null,
   nodeReplController = null,
   webController = null,
+  processJobsController = null,
   subagents = null,
   subagentContext = null,
   toolExecutionMode = "safe-parallel",
@@ -464,6 +482,7 @@ export function getPiBuiltinTools(allowedTools, {
     toolPolicy,
     sandboxPolicy,
     sandboxEngine,
+    processJobsController,
     forceSequential: toolExecutionMode === "sequential",
     ctx,
   };
@@ -514,6 +533,9 @@ export function getPiBuiltinTools(allowedTools, {
       timeout_ms: processTimeoutSchema,
       timeout: legacyBashTimeoutSchema,
       max_output_chars: bashLimitSchema,
+      ...(processJobsController ? {
+        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
+      } : {}),
     }, ["command"]), bashToolRun, toolContext),
     Exec: createBuiltinTool("Exec", "Exec", "Execute one program directly from an argv array without shell parsing. Prefer this for ordinary commands; use Bash only when shell syntax is required.", objectSchema({
       executable: { type: "string", minLength: 1 },
@@ -521,6 +543,9 @@ export function getPiBuiltinTools(allowedTools, {
       workdir: { type: "string" },
       timeout_ms: processTimeoutSchema,
       max_output_chars: bashLimitSchema,
+      ...(processJobsController ? {
+        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
+      } : {}),
     }, ["executable"]), execToolRun, toolContext),
     NodeRepl: nodeReplController
       ? createBuiltinTool(
@@ -618,41 +643,61 @@ export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPoli
 /**
  * @param {any} name
  * @param {any} cfg
- * @param {{cwd?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{cwd?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, mcpApps?: any}} [options]
  */
-async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine, ctx } = {}) {
+async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine, ctx, mcpApps } = {}) {
   const brand = (ctx ?? readToolRuntime()).runtimeBrand;
+  const privateCapabilityUrl = cfg?.[PRIVATE_CAPABILITY_URL] === true;
   const client = new McpClient(
     { name: `${brand.mcpClientName}/${name}`, version: brand.mcpClientVersion },
-    { capabilities: {} },
+    {
+      capabilities: mcpApps?.mimeTypes?.includes?.(MCP_APP_RESOURCE_MIME_TYPE)
+        ? {
+            extensions: {
+              [MCP_APPS_EXTENSION_ID]: {
+                mimeTypes: [MCP_APP_RESOURCE_MIME_TYPE],
+              },
+            },
+          }
+        : {},
+    },
   );
   let transport;
-  if (cfg.type === "http") {
-    transport = new StreamableHTTPClientTransport(new URL(cfg.url), { requestInit: { headers: cfg.headers || {} } });
-  } else if (cfg.type === "sse") {
-    transport = new SSEClientTransport(new URL(cfg.url), {
-      // SSE EventSourceInit's typed shape omits `headers`, but the transport
-      // forwards them to the underlying EventSource — keep the header pass-through.
-      eventSourceInit: /** @type {any} */ ({ headers: cfg.headers || {} }),
-      requestInit: { headers: cfg.headers || {} },
-    });
-  } else {
-    const prepared = await prepareMcpStdioCommand(cfg, { cwd, sandboxPolicy, sandboxEngine, ctx });
-    transport = new StdioClientTransport({
-      command: prepared.command,
-      args: prepared.args || [],
-      cwd: prepared.cwd,
-      env: { ...process.env, ...(prepared.env || {}) },
-    });
-    // Monkey-patched cleanup handle: not part of the MCP transport's typed shape.
-    /** @type {any} */ (transport).__monoSandboxCleanup = prepared.cleanup;
-  }
   try {
+    if (cfg.type === "http") {
+      transport = new StreamableHTTPClientTransport(new URL(cfg.url), { requestInit: { headers: cfg.headers || {} } });
+    } else if (cfg.type === "sse") {
+      transport = new SSEClientTransport(new URL(cfg.url), {
+        // SSE EventSourceInit's typed shape omits `headers`, but the transport
+        // forwards them to the underlying EventSource — keep the header pass-through.
+        eventSourceInit: /** @type {any} */ ({ headers: cfg.headers || {} }),
+        requestInit: { headers: cfg.headers || {} },
+      });
+    } else {
+      const prepared = await prepareMcpStdioCommand(cfg, { cwd, sandboxPolicy, sandboxEngine, ctx });
+      transport = new StdioClientTransport({
+        command: prepared.command,
+        args: prepared.args || [],
+        cwd: prepared.cwd,
+        env: { ...process.env, ...(prepared.env || {}) },
+      });
+      // Monkey-patched cleanup handle: not part of the MCP transport's typed shape.
+      /** @type {any} */ (transport).__monoSandboxCleanup = prepared.cleanup;
+    }
     await client.connect(transport);
-    return { name, client, transport };
+    return {
+      name,
+      client,
+      transport,
+      connectionId: randomUUID(),
+      retainedByMcpApps: false,
+      privateCapabilityUrl,
+      closed: false,
+    };
   } catch (error) {
     try { await transport?.close?.(); } catch { /* best-effort */ }
     try { await /** @type {any} */ (transport)?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+    if (privateCapabilityUrl) throw new Error("Private request-scoped MCP server connection failed.");
     throw error;
   }
 }
@@ -741,7 +786,7 @@ function withTimeout(promise, timeoutMs, signal, label, registerReset) {
 /**
  * @param {any} mcpConfig
  * @param {Set<any>} [reservedNames]
- * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any}} [options]
+ * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any, mcpApps?: any, runId?: string}} [options]
  */
 export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
   limits = {},
@@ -754,11 +799,19 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
   sandboxEngine = null,
   onToolProgress = null,
   ctx = null,
+  mcpApps = null,
+  runId = null,
 } = {}) {
   const clients = [];
   const tools = [];
   const entries = Object.entries(mcpConfig || {});
-  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine, ctx })));
+  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectMcpClient(name, cfg, {
+    cwd,
+    sandboxPolicy,
+    sandboxEngine,
+    ctx,
+    mcpApps,
+  })));
   const warnings = [];
   const seen = new Set(reservedNames);
 
@@ -797,7 +850,9 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
         type: "runtime_warning",
         warning_kind: "mcp_list_tools_failed",
         server: serverName,
-        message: error?.message || String(error),
+        message: connected.privateCapabilityUrl
+          ? "Private request-scoped MCP server did not expose its tools."
+          : error?.message || String(error),
       });
       continue;
     }
@@ -848,21 +903,27 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
               ...(progress?.message === undefined ? {} : { message: progress.message }),
             });
           };
+          const request = connected.client.callTool(
+            { name: sourceTool.name, arguments: normalizedParams || {} },
+            undefined,
+            // Forward the abort signal too, so a cancelled/timed-out call also cancels the
+            // in-flight MCP request on the wire (otherwise the SDK keeps awaiting until its own
+            // timeout, and an in-process loopback turn could post late after the bridge rejected).
+            {
+              timeout: mcpCallTimeoutMs,
+              resetTimeoutOnProgress: true,
+              maxTotalTimeout: mcpCallMaxTotalTimeoutMs,
+              signal,
+              onprogress,
+            },
+          ).catch((error) => {
+            if (connected.privateCapabilityUrl) {
+              throw new Error("Private request-scoped MCP tool call failed.");
+            }
+            throw error;
+          });
           const out = await withTimeout(
-            connected.client.callTool(
-              { name: sourceTool.name, arguments: normalizedParams || {} },
-              undefined,
-              // Forward the abort signal too, so a cancelled/timed-out call also cancels the
-              // in-flight MCP request on the wire (otherwise the SDK keeps awaiting until its own
-              // timeout, and an in-process loopback turn could post late after the bridge rejected).
-              {
-                timeout: mcpCallTimeoutMs,
-                resetTimeoutOnProgress: true,
-                maxTotalTimeout: mcpCallMaxTotalTimeoutMs,
-                signal,
-                onprogress,
-              },
-            ),
+            request,
             mcpCallTimeoutMs,
             signal,
             `${serverName}:${sourceTool.name}`,
@@ -871,6 +932,19 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
             },
           );
           const mcpCallDurationMs = Date.now() - mcpCallStartMs;
+          if (mcpApps) {
+            await registerMcpAppForToolResult({
+              mcpApps,
+              runId,
+              serverName,
+              connected,
+              sourceTool,
+              listedTools: listed.tools || [],
+              toolCallId,
+              toolInput: normalizedParams || {},
+              toolResult: out,
+            });
+          }
           const imageTruncations = [];
           return {
             content: coerceMcpContent(out, {
@@ -932,13 +1006,154 @@ async function closeWithTimeout(close, timeoutMs) {
   }
 }
 
+async function registerMcpAppForToolResult({
+  mcpApps,
+  runId,
+  serverName,
+  connected,
+  sourceTool,
+  listedTools,
+  toolCallId,
+  toolInput,
+  toolResult,
+}) {
+  const resourceUri = mcpAppResourceUri(sourceTool);
+  if (!resourceUri) return;
+  const fail = async (code, message) => {
+    try {
+      await mcpApps.recordFailure({
+        ...(runId ? { runId } : {}),
+        serverName,
+        toolName: sourceTool.name,
+        toolCallId,
+        code,
+        message,
+      });
+    } catch { /* A rich-part failure cannot turn a successful MCP call into a failed tool. */ }
+  };
+
+  if (!resourceUri.startsWith("ui://")) {
+    await fail("app_resource_invalid", "The MCP App resource URI is invalid.");
+    return;
+  }
+  const hostVersions = Array.isArray(mcpApps.protocolVersions)
+    ? mcpApps.protocolVersions.filter((value) => typeof value === "string")
+    : [];
+  const protocolVersion = MCP_APP_SUPPORTED_PROTOCOL_VERSIONS.find((version) => hostVersions.includes(version));
+  const hostMimeTypes = Array.isArray(mcpApps.mimeTypes)
+    ? mcpApps.mimeTypes.filter((value) => typeof value === "string")
+    : [];
+  if (
+    !protocolVersion
+    || !hostMimeTypes.includes(MCP_APP_RESOURCE_MIME_TYPE)
+  ) {
+    await fail("app_capability_mismatch", "The MCP App protocol or resource MIME type is incompatible with this host.");
+    return;
+  }
+
+  let resource;
+  try {
+    const response = await connected.client.readResource({ uri: resourceUri });
+    resource = selectMcpAppResource(response, resourceUri);
+  } catch {
+    await fail("app_resource_invalid", "The MCP App resource could not be resolved through its originating connection.");
+    return;
+  }
+  if (!resource) {
+    await fail("app_resource_invalid", "The MCP App resource is missing, oversized, or has an incompatible MIME type.");
+    return;
+  }
+
+  const connection = {
+    connectionId: connected.connectionId,
+    readResource: async (uri) => await connected.client.readResource({ uri }),
+    callTool: async (name, args, signal) => await connected.client.callTool(
+      { name, arguments: args && typeof args === "object" && !Array.isArray(args) ? args : {} },
+      undefined,
+      {
+        timeout: 120_000,
+        maxTotalTimeout: 120_000,
+        ...(signal ? { signal } : {}),
+      },
+    ),
+    close: async () => {
+      connected.retainedByMcpApps = false;
+      await closeConnectedMcpClient(connected, 5_000);
+    },
+  };
+  try {
+    const registered = await mcpApps.register({
+      ...(runId ? { runId } : {}),
+      serverName,
+      toolName: sourceTool.name,
+      ...(typeof sourceTool.title === "string" ? { title: sourceTool.title } : {}),
+      ...(typeof sourceTool.description === "string" ? { description: sourceTool.description } : {}),
+      toolCallId,
+      resourceUri,
+      protocolVersion,
+      toolInput,
+      toolResult,
+      resource,
+      appVisibleTools: listedTools
+        .filter((tool) => mcpToolVisibleToApp(tool))
+        .map((tool) => tool.name),
+      connection,
+    });
+    if (registered?.retainConnection === true && registered.part?.type === "mcp_app") {
+      connected.retainedByMcpApps = true;
+    }
+  } catch {
+    await fail("app_resource_invalid", "The MCP App host could not persist the negotiated resource.");
+  }
+}
+
+function mcpAppResourceUri(tool) {
+  const meta = tool?._meta || tool?.meta;
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+  if (meta.ui && typeof meta.ui === "object" && !Array.isArray(meta.ui)
+    && typeof meta.ui.resourceUri === "string") return meta.ui.resourceUri;
+  return typeof meta["ui/resourceUri"] === "string" ? meta["ui/resourceUri"] : null;
+}
+
+function mcpToolVisibleToApp(tool) {
+  const meta = tool?._meta || tool?.meta;
+  const visibility = meta?.ui?.visibility;
+  return !Array.isArray(visibility) || visibility.includes("app");
+}
+
+function selectMcpAppResource(response, resourceUri) {
+  const content = Array.isArray(response?.contents)
+    ? response.contents.find((entry) => entry?.uri === resourceUri)
+    : null;
+  if (!content || typeof content.text !== "string") return null;
+  const mimeType = content.mimeType || content.mime_type;
+  if (mimeType !== MCP_APP_RESOURCE_MIME_TYPE) return null;
+  if (Buffer.byteLength(content.text, "utf8") > MCP_APP_RESOURCE_MAX_BYTES) return null;
+  return {
+    uri: resourceUri,
+    mimeType,
+    text: content.text,
+    ...(content._meta && typeof content._meta === "object" && !Array.isArray(content._meta)
+      ? { _meta: content._meta }
+      : {}),
+  };
+}
+
+async function closeConnectedMcpClient(connected, timeoutMs) {
+  if (!connected || connected.closed === true) return;
+  connected.closed = true;
+  const { client, transport } = connected;
+  try { await closeWithTimeout(client?.close?.bind(client), timeoutMs); } catch { /* best-effort */ }
+  try { await closeWithTimeout(transport?.close?.bind(transport), timeoutMs); } catch { /* best-effort */ }
+  try { await transport?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+}
+
 export async function closePiMcpClients(clients, { timeoutMs = 5000 } = {}) {
   // Close the client first (stop accepting messages) then the transport (tear
   // down I/O), each bounded by a timeout so a hung stdio pipe cannot stall
   // shutdown — a common source of "Connection closed" churn on reconnect.
-  await Promise.all((clients || []).map(async ({ client, transport }) => {
-    try { await closeWithTimeout(client?.close?.bind(client), timeoutMs); } catch { /* best-effort */ }
-    try { await closeWithTimeout(transport?.close?.bind(transport), timeoutMs); } catch { /* best-effort */ }
-    try { await transport?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+  await Promise.all((clients || []).map(async (connected) => {
+    if (connected?.retainedByMcpApps === true) return;
+    await closeConnectedMcpClient(connected, timeoutMs);
   }));
 }

package/src/agent/tools/read.js

@@ -9,7 +9,16 @@ import {
 } from "./shared/constants.js";
 import { boundedInt, rememberRead, trimLine } from "./shared/dedup.js";
 import { capChars } from "./shared/output-truncation.js";
-import { isPathAllowed, resolveToolPath } from "./shared/path-resolver.js";
+import {
+  isPathAllowed,
+  isPathLexicallyAllowed,
+  resolveToolPath,
+} from "./shared/path-resolver.js";
+import {
+  protectedCommandSucceeded,
+  protectedFilesystemTargetPlan,
+  runProtectedFilesystemCommand,
+} from "./shared/protected-filesystem.js";
 
 // Raster image formats a vision model can consume directly. SVG is intentionally
 // excluded — it is XML text, so it stays on the line-numbered text path.
@@ -33,14 +42,19 @@ const OUTPUT_MIME_BY_FORMAT = {
   gif: "image/gif",
   webp: "image/webp",
 };
+const PROTECTED_READ_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+const PROTECTED_READ_SOURCE = String.raw`
+"use strict";
+const { readFileSync } = require("node:fs");
+process.stdout.write(readFileSync(process.argv[1]).toString("base64"));
+`;
 
 /**
- * @param {string} target
+ * @param {Buffer} source
  * @param {string} filePath
  * @param {string} imageMime
  */
-async function readImageForModel(target, filePath, imageMime) {
-  const source = readFileSync(target);
+async function readImageForModel(source, filePath, imageMime) {
   const inputOptions = { animated: ANIMATED_IMAGE_MIME_TYPES.has(imageMime) };
 
   try {
@@ -100,23 +114,49 @@ async function readImageForModel(target, filePath, imageMime) {
 
 /**
  * @param {{file_path: string, offset?: number, start_line?: number, limit?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
-export async function readToolImpl({ file_path, offset = 0, start_line, limit, max_output_chars, workdir }, { sandboxPolicy, ctx } = {}) {
+export async function readToolImpl({ file_path, offset = 0, start_line, limit, max_output_chars, workdir }, { sandboxPolicy, sandboxEngine, ctx } = {}) {
   const target = resolveToolPath(file_path, workdir, ctx);
-  if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${file_path}`;
-  if (!existsSync(target)) return `Error: File not found: ${file_path}`;
+  const protectedTarget = protectedFilesystemTargetPlan(target, { sandboxPolicy, ctx });
+  const protectedExecution = protectedTarget !== null;
+  if (protectedExecution) {
+    if (!isPathLexicallyAllowed(target, workdir, { sandboxPolicy, ctx })) {
+      return "Error: Protected filesystem read was denied.";
+    }
+  } else if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) {
+    return `Error: Path not allowed: ${file_path}`;
+  }
+  if (!protectedExecution && !existsSync(target)) return `Error: File not found: ${file_path}`;
+  let source;
+  try {
+    if (protectedExecution) {
+      const protectedResult = await runProtectedFilesystemCommand({
+        command: process.execPath,
+        args: ["--input-type=commonjs", "--eval", PROTECTED_READ_SOURCE, target],
+        cwd: protectedTarget.cwd,
+      }, { sandboxPolicy, sandboxEngine, ctx, maxBufferBytes: PROTECTED_READ_MAX_BUFFER_BYTES });
+      if (!protectedCommandSucceeded(protectedResult)) {
+        return "Error: Protected filesystem read was denied.";
+      }
+      source = Buffer.from(protectedResult.stdout, "base64");
+    } else {
+      source = readFileSync(target);
+    }
+  } catch {
+    return "Error: Protected filesystem read was denied.";
+  }
   // Image files are returned as an image result so vision models see pixels
   // rather than the raw bytes decoded (and garbled) as utf8 text. The builtin
   // tool wrapper turns this into an image content block; oversize images are
   // capped by the shared tool-result bloat guard.
   const imageMime = IMAGE_MIME_BY_EXT[extname(target).toLowerCase()];
   if (imageMime !== undefined) {
-    const image = await readImageForModel(target, file_path, imageMime);
+    const image = await readImageForModel(source, file_path, imageMime);
     if (image.error !== undefined) return image.error;
     return { kind: "image", data: image.data.toString("base64"), mimeType: image.mimeType };
   }
-  const content = readFileSync(target, "utf8");
+  const content = source.toString("utf8");
   let lines = content.split("\n");
   const total = lines.length;
   const explicitStartLine = Number(start_line);