feat(sparsekernel): honor plugin subprocess boundaries

Author: CharGrnmn

docs/architecture/local-agent-kernel.md

@@ -123,7 +123,7 @@ Sensitive operations should check capabilities before they mutate state or alloc
 - sandbox allocation;
 - tool invocation.
 
-Capability grants, revokes, and denied checks are audited. Embedded agent runs now materialize the active step as a task lease and transcript events, then wrap the effective tool set with the local ToolBroker outside tests unless explicitly disabled with `OPENCLAW_RUNTIME_TOOL_BROKER=off`. Set `OPENCLAW_RUNTIME_TOOL_BROKER=daemon` to use the `sparsekerneld` run-ledger and ToolBroker path; daemon setup failures fall back to the local runtime broker. Set `OPENCLAW_RUNTIME_TOOL_CAPABILITY_MODE=strict` to stop auto-granting sensitive tools such as `exec`, `read`, `write`, and `browser`; those tools then fail closed unless a capability already exists or `OPENCLAW_RUNTIME_TOOL_ALLOW_SENSITIVE=1` is set for compatibility. Set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec`, `bash`, and `shell` shaped tools through the sandbox broker command runner instead of the ambient in-process tool implementation when the active agent has sandbox allocation capability. Native in-process plugins remain trusted by default. When `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` is set, plugin tools with subprocess metadata execute through a JSON stdin/stdout worker via the sandbox broker, emit subprocess and sandbox audit events, and fail closed if the worker would use `local/no_isolation` without an explicit trusted-worker opt-out; plugin tools without subprocess metadata fail closed.
+Capability grants, revokes, and denied checks are audited. Embedded agent runs now materialize the active step as a task lease and transcript events, then wrap the effective tool set with the local ToolBroker outside tests unless explicitly disabled with `OPENCLAW_RUNTIME_TOOL_BROKER=off`. Set `OPENCLAW_RUNTIME_TOOL_BROKER=daemon` to use the `sparsekerneld` run-ledger and ToolBroker path; daemon setup failures fall back to the local runtime broker. Set `OPENCLAW_RUNTIME_TOOL_CAPABILITY_MODE=strict` to stop auto-granting sensitive tools such as `exec`, `read`, `write`, and `browser`; those tools then fail closed unless a capability already exists or `OPENCLAW_RUNTIME_TOOL_ALLOW_SENSITIVE=1` is set for compatibility. Set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec`, `bash`, and `shell` shaped tools through the sandbox broker command runner instead of the ambient in-process tool implementation when the active agent has sandbox allocation capability. Native in-process plugins remain trusted by default, but individual plugin tools can declare `processBoundary: "subprocess_required"` and operators can set `OPENCLAW_RUNTIME_PLUGIN_TRUST_DEFAULT=untrusted` to require subprocess workers for non-bundled plugin tools. When a subprocess boundary is required, plugin tools with subprocess metadata execute through a JSON stdin/stdout worker via the sandbox broker, emit subprocess and sandbox audit events, and fail closed if the worker would use `local/no_isolation` without an explicit trusted-worker opt-out; plugin tools without subprocess metadata fail closed.
 
 The SparseKernel daemon now exposes the v0 run and ToolBroker lifecycle over local JSON: session upsert/list, transcript append/list, task enqueue/claim-by-id/claim-next/heartbeat/complete/fail, tool-call create/start/complete/fail/list, browser acquire/release, sandbox allocate/release, and artifact access. Tool-call create checks `tool` / `<tool-name>` / `invoke`; completion records small structured output plus `artifact_ids`; and every transition writes audit records. See [Tool Broker](/architecture/tool-broker).
 

docs/architecture/security-boundaries.md

@@ -26,6 +26,7 @@ SparseKernel security claims must be precise.
 - Persisted lease metadata records the selected backend and policy intent; it is audit/accounting state, not isolation by itself.
 - Untrusted plugins must not get ambient host authority.
 - The subprocess-required plugin mode runs explicit JSON workers through the sandbox broker. It auto-selects an available isolated backend when possible, but it still only becomes suitable for untrusted code when the selected backend is a real isolation backend; `local/no_isolation` is blocked by default for plugin subprocess workers and should only be enabled for trusted local workers.
+- Plugin tool `processBoundary: "subprocess_required"` and `OPENCLAW_RUNTIME_PLUGIN_TRUST_DEFAULT=untrusted` are fail-closed controls for brokered tool execution; they do not make existing in-process plugin initialization safe.
 - Secrets should be referenced, not stored as plaintext in SQLite.
 
 Capabilities are the v0 policy primitive. They are intentionally simple: subject, resource, action, optional constraints, optional expiry. Denied sensitive checks are audit-logged.

