fix: ignore tools.exec.pathPrepend for node hosts

docs/cli/nodes.md

@@ -64,7 +64,7 @@ Invoke flags:
 Flags:
 
 - `--cwd <path>`: working directory.
-- `--env <key=val>`: env override (repeatable). Note: node hosts ignore `PATH` overrides.
+- `--env <key=val>`: env override (repeatable). Note: node hosts ignore `PATH` overrides (and `tools.exec.pathPrepend` is not applied to node hosts).
 - `--command-timeout <ms>`: command timeout.
 - `--invoke-timeout <ms>`: node invoke timeout (default `30000`).
 - `--needs-screen-recording`: require screen recording permission.

docs/tools/exec.md

@@ -50,7 +50,7 @@ Notes:
 - `tools.exec.security` (default: `deny` for sandbox, `allowlist` for gateway + node when unset)
 - `tools.exec.ask` (default: `on-miss`)
 - `tools.exec.node` (default: unset)
-- `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs.
+- `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs (gateway + sandbox only).
 - `tools.exec.safeBins`: stdin-only safe binaries that can run without explicit allowlist entries.
 
 Example:

src/agents/bash-tools.exec.ts

@@ -316,7 +316,16 @@ export function createExecTool(
         });
         applyShellPath(env, shellPath);
       }
-      applyPathPrepend(env, defaultPathPrepend);
+
+      // `tools.exec.pathPrepend` is only meaningful when exec runs locally (gateway) or in the sandbox.
+      // Node hosts intentionally ignore request-scoped PATH overrides, so don't pretend this applies.
+      if (host === "node" && defaultPathPrepend.length > 0) {
+        warnings.push(
+          "Warning: tools.exec.pathPrepend is ignored for host=node. Configure PATH on the node host/service instead.",
+        );
+      } else {
+        applyPathPrepend(env, defaultPathPrepend);
+      }
 
       if (host === "node") {
         const approvals = resolveExecApprovals(agentId, { security, ask });
@@ -362,10 +371,6 @@ export function createExecTool(
         const argv = buildNodeShellCommand(params.command, nodeInfo?.platform);
 
         const nodeEnv = params.env ? { ...params.env } : undefined;
-
-        if (nodeEnv) {
-          applyPathPrepend(nodeEnv, defaultPathPrepend, { requireExisting: true });
-        }
         const baseAllowlistEval = evaluateShellAllowlist({
           command: params.command,
           allowlist: [],