Clarify exec filesystem policy drift (#79153)

* docs: clarify exec filesystem policy

* fix: warn on exec filesystem policy drift

* docs: clarify exec filesystem mutation surface

docs/cli/security.md

@@ -33,7 +33,7 @@ It also emits `security.trust_model.multi_user_heuristic` when config suggests l
 For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
 It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
 For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.token` is short, when `hooks.path="/"`, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
-It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
+It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when write/edit tools are disabled but `exec` is still available without a constraining sandbox filesystem boundary, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
 It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
 It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
 It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).

docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -64,6 +64,7 @@ Rules of thumb:
 - `deny` always wins.
 - If `allow` is non-empty, everything else is treated as blocked.
 - Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
+- Tool policy filters tool availability by name; it does not inspect side effects inside `exec`. If `exec` is allowed, denying `write`, `edit`, or `apply_patch` does not make shell commands read-only.
 - `/exec` only changes session defaults for authorized senders; it does not grant tool access.
   Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
 
@@ -88,6 +89,7 @@ Available groups:
 - `group:runtime`: `exec`, `process`, `code_execution` (`bash` is accepted as
   an alias for `exec`)
 - `group:fs`: `read`, `write`, `edit`, `apply_patch`
+  For read-only agents, deny `group:runtime` as well as mutating filesystem tools unless sandbox filesystem policy or a separate host boundary enforces the read-only constraint.
 - `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
 - `group:memory`: `memory_search`, `memory_get`
 - `group:web`: `web_search`, `x_search`, `web_fetch`

docs/gateway/security/audit-checks.md

@@ -91,6 +91,7 @@ exhaustive):
 | `tools.exec.host_sandbox_no_sandbox_defaults`                 | warn          | `exec host=sandbox` fails closed when sandbox is off                                 | `tools.exec.host`, `agents.defaults.sandbox.mode`                                                    | no       |
 | `tools.exec.host_sandbox_no_sandbox_agents`                   | warn          | Per-agent `exec host=sandbox` fails closed when sandbox is off                       | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode`                                        | no       |
 | `tools.exec.security_full_configured`                         | warn/critical | Host exec is running with `security="full"`                                          | `tools.exec.security`, `agents.list[].tools.exec.security`                                           | no       |
+| `tools.exec.fs_tools_disabled_but_exec_enabled`               | warn          | Filesystem tool policy does not make shell execution read-only                       | `tools.deny`, `agents.list[].tools.deny`, `agents.*.sandbox.workspaceAccess`                         | no       |
 | `tools.exec.auto_allow_skills_enabled`                        | warn          | Exec approvals trust skill bins implicitly                                           | `~/.openclaw/exec-approvals.json`                                                                    | no       |
 | `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn          | Interpreter allowlists permit inline eval without forced reapproval                  | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, exec approvals allowlist | no       |
 | `tools.exec.safe_bins_interpreter_unprofiled`                 | warn          | Interpreter/runtime bins in `safeBins` without explicit profiles broaden exec risk   | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*`                    | no       |

docs/gateway/security/index.md

@@ -220,6 +220,7 @@ Advisory triage guidance:
 
 - **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot?
 - **Tool blast radius** (elevated tools + open rooms): could prompt injection turn into shell/file/network actions?
+- **Exec filesystem drift**: are mutating filesystem tools denied while `exec`/`process` remain available without sandbox filesystem constraints?
 - **Exec approval drift** (`security=full`, `autoAllowSkills`, interpreter allowlists without `strictInlineEval`): are host-exec guardrails still doing what you think they are?
   - `security="full"` is a broad posture warning, not proof of a bug. It is the chosen default for trusted personal-assistant setups; tighten it only when your threat model needs approval or allowlist guardrails.
 - **Network exposure** (Gateway bind/auth, Tailscale Serve/Funnel, weak/short auth tokens).

docs/gateway/tools-invoke-http-api.md

@@ -97,6 +97,7 @@ If a tool is not allowed by policy, the endpoint returns **404**.
 Important boundary notes:
 
 - Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, `/tools/invoke` does not add an extra per-call approval prompt.
+- If `exec` is reachable here, treat it as a mutating shell surface. Denying `write`, `edit`, `apply_patch`, or HTTP filesystem-write tools does not make shell execution read-only.
 - Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (and ideally separate OS users/hosts).
 
 Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):

docs/tools/exec-approvals.md

@@ -56,7 +56,8 @@ Exec approvals are enforced locally on the execution host:
 
 - Gateway-authenticated callers are trusted operators for that Gateway.
 - Paired nodes extend that trusted operator capability onto the node host.
-- Exec approvals reduce accidental execution risk, but are **not** a per-user auth boundary.
+- Exec approvals reduce accidental execution risk, but are **not** a per-user auth boundary or filesystem read-only policy.
+- Once approved, a command can mutate files according to the selected host or sandbox filesystem permissions.
 - Approved node-host runs bind canonical execution context: canonical cwd, exact argv, env binding when present, and pinned executable path when applicable.
 - For shell scripts and direct interpreter/runtime file invocations, OpenClaw also tries to bind one concrete local file operand. If that bound file changes after approval but before execution, the run is denied instead of executing drifted content.
 - File binding is intentionally best-effort, **not** a complete semantic model of every interpreter/runtime loader path. If approval mode cannot identify exactly one concrete local file to bind, it refuses to mint an approval-backed run instead of pretending full coverage.

docs/tools/exec.md

@@ -6,8 +6,9 @@ read_when:
 title: "Exec tool"
 ---
 
-Run shell commands in the workspace. Supports foreground + background execution via `process`.
-If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+Run shell commands in the workspace. `exec` is a mutating shell surface: commands can create, edit, or delete files wherever the selected host or sandbox filesystem permits. Disabling OpenClaw filesystem tools such as `write`, `edit`, or `apply_patch` does not make `exec` read-only.
+
+Supports foreground + background execution via `process`. If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
 Background sessions are scoped per agent; `process` only sees sessions from the same agent.
 
 ## Parameters

docs/tools/multi-agent-sandbox-tools.md

@@ -300,7 +300,7 @@ Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defau
     }
     ```
   </Tab>
