geneseed 3.2.0 → 3.4.0

package/js/hosts/hooks.mjs

@@ -1,9 +1,21 @@
 /**
- * The four HOOK verbs — `context`, `git-gate`, `rule-gate`, `learn` — in Node.
+ * The five HOOK verbs — `context`, `git-gate`, `rule-gate`, `tool-gate`, `learn` — in Node.
  *
  * These are the commands the emitted `settings.json` actually invokes on a user's machine,
- * every session: a SessionStart injector, two PreToolUse gates, and a Stop/SubagentStop
- * distiller. Since P5b they are also what the emitted hooks name: `bin/build-driver.mjs` bakes
+ * every session: a SessionStart injector, two PreToolUse gates (and `tool-gate`, the two
+ * fused for a host that runs ONE command per event), and a Stop/SubagentStop/PreCompact
+ * distiller.
+ *
+ * ONE VERB, TWO DIALECTS. `--host` names the host that will read the verdict. Claude Code
+ * (the default) reads `hookSpecificOutput.permissionDecision: "ask"` and shows the user a
+ * prompt. GitHub Copilot's `toolCall` hook has no ask tier — its stdout contract is
+ * `{"block": true|false}` — so on `--host copilot` the two Laws that admit no judgement call
+ * (I, IV) BLOCK and everything that was an ask (process 1, process 5, a gate error) is a
+ * warning on stderr, which Copilot logs. The same stance the OpenCode guard plugin takes
+ * where its `tool.execute.before` can only allow or throw. `--host bob` is Bob's own
+ * protocol: PreToolUse ignores stdout and refuses only on EXIT CODE 2, so the two Laws
+ * exit 2 with the reason on stderr and the rest is a stderr line with exit 0; SessionStart
+ * context is plain stdout, as on Claude. Since P5b they are also what the emitted hooks name: `bin/build-driver.mjs` bakes
  * `<node> <checkout>/bin/geneseed-hook.mjs` into the machine-wide shim, so an install this
  * driver emits has no Python in its hook path at all — which is what let the interpreter
  * discovery and its exit-4 refusal be deleted rather than merely bypassed.
@@ -31,7 +43,8 @@
  * and every file left behind. Absolute rather than compared is what let it survive the deletion
  * of the implementation it was once compared against.
  */
-import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, realpathSync }
+import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, realpathSync,
+  appendFileSync, writeFileSync }
   from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -43,7 +56,7 @@ import { NO_WINDOW } from '../lib/proc.mjs';
 // module to find it: the CLI is under a hard transitive `child_process` ban and `learn`
 // spawns. So the resolver has one owner in `js/hosts/hosts.mjs` rather than a second copy — and
 // with it went this file's private `opencodeConfigDir`, whose only caller it was.
-import { resolveMemoryDir, expanduser } from './hosts.mjs';
+import { resolveMemoryDir, expanduser, sovereignBypass } from './hosts.mjs';
 
 const ROOT = path.resolve(import.meta.dirname, '../..');
 
@@ -72,10 +85,12 @@ const ROOT = path.resolve(import.meta.dirname, '../..');
 // an adjudicated product decision (`TheTildeUserFormIsADeliberateDivergence`) that the hook
 // was quietly exempt from because it had a private copy. It now imports the owner. The
 // refusal throws, so `sovereignBypass` and `cmdContext` below contain it per entry / per
