feat(coding-agents): optInOnly — run memory only in projects that were opted in (#3433)

Closes #3427.

By default every project gets memory, which is what makes the plugin zero-setup.
For shared machines and client work that is the wrong default: unrelated
directories create banks nobody asked for, and there was no way to say "off
unless I name it".

  { "optInOnly": true, "optInPaths": ["~/work/client-x", "~/oss"] }

Anything outside those paths is inert — no bank created, nothing retained, no
seed — and the agent behaves as it would without the plugin.

Approval is deliberately separate from routing. `optInPaths` says WHICH PROJECTS,
not which bank, so an approved repo keeps its usual coding-agent::{gitProject}
name and approving costs no naming decisions. Paths are prefixes with `~`
expanded, so approving ~/work approves the repos under it while each still gets
its own bank. That is why this is not built on mapPathToBank, which the issue
reporter and I both first reached for: using it for approval forces you to name a
bank per project and collapses a whole tree into one.

A mapPathToBank entry does count as opted in — routing a path to a named bank
already declares that project. A bare bankId does not: it names a bank rather
than a project, so it cannot express which work may be remembered, and a privacy
switch has to fail closed.

Enforced through the `disabled` gate every entry point already checks after bank
resolution: applyBankConfig takes the directory the bank came from and returns a
disabled config when it is not opted in. That reuses a path already known to stop
a run before anything creates a bank, rather than adding a second thing nine call
sites must remember.

Verified end to end against a live server as well as in unit tests: an unlisted
project produced no plugin events and no bank, while an opted-in one under the
same config seeded, injected and retained normally.

Why not a `.hindsight.json` in the repo (the issue's Idea C): the config module
deliberately reads no repo-carried file, because an untrusted repository must not
be able to influence memory behaviour — and here it would let a cloned repo turn
memory ON, which is exactly backwards for a privacy control.

Author: nicoloboschi

hindsight-docs/docs-integrations/coding-agents.md

@@ -284,6 +284,32 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
 per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
 as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
 
+### Opt-in only
+
+By default every project gets memory — that is what makes the plugin zero-setup. If you would
+rather nothing be remembered until you say so, turn memory off everywhere and name the projects
+that may use it:
+
+```jsonc
+{
+  "optInOnly": true,
+  "optInPaths": ["~/work/client-x", "~/oss"],
+}
+```
+
+Anything outside those paths is **inert**: no bank is created, nothing is retained, no seed runs,
+and the agent behaves exactly as it would without the plugin. Approving costs nothing else —
+`optInPaths` says _which projects_, not _which bank_, so an approved repo keeps its usual
+`coding-agent::{gitProject}` name. Paths are prefixes, so approving `~/work` approves every repo
+under it while each still gets its own bank.
+
+A `mapPathToBank` entry counts as opted in too, since routing a path to a named bank already
+declares that project. A bare `bankId` does not: it names a bank rather than a project, so it
+cannot say which work may be remembered, and a privacy switch has to fail closed.
+
+There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
+cloned repository must not be able to turn memory on.
+
 There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
 per-agent differences are `harnesses.<name>`.
 
@@ -310,6 +336,8 @@ hook by Codex...), so one shared config serves several agents side by side:
 | `dynamicBankId`         | dynamic iff no `bankId`              | force dynamic (`true`) or static (`false`) resolution                                                                                                                                                                               |
 | `bankIdTemplate`        | `"coding-agent::{gitProject}"`       | dynamic bank id format; the default makes every agent share one bank per repo                                                                                                                                                       |
 | `mapPathToBank`         | —                                    | absolute path → bank; **longest prefix wins**; overrides everything                                                                                                                                                                 |
+| `optInOnly`             | `false`                              | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see Opt-in only                                                                                                              |
+| `optInPaths`            | —                                    | directories opted in, matched as prefixes with `~` expanded; each repo beneath keeps its own dynamic bank                                                                                                                           |
 | `resolveWorktrees`      | `true`                               | `{gitProject}`: linked worktrees share the main repo's bank                                                                                                                                                                         |
 | `retainTags`            | —                                    | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below                                                                                         |
 | `retainMetadata`        | —                                    | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}`                                                                                                                                        |

hindsight-integrations/coding-agents/README.md

@@ -277,6 +277,32 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
 per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
 as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
 
+### Opt-in only
+
+By default every project gets memory — that is what makes the plugin zero-setup. If you would
+rather nothing be remembered until you say so, turn memory off everywhere and name the projects
+that may use it:
+
+```jsonc
+{
+  "optInOnly": true,
+  "optInPaths": ["~/work/client-x", "~/oss"],
+}
+```
+
+Anything outside those paths is **inert**: no bank is created, nothing is retained, no seed runs,
+and the agent behaves exactly as it would without the plugin. Approving costs nothing else —
+`optInPaths` says _which projects_, not _which bank_, so an approved repo keeps its usual
+`coding-agent::{gitProject}` name. Paths are prefixes, so approving `~/work` approves every repo
+under it while each still gets its own bank.
+
+A `mapPathToBank` entry counts as opted in too, since routing a path to a named bank already
+declares that project. A bare `bankId` does not: it names a bank rather than a project, so it
+cannot say which work may be remembered, and a privacy switch has to fail closed.
+
+There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
+cloned repository must not be able to turn memory on.
+
 There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
 per-agent differences are `harnesses.<name>`.
 
@@ -303,6 +329,8 @@ hook by Codex...), so one shared config serves several agents side by side:
 | `dynamicBankId`         | dynamic iff no `bankId`              | force dynamic (`true`) or static (`false`) resolution                                                                                                                                                                               |
 | `bankIdTemplate`        | `"coding-agent::{gitProject}"`       | dynamic bank id format; the default makes every agent share one bank per repo                                                                                                                                                       |
 | `mapPathToBank`         | —                                    | absolute path → bank; **longest prefix wins**; overrides everything                                                                                                                                                                 |
+| `optInOnly`             | `false`                              | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only)                                                                                                              |
+| `optInPaths`            | —                                    | directories opted in, matched as prefixes with `~` expanded; each repo beneath keeps its own dynamic bank                                                                                                                           |
 | `resolveWorktrees`      | `true`                               | `{gitProject}`: linked worktrees share the main repo's bank                                                                                                                                                                         |
 | `retainTags`            | —                                    | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below                                                                                         |
 | `retainMetadata`        | —                                    | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}`                                                                                                                                        |