-  <Tab title="Safe execution (no file modifications)">
+  <Tab title="Shell execution with filesystem tools disabled">
     ```json
     {
       "tools": {
@@ -309,6 +309,11 @@ Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defau
       }
     }
     ```
+
+    <Warning>
+    This policy disables OpenClaw filesystem tools, but `exec` is still a shell and can write files wherever the selected host or sandbox filesystem allows. For a read-only agent, deny `exec` and `process`, or combine shell access with sandbox filesystem controls such as `agents.defaults.sandbox.workspaceAccess: "ro"` or `"none"`.
+    </Warning>
+
   </Tab>
   <Tab title="Communication-only">
     ```json

src/commands/doctor-security.test.ts

@@ -271,6 +271,43 @@ describe("noteSecurityWarnings gateway exposure", () => {
     expect(message).toContain("openclaw approvals get --gateway");
   });
 
+  it("warns when filesystem tools are disabled but exec remains available", async () => {
+    await noteSecurityWarnings({
+      tools: {
+        allow: ["read", "exec", "process"],
+        deny: ["write", "edit", "apply_patch"],
+      },
+    } as OpenClawConfig);
+
+    const message = lastMessage();
+    expect(message).toContain("filesystem write tools are disabled, but exec is still available");
+    expect(message).toContain("Runtime tools: exec, process");
+    expect(message).toContain('sandbox.mode="off"');
+    expect(message).toContain("also deny exec/process");
+  });
+
+  it("does not warn about exec filesystem policy when sandbox access is read-only", async () => {
+    await noteSecurityWarnings({
+      agents: {
+        defaults: {
+          sandbox: {
+            mode: "all",
+            workspaceAccess: "ro",
+          },
+        },
+      },
+      tools: {
+        allow: ["read", "exec", "process"],
+        deny: ["write", "edit", "apply_patch"],
+      },
+    } as OpenClawConfig);
+
+    const message = lastMessage();
+    expect(message).not.toContain(
+      "filesystem write tools are disabled, but exec is still available",
+    );
+  });
+
   it("warns when tools.exec is broader than host exec defaults", async () => {
     await withExecApprovalsFile(
       {

src/commands/doctor-security.ts

@@ -10,6 +10,7 @@ import { isLoopbackHost, resolveGatewayBindHost } from "../gateway/net.js";
 import { resolveExecPolicyScopeSnapshot } from "../infra/exec-approvals-effective.js";
 import { loadExecApprovals, type ExecAsk, type ExecSecurity } from "../infra/exec-approvals.js";
 import { resolveDmAllowState } from "../security/dm-policy-shared.js";
+import { collectExecFilesystemPolicyDriftHits } from "../security/exec-filesystem-policy.js";
 import { normalizeOptionalString } from "../shared/string-coerce.js";
 import { note } from "../terminal/note.js";
 import { resolveDefaultChannelAccountContext } from "./channel-account-context.js";
@@ -165,6 +166,18 @@ function collectDurableExecApprovalWarnings(cfg: OpenClawConfig): string[] {
   return [];
 }
 
+function collectExecFilesystemPolicyWarnings(cfg: OpenClawConfig): string[] {
+  return collectExecFilesystemPolicyDriftHits(cfg).map((hit) =>
+    [
+      `- ${hit.scopeLabel}: filesystem write tools are disabled, but exec is still available.`,
+      `  Runtime tools: ${hit.runtimeTools.join(", ")}; disabled filesystem tools: ${hit.disabledFilesystemTools.join(", ")}.`,
+      `  Effective exec host is "${hit.execHost}" with sandbox.mode="${hit.sandboxMode}" and workspaceAccess="${hit.sandboxWorkspaceAccess}".`,
+      "  The exec shell can still write wherever that host or sandbox filesystem permits.",
+      '  For read-only agents, also deny exec/process; otherwise use sandbox mode "all" with workspaceAccess "ro" or "none".',
+    ].join("\n"),
+  );
+}
+
 export async function noteSecurityWarnings(cfg: OpenClawConfig) {
   const warnings: string[] = [];
   const auditHint = `- Run: ${formatCliCommand("openclaw security audit --deep")}`;
@@ -179,6 +192,7 @@ export async function noteSecurityWarnings(cfg: OpenClawConfig) {
 
   warnings.push(...collectImplicitHeartbeatDirectPolicyWarnings(cfg));
   warnings.push(...collectExecPolicyConflictWarnings(cfg));
+  warnings.push(...collectExecFilesystemPolicyWarnings(cfg));
   warnings.push(...collectDurableExecApprovalWarnings(cfg));
 
   // ===========================================

src/security/audit-exec-surface.test.ts

@@ -8,7 +8,8 @@ function hasFinding(
     | "tools.exec.auto_allow_skills_enabled"
     | "tools.exec.allowlist_interpreter_without_strict_inline_eval"
     | "security.exposure.open_channels_with_exec"
-    | "tools.exec.security_full_configured",
+    | "tools.exec.security_full_configured"
+    | "tools.exec.fs_tools_disabled_but_exec_enabled",
   severity: "warn" | "critical",
   findings: ReturnType<typeof collectExecRuntimeFindings>,
 ) {
@@ -122,4 +123,42 @@ describe("security audit exec surface findings", () => {
       true,
     );
   });
+
+  it("warns when filesystem tools are disabled but exec remains available", () => {
+    const findings = collectExecRuntimeFindings({
+      tools: {
+        allow: ["read", "exec", "process"],
+        deny: ["write", "edit", "apply_patch"],
+      },
+    } satisfies OpenClawConfig);
+
+    const finding = findings.find(
+      (entry) => entry.checkId === "tools.exec.fs_tools_disabled_but_exec_enabled",
+    );
+    expect(finding?.severity).toBe("warn");
+    expect(finding?.detail).toContain("tools");
+    expect(finding?.detail).toContain("runtime=[exec, process]");
+    expect(finding?.remediation).toContain("deny exec and process");
+  });
+
+  it("does not warn when sandbox filesystem policy constrains exec", () => {
+    const findings = collectExecRuntimeFindings({
+      agents: {
+        defaults: {
+          sandbox: {
+            mode: "all",
+            workspaceAccess: "ro",
+          },
+        },
+      },
+      tools: {
+        allow: ["read", "exec", "process"],
+        deny: ["write", "edit", "apply_patch"],
+      },
+    } satisfies OpenClawConfig);
+
+    expect(hasFinding("tools.exec.fs_tools_disabled_but_exec_enabled", "warn", findings)).toBe(
+      false,
+    );
+  });
 });

src/security/audit.ts

@@ -30,6 +30,7 @@ import type {
   SecurityAuditSummary,
 } from "./audit.types.js";
 import { collectEnabledInsecureOrDangerousFlags } from "./dangerous-config-flags.js";
+import { collectExecFilesystemPolicyDriftHits } from "./exec-filesystem-policy.js";
 import type { ExecFn } from "./windows-acl.js";
 
 type ExecDockerRawFn = typeof import("../agents/sandbox/docker.js").execDockerRaw;
@@ -581,6 +582,20 @@ export function collectExecRuntimeFindings(cfg: OpenClawConfig): SecurityAuditFi
     });
   }
 
+  const execFilesystemPolicyHits = collectExecFilesystemPolicyDriftHits(cfg);
+  if (execFilesystemPolicyHits.length > 0) {
+    findings.push({
+      checkId: "tools.exec.fs_tools_disabled_but_exec_enabled",
+      severity: "warn",
+      title: "Filesystem tool policy does not make exec read-only",
+      detail:
+        `Found scopes where write/edit/apply_patch are unavailable but exec remains available:\n${execFilesystemPolicyHits.map((hit) => `- ${hit.scopeLabel}: runtime=[${hit.runtimeTools.join(", ")}], disabledFs=[${hit.disabledFilesystemTools.join(", ")}], exec.host=${hit.execHost}, sandbox=${hit.sandboxMode}, workspaceAccess=${hit.sandboxWorkspaceAccess}`).join("\n")}\n` +
+        "The exec tool is a shell and can still write files wherever the selected host or sandbox filesystem permits it.",
+      remediation:
+        'For read-only agents, deny exec and process too. If shell access is intentional, constrain the filesystem boundary with sandbox mode "all" and workspaceAccess "ro" or "none".',
+    });
+  }
+
   const autoAllowSkillsHits = collectAutoAllowSkillsHits(approvals);
   if (autoAllowSkillsHits.length > 0) {
     findings.push({

src/security/exec-filesystem-policy.ts

@@ -0,0 +1,140 @@
+import { pickSandboxToolPolicy } from "../agents/sandbox-tool-policy.js";
+import { resolveSandboxConfigForAgent } from "../agents/sandbox/config.js";
+import { resolveSandboxToolPolicyForAgent } from "../agents/sandbox/tool-policy.js";
+import type { SandboxToolPolicy } from "../agents/sandbox/types.js";
+import { isToolAllowedByPolicies } from "../agents/tool-policy-match.js";
+import { resolveToolProfilePolicy } from "../agents/tool-policy.js";
+import type { OpenClawConfig } from "../config/config.js";
+import type { AgentToolsConfig, ExecToolConfig } from "../config/types.tools.js";
+
+const MUTATING_FS_TOOLS = ["write", "edit", "apply_patch"] as const;
+const RUNTIME_TOOLS = ["exec", "process"] as const;
+
+export type ExecFilesystemPolicyDriftHit = {
+  scopeLabel: string;
+  runtimeTools: string[];
+  disabledFilesystemTools: string[];
+  sandboxMode: "off" | "non-main" | "all";
+  sandboxWorkspaceAccess: "none" | "ro" | "rw";
+  execHost: NonNullable<ExecToolConfig["host"]>;
+};
+
+function resolveToolPolicies(params: {
+  cfg: OpenClawConfig;
+  agentTools?: AgentToolsConfig;
+  sandboxMode: "off" | "non-main" | "all";
+  agentId?: string;
+}): SandboxToolPolicy[] {
+  const policies: SandboxToolPolicy[] = [];
+  const profile = params.agentTools?.profile ?? params.cfg.tools?.profile;
+  const profilePolicy = resolveToolProfilePolicy(profile);
+  if (profilePolicy) {
+    policies.push(profilePolicy);
+  }
+
+  const globalPolicy = pickSandboxToolPolicy(params.cfg.tools ?? undefined);
+  if (globalPolicy) {
+    policies.push(globalPolicy);
+  }
+
+  const agentPolicy = pickSandboxToolPolicy(params.agentTools);
+  if (agentPolicy) {
+    policies.push(agentPolicy);
+  }
+
+  if (params.sandboxMode === "all") {
+    policies.push(resolveSandboxToolPolicyForAgent(params.cfg, params.agentId));
+  }
+
+  return policies;
+}
+
+function resolveExecHost(params: {
+  globalExec?: ExecToolConfig;
+  agentExec?: ExecToolConfig;
+}): NonNullable<ExecToolConfig["host"]> {
+  return params.agentExec?.host ?? params.globalExec?.host ?? "auto";
+}
+
+function isExecFilesystemConstrained(params: {
+  sandboxMode: "off" | "non-main" | "all";
+  sandboxWorkspaceAccess: "none" | "ro" | "rw";
+  execHost: NonNullable<ExecToolConfig["host"]>;
+}): boolean {
+  if (params.sandboxMode !== "all") {
+    return false;
+  }
+  if (params.execHost === "gateway" || params.execHost === "node") {
+    return false;
+  }
+  return params.sandboxWorkspaceAccess !== "rw";
+}
+
+export function collectExecFilesystemPolicyDriftHits(
+  cfg: OpenClawConfig,
+): ExecFilesystemPolicyDriftHit[] {
+  const hits: ExecFilesystemPolicyDriftHit[] = [];
+  const globalExec = cfg.tools?.exec;
+  const contexts: Array<{
+    scopeLabel: string;
+    agentId?: string;
+    tools?: AgentToolsConfig;
+  }> = [{ scopeLabel: "tools" }];
+
+  for (const agent of cfg.agents?.list ?? []) {
+    if (!agent || typeof agent !== "object" || typeof agent.id !== "string") {
+      continue;
+    }
+    contexts.push({
+      scopeLabel: `agents.list.${agent.id}.tools`,
+      agentId: agent.id,
+      tools: agent.tools,
+    });
+  }
+
+  for (const context of contexts) {
+    const sandbox = resolveSandboxConfigForAgent(cfg, context.agentId);
+    const execHost = resolveExecHost({
+      globalExec,
+      agentExec: context.tools?.exec,
+    });
+    if (
+      isExecFilesystemConstrained({
+        sandboxMode: sandbox.mode,
+        sandboxWorkspaceAccess: sandbox.workspaceAccess,
+        execHost,
+      })
+    ) {
+      continue;
+    }
+
+    const policies = resolveToolPolicies({
+      cfg,
+      agentTools: context.tools,
+      sandboxMode: sandbox.mode,
+      agentId: context.agentId,
+    });
+    const runtimeTools = RUNTIME_TOOLS.filter((tool) => isToolAllowedByPolicies(tool, policies));
+    if (!runtimeTools.includes("exec")) {
+      continue;
+    }
+
+    const disabledFilesystemTools = MUTATING_FS_TOOLS.filter(
+      (tool) => !isToolAllowedByPolicies(tool, policies),
+    );
+    if (disabledFilesystemTools.length !== MUTATING_FS_TOOLS.length) {
+      continue;
+    }
+
+    hits.push({
+      scopeLabel: context.scopeLabel,
+      runtimeTools,
+      disabledFilesystemTools,
+      sandboxMode: sandbox.mode,
+      sandboxWorkspaceAccess: sandbox.workspaceAccess,
+      execHost,
+    });
+  }
+
+  return hits;
+}