diff --git a/docs/cli/nodes.md b/docs/cli/nodes.md index 547b40e4f..59c8a342d 100644 --- a/docs/cli/nodes.md +++ b/docs/cli/nodes.md @@ -64,7 +64,7 @@ Invoke flags: Flags: - `--cwd `: working directory. -- `--env `: env override (repeatable). Note: node hosts ignore `PATH` overrides. +- `--env `: env override (repeatable). Note: node hosts ignore `PATH` overrides (and `tools.exec.pathPrepend` is not applied to node hosts). - `--command-timeout `: command timeout. - `--invoke-timeout `: node invoke timeout (default `30000`). - `--needs-screen-recording`: require screen recording permission. diff --git a/docs/tools/exec.md b/docs/tools/exec.md index 3bf06687e..27735f60d 100644 --- a/docs/tools/exec.md +++ b/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: diff --git a/src/agents/bash-tools.exec.ts b/src/agents/bash-tools.exec.ts index fa8324185..9b17e9bfd 100644 --- a/src/agents/bash-tools.exec.ts +++ b/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: [],