hindsight-integrations/coding-agents/src/antigravity-statusline.ts

@@ -19,7 +19,7 @@ export function buildAntigravityStatusLine(state: AntigravityStatusLineState, cf
   const cwd = state.cwd || state.workspace?.current_dir;
   if (!cwd) return brandWord();
 
-  const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, "antigravity-cli"));
+  const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, "antigravity-cli"), cwd);
   return resolved.cfg.disabled ? "" : `${brandWord()} · ${resolved.bankId}`;
 }
 

hindsight-integrations/coding-agents/src/cline.ts

@@ -185,7 +185,11 @@ export function createClineHooks(
 function createRuntime(workspaceRoot: string | undefined): RuntimeCore | undefined {
   let cfg = loadConfig({ harness: HARNESS });
   if (cfg.disabled) return undefined;
-  const resolved = applyBankConfig(cfg, deriveBankId(cfg, workspaceRoot || process.cwd(), HARNESS));
+  const resolved = applyBankConfig(
+    cfg,
+    deriveBankId(cfg, workspaceRoot || process.cwd(), HARNESS),
+    workspaceRoot || process.cwd()
+  );
   cfg = resolved.cfg;
   if (cfg.disabled) return undefined;
   const client = new HindsightClient({

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

@@ -32,6 +32,8 @@ export interface BankConfig {
   bankIdTemplate?: string;
   mapPathToBank?: Record<string, string>;
   resolveWorktrees?: boolean; // default true: worktrees share the main repo's bank
+  optInOnly?: boolean; // memory runs ONLY where opted in (see isOptedIn)
+  optInPaths?: string[]; // directories opted in, matched as prefixes
 }
 
 const DEFAULT_BANK_NAME = "coding";
@@ -123,20 +125,55 @@ function gitProjectName(directory: string, resolveWorktrees: boolean): string {
   return dirName(directory);
 }
 
+/** A configured directory, `~`-expanded and normalised, without a trailing separator. */
+function configuredDir(dir: string): string {
+  const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
+  return normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
+}
+
+/** Whether `directory` IS `configured`, or lives under it. */
+function isWithin(directory: string, configured: string): boolean {
+  return directory === configured || directory.startsWith(configured + sep);
+}
+
 /** Longest-prefix match of `directory` against the map's absolute paths (exact or ancestor). */
 function mapLookup(map: Record<string, string>, directory: string): string | undefined {
   const cwd = normalize(directory);
   let best: { len: number; bank: string } | undefined;
   for (const [dir, bank] of Object.entries(map)) {
-    const expanded = dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
-    const p = normalize(expanded).replace(new RegExp(`\\${sep}+$`), "");
-    if (cwd === p || cwd.startsWith(p + sep)) {
+    const p = configuredDir(dir);
+    if (isWithin(cwd, p)) {
       if (!best || p.length > best.len) best = { len: p.length, bank };
     }
   }
   return best?.bank;
 }
 
+/**
+ * Whether memory may run for this directory at all.
+ *
+ * Off by default: without `optInOnly` every project gets memory, which is what makes the plugin
+ * zero-setup. With it, the plugin stays inert — no bank, no retain, no seed — unless the directory
+ * was named on purpose, which means one of:
+ *
+ *   - it is under an `optInPaths` entry (prefix-matched, so approving a directory approves the
+ *     repos beneath it while each keeps its own dynamic bank), or
+ *   - it is under a `mapPathToBank` entry, since routing a path to a named bank is already a
+ *     deliberate declaration of that project.
+ *
+ * A bare `bankId` deliberately does NOT approve anything: it names a bank, not a project, so it
+ * cannot express which work is allowed to be remembered. Under `optInOnly` an unlisted project is
+ * inert even then — a privacy switch has to fail closed.
+ */
+export function isOptedIn(config: BankConfig, directory: string): boolean {
+  if (!config.optInOnly) return true;
+  if (!directory) return false;
+  const cwd = normalize(directory);
+  if ((config.optInPaths ?? []).some((dir) => dir && isWithin(cwd, configuredDir(dir))))
+    return true;
+  return Boolean(config.mapPathToBank && mapLookup(config.mapPathToBank, directory));
+}
+
 /** Derive the bank id for a working directory (see module doc for the resolution order). */
 export function deriveBankId(config: BankConfig, directory: string, harness = "coding"): string {
   const mapped =

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

@@ -15,6 +15,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { DEFAULT_SEED_LIMIT } from "./seed";
+import { isOptedIn } from "./bank";
 
 /** Default config-file path: ~/.hindsight/coding-agent.json */
 export // HINDSIGHT_CONFIG joins the two env exceptions (diag/log files): it points at THE config file,
@@ -63,6 +64,14 @@ export interface RawConfig {
   //   placeholders: {gitProject} {project} {harness} {channel} {user} (see core/bank.ts)
   mapPathToBank?: Record<string, string>; // absolute path -> bank; longest prefix wins; overrides everything
   resolveWorktrees?: boolean; // {gitProject}: worktrees share the main repo's bank (default true)
+  /** Run memory ONLY in projects that were opted in (default false: every project gets memory,
+   *  which is what makes the plugin zero-setup). With it on, an unlisted project is inert — no
+   *  bank is created, nothing is retained, no seed runs — so unrelated work leaves no trace. */
+  optInOnly?: boolean;
+  /** Directories opted in, matched as PREFIXES with `~` expanded: approving a directory approves
+   *  the repos beneath it, and each still gets its own dynamic bank. A `mapPathToBank` entry counts
+   *  as opted in too, since routing a path to a named bank already declares that project. */
+  optInPaths?: string[];
   harness?: string; // runtime adapter (default "opencode")
   disabled?: boolean; // hard off-switch — inert plugin, for a no-memory baseline (default false)
   retainSessions?: boolean; // opencode plugin write-back (default true; set false to opt out). Hook harnesses always write back on Stop and ignore this flag.
@@ -127,6 +136,8 @@ export interface Config {
   bankIdTemplate?: string;
   mapPathToBank?: Record<string, string>;
   resolveWorktrees?: boolean;
+  optInOnly: boolean;
+  optInPaths: string[];
   harness: string;
   disabled: boolean;
   retainSessions: boolean;
@@ -173,6 +184,11 @@ export function resolveConfig(raw: RawConfig = {}): Config {
     bankIdTemplate: raw.bankIdTemplate,
     mapPathToBank: raw.mapPathToBank,
     resolveWorktrees: raw.resolveWorktrees,
+    optInOnly: raw.optInOnly ?? false,
+    // Same shape as retainTags: a config typo must not become a path that silently approves nothing.
+    optInPaths: Array.isArray(raw.optInPaths)
+      ? raw.optInPaths.filter((p): p is string => typeof p === "string" && p.trim() !== "")
+      : [],
     harness: raw.harness ?? "opencode",
     disabled: raw.disabled ?? false,
     retainSessions: raw.retainSessions ?? true, // opencode: write back by default (parity with hook-harness Stop)
@@ -273,6 +289,8 @@ const ENV_KEYS = {
   dynamicBankId: "HINDSIGHT_DYNAMIC_BANK_ID",
   bankIdTemplate: "HINDSIGHT_BANK_ID_TEMPLATE",
   resolveWorktrees: "HINDSIGHT_RESOLVE_WORKTREES",
+  optInOnly: "HINDSIGHT_OPT_IN_ONLY",
+  optInPaths: "HINDSIGHT_OPT_IN_PATHS",
   harness: "HINDSIGHT_HARNESS",
   disabled: "HINDSIGHT_DISABLED",
   retainSessions: "HINDSIGHT_RETAIN_SESSIONS",
@@ -297,13 +315,14 @@ const ENV_KEYS = {
 const ENV_BOOLEANS = new Set<keyof RawConfig>([
   "dynamicBankId",
   "resolveWorktrees",
+  "optInOnly",
   "disabled",
   "retainSessions",
   "autoReflect",
   "autoSeed",
   "codebaseSurvey",
 ]);
-const ENV_LISTS = new Set<keyof RawConfig>(["retainTags"]);
+const ENV_LISTS = new Set<keyof RawConfig>(["retainTags", "optInPaths"]);
 const ENV_NUMBERS = new Set<keyof RawConfig>([
   "apiPort",
   "daemonIdleTimeout",
@@ -366,6 +385,10 @@ const BANK_OVERRIDE_EXCLUDED = [
   "mapPathToBank",
   "dynamicBankId",
   "resolveWorktrees",
+  // Approval is decided BEFORE the bank is resolved, so a `banks.<id>` section naming these could
+  // only ever arrive too late to matter — strip them rather than let them read as effective.
+  "optInOnly",
+  "optInPaths",
   "harness",
 ] as const;
 
@@ -374,7 +397,18 @@ const BANK_OVERRIDE_EXCLUDED = [
  * that runs AFTER bank resolution, giving per-repo opt-in/out (disable, retainSessions, gitIngest,
  * survey settings, ...) from the ONE global config file.
  */
-export function applyBankConfig(cfg: Config, resolvedId: string): { cfg: Config; bankId: string } {
+export function applyBankConfig(
+  cfg: Config,
+  resolvedId: string,
+  /** The directory the bank was resolved FROM. Supplying it enforces `optInOnly`; every entry
+   *  point already has it to hand, having just passed it to `deriveBankId`. */
+  directory?: string
+): { cfg: Config; bankId: string } {
+  // Rides the `disabled` gate every entry point already checks after bank resolution, rather than
+  // adding a second thing eight call sites must remember — and that gate is known to stop the run
+  // before anything creates a bank.
+  if (directory !== undefined && !isOptedIn(cfg, directory))
+    return { cfg: { ...cfg, disabled: true }, bankId: resolvedId };
   const section = cfg.banks[resolvedId];
   if (!section) return { cfg, bankId: resolvedId };
   const safe: Record<string, unknown> = { ...section };

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

@@ -228,7 +228,7 @@ export async function runHook(
   const out = (context: string | undefined, notice?: string) =>
     process.stdout.write(JSON.stringify(spec.emit(context ?? "", notice, ev)));
 
-  const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness));
+  const resolved = applyBankConfig(cfg, deriveBankId(cfg, cwd, spec.harness), cwd);
   cfg = resolved.cfg;
   const bankId = resolved.bankId;
   if (cfg.disabled) {