fix(opencode): allow aft_outline + aft_zoom for all hidden subagents

Adds the read-only AFT navigation tools to historian, dreamer, and
sidekick allow-lists. These are exactly the right shape for hidden
subagents that need to inspect code structure without dragging in
whole files: aft_outline returns a symbol-level outline, aft_zoom
returns the source of a single named symbol.

Per-agent rationale:

  - historian / historian-editor / compressor: can now verify a
    referenced symbol or skim file structure when writing accurate
    compartment summaries, without falling back to whole-file reads.

  - dreamer: the key-files identification prompt at
    features/magic-context/key-files/identify-key-files.ts:257-258
    already tells the model to use aft_outline / aft_zoom. Without
    them in the allow-list those calls would have been denied,
    which would silently regress the key-files identification task.

  - sidekick: can pull lightweight symbol-scoped context when the
    user's prompt references a specific file or symbol. Sidekick's
    read still stays denied — it should pull symbol-scoped views
    via aft_zoom, not arbitrary file contents.

Allow-lists now:

  HISTORIAN_ALLOWED_TOOLS = read, aft_outline, aft_zoom
  DREAMER_ALLOWED_TOOLS   = read, grep, glob, bash, aft_outline,
                            aft_zoom, ctx_memory, ctx_search, ctx_note
  SIDEKICK_ALLOWED_TOOLS  = ctx_search, ctx_memory, aft_outline,
                            aft_zoom

Tests updated and expanded: 1479 pass / 0 fail (+3 new aft assertions
across the three agents). Permission integration shape tests now
verify the exact final ruleset for each agent.

Author: ualtinok

packages/plugin/src/agents/permissions.test.ts

