fix(coding-agents): run the opencode survey under our own agent, not plan mode (#3460)

* fix(coding-agents): run the opencode survey under our own agent, not plan mode

Fixes #3450.

The codebase survey ran as `opencode run --agent plan`, chosen as the read-only
boundary for a session that reads untrusted repo files. But plan mode is not a
permission boundary for what the survey needs to do — it is a PROMPT. Captured
from a live opencode 1.18.9 session (fake model endpoint, so this is the request
opencode actually builds, not an inference from behaviour), every user message
carries:

  CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase. STRICTLY FORBIDDEN:
  ANY file edits, modifications, or system changes ... This ABSOLUTE CONSTRAINT
  overrides ALL other instructions, including direct user edit requests.

while `hindsight_ingest_document` stays in the tool list — plan's ruleset denies
only `edit`. So the survey is handed a tool and told not to use it, and whether
the repo gets seeded depends on how literally the model reads "system changes".
#3450 saw it stall on ~half their repos, the agent asking for an approval plan
mode cannot grant even when the user says yes.

Wording cannot fix this: the reminder claims to override all other instructions,
and the reporter's transcript is the model saying exactly that back to them.

So the survey now runs under an agent this plugin defines itself, through
opencode's `config` hook — nothing lands in the user's opencode.json, and an
entry they defined under that name wins. Measured on the same rig:

  --agent plan             reminder in 9/9 captured requests
  --agent hindsight-survey reminder in 0, tools offered: glob, grep, read,
                           hindsight_ingest_document

It is also a TIGHTER sandbox than plan mode, which is what makes it safe for
untrusted repo content. opencode drops denied tools from the model's tool list
entirely, so `"*": "deny"` plus four allows is the boundary: no write, no bash,
and no `task` — plan left all three reachable, and `task` reaches a subagent that
can write. Probed live by asking the survey agent to create a file and to run
touch: both refused, neither file appeared.

Verified end to end against a live opencode with no agent in the user's config,
so the definition could only come from the plugin: 4 ingest calls per run.

* fix(coding-agents): pin the opencode config hook to the SDK's own Hooks type

Code review on the parent commit: nothing checked that `config` is a hook name
opencode actually calls. plugin-entry.ts casts the whole runtime object to the
host's Hooks type — the other hooks take deliberately narrower params than the
SDK declares, so they cannot be checked — which means a misnamed or re-signatured
hook would compile, silently never fire, and leave the survey invoking an agent
the host never heard of.

Declaring just this hook as `Pick<Hooks, "config">` restores the check where it
matters. Confirmed by renaming it: tsc now fails with "Object literal may only
specify known properties, but 'configg' does not exist in type
Pick<Hooks, "config">".

The one cast that remains is `permission`, which the published type models with a
fixed key set (edit/bash/webfetch/…) while the runtime takes arbitrary action
names — opencode's own built-in `explore` agent is defined with `"*": "deny"`
plus per-tool allows. Casting the agent entry beats widening it to `unknown`,
which would drop the checking on `description`/`mode` as well.

Re-verified against live opencode 1.18.9 after the change: 4 ingest calls, same
as before. 499 tests, tsc and prettier clean.

Author: nicoloboschi

hindsight-integrations/coding-agents/src/core/survey.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveClaudeBin, startCodebaseSurvey, SURVEY_PROMPT } from "./survey";
+import {
+  resolveClaudeBin,
+  startCodebaseSurvey,
+  SURVEY_AGENT,
+  SURVEY_AGENT_CONFIG,
+  SURVEY_PROMPT,
+} from "./survey";
 
 describe("resolveClaudeBin", () => {
   const ORIGINAL_ENV = process.env.HINDSIGHT_CLAUDE_BIN;
@@ -125,8 +131,8 @@ describe("startCodebaseSurvey", () => {
     expect(options.env.HINDSIGHT_DISABLE_HOOKS).toBe("1");
   });
 
-  // ── opencode recipe (read-only plan agent; tools from the loaded plugin) ───────────────────────
-  it("opencode: spawns `opencode run --agent plan` with the prompt", () => {
+  // ── opencode recipe (our own read-only agent; tools from the loaded plugin) ────────────────────
+  it("opencode: spawns `opencode run` under OUR survey agent, never the built-in plan agent", () => {
     const spawn = fakeSpawn();
     startCodebaseSurvey("/repo", {
       harness: "opencode",
@@ -135,10 +141,28 @@ describe("startCodebaseSurvey", () => {
     });
     const [bin, argv, options] = spawn.mock.calls[0];
     expect(bin).toBe("opencode");
-    expect(argv).toEqual(["run", "--agent", "plan", SURVEY_PROMPT]);
+    expect(argv).toEqual(["run", "--agent", SURVEY_AGENT, SURVEY_PROMPT]);
+    // `plan` appends a read-only system-reminder that talks models out of the ingest call the
+    // survey exists to make (#3450) — the whole point is not to run under it.
+    expect(argv).not.toContain("plan");
     expect(options.env.HINDSIGHT_DISABLE_HOOKS).toBe("1");
   });
 
+  // The recipe above is only safe because the agent it names is read-only. opencode drops denied
+  // tools from the model's tool list entirely, so this ruleset IS the sandbox.
+  it("the survey agent denies everything except reading and the one ingest tool", () => {
+    expect(SURVEY_AGENT_CONFIG.permission["*"]).toBe("deny");
+    expect(SURVEY_AGENT_CONFIG.permission.hindsight_ingest_document).toBe("allow");
+    const allowed = Object.entries(SURVEY_AGENT_CONFIG.permission)
+      .filter(([, v]) => v === "allow")
+      .map(([k]) => k)
+      .sort();
+    expect(allowed).toEqual(["glob", "grep", "hindsight_ingest_document", "read"]);
+    // No write, no bash, and no `task` — which would reach a subagent that CAN write.
+    for (const escape of ["write", "edit", "bash", "task", "patch"])
+      expect(SURVEY_AGENT_CONFIG.permission).not.toHaveProperty(escape, "allow");
+  });
+
   // ── agent selection + fallback ─────────────────────────────────────────────────────────────────
   it("honors the HINDSIGHT_CODEX_BIN override for the codex binary", () => {
     const spawn = fakeSpawn();

hindsight-integrations/coding-agents/src/core/survey.ts

@@ -17,8 +17,9 @@
  *   - codex  : `codex exec --sandbox read-only -c mcp_servers.hindsight…` (inline MCP, self-contained)
  *   - antigravity : `agy -p … --mode=plan --cwd <repo>` (read-only planning mode; MCP from the
  *                  global Antigravity customization config)
- *   - opencode: `opencode run --agent plan …` (read-only agent; tools from the loaded plugin, which
- *               under HINDSIGHT_DISABLE_HOOKS registers tools but skips seed/recall/write-back)
+ *   - opencode: `opencode run --agent hindsight-survey …` (a read-only agent OUR plugin defines —
+ *               see SURVEY_AGENT; tools from the loaded plugin, which under HINDSIGHT_DISABLE_HOOKS
+ *               registers tools but skips seed/recall/write-back)
  * Each is read-only sandboxed (prompt-injection safety, since the survey reads untrusted repo files)
  * and spawned with HINDSIGHT_DISABLE_HOOKS=1 so the survey's own session doesn't re-fire our hooks.
  *
@@ -58,6 +59,39 @@ export function resolveClaudeBin(explicit?: string): string {
   return "claude";
 }
 
+/**
+ * The opencode agent the survey runs under, defined by our own plugin (harness/opencode.ts feeds
+ * this to opencode's `config` hook) so the recipe below needs nothing in the user's opencode.json.
+ *
+ * It replaces the built-in `plan` agent, which was chosen as the read-only boundary but appends a
+ * system-reminder to every user message — "CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase
+ * … ANY file edits, modifications, or system changes … This ABSOLUTE CONSTRAINT overrides ALL other
+ * instructions" — while leaving plugin tools callable (plan denies only `edit`). The survey exists
+ * to call hindsight_ingest_document, which reads as a "system change", so completion came down to
+ * how literally a model took the reminder: #3450 saw the seed stall on ~half their repos, the agent
+ * asking for permission that plan mode cannot grant. Prompt wording cannot win that argument — the
+ * reminder claims to override all other instructions.
+ *
+ * The ruleset is also a TIGHTER boundary than plan's: opencode drops denied tools from the tool
+ * list entirely, so the session is offered exactly read/grep/glob plus the one ingest tool — no
+ * write, no bash, and no `task` (plan left all three reachable, and `task` reaches a subagent that
+ * CAN write). Verified against opencode 1.18.9.
+ */
+export const SURVEY_AGENT = "hindsight-survey";
+
+export const SURVEY_AGENT_CONFIG = {
+  description:
+    "One-time read-only structural survey that seeds this repository's Hindsight memory.",
+  mode: "primary",
+  permission: {
+    "*": "deny",
+    read: "allow",
+    grep: "allow",
+    glob: "allow",
+    hindsight_ingest_document: "allow",
+  },
+} as const;
+
 /** Resolve a harness's agent CLI binary: explicit `claudeBin` (claude only) -> `HINDSIGHT_<AGENT>_BIN`
  *  env override -> the bare command name (resolved on PATH at spawn time). */
 function resolveAgentBin(harness: SurveyHarness, claudeBin?: string): string {
@@ -232,13 +266,16 @@ function buildSurveyPlan(
       };
     }
     case "opencode": {
-      // `opencode run` under the read-only `plan` agent (the injection boundary). The hindsight tools
-      // come from the loaded plugin; under HINDSIGHT_DISABLE_HOOKS the plugin registers its tools but
-      // skips seed/recall/write-back (runtime.ts), so this survey run doesn't re-seed itself. Model
-      // left to opencode's configured default (its `provider/model` format differs per setup).
+      // `opencode run` under the survey agent OUR OWN PLUGIN defines (harness/opencode.ts), which
+      // is both the injection boundary and the reason the seed completes: the built-in `plan` agent
+      // used to fill that slot, but its read-only system-reminder talked models out of the ingest
+      // call the survey exists to make (#3450). The hindsight tools come from the loaded plugin;
+      // under HINDSIGHT_DISABLE_HOOKS it registers tools but skips seed/recall/write-back
+      // (runtime.ts), so this survey run doesn't re-seed itself. Model left to opencode's
+      // configured default (its `provider/model` format differs per setup).
       return {
         bin,
-        args: ["run", "--agent", "plan", SURVEY_PROMPT],
+        args: ["run", "--agent", SURVEY_AGENT, SURVEY_PROMPT],
         env,
       };
     }

hindsight-integrations/coding-agents/src/harness/opencode.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The opencode adapter's `config` hook: it teaches the host about the survey agent, so the recipe
+ * in core/survey.ts (`opencode run --agent hindsight-survey`) needs nothing in the user's
+ * opencode.json. See SURVEY_AGENT in core/survey.ts for why the built-in `plan` agent can't do it.
+ */
+import { describe, expect, it } from "vitest";
+import { opencodeAdapter } from "./opencode";
+import type { RuntimeCore } from "../core/runtime";
+import { SURVEY_AGENT, SURVEY_AGENT_CONFIG } from "../core/survey";
+
+/** Only the members createRuntime touches when it builds the hook object. */
+function fakeCore() {
+  return { harness: "opencode", toolSpecs: () => [] } as unknown as RuntimeCore;
+}
+
+type ConfigHook = (cfg: { agent?: Record<string, unknown> }) => Promise<void>;
+
+function configHook(): ConfigHook {
+  const runtime = opencodeAdapter.createRuntime(fakeCore()) as { config?: ConfigHook };
+  if (!runtime.config) throw new Error("adapter exposes no config hook");
+  return runtime.config;
+}
+
+describe("opencode config hook", () => {
+  it("defines the survey agent on a config that has no agents at all", async () => {
+    const cfg: { agent?: Record<string, unknown> } = {};
+    await configHook()(cfg);
+    expect(cfg.agent?.[SURVEY_AGENT]).toEqual(SURVEY_AGENT_CONFIG);
+  });
+
+  it("leaves the user's other agents alone", async () => {
+    const mine = { description: "mine" };
+    const cfg = { agent: { reviewer: mine } as Record<string, unknown> };
+    await configHook()(cfg);
+    expect(cfg.agent.reviewer).toBe(mine);
+    expect(cfg.agent[SURVEY_AGENT]).toEqual(SURVEY_AGENT_CONFIG);
+  });
+
+  it("does NOT overwrite a hindsight-survey agent the user defined themselves", async () => {
+    // Their file is the last word: someone who redefines this name has a reason, and silently
+    // replacing it would be a plugin overriding local config.
+    const theirs = { description: "customised", mode: "primary" };
+    const cfg = { agent: { [SURVEY_AGENT]: theirs } as Record<string, unknown> };
+    await configHook()(cfg);
+    expect(cfg.agent[SURVEY_AGENT]).toBe(theirs);
+  });
+});

hindsight-integrations/coding-agents/src/harness/opencode.ts

@@ -9,6 +9,7 @@
  * This is the only opencode-specific file; everything it uses is in ../core.
  */
 import { tool } from "@opencode-ai/plugin";
+import type { Config, Hooks } from "@opencode-ai/plugin";
 import type { RuntimeCore } from "../core/runtime";
 import type { HarnessAdapter } from "../core/types";
 import { diag } from "../core/diag";
@@ -19,10 +20,38 @@ import {
   type OcMessage,
 } from "../core/transcript-opencode";
 import { jsonChatReader } from "./registry";
+import { SURVEY_AGENT, SURVEY_AGENT_CONFIG } from "../core/survey";
 
 // opencode message part shape for the per-turn prompt (structurally typed).
 type Part = { type?: string; text?: string };
 
+/**
+ * Teach the host about the survey agent (core/survey.ts spawns `opencode run --agent
+ * hindsight-survey`), so the recipe needs nothing in the user's opencode.json.
+ *
+ * Declared as `Pick<Hooks, "config">` rather than inlined into the returned object, and that IS the
+ * point: plugin-entry.ts casts the whole runtime object to the host's Hooks type (the other hooks
+ * take deliberately narrower params than the SDK declares, so they cannot be checked), which means
+ * nothing would catch this hook being misnamed or its signature changing under us — it would just
+ * silently never fire, and the survey would die on an agent the host never heard of. Pinning this
+ * one hook to the SDK's own type restores that check where it matters.
+ */
+const surveyAgentHook: Pick<Hooks, "config"> = {
+  config: async (cfg: Config) => {
+    cfg.agent ??= {};
+    // Never overwrite an existing entry: a user who defined `hindsight-survey` themselves outranks
+    // us.
+    //
+    // The cast covers one field the published type under-describes: `permission` is declared with a
+    // fixed key set (edit/bash/webfetch/…), while the runtime takes arbitrary action names —
+    // opencode's own built-in `explore` agent is defined with `"*": "deny"` plus per-tool allows,
+    // and a live 1.18.9 session under this agent was offered exactly glob/grep/read/
+    // hindsight_ingest_document. Casting the entry beats widening it to `unknown`, which would drop
+    // the checking on `description`/`mode` too.
+    cfg.agent[SURVEY_AGENT] ??= SURVEY_AGENT_CONFIG as NonNullable<Config["agent"]>[string];
+  },
+};
+
 const textOf = (parts: Part[]) =>
   (parts || [])
     .filter((p) => p?.type === "text" && p.text)
@@ -64,6 +93,7 @@ function createRuntime(core: RuntimeCore) {
   for (const spec of core.toolSpecs()) tools[spec.name] = toOpencodeTool(spec);
 
   return {
+    ...surveyAgentHook,
     tool: tools,
     // Each user turn: recall on the prompt; the injection it builds is pushed by system.transform.
     "chat.message": async (input: { sessionID?: string }, output: { parts: Part[] }) => {