docs/architecture/tool-broker.md

@@ -42,4 +42,4 @@ For exec-shaped tools, set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec
 
 Sandbox allocations persist the selected backend and trust-zone policy snapshot in resource-lease metadata. A restarted broker object can recover whether an allocation was local/no-isolation, bwrap, minijail, or Docker without relying on an in-memory map. Docker command execution is explicit: callers must provide `dockerImage` or `OPENCLAW_SPARSEKERNEL_DOCKER_IMAGE`, the wrapper uses `--pull never`, drops Linux capabilities, sets `no-new-privileges`, applies read-only root/tmpfs defaults, maps trust-zone memory/process limits to Docker flags, and keeps container networking disabled unless a policy proxy is configured. `OPENCLAW_RUNTIME_SANDBOX_REQUIRE_PROXY=1` makes network-allowing sandbox allocations fail closed unless the trust zone has a valid loopback proxy reference and the selected backend can carry that proxy path; Docker workers receive `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` pointing at `host.docker.internal`. `OPENCLAW_RUNTIME_SANDBOX_REQUIRE_HARD_EGRESS=1` is stricter: network-allowing sandbox allocations fail closed because current v0 backends do not provide bypass-proof host egress enforcement.
 
-V0 does not move native plugins out of process by default. It establishes the ledger and API contract so OpenClaw adapters can route invocation through SparseKernel now, then move untrusted or community plugins behind stronger process or sandbox boundaries later. Set `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` to require plugin tools to provide subprocess metadata. Opt-in workers receive a JSON request on stdin with `protocol`, `pluginId`, `toolName`, `toolCallId`, `params`, and broker context, and must return an `AgentToolResult` JSON object on stdout. Plugin subprocess workers now execute through the sandbox broker as `plugin_untrusted` leases by default, so allocation capability, command audit events, usage records, and release accounting apply to plugin workers too. When no explicit backend is configured, the broker auto-selects the first available isolated plugin backend from `bwrap`, `minijail`, then Docker when a plugin Docker image is configured. Operators can override the order with `OPENCLAW_RUNTIME_PLUGIN_SANDBOX_BACKENDS`, force one backend with `OPENCLAW_RUNTIME_PLUGIN_SANDBOX_BACKEND`, or provide Docker with `OPENCLAW_RUNTIME_PLUGIN_DOCKER_IMAGE`. The broker fails closed when only `local/no_isolation` remains unless the plugin marks the subprocess sandbox `requireIsolated: false` or `OPENCLAW_RUNTIME_PLUGIN_ALLOW_NO_ISOLATION=1` is set for trusted local workers. Plugin tools without subprocess metadata fail closed with `plugin_tool.subprocess_required` audit records.
+V0 does not move every native plugin out of process by default. It establishes the ledger and API contract so OpenClaw adapters can route invocation through SparseKernel now, then move untrusted or community plugins behind stronger process or sandbox boundaries incrementally. A plugin tool can now register `processBoundary: "subprocess_required"` plus subprocess worker metadata to require an out-of-process boundary for that tool. Set `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` to require all plugin tools to provide subprocess metadata. Set `OPENCLAW_RUNTIME_PLUGIN_TRUST_DEFAULT=untrusted` to require subprocess metadata for non-bundled plugin tools unless the tool explicitly opts into `processBoundary: "in_process"` for trusted local code. Opt-in workers receive a JSON request on stdin with `protocol`, `pluginId`, `toolName`, `toolCallId`, `params`, and broker context, and must return an `AgentToolResult` JSON object on stdout. Plugin subprocess workers now execute through the sandbox broker as `plugin_untrusted` leases by default, so allocation capability, command audit events, usage records, and release accounting apply to plugin workers too. When no explicit backend is configured, the broker auto-selects the first available isolated plugin backend from `bwrap`, `minijail`, then Docker when a plugin Docker image is configured. Operators can override the order with `OPENCLAW_RUNTIME_PLUGIN_SANDBOX_BACKENDS`, force one backend with `OPENCLAW_RUNTIME_PLUGIN_SANDBOX_BACKEND`, or provide Docker with `OPENCLAW_RUNTIME_PLUGIN_DOCKER_IMAGE`. The broker fails closed when only `local/no_isolation` remains unless the plugin marks the subprocess sandbox `requireIsolated: false` or `OPENCLAW_RUNTIME_PLUGIN_ALLOW_NO_ISOLATION=1` is set for trusted local workers. Plugin tools without subprocess metadata fail closed with `plugin_tool.subprocess_required` audit records.