-// call: a hook that CRASHES reports success, because these gates exit 0 and signal on
-// stdout, so "the gate blew up" and "the gate found nothing" are the same observation to
-// Claude. `resolvePath` just below is the THIRD copy of a primitive `js/hosts/hosts.mjs` also
-// exports, and is the next item in this series.
+// call. For the two GATES that containment is not enough, and `guardGate` below is the
+// contract: these verbs exit 0 and signal on stdout, so "the gate blew up" and "the gate
+// found nothing" would be the SAME observation to Claude — a crash would be a silent allow.
+// A gate that cannot evaluate a call therefore asks, and says why. `resolvePath` just below
+// is the THIRD copy of a primitive `js/hosts/hosts.mjs` also exports, and is the next item
+// in this series.
 
 /**
  * `Path(p).resolve()` — absolute, symlinks followed, and the filesystem's OWN casing.
@@ -229,7 +244,6 @@ const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor',
 
 const CLAUDE_MARKERS = ['.claude', '.bob'];
 const GENESEED_MANIFEST = '.geneseed-manifest.json';
-const EXCLUDES_FILE = 'excludes.json';
 
 /**
  * `_global_hook_standing_down` — project-bypasses-global.
@@ -252,52 +266,10 @@ export function globalHookStandingDown(hookRoot, cwd) {
   return false;
 }
 
-/**
- * `sovereign_bypass` — the user's own excludes.json, read on EVERY hook call so an edit
- * takes effect without a re-emit. Every failure mode degrades to false: a hook must never
- * fail or block on a file the user owns.
- */
-export function sovereignBypass(root) {
-  if (!root) return false;
-  let entries;
-  try {
-    const data = JSON.parse(readText(path.join(root, EXCLUDES_FILE)));
-    entries = Array.isArray(data && data.excludes) ? data.excludes : [];
-  } catch {
-    return false;
-  }
-  let cwd;
-  try {
-    cwd = normcase(resolvePath(process.cwd()));
-  } catch {
-    return false;
-  }
-  for (const entry of entries) {
-    const raw = (entry && typeof entry === 'object' ? entry.path : entry) || '';
-    if (typeof raw !== 'string' || !raw.trim()) continue;
-    let base;
-    try {
-      // `.rstrip("\\/")` AFTER normcase, exactly as the Python orders it, so the separator
-      // test below cannot be fooled by a trailing slash in the user's file.
-      //
-      // `withDiscardableStderr` because `expanduser` writes its refusal at the RAISE SITE
-      // and this caller catches: the reference prints nothing here, so replaying the
-      // message would be a stderr divergence on every hook call for one bad entry.
-      base = withDiscardableStderr(
-        () => normcase(toPlatformPath(expanduser(raw.trim()))).replace(/[\\/]+$/, ''));
-    } catch {
-      // PER ENTRY, and the loop continues. One unusable line in a file the USER hand-edits
-      // must not decide the whole function — `expanduser` refuses a `~user` form, and the
-      // reference's `Path.expanduser()` raises RuntimeError on the same input on POSIX.
-      // Skipping errs toward the gate staying ACTIVE, which is the safe direction: this
-      // feeds `git-gate`/`rule-gate`, which exit 0 and signal on stdout, so a crash here
-      // would read as a clean pass while gating nothing.
-      continue;
-    }
-    if (cwd === base || cwd.startsWith(base + path.sep)) return true;
-  }
-  return false;
-}
+// `sovereignBypass` moved to `./hosts.mjs` so `status` can read it without importing this
+// module's `child_process` binding; re-exported because the tests and the excludes writer's
+// docblock name it here.
+export { sovereignBypass };
 
 /** `_disp` — relative to the repo root when it sits under it, else verbatim. */
 function disp(pathStr, root) {
@@ -469,6 +441,7 @@ export function resolveContextSets(root) {
 }
 
 export function cmdContext(args) {
+  setHost(args);
   // Discovery runs against the project root the hook was launched from — Claude runs
   // SessionStart hooks with cwd = repo root — not the harness package dir.
   // The only two `resolvePath` calls in this file whose argument can be a `~user` path the
@@ -523,7 +496,12 @@ export function cmdContext(args) {
     lines.push('');
   }
 
-  out(`${lines.join('\n')}\n`);
+  // Claude Code takes a SessionStart hook's plain stdout as context. Copilot's `sessionStart`
+  // wants a JSON document and reads `additionalContext` out of it; plain text there would be
+  // parsed as nothing and silently dropped.
+  // Bob reads a SessionStart hook's stdout as context exactly as Claude does.
+  const text = `${lines.join('\n')}\n`;
+  out(HOST === 'copilot' ? `${jsonDumpsCompact({ additionalContext: text })}\n` : text);
   return 0;
 }
 
@@ -537,6 +515,15 @@ export function cmdContext(args) {
 // one line and a `commit` on the next are two commands, not one.
 const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/;
 
+// Law IV's boundary half: the git verbs that rewrite or discard history. Law IX (now rigor 5)
+// says a rule in a prompt is a request and a rule at a boundary is a constraint; before this
+// regex the harness enforced one doctrine rule and no law. `checkout --` is listed because it
+// reverts to the INDEX and eats unstaged work; `checkout <branch>` is not. `clean -f` matches
+// any flag cluster carrying `f` (`-fd`, `-xf`) and never `-n`. `push --force*` trips this gate
+// rather than process 5's so the stronger reason is the one the user reads.
+const DESTRUCTIVE_GIT_RE =
+  /\bgit\b[^\n]*\b(?:reset\s+--hard|clean\s+-[a-zA-Z]*f|branch\s+-D|checkout\s+--\s|push\s+[^\n]*--force)/;
+
 /** The `permissionDecision: "ask"` document, in Python's compact `json.dumps` spelling. */
 function askDecision(reason) {
   return `${jsonDumpsCompact({
@@ -548,21 +535,162 @@ function askDecision(reason) {
   })}\n`;
 }
 
-export function cmdGitGate(args) {
-  if (sovereignBypass(args.root)) return 0;
-  let command;
+/**
+ * The host reading this process's verdict — `--host` on the emitted command, `claude` when
+ * absent. Module state rather than a parameter because a hook process answers exactly one
+ * call: set once at the verb's entry (`guardGate`, `cmdContext`), read where the output
+ * dialect is chosen.
+ */
+let HOST = 'claude';
+const setHost = (args) => { HOST = (args && args.host) || 'claude'; };
+
+/** Copilot's `toolCall` verdict: `{"block": true}` plus the reason it displays. */
+function blockDecision(reason) {
+  return `${jsonDumpsCompact({ block: true, reason })}\n`;
+}
+
+/**
+ * Bob's PreToolUse protocol: stdout is ignored and EXIT CODE 2 is the one refusal. The
+ * single exception to "every gate exits 0" in this file, confined to `--host bob` — on
+ * Claude Code a non-zero exit is a broken hook, on Bob it is the verdict.
+ */
+const BOB_DENY_EXIT = 2;
+
+/**
+ * On a host with no ask tier, which rules are worth a hard block. Laws I and IV: a
+ * credential in a tracked file and a history-discarding git act are wrong in every context,
+ * so refusing them costs nothing. Process 1 and process 5 are the USER's calls — a hard
+ * block would make Copilot unable to commit at all — so they become a warning the host
+ * logs. `gate-error` is a warning too: a crashed gate that blocked every tool call would be
+ * a lockout, not a safeguard, and there is no prompt through which the user could clear it.
+ */
+const BLOCK_RULES = new Set(['law-1', 'law-4']);
+
+/** Where the gate ledger lives inside an install: the notebook is the agent's own, gitignored space. */
+export const GATE_LEDGER = path.join('notebook', 'gates.jsonl');
+
+/**
+ * THE GATE LEDGER — one JSON line per ask, nothing per defer.
+ *
+ * The gates are the only mechanical enforcement the harness has, and until this line
+ * nothing recorded whether they ever fired: no way to tell whether Law I has caught a secret
+ * this year, or whether the process 5 prompt is signal or noise. `status` counts these by
+ * rule. It records the RULE, never the command or the content that tripped it — a ledger
+ * that stored the string Law I caught would itself be a place a secret lands. And it records
+ * only `asked`: the host never tells a hook how the user answered, so a `decided` column
+ * would be a claim the hook cannot make. Written only on the ask path, which is the rare
+ * one; the defer path — every other tool call — pays nothing. A ledger that cannot be
+ * written must never change the decision, hence the swallow.
+ *
+ * Capped at the newest MAX_LEDGER_LINES, like the agent lessons and the notes beside it: an
+ * install lives for months and `status` only ever counts, so the oldest asks carry no
+ * information a trimmed file loses. The re-read happens on the ask path only.
+ */
+const MAX_LEDGER_LINES = 1000;
+function ledger(root, verb, rule) {
+  if (!root) return;
   try {
-    const payload = JSON.parse(readStdin() || '{}');
-    command = ((payload && payload.tool_input) || {}).command;
-  } catch {
+    const file = path.join(root, GATE_LEDGER);
+    appendFileSync(file, `${JSON.stringify({
+      ts: new Date().toISOString(), verb, rule, cwd: process.cwd(),
+    })}\n`);
+    const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > MAX_LEDGER_LINES) {
+      writeFileSync(file, `${lines.slice(-MAX_LEDGER_LINES).join('\n')}\n`);
+    }
+  } catch { /* see above: the ledger never decides */ }
+}
+
+/**
+ * Ask, and record that we asked. Every ask site goes through here so none can skip the
+ * ledger. On `--host copilot` the ask becomes a block or a warning (see `BLOCK_RULES`); the
+ * ledger records the block, never the warning — a warning asked nothing of anyone.
+ */
+function ask(args, verb, rule, reason) {
+  if (HOST === 'copilot' || HOST === 'bob') {
+    if (!BLOCK_RULES.has(rule)) {
+      // Neither host has an ask tier; a stderr line is the nudge, and the call goes through.
+      err(`[geneseed] ${reason}\n`);
+      return 0;
+    }
+    ledger(args && args.root, verb, rule);
+    if (HOST === 'bob') {
+      // stdout is not read on Bob's PreToolUse; the reason goes where Bob's hook log looks.
+      err(`[geneseed] BLOCKED: ${reason}\n`);
+      return BOB_DENY_EXIT;
+    }
+    out(blockDecision(reason));
     return 0;
   }
-  if (typeof command !== 'string' || !GIT_GATE_RE.test(command)) return 0;
-  out(askDecision('Geneseed Doctrine process 5 \u2014 every git commit/push needs explicit '
-    + 'approval'));
+  ledger(args && args.root, verb, rule);
+  out(askDecision(reason));
   return 0;
 }
 
+/**
+ * FAIL CLOSED. Wraps a gate verb so that any throw — a payload that is not JSON, a path
+ * primitive refusing a form, a bug — becomes an `ask` carrying the error, never a silent
+ * allow. The host reads exit 0 + empty stdout as "the gate deferred", which is exactly what a
+ * crashed gate would otherwise look like. A well-formed ABSENCE (empty stdin, `{}`, a null
+ * `tool_input`) is still a defer: there is nothing to evaluate, and asking on every
+ * hand-run invocation would teach the user to allow-list the gate.
+ */
+export function guardGate(fn, verb = 'gate') {
+  return (args) => {
+    setHost(args);
+    try {
+      return fn(args);
+    } catch (e) {
+      const why = e && e.message ? e.message : String(e);
+      return ask(args, verb, 'gate-error', `Geneseed gate error — ${why}. The gate could `
+        + 'not evaluate this call, so it does not defer.');
+    }
+  };
+}
+
+/**
+ * The hook payload on stdin, or null for a well-formed absence. Not-JSON THROWS.
+ *
+ * Copilot spells the same payload in camelCase — `toolName`/`toolInput` where Claude sends
+ * `tool_name`/`tool_input` — and fires `toolCall` both before AND after the tool runs
+ * (`phase`). The field names are folded to Claude's so every gate reads one shape; the
+ * `after` phase is a well-formed absence, since there is nothing left to gate.
+ */
+function readPayload() {
+  const raw = readStdin();
+  if (!raw.trim()) return null;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error('the hook payload on stdin is not JSON');
+  }
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.phase === 'after') return null;
+  if (payload.tool_input === undefined && payload.toolInput !== undefined) {
+    payload.tool_input = payload.toolInput;
+  }
+  return payload;
+}
+
+function gitGate(args) {
+  if (sovereignBypass(args.root)) return 0;
+  return gitDecide(args, readPayload());
+}
+
+function gitDecide(args, payload) {
+  const command = ((payload && payload.tool_input) || {}).command;
+  if (typeof command !== 'string') return 0;
+  if (DESTRUCTIVE_GIT_RE.test(command)) {
+    return ask(args, 'git-gate', 'law-4', 'Geneseed Law IV \u2014 a history-rewriting or '
+      + 'discarding git act needs confirmation bound to this specific command');
+  }
+  if (!GIT_GATE_RE.test(command)) return 0;
+  return ask(args, 'git-gate', 'process-5', 'Geneseed Doctrine process 5 \u2014 every git '
+    + 'commit/push needs explicit approval');
+}
+export const cmdGitGate = guardGate(gitGate, 'git-gate');
+
 // ======================================================================================
 // rule-gate — Doctrine process 1's tool-boundary backstop
 // ======================================================================================
