fix(opencode): lock down hidden subagent tool permissions

ualtinok · ualtinok · commit 571d0141049e · 2026-05-20T16:33:57.000+08:00
Historian, dreamer, and sidekick are registered with `mode: "subagent"` but
their `permission` field was never set, so each spawned session inherited
the full primary-agent tool surface (`task`, `bash`, `edit`, `webfetch`,
`websearch`, `read`, `grep`, `glob`, all MCP tools, etc.).

`mode: "subagent"` + `hidden: true` only control visibility in the agent
picker — they do NOT restrict tool access. The auto-`task`-deny in
OpenCode's `deriveSubagentSessionPermission` (subagent-permissions.ts)
fires only when an agent is INVOKED via the parent's `task()` tool, not
when spawned directly via `client.session.prompt(...)` like we do.

Result observed in the wild: historian sometimes used
`task(subagent_type=explore)` to fan out, which it should never do.

Fix mirrors OpenCode's own `explore` agent (`packages/opencode/src/
agent/agent.ts:179-201`): set `permission: { "*": "deny", ...allows }`
on each hidden-agent config. `Permission.fromConfig` converts the flat
map to a `Rule[]` ruleset, and `evaluate` uses `findLast` so named
allows defeat the wildcard deny.

Allow-lists per agent:
  - historian / historian-editor: `read` (state-file offload only)
  - dreamer: `read` (key-files) + `ctx_memory`, `ctx_search`, `ctx_note`
  - sidekick: `ctx_search`, `ctx_memory` (read-only memory retrieval)

User-supplied `pluginConfig.&lt;agent&gt;.permission` overrides still merge on
top via object-spread, so advanced users can extend the allow-list in
`magic-context.jsonc` if they really need to grant more tools.

Pi side already restricts via `--no-extensions --no-skills` on the spawn
command line, so no Pi-side change is needed.

Tests: 16 new unit tests in agents/permissions.test.ts covering the
helper's deny-first ordering, the per-agent allow-list shapes, and
locking in the "no task / bash / edit" invariant. Full plugin suite:
1473 pass / 0 fail.
diff --git a/packages/plugin/src/agents/permissions.test.ts b/packages/plugin/src/agents/permissions.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "bun:test";
+import {
+    buildAllowOnlyPermission,
+    DREAMER_ALLOWED_TOOLS,
+    HISTORIAN_ALLOWED_TOOLS,
+    SIDEKICK_ALLOWED_TOOLS,
+} from "./permissions";
+
+describe("buildAllowOnlyPermission", () => {
+    it("starts with wildcard deny so nothing is allowed by default", () => {
+        const perm = buildAllowOnlyPermission([]);
+        expect(perm["*"]).toBe("deny");
+    });
+
+    it("layers the allow-list on top of the wildcard deny", () => {
+        const perm = buildAllowOnlyPermission(["read", "ctx_search"]);
+        expect(perm["*"]).toBe("deny");
+        expect(perm.read).toBe("allow");
+        expect(perm.ctx_search).toBe("allow");
+    });
+
+    it("places named allows AFTER the wildcard deny so findLast-semantics make them win", () => {
+        // OpenCode's Permission.evaluate uses `findLast` over the ruleset
+        // built from this object's insertion order. If "*" appeared after a
+        // named tool, the deny would clobber it — guard against accidental
+        // regressions in the helper's ordering.
+        const perm = buildAllowOnlyPermission(["read"]);
+        const keys = Object.keys(perm);
+        const wildcardIdx = keys.indexOf("*");
+        const readIdx = keys.indexOf("read");
+        expect(wildcardIdx).toBeLessThan(readIdx);
+    });
+
+    it("never accidentally allows `task`, `bash`, or `edit` unless explicitly listed", () => {
+        // The whole point of this helper is preventing historian / dreamer /
+        // sidekick from inheriting the primary-agent surface. Lock that in.
+        const perm = buildAllowOnlyPermission(["read"]);
+        expect(perm.task).toBeUndefined();
+        expect(perm.bash).toBeUndefined();
+        expect(perm.edit).toBeUndefined();
+        expect(perm.webfetch).toBeUndefined();
+        expect(perm.websearch).toBeUndefined();
+        // The wildcard deny covers them via findLast — verified above.
+    });
+
+    it("returns an empty allow-list as just the wildcard deny", () => {
+        const perm = buildAllowOnlyPermission([]);
+        expect(Object.keys(perm)).toEqual(["*"]);
+    });
+});
+
+describe("HISTORIAN_ALLOWED_TOOLS", () => {
+    it("includes only `read` (for state-file offload)", () => {
+        // Historian's only tool need is reading the offloaded existing-state
+        // XML the runner writes to a temp file. Nothing else.
+        expect(HISTORIAN_ALLOWED_TOOLS).toEqual(["read"]);
+    });
+
+    it("does NOT include `task` (the bug we're fixing — preventing subagent fanout)", () => {
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("task");
+    });
+
+    it("does NOT include any edit / bash / web tools", () => {
+        for (const dangerous of ["bash", "edit", "write", "webfetch", "websearch"]) {
+            expect(HISTORIAN_ALLOWED_TOOLS).not.toContain(dangerous);
+        }
+    });
+});
+
+describe("DREAMER_ALLOWED_TOOLS", () => {
+    it("includes read + ctx_memory + ctx_search + ctx_note", () => {
+        // Dreamer needs: `read` (key-files identification), `ctx_memory`
+        // (consolidate/verify/archive/merge/update), `ctx_search`
+        // (smart-note evaluation, retrieval-count checks), `ctx_note`
+        // (smart-note dismiss/update).
+        expect(DREAMER_ALLOWED_TOOLS).toContain("read");
+        expect(DREAMER_ALLOWED_TOOLS).toContain("ctx_memory");
+        expect(DREAMER_ALLOWED_TOOLS).toContain("ctx_search");
+        expect(DREAMER_ALLOWED_TOOLS).toContain("ctx_note");
+    });
+
+    it("does NOT include `task` or edit/bash/web tools", () => {
+        for (const denied of ["task", "bash", "edit", "write", "webfetch", "websearch"]) {
+            expect(DREAMER_ALLOWED_TOOLS).not.toContain(denied);
+        }
+    });
+});
+
+describe("SIDEKICK_ALLOWED_TOOLS", () => {
+    it("includes only ctx_search + ctx_memory (read-only memory retrieval)", () => {
+        // Sidekick is the /ctx-aug memory retriever. It augments the user
+        // prompt with relevant memories — no edits, no subagents, no bash.
+        expect(SIDEKICK_ALLOWED_TOOLS).toEqual(["ctx_search", "ctx_memory"]);
+    });
+
+    it("does NOT include `read` (sidekick doesn't touch the filesystem)", () => {
+        expect(SIDEKICK_ALLOWED_TOOLS).not.toContain("read");
+    });
+
+    it("does NOT include `task` or any edit / bash / web tool", () => {
+        for (const denied of ["task", "bash", "edit", "write", "webfetch", "websearch"]) {
+            expect(SIDEKICK_ALLOWED_TOOLS).not.toContain(denied);
+        }
+    });
+});
+
+describe("integration: full hidden-agent permission shape", () => {
+    it("historian permission object: `*` denied, only `read` allowed", () => {
+        const perm = buildAllowOnlyPermission(HISTORIAN_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            read: "allow",
+        });
+    });
+
+    it("dreamer permission object: `*` denied + read + ctx_* allowed", () => {
+        const perm = buildAllowOnlyPermission(DREAMER_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            read: "allow",
+            ctx_memory: "allow",
+            ctx_search: "allow",
+            ctx_note: "allow",
+        });
+    });
+
+    it("sidekick permission object: `*` denied + ctx_search + ctx_memory allowed", () => {
+        const perm = buildAllowOnlyPermission(SIDEKICK_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            ctx_search: "allow",
+            ctx_memory: "allow",
+        });
+    });
+});
diff --git a/packages/plugin/src/agents/permissions.ts b/packages/plugin/src/agents/permissions.ts
@@ -0,0 +1,106 @@
+/**
+ * Permission rulesets for Magic Context's hidden subagents.
+ *
+ * # Why this exists
+ *
+ * Hidden agents (`historian`, `historian-editor`, `dreamer`, `sidekick`) are
+ * registered with `mode: "subagent"` and `hidden: true`, but those flags
+ * only control visibility in the UI picker — they do NOT restrict which
+ * tools the spawned session can call. By default a registered subagent
+ * inherits the FULL primary-agent tool surface: `task`, `bash`, `edit`,
+ * `webfetch`, `websearch`, `read`, `grep`, `glob`, every MCP tool, etc.
+ *
+ * That default is wrong for our agents:
+ *   - Historian should be a pure XML-emitting summarizer. It must not
+ *     dispatch `task(subagent_type=explore)` to fan out, edit files,
+ *     run bash, or fetch the web — its job is to read offloaded state
+ *     files and emit `<compartment>` blocks.
+ *   - The `task` permission only gets auto-denied when an agent is
+ *     INVOKED via the parent's `task()` tool (see OpenCode's
+ *     `deriveSubagentSessionPermission`). Our hidden agents are spawned
+ *     directly via `client.session.prompt(...)` from the plugin
+ *     runtime, so that auto-deny never fires — they get the same
+ *     `task` permission as a primary `build` agent.
+ *
+ * # Design
+ *
+ * Each hidden agent's `permission` field starts with `{ "*": "deny" }`
+ * and adds explicit `allow` entries for ONLY the tool ids it needs.
+ * OpenCode's `Permission.fromConfig` converts this flat map into a
+ * `Rule[]` ruleset where later entries override earlier ones, so the
+ * named allows always win against the wildcard deny.
+ *
+ * This is the same pattern OpenCode's own `explore` subagent uses
+ * (see `packages/opencode/src/agent/agent.ts:179-201`).
+ *
+ * User-supplied agent overrides (`pluginConfig.historian.permission`,
+ * etc.) still merge on top via OpenCode's `Permission.merge`, so
+ * advanced users can extend the allow-list without us blocking them.
+ *
+ * # What each agent needs
+ *
+ *   - **historian / historian-editor / compressor**: just `read`. The
+ *     runner offloads large existing-state XML to a temp file under
+ *     `<project>/.opencode/magic-context/historian/` and the prompt
+ *     instructs the model to read that file. The model's only output
+ *     channel is its text response (the `<output>...</output>` XML).
+ *
+ *   - **dreamer**: `read` (for the key-files identification task),
+ *     plus the Magic Context MCP tools `ctx_memory`, `ctx_search`,
+ *     `ctx_note`. Dreamer task prompts in
+ *     `features/magic-context/dreamer/task-prompts.ts` explicitly
+ *     call these tools to consolidate, verify, archive, merge, and
+ *     update memories, plus evaluate smart notes.
+ *
+ *   - **sidekick**: `ctx_search` and `ctx_memory` (read-only ops).
+ *     Sidekick's job is augmenting user prompts via memory retrieval
+ *     — see `features/magic-context/sidekick/agent.ts`.
+ */
+
+/**
+ * Build a `permission` map suitable for `AgentConfig.permission`. Starts
+ * with a wildcard deny, then layers in the named tool allows on top.
+ * OpenCode's `Permission.fromConfig` preserves insertion order and its
+ * `evaluate` uses `findLast`, so named allows defeat the wildcard deny.
+ *
+ * Returns `Record<string, "deny" | "allow">` which the SDK's
+ * `AgentConfig.permission` type accepts via its `[key: string]: unknown`
+ * index signature. The same pattern is used by OpenCode's built-in
+ * `explore`/`scout`/`general` agents and by Alfonso for its static
+ * agent profiles.
+ */
+export function buildAllowOnlyPermission(
+    allowedTools: readonly string[],
+): Record<string, "deny" | "allow"> {
+    const permission: Record<string, "deny" | "allow"> = { "*": "deny" };
+    for (const tool of allowedTools) {
+        permission[tool] = "allow";
+    }
+    return permission;
+}
+
+/**
+ * Tools the historian + historian-editor + compressor agents need.
+ * Historian runners offload large `<existing_state>` XML to disk and
+ * tell the model to `read` it before emitting the summary XML. Nothing
+ * else is needed — no bash, no edits, no other subagents.
+ */
+export const HISTORIAN_ALLOWED_TOOLS = ["read"] as const;
+
+/**
+ * Tools the dreamer agent needs. Memory consolidation/verification/
+ * archive/merge/update flows go through `ctx_memory`; smart-note
+ * evaluation uses `ctx_search` and `ctx_note`; the key-files
+ * identification task uses `read` to inspect candidate files before
+ * picking which ones to pin.
+ */
+export const DREAMER_ALLOWED_TOOLS = ["read", "ctx_memory", "ctx_search", "ctx_note"] as const;
+
+/**
+ * Tools the sidekick agent needs. Sidekick is a read-only memory
+ * retriever for `/ctx-aug` — it queries the project's memory store
+ * via `ctx_search` and (rarely) reads specific memories with
+ * `ctx_memory(action="list")`. It must NOT spawn subagents, edit
+ * files, or run bash.
+ */
+export const SIDEKICK_ALLOWED_TOOLS = ["ctx_search", "ctx_memory"] as const;
diff --git a/packages/plugin/src/index.ts b/packages/plugin/src/index.ts
@@ -1,6 +1,12 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { DREAMER_AGENT } from "./agents/dreamer";
 import { HISTORIAN_AGENT, HISTORIAN_EDITOR_AGENT } from "./agents/historian";
+import {
+    buildAllowOnlyPermission,
+    DREAMER_ALLOWED_TOOLS,
+    HISTORIAN_ALLOWED_TOOLS,
+    SIDEKICK_ALLOWED_TOOLS,
+} from "./agents/permissions";
 import { SIDEKICK_AGENT } from "./agents/sidekick";
 import { loadPluginConfig } from "./config";
 import { getMagicContextBuiltinCommands } from "./features/builtin-commands/commands";
@@ -299,19 +305,58 @@ const plugin: Plugin = async (ctx) => {
             await hooks.magicContext?.["experimental.text.complete"]?.(input, output);
         },
         config: async (config) => {
+            /**
+             * Build a hidden-agent config with a deny-everything-by-default
+             * permission baseline plus an explicit allow-list of tool ids the
+             * agent actually needs. See `agents/permissions.ts` for the
+             * rationale — without this, registered subagents inherit the full
+             * primary-agent tool surface (`task`, `bash`, `edit`, `webfetch`,
+             * etc.) because the auto-`task`-deny in
+             * `deriveSubagentSessionPermission` only applies to subagents
+             * INVOKED via the parent's `task()` tool, not to subagents spawned
+             * directly via `client.session.prompt(...)` from plugin runtime.
+             *
+             * Permission precedence:
+             *   1. `buildAllowOnlyPermission(allowedTools)` → wildcard deny +
+             *      our named allows (insertion order; `findLast` makes later
+             *      named allows defeat the wildcard deny).
+             *   2. User-supplied `overrides.permission` is merged on top via
+             *      object-spread, so users CAN extend the allow-list in
+             *      `magic-context.jsonc` if they really need to grant more
+             *      tools to a hidden agent.
+             *   3. OpenCode then merges the runtime defaults (`Permission.merge(item.permission, Permission.fromConfig(value.permission ?? {}))` in
+             *      `packages/opencode/src/agent/agent.ts:306`) so OpenCode
+             *      user-config-level agent overrides win last.
+             */
             const buildHiddenAgentConfig = (
                 agentId: string,
                 prompt: string,
+                allowedTools: readonly string[],
                 overrides?: Record<string, unknown>,
-            ) => ({
-                prompt,
-                ...(getAgentFallbackModels(agentId)
-                    ? { fallback_models: getAgentFallbackModels(agentId) }
-                    : {}),
-                ...(overrides ?? {}),
-                mode: "subagent" as const,
-                hidden: true,
-            });
+            ) => {
+                const { permission: overridePermission, ...restOverrides } = (overrides ?? {}) as {
+                    permission?: Record<string, unknown>;
+                    [key: string]: unknown;
+                };
+                const basePermission = buildAllowOnlyPermission(allowedTools);
+                return {
+                    prompt,
+                    ...(getAgentFallbackModels(agentId)
+                        ? { fallback_models: getAgentFallbackModels(agentId) }
+                        : {}),
+                    ...restOverrides,
+                    // Permission baseline goes after `restOverrides` so that
+                    // accidental `permission` keys in user overrides we DIDN'T
+                    // explicitly destructure can't bypass the deny. The explicit
+                    // override (destructured above) is then layered on top.
+                    permission: {
+                        ...basePermission,
+                        ...(overridePermission ?? {}),
+                    },
+                    mode: "subagent" as const,
+                    hidden: true,
+                };
+            };
 
             const commandConfig = {
                 ...(config.command ?? {}),
@@ -360,23 +405,27 @@ const plugin: Plugin = async (ctx) => {
                 [DREAMER_AGENT]: buildHiddenAgentConfig(
                     DREAMER_AGENT,
                     DREAMER_SYSTEM_PROMPT,
+                    DREAMER_ALLOWED_TOOLS,
                     dreamerAgentOverrides,
                 ),
                 [HISTORIAN_AGENT]: buildHiddenAgentConfig(
                     HISTORIAN_AGENT,
                     pluginConfig.dreamer?.user_memories?.enabled
                         ? COMPARTMENT_AGENT_SYSTEM_PROMPT + USER_OBSERVATIONS_APPENDIX
                         : COMPARTMENT_AGENT_SYSTEM_PROMPT,
+                    HISTORIAN_ALLOWED_TOOLS,
                     historianAgentOverrides,
                 ),
                 [HISTORIAN_EDITOR_AGENT]: buildHiddenAgentConfig(
                     HISTORIAN_EDITOR_AGENT,
                     HISTORIAN_EDITOR_SYSTEM_PROMPT,
+                    HISTORIAN_ALLOWED_TOOLS,
                     historianAgentOverrides,
                 ),
                 [SIDEKICK_AGENT]: buildHiddenAgentConfig(
                     SIDEKICK_AGENT,
                     SIDEKICK_SYSTEM_PROMPT,
+                    SIDEKICK_ALLOWED_TOOLS,
                     sidekickAgentOverrides,
                 ),
             };