@@ -50,10 +50,18 @@ describe("buildAllowOnlyPermission", () => {
 });
 
 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("includes `read` (for state-file offload)", () => {
+        // Historian's primary tool need is reading the offloaded
+        // existing-state XML the runner writes to a temp file.
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("read");
+    });
+
+    it("includes `aft_outline` and `aft_zoom` for token-efficient repo navigation", () => {
+        // Read-only AFT navigation tools let historian/compressor verify
+        // a symbol or skim file structure when writing accurate
+        // compartment summaries without dragging in whole files.
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("aft_outline");
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("aft_zoom");
     });
 
     it("does NOT include `task` (the bug we're fixing — preventing subagent fanout)", () => {
@@ -65,6 +73,13 @@ describe("HISTORIAN_ALLOWED_TOOLS", () => {
             expect(HISTORIAN_ALLOWED_TOOLS).not.toContain(dangerous);
         }
     });
+
+    it("does NOT include `grep` or `glob` (historian summarizes, not explores)", () => {
+        // Historian's job is summarizing the input it was given.
+        // Repo-wide exploration belongs to dreamer / primary agents.
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("grep");
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("glob");
+    });
 });
 
 describe("DREAMER_ALLOWED_TOOLS", () => {
@@ -111,13 +126,25 @@ describe("DREAMER_ALLOWED_TOOLS", () => {
 });
 
 describe("SIDEKICK_ALLOWED_TOOLS", () => {
-    it("includes only ctx_search + ctx_memory (read-only memory retrieval)", () => {
+    it("includes ctx_search + ctx_memory for 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"]);
+        // prompt with relevant memories.
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("ctx_search");
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("ctx_memory");
+    });
+
+    it("includes `aft_outline` and `aft_zoom` for lightweight structural context", () => {
+        // Sidekick can pull file outline / symbol body when the user's
+        // prompt references a specific file or symbol, without dragging
+        // in whole files.
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("aft_outline");
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("aft_zoom");
     });
 
-    it("does NOT include `read` (sidekick doesn't touch the filesystem)", () => {
+    it("does NOT include `read` (use aft_outline/aft_zoom for navigation instead)", () => {
+        // Sidekick should pull symbol-scoped views, not arbitrary file
+        // contents. If it needs full source it can use aft_zoom on a
+        // specific symbol.
         expect(SIDEKICK_ALLOWED_TOOLS).not.toContain("read");
     });
 
@@ -129,34 +156,40 @@ describe("SIDEKICK_ALLOWED_TOOLS", () => {
 });
 
 describe("integration: full hidden-agent permission shape", () => {
-    it("historian permission object: `*` denied, only `read` allowed", () => {
+    it("historian permission object: `*` denied + read + aft_outline + aft_zoom allowed", () => {
         const perm = buildAllowOnlyPermission(HISTORIAN_ALLOWED_TOOLS);
         expect(perm).toEqual({
             "*": "deny",
             read: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
         });
     });
 
-    it("dreamer permission object: `*` denied + read + grep + glob + bash + ctx_* allowed", () => {
+    it("dreamer permission object: `*` denied + repo-exploration + ctx_* + aft_* allowed", () => {
         const perm = buildAllowOnlyPermission(DREAMER_ALLOWED_TOOLS);
         expect(perm).toEqual({
             "*": "deny",
             read: "allow",
             grep: "allow",
             glob: "allow",
             bash: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
             ctx_memory: "allow",
             ctx_search: "allow",
             ctx_note: "allow",
         });
     });
 
-    it("sidekick permission object: `*` denied + ctx_search + ctx_memory allowed", () => {
+    it("sidekick permission object: `*` denied + ctx_* + aft_* allowed", () => {
         const perm = buildAllowOnlyPermission(SIDEKICK_ALLOWED_TOOLS);
         expect(perm).toEqual({
             "*": "deny",
             ctx_search: "allow",
             ctx_memory: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
         });
     });
 });

packages/plugin/src/agents/permissions.ts

@@ -39,13 +39,16 @@
  *
  * # 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).
+ *   - **historian / historian-editor / compressor**: `read` plus the
+ *     read-only AFT navigation tools `aft_outline` and `aft_zoom`.
+ *     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. AFT navigation
+ *     is allowed so historian can verify a symbol or file structure
+ *     when writing accurate compartment summaries.
  *
- *   - **dreamer**: `read`, `grep`, `glob`, `bash`, plus the Magic
+ *   - **dreamer**: `read`, `grep`, `glob`, `bash`, the read-only AFT
+ *     navigation tools `aft_outline` and `aft_zoom`, plus the Magic
  *     Context MCP tools `ctx_memory`, `ctx_search`, `ctx_note`.
  *     Dreamer task prompts in
  *     `features/magic-context/dreamer/task-prompts.ts` explicitly tell
@@ -57,9 +60,12 @@
  *     `websearch` remain denied — dreamer must not spawn subagents
  *     or commit changes.
  *
- *   - **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`.
+ *   - **sidekick**: `ctx_search`, `ctx_memory`, plus the read-only AFT
+ *     navigation tools `aft_outline` and `aft_zoom`. Sidekick's job
+ *     is augmenting user prompts via memory retrieval — see
+ *     `features/magic-context/sidekick/agent.ts`. AFT navigation lets
+ *     it pull symbol-scoped structural context for prompts that
+ *     reference a specific file or symbol.
  */
 
 /**
@@ -86,11 +92,20 @@ export function buildAllowOnlyPermission(
 
 /**
  * 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.
+ * tell the model to `read` it before emitting the summary XML. The
+ * core need is `read`; we also allow the read-only AFT navigation
+ * tools `aft_outline` and `aft_zoom` so that if a historian/compressor
+ * ever needs to verify a symbol or skim a file's structure to write
+ * an accurate compartment summary, it can do so token-efficiently
+ * instead of pulling whole files via `read`.
+ *
+ * Still denied: bash, edit, write, task, grep/glob, webfetch/
+ * websearch. Historian's job is summarizing the input it was given,
+ * not exploring the repo.
  */
-export const HISTORIAN_ALLOWED_TOOLS = ["read"] as const;
+export const HISTORIAN_ALLOWED_TOOLS = ["read", "aft_outline", "aft_zoom"] as const;
 
 /**
  * Tools the dreamer agent needs. This is the broadest hidden-agent
@@ -125,6 +140,8 @@ export const DREAMER_ALLOWED_TOOLS = [
     "grep",
     "glob",
     "bash",
+    "aft_outline",
+    "aft_zoom",
     "ctx_memory",
     "ctx_search",
     "ctx_note",
@@ -134,7 +151,18 @@ export const DREAMER_ALLOWED_TOOLS = [
  * 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.
+ * `ctx_memory(action="list")`.
+ *
+ * Also allow `aft_outline` and `aft_zoom` so sidekick can pull
+ * lightweight structural context about a file or symbol when the
+ * user's prompt references it directly — token-efficient navigation
+ * without dragging in whole files.
+ *
+ * Still denied: spawning subagents, edits, bash, web fetches.
  */
-export const SIDEKICK_ALLOWED_TOOLS = ["ctx_search", "ctx_memory"] as const;
+export const SIDEKICK_ALLOWED_TOOLS = [
+    "ctx_search",
+    "ctx_memory",
+    "aft_outline",
+    "aft_zoom",
+] as const;