@mono-agent/agent-runtime 0.19.1 → 0.20.0

package/MIGRATION.md

@@ -490,7 +490,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.19.x` package contract. Keep
+This guide describes the published `0.20.x` package contract. Keep
 `@mono-agent/agent-runtime`, `@mono-agent/runtime-adapter`, and other
 `@mono-agent/*` packages on the same lockstep version when upgrading. The paired
 runtime adapter no longer exposes `piReasoningSummary` in its run-options type.

package/README.md

@@ -53,6 +53,18 @@ console.log(result.text);
 `Glob` and `Grep` prefer the packaged `@vscode/ripgrep` binary on supported
 platforms. An explicit `ripgrepPath` wins, with `PATH` as the final fallback.
 
+### Pi-native MCP Apps bridge
+
+Only the Pi-native bridge declares `supports_mcp_apps`. When a host supplies an
+MCP Apps registry, the MCP client advertises the standard ext-apps UI MIME
+capability. The host then explicitly intersects the two reviewed protocol
+revisions, reads only the originating tool's declared `ui://` resource, and
+receives one exact connection capability. Successful registration retains that
+existing MCP client instead of creating a client per UI call; host LRU/idle
+eviction closes the client, transport, and sandbox cleanup. Other runtime
+backends do not advertise or receive this extension.
+See [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/).
+
 ## Architecture
 
 The package uses a fixed registry of bridge descriptors and loads provider code
@@ -64,10 +76,14 @@ only after a run selects a matching model reference and execution mode:
 2. `resolveRuntimeBridge()` checks the six static bridge descriptors in order.
 3. The selected descriptor lazily imports its provider implementation.
 4. The bridge prepares the runtime inputs it supports, including managed or MCP
-   tools only where that bridge can represent them, streams normalized events,
-   and returns a provider-neutral `RuntimeResult`.
-5. The host validates any domain-specific result and owns persistence or UI
-   effects.
+   tools only where that bridge can represent them, and streams normalized
+   events through the lifecycle gate.
+5. For each managed-tool start/result, the gate awaits the host's incremental
+   persistence sink before publishing the same block with history metadata to
+   the client; provider events remain deterministically ordered even for
+   parallel tools.
+6. The bridge returns a provider-neutral `RuntimeResult`; the host owns storage,
+   recovery, and UI effects.
 
 ### Package structure
 
@@ -82,6 +98,58 @@ only after a run selects a matching model reference and execution mode:
 The detailed lifecycle, provider-session differences, and host boundary are in
 the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md).
 
+### Managed-tool lifecycle fidelity
+
+`RuntimeRunOptions.toolLifecycleSink` is an awaited host-owned boundary. The
+runtime sends redaction-eligible raw arguments/content plus stable provider call
+id and name; the host returns only record/sequence, persistence/truncation byte
+metadata, and opaque artifact references. That returned metadata is attached to
+the exact normalized `tool_use` / `tool_result` event rendered by clients. Sink
+failure is fail-soft and explicit (`persistence: "failed"` plus an error code),
+never fake success. A callback exception cannot duplicate a client event.
+
+Provider bridges only claim terminal distinctions their structured protocol
+actually supplies:
+
+| Bridge | Genuine tool-result distinctions | Conservative fallback |
+| --- | --- | --- |
+| Pi native | `success`, `error`, numeric `exit_nonzero`, structured `timeout`, structured `signal`, and abort-backed `cancelled`; host approval denial/expiry adds `rejected`/`timeout` | Unknown failed outcome → `error` |
+| Codex app-server | `success`, `error`, and numeric command `exit_nonzero`; shared host abort rules still apply | Other failed item → `error`; no result before run end remains dangling for host closure/recovery |
+| Claude SDK | `success` / `error`; shared host approval events can add `rejected`/`timeout` and an aborted error result can add `cancelled` | Undistinguished failed result → `error` |
+| Claude Code CLI | `success` / `error`; a Codex-shaped command item with an explicit non-zero code is `exit_nonzero`; shared approval/abort rules still apply | Undistinguished failed result → `error` |
+| OpenCode app-server | `success` / `error`; shared approval/abort rules still apply | Undistinguished failed result → `error` |
+| ACP v1 | `completed` → `success`, `failed` → `error`; shared approval/abort rules still apply | ACP exposes no tool-level signal/exit/timeout distinction, so failed → `error` |
+
+The runtime never derives a state from result prose. Structured timeout, signal,
+non-zero exit, completed success, and a specific non-runtime, non-cancellation
+provider failure win over a later outer abort. For a failed result with an
+aborted outer signal, cancellation wins over a provider bridge's otherwise
+generic `error` / `runtime_error` fallback. Whenever that outer abort determines
+the result—including when the bridge supplied a trusted `cancelled` hint—the
+failure kind comes only from host abort provenance: the cross-package own
+data-property brand `channelUserCancel === true` maps to `cancelled_user`; every
+unbranded reason maps to generic `cancelled`. Accessors, Proxies, inherited or
+brand-shaped impostors, error prose, class/channel names, reason `kind` or `code`
+strings, and raw provider result data never select host provenance.
+Without an outer abort, a trusted `cancelled` hint retains a known cancellation
+failure kind and otherwise falls back to `cancelled`.
+
+This outer-abort rule matches the harness run-level classifier. The standalone
+runtime keeps its zero-`@mono-agent/*` dependency boundary by recognizing the
+shared brand structurally rather than importing `@mono-agent/agent-contracts`.
+Its deliberate extra fidelity is tool-level only: a trusted bridge hint can
+retain a cancellation subtype when no outer abort exists. The run-level harness
+has no corresponding tool hint, so this does not widen a shared core contract.
+A started call with no result is closed by the harness as `cancelled`, `error`,
+or `interrupted` from the run boundary; process-startup recovery specifically
+uses `interrupted` and does not rerun the tool.
+
+Terminal states reuse the observability taxonomy: `success` has no failure kind;
+`signal` and `interrupted` map to `process_death`; `cancelled` preserves a known
+`cancelled`, `cancelled_user`, `cancelled_stale`, `cancelled_shutdown`, or
+`cancelled_signal`; `rejected`, `error`, `exit_nonzero`, and `timeout` use a
+provider-supplied known kind when available and otherwise `runtime_error`.
+
 ## Public API
 
 ### Start here
@@ -753,6 +821,7 @@ Per-call options (a non-exhaustive selection):
 | `nativeSubagents` | `object` | Caller-defined Claude native `Task` profiles. Direct Codex rejects configured teammate definitions because Codex owns its collaboration agents. |
 | `settingSources` | `("user" \| "project" \| "local")[]` | Claude Agent SDK filesystem settings opt-in. Omitted/empty disables those three sources; Anthropic managed settings still apply. |
 | `codexLoadProjectDocs` | `boolean` | Codex app-server repository-instruction opt-in. Omitted/false sets `project_doc_max_bytes=0`; true restores Codex defaults. Explicit `codexAppServerArgs` wins. |
+| `codexSandboxNetworkAccess` | `boolean` | Code-only Codex app-server per-turn network control. Only strict `true` enables it for plan/default/acceptEdits; omitted or any other value disables it. |
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http); on direct Codex, each forwarded server authorizes its own tool calls. |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
 | `webSearchConfig` | `{ backend?, endpoint? }` | Run-scoped local SearXNG/keyless WebSearch backend selection. |
@@ -818,6 +887,15 @@ Codex and its own collaboration agents should load repository instructions. If
 `codexAppServerArgs` is supplied, that explicit argument vector is authoritative
 and `codexLoadProjectDocs` does not alter it.
 
+`codexSandboxNetworkAccess` is a separate code-only, provider-native control.
+It is unrelated to `RuntimeRunOptions.sandboxPolicy`, which controls
+mono-agent's own sandbox and is not consumed by Codex's provider-owned tool
+loop. Only strict `true` enables network access for plan/read-only and
+default/acceptEdits/workspace-write turns; the no-tools probe remains offline
+and bypass remains danger-full-access. Combining workspace-write with network
+access grants repository read and network egress in the same turn. Prefer
+`permissionMode: "plan"` when only read-only browsing is needed.
+
 Provider-native and in-process delegation share `subagent_activity` telemetry.
 `subagent.id` is the canonical parent attachment key: the initiating parent
 tool-use id whenever the provider exposes it, or a stable synthetic key for an
@@ -907,6 +985,17 @@ by one lazily started Node.js REPL child per run. You select them via
 - The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
 - Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
 
+The Pi-native tool context may structurally receive a host process-job
+controller. Only then do Exec and Bash add optional `background`; with no
+controller their schemas and foreground path are unchanged. A background call
+hands the exact prepared command to the controller and stops awaiting it. The
+kernel first creates a command-agnostic detached POSIX group leader; only after
+the host durably records its PID, equal PGID, and process incarnation does the
+kernel release the exact target over an anonymous pipe. The kernel also owns
+whole-tree completion, while the host owns durable policy, persistence, wake
+delivery, and operator state. The kernel intentionally imports no workspace
+contract package for this boundary.
+
 `NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Exec`/`Bash` and communicates through token-authenticated, length-prefixed JSON frames on ordinary stdin/stdout; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
 
 `WebSearch` uses a configured loopback SearXNG endpoint and/or deterministic
@@ -987,6 +1076,12 @@ Behaviour:
 - Chain exhausted → `failureKind: "provider_unavailable_exhausted"`, `failoverHistory` lists every attempt.
 - `uniform` safety keeps the shared monotonic runtime; `per-route-native` isolates
   route runtimes and records each bounded safety contract/status.
+- A `per-route-native` non-Pi route cannot project non-empty internal
+  `sandboxPolicy.protectedRoots`; the router records `safety_unavailable` and
+  advances before route resolution or provider invocation. Empty protected-root
+  sets preserve ordinary provider-native behavior, while Pi routes retain the
+  policy. The same invariant covers model routes reached through `Agent`
+  children.
 - Pi route telemetry distinguishes `disabled`, fail-closed `mono-agent-srt`,
   and `mono-agent-srt-unsafe-host-fallback`; the last describes a configured
   policy that prefers SRT but permits host execution, not which branch ran.
@@ -1198,6 +1293,8 @@ runtime fails closed.
   shows the code-only host hooks.
 - [Local-first web research](https://mono-agent-docs.vercel.app/tools/web-research/)
   documents SearXNG, extraction, retry, browser isolation, and sandbox policy.
+- [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
+  documents the host bridge, browser sandbox, and lifecycle limits.
 - [Architecture](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md)
   and [migration guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/MIGRATION.md)
   cover internal flow and upgrades from `0.3.x`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/sandbox-seam.js

@@ -48,12 +48,20 @@
  * @property {string} command
  * @property {ReadonlyArray<string>} [args]
  * @property {string} [cwd]
- * @property {Object<string, string|undefined>} [env]
+ * @property {Record<string, string|undefined>} [env]
  * @property {boolean} [allowLocalBinding] Trusted per-command capability.
  */
 
 /**
- * @typedef {SandboxCommandSpec & {sandboxed: boolean, cleanup?: () => Promise<void>}} PreparedSandboxCommand
+ * @typedef {Object} PreparedSandboxCommand
+ * @property {string} command
+ * @property {ReadonlyArray<string>} args
+ * @property {string} cwd
+ * @property {Record<string, string|undefined>} [env]
+ * @property {boolean} [allowLocalBinding]
+ * @property {boolean} sandboxed
+ * @property {string} [sandboxSettingsPath]
+ * @property {() => Promise<void>} [cleanup]
  */
 
 /**
@@ -77,6 +85,7 @@
  * @property {SandboxNetworkPolicyLike} [network]
  * @property {ReadonlyArray<string>} [readableRoots]
  * @property {ReadonlyArray<string>} [writableRoots]
+ * @property {ReadonlyArray<string>} [protectedRoots] Host-internal roots denied for both reads and writes.
  * @property {ReadonlyArray<string>} [denyWrite]
  * @property {string} [root]
  */