@@ -595,23 +723,57 @@ function ruleGateTarget(p, root) {
   }
 }
 
-export function cmdRuleGate(args) {
+// Law I's boundary half. High-precision vendor prefixes only — a generic "looks like entropy"
+// scan would fire on every hash and lockfile, and a gate that cries wolf gets allow-listed.
+// `.env*` is exempt because Law I names it as the place a secret may live.
+const SECRET_RE =
+  /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const DOTENV_RE = /(^|[\\/])\.env(\.[^\\/]*)?$/;
+
+function ruleGate(args) {
   if (sovereignBypass(args.root)) return 0;
-  let p;
-  try {
-    const payload = JSON.parse(readStdin() || '{}');
-    const ti = (payload && payload.tool_input) || {};
-    p = ti.file_path || ti.path || '';
-  } catch {
-    return 0;
-  }
+  return ruleDecide(args, readPayload());
+}
+
+function ruleDecide(args, payload) {
+  const ti = (payload && payload.tool_input) || {};
+  const p = ti.file_path || ti.path || '';
   if (typeof p !== 'string' || !p) return 0;
+  // Write carries `content`, Edit carries `new_string`; either can plant a credential.
+  const body = typeof ti.content === 'string' ? ti.content
+    : typeof ti.new_string === 'string' ? ti.new_string : '';
+  if (body && !DOTENV_RE.test(p) && SECRET_RE.test(body)) {
+    return ask(args, 'rule-gate', 'law-1', `Geneseed Law I — ${p} would carry a `
+      + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
+      + 'tracked file.');
+  }
   const target = ruleGateTarget(p, args.root);
   if (!target) return 0;
-  out(askDecision(`Geneseed Doctrine process 1 \u2014 writing to ${target}: a standing rule, or a `
-    + "fact to remember? That choice is the user's. Run the rule skill first."));
-  return 0;
+  return ask(args, 'rule-gate', 'process-1', `Geneseed Doctrine process 1 \u2014 writing to `
+    + `${target}: a standing rule, or a fact to remember? That choice is the user's. Run the `
+    + 'rule skill first.');
+}
+export const cmdRuleGate = guardGate(ruleGate, 'rule-gate');
+
+// ======================================================================================
+// tool-gate — both gates behind one command
+// ======================================================================================
+
+/**
+ * Copilot's settings carry ONE command per hook event, not a list of matcher groups, so
+ * its `toolCall` hook cannot name `git-gate` for Bash and `rule-gate` for Write the way
+ * Claude's `PreToolUse` does. This verb is the two fused, dispatched on the payload rather
+ * than on a matcher: a `command` field is a shell call and gets the git checks, a path
+ * field is a write and gets the rule checks. Nothing here decides anything the two named
+ * gates do not — it only removes the need for a matcher the host does not have.
+ */
+function toolGate(args) {
+  if (sovereignBypass(args.root)) return 0;
+  const payload = readPayload();
+  const ti = (payload && payload.tool_input) || {};
+  return typeof ti.command === 'string' ? gitDecide(args, payload) : ruleDecide(args, payload);
 }
+export const cmdToolGate = guardGate(toolGate, 'tool-gate');
 
 // ======================================================================================
 // learn — distil notes/transcripts into deduped memory entries

package/js/hosts/hosts.mjs

@@ -17,12 +17,66 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { printErr, withDiscardableStderr, isDir } from '../lib/fs.mjs';
-import { toPlatformPath } from '../lib/paths.mjs';
+import { printErr, withDiscardableStderr, isDir, readText } from '../lib/fs.mjs';
+import { toPlatformPath, normcase } from '../lib/paths.mjs';
 
 /** `_build_global.GLOBAL_MANIFEST` — the file whose presence means "a global install". */
 export const GLOBAL_MANIFEST = '.geneseed-manifest.json';
 
+/** The user's own per-install exclusion list; `js/build/stubs.mjs` seeds it, this file reads it. */
+export const EXCLUDES_FILE = 'excludes.json';
+
+/**
+ * `sovereign_bypass` — the user's own excludes.json, read on EVERY hook call so an edit
+ * takes effect without a re-emit. Every failure mode degrades to false: a hook must never
+ * fail or block on a file the user owns.
+ *
+ * LIVES HERE, NOT IN `hooks.mjs`, because two readers need it and only one of them may pay
+ * for the other: the hook (hot path, already imports this module) and `status` (the CLI,
+ * under the transitive `child_process` ban that `hooks.mjs`'s `learn` verb breaks). A
+ * second copy in `js/inspect/` was the alternative, and a copy is what let the `~user`
+ * refusal diverge between the two CLIs once already (see `hooks.mjs`'s header).
+ */
+export function sovereignBypass(root) {
+  if (!root) return false;
+  let entries;
+  try {
+    const data = JSON.parse(readText(path.join(root, EXCLUDES_FILE)));
+    entries = Array.isArray(data && data.excludes) ? data.excludes : [];
+  } catch {
+    return false;
+  }
+  let cwd;
+  try {
+    cwd = normcase(resolvePath(process.cwd()));
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const raw = (entry && typeof entry === 'object' ? entry.path : entry) || '';
+    if (typeof raw !== 'string' || !raw.trim()) continue;
+    let base;
+    try {
+      // `.rstrip("\\/")` AFTER normcase, exactly as the Python orders it, so the separator
+      // test below cannot be fooled by a trailing slash in the user's file.
+      //
+      // `withDiscardableStderr` because `expanduser` writes its refusal at the RAISE SITE
+      // and this caller catches: the reference prints nothing here, so replaying the
+      // message would be a stderr divergence on every hook call for one bad entry.
+      base = withDiscardableStderr(
+        () => normcase(toPlatformPath(expanduser(raw.trim()))).replace(/[\\/]+$/, ''));
+    } catch {
+      // PER ENTRY, and the loop continues. One unusable line in a file the USER hand-edits
+      // must not decide the whole function — `expanduser` refuses a `~user` form, and the
+      // reference's `Path.expanduser()` raises RuntimeError on the same input on POSIX.
+      // Skipping errs toward the gate staying ACTIVE, which is the safe direction.
+      continue;
+    }
+    if (cwd === base || cwd.startsWith(base + path.sep)) return true;
+  }
+  return false;
+}
+
 /**
  * `_build_core.VERSION_MARKER`. Third caller, so it moves here — `js/build/version.mjs` and
  * `js/inspect/diff.mjs` each had a private const of their own and `js/maintain/uninstall.mjs` would have made

package/js/hosts/link.mjs

@@ -24,7 +24,7 @@
  * The second removes a working feature from every GIT-CHECKOUT user — for whom `link` is
  * the only thing that puts `geneseed` on PATH, because there is no package manager in that
  * story — in order to spare npm users a duplicate. It also spends a `web/dist` rebuild on a
- * deletion. So: they ship, they port, and `NOT_PORTED_ACTIONS` empties.
+ * deletion. So: they ship, and they port.
  *
  * The npm duplication is left as it is rather than papered over with a new "you already have
  * this" refusal: that would be a REDESIGN of the verb, the reference has no such arm, and a

package/js/hosts/mcp.mjs

@@ -244,8 +244,10 @@ export function mcpConfigFor(host, scope, root) {
       : resolvePath(path.join(os.homedir(), '.claude.json'));
   }
   if (host === 'bob') {
+    // Nested at global scope, as Bob's hooks doc places the global file (and as the emit
+    // now writes it); the project file is flat.
     return scope === 'project' ? path.join(root, '.bob', 'settings.json')
-      : path.join(bobConfigDir(), 'settings.json');
+      : path.join(bobConfigDir(), 'settings', 'settings.json');
   }
   if (host === 'copilot') {
     // The Copilot CLI reads MCP servers from ~/.copilot/mcp-config.json only — no per-repo

package/js/hosts/native.mjs

@@ -112,6 +112,53 @@ export function descOf(text) {
   return firstBlockquote(text);
 }
 
+/**
+ * The `**Trigger:**` paragraph of a skill, flattened to one line — markdown links reduced
+ * to their text, HTML comments dropped, whitespace collapsed. '' when the skill has none.
+ *
+ * Why it exists: on Claude Code (and Bob) the frontmatter `description:` is the ONLY text
+ * the model matches a task against before deciding to load a skill. The purpose line says
+ * what a skill does; the trigger says WHEN — and a catalogue of purposes alone left the
+ * model choosing `tdd` from "Drive implementation with tests" without ever seeing "before
+ * writing implementation code". The AGENT.md §4 table carried the triggers, but native
+ * hosts collapse that table to a pointer (`hostCatalogsNatively`), so the trigger reached
+ * no host at all. `skillDescription` below concatenates the two.
+ */
+export function triggerOf(text) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((ln) => /^\*\*Trigger:\*\*/.test(ln.trim()));
+  if (start < 0) return '';
+  const para = [];
+  for (let i = start; i < lines.length; i += 1) {
+    const s = lines[i].trim();
+    if (i > start && (s === '' || s.startsWith('#') || s.startsWith('**'))) break;
+    para.push(s);
+  }
+  return para.join(' ')
+    .replace(/^\*\*Trigger:\*\*\s*/, '')
+    .replace(HTML_COMMENT_RE, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Purpose + trigger, the emitted `description:` of a skill. Capped so a long trigger (a
+ * few carry three sentences of disambiguation) cannot blow past what hosts display —
+ * cut at the last sentence end inside the cap, never mid-word.
+ */
+const DESCRIPTION_CAP = 900;
+export function skillDescription(text) {
+  const desc = descOf(text);
+  const trig = triggerOf(text);
+  if (!trig) return desc;
+  const full = `${desc} Use when: ${trig}`;
+  if (full.length <= DESCRIPTION_CAP) return full;
+  const cut = full.slice(0, DESCRIPTION_CAP);
+  const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('; '));
+  return end > desc.length ? cut.slice(0, end + 1) : cut.replace(/\s+\S*$/, '') + '…';
+}
+
 /** `_build_render._HTML_COMMENT_RE`. */
 const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
 
@@ -149,6 +196,20 @@ function isReadonly(text) {
   return text.includes('Read-only');
 }
 
+/**
+ * A skill only the USER may open. The marker is an HTML comment in the source spec
+ * (`<!-- invocation: user -->`, placed under the purpose blockquote), and it renders to
+ * Claude Code's `disable-model-invocation: true`: the skill still answers `/name`, but its
+ * description leaves the model's always-on catalogue and the model never self-triggers it.
+ * Same precedent as `isReadonly` — a phrase in the spec, not a second manifest to keep in
+ * step. Which skills carry it is an authoring decision: the teaching skills a human runs on
+ * themselves, and the ones gated on an environment the model cannot see (a herdr pane).
+ */
+const USER_INVOKED_RE = /<!--\s*invocation:\s*user\s*-->/;
+export function isUserInvokedOnly(text) {
+  return USER_INVOKED_RE.test(text);
+}
+
 /** `_build_emit._strip_skill_body_links`. */
 export function stripSkillBodyLinks(body) {
   return body.replace(SKILL_BODY_LINK_RE, '$1');
@@ -230,22 +291,28 @@ export function pushOverrideLines(fm, ov) {
   if (given(ov.steps)) fm.push(`steps: ${formatValue(ov.steps)}`);
 }
 
+/** The two opt-in markers a read-only spec may carry. Bare substring tests, like `isReadonly`. */
+const BASH_MARKER = '<!-- bash: allow -->';
+const WEBFETCH_MARKER = '<!-- webfetch: allow -->';
+
 /**
  * The readonly-tool line `claudeAgentFrontmatter`/`copilotAgentFrontmatter` each emit — a
  * DENYLIST for Claude, an ALLOWLIST for Copilot — differing only in the key, the base list,
- * the one extra entry the `<!-- bash: allow -->` marker toggles, and whether the value is
- * bracketed. `extraWhenBashAllowed` is `false` for Claude (Bash is denied UNLESS the marker
- * allows it) and `true` for Copilot (`execute` is allowed ONLY IF the marker is present) —
- * the same marker, read in the opposite sense a denylist and an allowlist require.
+ * the gated entries the markers toggle, and whether the value is bracketed. Each `gated`
+ * row is `[tool, marker, listedWhenMarked]`: `false` for Claude (the tool is denied UNLESS
+ * the marker allows it) and `true` for Copilot (the tool is allowed ONLY IF the marker is
+ * present) — the same marker, read in the opposite sense a denylist and an allowlist
+ * require. Row order is emit order: WebFetch before Bash keeps the unmarked Claude line
+ * byte-identical to what it was before the webfetch marker existed.
  */
 const READONLY_TOOLS = {
   claude: {
-    key: 'disallowedTools', tools: ['Write', 'Edit', 'NotebookEdit', 'WebFetch'],
-    extra: 'Bash', extraWhenBashAllowed: false, brackets: false,
+    key: 'disallowedTools', tools: ['Write', 'Edit', 'NotebookEdit'], brackets: false,
+    gated: [['WebFetch', WEBFETCH_MARKER, false], ['Bash', BASH_MARKER, false]],
   },
   copilot: {
-    key: 'tools', tools: ['read', 'search', 'todo', 'agent'],
-    extra: 'execute', extraWhenBashAllowed: true, brackets: true,
+    key: 'tools', tools: ['read', 'search', 'todo', 'agent'], brackets: true,
+    gated: [['fetch', WEBFETCH_MARKER, true], ['execute', BASH_MARKER, true]],
   },
 };
 
@@ -255,11 +322,11 @@ function claudeCopilotAgentFrontmatter(host, stem, text, overrides) {
   const ov = agentOverride(overrides, stem);
   if (isTruthy(ov.model)) fm.push(`model: ${formatValue(ov.model)}`);
   if (isReadonly(text)) {
-    const {
-      key, tools, extra, extraWhenBashAllowed, brackets,
-    } = READONLY_TOOLS[host];
+    const { key, tools, brackets, gated } = READONLY_TOOLS[host];
     const list = [...tools];
-    if (text.includes('<!-- bash: allow -->') === extraWhenBashAllowed) list.push(extra);
+    for (const [tool, marker, listedWhenMarked] of gated) {
+      if (text.includes(marker) === listedWhenMarked) list.push(tool);
+    }
     fm.push(`${key}: ${brackets ? `[${list.join(', ')}]` : list.join(', ')}`);
   }
   return fm;
@@ -280,8 +347,9 @@ function opencodeAgentFrontmatter(stem, text, overrides, theme = null) {
   fm.push(`color: ${agentColor(stem, theme)}`);
   pushOverrideLines(fm, agentOverride(overrides, stem));
   if (isReadonly(text)) {
-    fm.push('permission:', '  edit: deny', '  webfetch: deny');
-    if (text.includes('<!-- bash: allow -->')) fm.push('  bash:', '    "*": ask');
+    fm.push('permission:', '  edit: deny',
+      `  webfetch: ${text.includes(WEBFETCH_MARKER) ? 'allow' : 'deny'}`);
+    if (text.includes(BASH_MARKER)) fm.push('  bash:', '    "*": ask');
     else fm.push('  bash: deny');
   }
   return fm;
@@ -419,7 +487,10 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
       kind = 'agent';
     } else {
       // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
-      fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+      // The user-only key is emitted for every host too — Claude Code and Bob honour it,
+      // OpenCode and Copilot ignore an unknown key — so the identity holds.
+      fm = [`name: ${stem}`, `description: ${jsonDumps(skillDescription(text))}`];
+      if (isUserInvokedOnly(text)) fm.push('disable-model-invocation: true');
       body = stripSkillBodyLinks(body);
       dest = path.join(skillsDir, stem, 'SKILL.md');
       kind = 'skill';