src/local-kernel/tool-broker-runtime.ts

@@ -17,7 +17,7 @@ import {
 import {
   CapabilityToolBroker,
   isSandboxCommandToolName,
-  requiresPluginSubprocess,
+  pluginToolRequiresSubprocess,
   resolvePluginSandboxConfig,
   resolvePluginSubprocessPlan,
   type PluginSubprocessPlan,
@@ -304,16 +304,13 @@ function wrapDaemonPluginSubprocessTools(
   capabilityExpiresAt: string,
 ): AnyAgentTool[] {
   const env = input.env ?? process.env;
-  const strictPluginBoundary =
-    requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY) ||
-    requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS);
   return input.tools.map((tool) => {
     const pluginMeta = getPluginToolMeta(tool);
     if (!pluginMeta) {
       return tool;
     }
     const plan = resolvePluginSubprocessPlan(pluginMeta);
-    if (!plan && !strictPluginBoundary) {
+    if (!plan && !pluginToolRequiresSubprocess(pluginMeta, env)) {
       return tool;
     }
     return {

src/local-kernel/tool-broker.test.ts

@@ -426,6 +426,74 @@ describe("CapabilityToolBroker", () => {
     }
   });
 
+  it("fails closed when plugin tool metadata requires a subprocess boundary", async () => {
+    const db = new LocalKernelDatabase({ dbPath: ":memory:" });
+    try {
+      db.ensureAgent({ id: "main" });
+      db.grantCapability({
+        subjectType: "agent",
+        subjectId: "main",
+        resourceType: "tool",
+        resourceId: "plugin_tool",
+        action: "invoke",
+      });
+      const rawTool = makeTool("plugin_tool");
+      setPluginToolMeta(rawTool, {
+        pluginId: "community-plugin",
+        optional: false,
+        processBoundary: "subprocess_required",
+      });
+      const broker = new CapabilityToolBroker(db);
+      const tool = broker.wrapTool(rawTool, {
+        subject: { subjectType: "agent", subjectId: "main" },
+        agentId: "main",
+      });
+      await expect(tool.execute("call-plugin-boundary", {})).rejects.toThrow(
+        /out-of-process execution/,
+      );
+      expect(db.listAudit({ limit: 20 }).map((entry) => entry.action)).toEqual(
+        expect.arrayContaining(["plugin_tool.subprocess_required", "tool_call.failed"]),
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  it("can require subprocess boundaries for non-bundled plugin tools", async () => {
+    const db = new LocalKernelDatabase({ dbPath: ":memory:" });
+    try {
+      db.ensureAgent({ id: "main" });
+      db.grantCapability({
+        subjectType: "agent",
+        subjectId: "main",
+        resourceType: "tool",
+        resourceId: "plugin_tool",
+        action: "invoke",
+      });
+      const rawTool = makeTool("plugin_tool");
+      setPluginToolMeta(rawTool, {
+        pluginId: "workspace-plugin",
+        optional: false,
+        origin: "workspace",
+      });
+      const broker = new CapabilityToolBroker(db, {
+        env: { OPENCLAW_RUNTIME_PLUGIN_TRUST_DEFAULT: "untrusted" } as NodeJS.ProcessEnv,
+      });
+      const tool = broker.wrapTool(rawTool, {
+        subject: { subjectType: "agent", subjectId: "main" },
+        agentId: "main",
+      });
+      await expect(tool.execute("call-untrusted-plugin", {})).rejects.toThrow(
+        /out-of-process execution/,
+      );
+      expect(db.listAudit({ limit: 20 }).map((entry) => entry.action)).toEqual(
+        expect.arrayContaining(["plugin_tool.subprocess_required", "tool_call.failed"]),
+      );
+    } finally {
+      db.close();
+    }
+  });
+
   it("auto-selects an available isolated backend for plugin subprocess workers", () => {
     expect(
       resolvePluginSandboxConfig({

src/local-kernel/tool-broker.ts

@@ -118,6 +118,36 @@ export function requiresPluginSubprocess(raw: string | undefined): boolean {
   );
 }
 
+function requiresNonBundledPluginSubprocess(raw: string | undefined): boolean {
+  const normalized = raw?.trim().toLowerCase();
+  return normalized === "untrusted" || normalized === "non-bundled" || normalized === "non_bundled";
+}
+
+export function pluginToolRequiresSubprocess(
+  meta: PluginToolMeta | undefined,
+  env: NodeJS.ProcessEnv,
+): boolean {
+  if (!meta) {
+    return false;
+  }
+  if (
+    requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY) ||
+    requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS)
+  ) {
+    return true;
+  }
+  if (meta.processBoundary === "subprocess_required") {
+    return true;
+  }
+  if (meta.processBoundary === "in_process") {
+    return false;
+  }
+  return (
+    requiresNonBundledPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_TRUST_DEFAULT) &&
+    meta.origin !== "bundled"
+  );
+}
+
 export type PluginSubprocessPlan = NonNullable<PluginToolMeta["subprocess"]>;
 
 export type PluginSandboxConfig = {
@@ -345,12 +375,7 @@ export class CapabilityToolBroker {
         }
         const env = this.options.env ?? process.env;
         const pluginSubprocessPlan = resolvePluginSubprocessPlan(pluginMeta);
-        if (
-          pluginMeta &&
-          (requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY) ||
-            requiresPluginSubprocess(env.OPENCLAW_RUNTIME_PLUGIN_PROCESS)) &&
-          !pluginSubprocessPlan
-        ) {
+        if (pluginMeta && pluginToolRequiresSubprocess(pluginMeta, env) && !pluginSubprocessPlan) {
           const err = new Error(
             `Plugin tool ${tool.name} from ${pluginMeta.pluginId} requires out-of-process execution, but no subprocess worker is configured.`,
           );

src/plugins/bundled-capability-runtime.ts

@@ -485,6 +485,7 @@ export function loadBundledCapabilityRuntimeRegistry(params: {
           factory: () => tool,
           names: [tool.name],
           optional: false,
+          origin: record.origin,
           source: record.source,
           rootDir: record.rootDir,
         })),

src/plugins/registry-types.ts

@@ -29,6 +29,7 @@ import type {
   OpenClawPluginCliCommandDescriptor,
   OpenClawPluginCliRegistrar,
   OpenClawPluginCommandDefinition,
+  OpenClawPluginToolOptions,
   OpenClawPluginGatewayRuntimeScopeSurface,
   OpenClawGatewayDiscoveryService,
   OpenClawPluginHttpRouteAuth,
@@ -59,6 +60,9 @@ export type PluginToolRegistration = {
   factory: OpenClawPluginToolFactory;
   names: string[];
   optional: boolean;
+  origin: PluginOrigin;
+  processBoundary?: OpenClawPluginToolOptions["processBoundary"];
+  subprocess?: OpenClawPluginToolOptions["subprocess"];
   source: string;
   rootDir?: string;
 };

src/plugins/registry.ts

@@ -117,6 +117,7 @@ import type {
   OpenClawPluginService,
   OpenClawPluginToolContext,
   OpenClawPluginToolFactory,
+  OpenClawPluginToolOptions,
   PluginHookHandlerMap,
   PluginHookName,
   PluginHookRegistration as TypedPluginHookRegistration,
@@ -387,7 +388,7 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
   const registerTool = (
     record: PluginRecord,
     tool: AnyAgentTool | OpenClawPluginToolFactory,
-    opts?: { name?: string; names?: string[]; optional?: boolean },
+    opts?: OpenClawPluginToolOptions,
   ) => {
     if (pluginsWithChannelRegistrationConflict.has(record.id)) {
       return;
@@ -411,6 +412,9 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
       factory,
       names: normalized,
       optional,
+      origin: record.origin,
+      ...(opts?.processBoundary ? { processBoundary: opts.processBoundary } : {}),
+      ...(opts?.subprocess ? { subprocess: opts.subprocess } : {}),
       source: record.source,
       rootDir: record.rootDir,
     });

src/plugins/tool-types.ts

@@ -38,10 +38,35 @@ export type OpenClawPluginToolFactory = (
   ctx: OpenClawPluginToolContext,
 ) => AnyAgentTool | AnyAgentTool[] | null | undefined;
 
+export type OpenClawPluginToolSubprocessOptions = {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  sandbox?: {
+    trustZoneId?: string;
+    backend?:
+      | "local/no_isolation"
+      | "docker"
+      | "bwrap"
+      | "minijail"
+      | "ssh"
+      | "openshell"
+      | "vm"
+      | "other";
+    dockerImage?: string;
+    requireIsolated?: boolean;
+    maxRuntimeMs?: number;
+    maxBytesOut?: number;
+  };
+};
+
 export type OpenClawPluginToolOptions = {
   name?: string;
   names?: string[];
   optional?: boolean;
+  processBoundary?: "in_process" | "subprocess_required";
+  subprocess?: OpenClawPluginToolSubprocessOptions;
 };
 
 export type OpenClawPluginHookOptions = {