@@ -173,11 +182,16 @@ function mergePolicies(configured, request) {
   const configuredIsReal = isRealSandboxMode(configured.mode);
   const requestIsReal = isRealSandboxMode(request.mode);
   const mode = configuredIsReal ? configured.mode : (requestIsReal ? request.mode : (request.mode ?? configured.mode));
+  const protectedRoots = [...new Set([
+    ...(configured.protectedRoots ?? []),
+    ...(request.protectedRoots ?? []),
+  ])].sort();
   return {
     ...configured,
     ...request,
     mode,
     network: mergeNetwork(configured.network, request.network),
+    protectedRoots,
   };
 }
 

package/src/agent/tools/bash.js

@@ -14,6 +14,7 @@ import {
   DEFAULT_PROCESS_BUFFER_BYTES,
   runPreparedProcess,
 } from "./shared/process-runner.js";
+import { handOffProcessJob } from "./shared/process-jobs.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
@@ -56,8 +57,8 @@ export function normalizeProcessTimeoutMs(value, fallback = DEFAULT_BASH_TIMEOUT
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: 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 = {}) {
   return (await bashToolRun(params, options)).text;
@@ -66,8 +67,8 @@ export async function bashToolImpl(params, options = {}) {
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export async function bashToolRun(
   {
@@ -76,12 +77,14 @@ export async function bashToolRun(
     timeout_ms,
     max_output_chars,
     workdir,
+    background,
   },
   {
     signal,
     sandboxPolicy,
     sandboxEngine,
     ctx,
+    processJobsController,
   } = {},
 ) {
   const startedAt = Date.now();
@@ -127,6 +130,25 @@ export async function bashToolRun(
     return failed(`Error: ${error?.message || String(error)}`, "sandbox_prepare_failed", startedAt);
   }
 
+  if (background === true && processJobsController) {
+    const requestedTimeoutMs = timeout_ms !== undefined
+      ? timeoutMs
+      : (timeout === undefined ? undefined : timeoutMs);
+    const handedOff = await handOffProcessJob({
+      controller: processJobsController,
+      tool: "Bash",
+      prepared,
+      summary: `Bash command (${command.length} characters; content redacted)`,
+      timeoutMs: requestedTimeoutMs,
+      maxOutputChars: max_output_chars === undefined ? undefined : maxChars,
+      startedAt,
+      failed,
+    });
+    return handedOff.error || !legacyTimeoutUsed
+      ? handedOff
+      : { ...handedOff, outcome: { ...handedOff.outcome, legacyTimeoutUsed: true } };
+  }
+
   let result;
   let cleanupError;
   try {

package/src/agent/tools/edit.js

@@ -1,15 +1,82 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { isPathAllowed, isWritablePathAllowed, resolveToolPath } from "./shared/path-resolver.js";
+import {
+  isPathAllowed,
+  isPathLexicallyAllowed,
+  isWritablePathAllowed,
+  isWritablePathLexicallyAllowed,
+  resolveToolPath,
+} from "./shared/path-resolver.js";
+import {
+  protectedCommandSucceeded,
+  protectedFilesystemTargetPlan,
+  runProtectedFilesystemCommand,
+} from "./shared/protected-filesystem.js";
+
+const PROTECTED_EDIT_SOURCE = String.raw`
+"use strict";
+const { readFileSync, writeFileSync } = require("node:fs");
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  const request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  const content = readFileSync(process.argv[1], "utf8");
+  const count = content.split(request.oldString).length - 1;
+  if (count === 0) return process.stdout.write(JSON.stringify({ status: "missing", count }));
+  if (!request.replaceAll && count > 1) return process.stdout.write(JSON.stringify({ status: "ambiguous", count }));
+  writeFileSync(
+    process.argv[1],
+    request.replaceAll
+      ? content.replaceAll(request.oldString, request.newString)
+      : content.replace(request.oldString, request.newString),
+    "utf8",
+  );
+  process.stdout.write(JSON.stringify({ status: "edited", count }));
+});
+`;
 
 /**
  * @param {{file_path: string, old_string: string, new_string: string, replace_all?: boolean, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
-export async function editToolImpl({ file_path, old_string, new_string, replace_all = false, workdir }, { sandboxPolicy, ctx } = {}) {
+export async function editToolImpl({ file_path, old_string, new_string, replace_all = false, workdir }, { sandboxPolicy, sandboxEngine, ctx } = {}) {
   const target = resolveToolPath(file_path, workdir, ctx);
   const pathOptions = { sandboxPolicy, ctx };
-  if (!isPathAllowed(target, workdir, pathOptions) || !isWritablePathAllowed(target, workdir, pathOptions)) 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, pathOptions)
+      || !isWritablePathLexicallyAllowed(target, workdir, pathOptions)) {
+      return "Error: Protected filesystem edit was denied.";
+    }
+  } else if (!isPathAllowed(target, workdir, pathOptions)
+    || !isWritablePathAllowed(target, workdir, pathOptions)) {
+    return `Error: Path not allowed: ${file_path}`;
+  }
+  if (!protectedExecution && !existsSync(target)) return `Error: File not found: ${file_path}`;
+  if (protectedExecution) {
+    try {
+      const protectedResult = await runProtectedFilesystemCommand({
+        command: process.execPath,
+        args: ["--input-type=commonjs", "--eval", PROTECTED_EDIT_SOURCE, target],
+        cwd: protectedTarget.cwd,
+      }, {
+        sandboxPolicy,
+        sandboxEngine,
+        ctx,
+        input: JSON.stringify({ oldString: old_string, newString: new_string, replaceAll: replace_all }),
+      });
+      if (!protectedCommandSucceeded(protectedResult)) {
+        return "Error: Protected filesystem edit was denied.";
+      }
+      const result = JSON.parse(protectedResult.stdout);
+      if (result.status === "missing") return `Error: old_string not found in ${target}`;
+      if (result.status === "ambiguous") return `Error: old_string found ${result.count} times`;
+      if (result.status !== "edited") return "Error: Protected filesystem edit was denied.";
+      return `Successfully edited ${target}`;
+    } catch {
+      return "Error: Protected filesystem edit was denied.";
+    }
+  }
   const content = readFileSync(target, "utf8");
   const count = content.split(old_string).length - 1;
   if (count === 0) return `Error: old_string not found in ${target}`;

package/src/agent/tools/exec.js

@@ -15,15 +15,18 @@ import {
   DEFAULT_PROCESS_BUFFER_BYTES,
   runPreparedProcess,
 } from "./shared/process-runner.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_EXEC_TIMEOUT_MS = 120_000;
 const MAX_EXEC_ARGS = 256;
 
+/** @typedef {import("./shared/process-jobs.js").ProcessJobsController} ProcessJobsController */
+
 /**
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export async function execToolImpl(params, options = {}) {
   return (await execToolRun(params, options)).text;
@@ -32,8 +35,8 @@ export async function execToolImpl(params, options = {}) {
 /**
  * Execute an argv vector directly, without shell parsing.
  *
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export async function execToolRun(
   {
@@ -42,12 +45,14 @@ export async function execToolRun(
     workdir,
     timeout_ms,
     max_output_chars,
+    background,
   },
   {
     signal,
     sandboxPolicy,
     sandboxEngine,
     ctx,
+    processJobsController,
   } = {},
 ) {
   const startedAt = Date.now();
@@ -90,6 +95,19 @@ export async function execToolRun(
     return failed(`Error: ${error?.message || String(error)}`, "sandbox_prepare_failed", startedAt);
   }
 
+  if (background === true && processJobsController) {
+    return handOffProcessJob({
+      controller: processJobsController,
+      tool: "Exec",
+      prepared,
+      summary: `Exec command (${args.length} argument${args.length === 1 ? "" : "s"}; values redacted)`,
+      timeoutMs: timeout_ms === undefined ? undefined : timeoutMs,
+      maxOutputChars: max_output_chars === undefined ? undefined : maxChars,
+      startedAt,
+      failed,
+    });
+  }
+
   let result;
   let cleanupError;
   try {

package/src/agent/tools/glob.js

@@ -9,9 +9,18 @@ import {
 import { boundedInt, safeStat } from "./shared/dedup.js";
 import {
   isPathAllowed,
+  isPathLexicallyAllowed,
+  protectedRelativePaths,
   resolveToolPath,
   workspaceRoot,
 } from "./shared/path-resolver.js";
+import {
+  normalizeProtectedSearchLine,
+  protectedDirectorySearchTarget,
+  protectedFilesystemTargetPlan,
+  runProtectedFilesystemCommand,
+  scopeProtectedSearchGlob,
+} from "./shared/protected-filesystem.js";
 import {
   capLines,
   excludedGlobArgs,
@@ -26,31 +35,77 @@ const execFileAsync = promisify(execFile);
 
 /**
  * @param {{pattern: string, path?: string, 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 globToolImpl({ pattern, path, limit, offset = 0, max_matches, max_output_chars, workdir }, { sandboxPolicy, ctx } = {}) {
+export async function globToolImpl({ pattern, path, limit, offset = 0, max_matches, max_output_chars, workdir }, { sandboxPolicy, sandboxEngine, ctx } = {}) {
   const cwd = resolveToolPath(path || workspaceRoot(workdir, ctx), workdir, ctx);
-  if (!isPathAllowed(cwd, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${cwd}`;
-  const stat = safeStat(cwd);
-  if (!stat?.isDirectory()) return `Error: Glob path is not a directory: ${cwd}`;
+  const protectedSearch = protectedFilesystemTargetPlan(cwd, { sandboxPolicy, ctx });
+  const protectedExecution = protectedSearch !== null;
+  if (protectedExecution) {
+    if (!isPathLexicallyAllowed(cwd, workdir, { sandboxPolicy, ctx })) {
+      return "Error: Protected filesystem search was denied.";
+    }
+  } else if (!isPathAllowed(cwd, workdir, { sandboxPolicy, ctx })) {
+    return `Error: Path not allowed: ${cwd}`;
+  }
+  if (!protectedExecution) {
+    const stat = safeStat(cwd);
+    if (!stat?.isDirectory()) return `Error: Glob path is not a directory: ${cwd}`;
+  }
   const resultLimit = boundedInt(limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
+  const normalizedPattern = normalizeGlobPattern(pattern);
   const args = [
     "--files",
     "--hidden",
     "--color=never",
     "--glob",
-    normalizeGlobPattern(pattern),
+    protectedExecution
+      ? scopeProtectedSearchGlob(normalizedPattern, protectedSearch.searchTarget)
+      : normalizedPattern,
     ...excludedGlobArgs(),
   ];
+  const searchCwd = protectedSearch?.cwd ?? cwd;
+  const protectedPaths = protectedRelativePaths(searchCwd, { sandboxPolicy, ctx });
+  for (const protectedPath of protectedPaths) {
+    args.push("--glob", `!${protectedPath}`, "--glob", `!${protectedPath}/**`);
+  }
+  if (protectedExecution) args.push("--", protectedDirectorySearchTarget(protectedSearch.searchTarget));
   const rgPath = resolveRgPath({ ctx });
   if (!rgPath) return ripgrepMissingMessage(ctx);
   try {
-    const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
-    const lines = stdout.trim().split("\n").filter(Boolean).sort((a, b) => {
+    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: searchCwd,
+      }, { sandboxPolicy, sandboxEngine, ctx, maxBufferBytes: SEARCH_MAX_BUFFER });
+      if (protectedResult?.code === 1) return "No files found matching pattern.";
+      if (protectedResult === null
+        || protectedResult.code !== 0
+        || protectedResult.bufferExceeded
+        || protectedResult.timedOut) {
+        return "Error: Protected filesystem search was denied.";
+      }
+      stdout = protectedResult.stdout;
+    }
+    const lines = stdout.trim().split("\n")
+      .filter(Boolean)
+      .filter((line) => !protectedPaths.some((path) => line === path || line.startsWith(`${path}/`)))
+      .map((line) => protectedExecution
+        ? normalizeProtectedSearchLine(line, protectedSearch.searchTarget)
+        : line)
+      .sort((a, b) => {
+      // Do not follow a model-controlled output symlink on the host merely to
+      // rank results: with protected roots active, the actual search already
+      // crossed SRT and lexical ordering avoids a post-search metadata race.
+      if (protectedExecution) return a.localeCompare(b);
       const aStat = safeStat(resolve(cwd, a));
       const bStat = safeStat(resolve(cwd, b));
       return (bStat?.mtimeMs || 0) - (aStat?.mtimeMs || 0) || a.localeCompare(b);
-    });
+      });
     const result = formatSearchLines(lines, {
       label: "Glob",
       noMatches: "No files found matching pattern.",
@@ -61,6 +116,7 @@ export async function globToolImpl({ pattern, path, limit, offset = 0, max_match
     });
     return result === "No files found matching pattern." ? result : `${result}\n\n${excludedPathSummary()}`;
   } catch (err) {
+    if (protectedExecution) return "Error: Protected filesystem search was denied.";
     if (err.code === 1) return "No files found matching pattern.";
     if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" || /maxBuffer/i.test(err.message || "")) {
       return `${capLines(err.stdout || "", {