geneseed 3.3.0 → 3.5.0

package/js/hosts/hooks.mjs

@@ -8,11 +8,9 @@
  *
  * 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
+ * prompt. GitHub Copilot's `preToolUse` reads the same decision TOP-LEVEL —
+ * `{"permissionDecision": "ask", "permissionDecisionReason": …}` — so `--host copilot` asks
+ * exactly where Claude asks, in Copilot's envelope. `--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
@@ -43,7 +41,7 @@
  * 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,
   appendFileSync, writeFileSync }
   from 'node:fs';
 import path from 'node:path';
@@ -56,7 +54,9 @@ 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, sovereignBypass } from './hosts.mjs';
+import {
+  GATE_LEDGER, resolveMemoryDir, resolvePath, sovereignBypass,
+} from './hosts.mjs';
 
 const ROOT = path.resolve(import.meta.dirname, '../..');
 
@@ -88,32 +88,8 @@ const ROOT = path.resolve(import.meta.dirname, '../..');
 // 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.
- *
- * `realpathSync` throws on a path that does not exist, which is routine here (an
- * `excludes.json` may name a folder that was deleted), so the existing prefix is
- * canonicalised and the rest appended verbatim — `resolve(strict=False)`'s behaviour.
- */
-function resolvePath(p) {
-  let cur = path.resolve(expanduser(p));
-  const tail = [];
-  for (;;) {
-    try {
-      return tail.length ? path.join(realpathSync.native(cur), ...tail)
-        : realpathSync.native(cur);
-    } catch {
-      const parent = path.dirname(cur);
-      if (parent === cur) return path.resolve(expanduser(p));
-      tail.unshift(path.basename(cur));
-      cur = parent;
-    }
-  }
-}
+// A gate that cannot evaluate a call therefore asks, and says why. `resolvePath` comes from
+// `js/hosts/hosts.mjs`, which this module already imports — it had kept a private copy.
 
 // NOT imported from `js/lib/fs.mjs` (the owner everywhere else) — hot path, no new import cost.
 const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
@@ -242,6 +218,19 @@ const LAZY_DIRS = ['docs', 'doc', 'documentation', 'architecture', 'adr', 'ADR']
 const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next',
   'target', '.venv', '__pycache__', '.opencode', '.harness']);
 
+// The root instruction file a host already loads by itself. Injecting it again pays the
+// whole harness twice per session — and was doing exactly that until 2026-09: every hooked
+// host had its own root in EAGER_ROOT. Other tools' roots stay eager (a repo carrying a
+// hand-written AGENTS.md is worth showing Claude Code); only the host's OWN is dropped.
+// The OpenCode context plugin carries the same rule for AGENT.md/AGENTS.md/CLAUDE.md.
+const NATIVE_ROOT = { claude: ['CLAUDE.md'], bob: ['AGENTS.md'], copilot: ['AGENTS.md'] };
+
+// Eager injection budget: a root README of 40k chars was going out whole, every session and
+// every compaction, and cost more than the harness itself. Per-file cut at the last line
+// break under the cap; files that would push the total over the budget are listed lazy.
+const EAGER_FILE_BYTES = 16 * 1024;
+const EAGER_TOTAL_BYTES = 48 * 1024;
+
 const CLAUDE_MARKERS = ['.claude', '.bob'];
 const GENESEED_MANIFEST = '.geneseed-manifest.json';
 
@@ -310,12 +299,14 @@ function rglobMd(dir, acc = []) {
  * Root entry docs are eager; other root markdown, the doc trees and monorepo package
  * READMEs are lazy.
  */
-export function discoverContext(root) {
+export function discoverContext(root, host = HOST) {
   const eager = new Map();
   const lazy = new Map();
+  const native = NATIVE_ROOT[host] || [];
   for (const full of sortPaths(listDir(root).map((n) => path.join(root, n)))) {
     if (!isFile(full)) continue;
     const name = path.basename(full);
+    if (native.includes(name)) continue;
     if (EAGER_ROOT.includes(name)) eager.set(full, null);
     else if (path.extname(name).toLowerCase() === '.md') lazy.set(full, null);
   }
@@ -473,25 +464,42 @@ export function cmdContext(args) {
     `=== PROJECT CONTEXT \u2014 binding for this repo (via ${source}) ===`,
     '',
   ];
+  let spent = 0;
+  const demoted = [];
   for (const entry of eager) {
     const p = entry.path === undefined ? '' : entry.path;
     const desc = entry.description === undefined ? '' : entry.description;
     const target = path.isAbsolute(p) ? p : path.join(root, p);
-    lines.push(`----- ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''} -----`);
+    let text;
     try {
-      lines.push(readText(target).replace(/\n+$/, ''));
+      text = readText(target).replace(/\n+$/, '');
     } catch (e) {
-      lines.push(`[context] MISSING eager file: ${asOsError(e, target)}`);
+      lines.push(`----- ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''} -----`,
+        `[context] MISSING eager file: ${asOsError(e, target)}`, '');
+      continue;
     }
-    lines.push('');
+    if (text.length > EAGER_FILE_BYTES) {
+      const nl = text.lastIndexOf('\n', EAGER_FILE_BYTES);
+      text = `${text.slice(0, nl > 0 ? nl : EAGER_FILE_BYTES)}\n`
+        + `[context] truncated at ${EAGER_FILE_BYTES / 1024} KB \u2014 read ${disp(p, root)} `
+        + 'on demand for the rest';
+    }
+    if (spent + text.length > EAGER_TOTAL_BYTES) {
+      demoted.push(entry);
+      continue;
+    }
+    spent += text.length;
+    lines.push(`----- ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''} -----`, text, '');
   }
 
-  if (lazy.length) {
+  if (lazy.length || demoted.length) {
     lines.push('--- Lazy entries (load only when the task needs them) ---');
-    for (const entry of lazy) {
+    for (const entry of [...lazy, ...demoted]) {
       const p = entry.path === undefined ? '' : entry.path;
       const desc = entry.description === undefined ? '' : entry.description;
-      lines.push(`  - ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''}`);
+      const over = demoted.includes(entry)
+        ? ` (eager, but over the ${EAGER_TOTAL_BYTES / 1024} KB session budget \u2014 read on demand)` : '';
+      lines.push(`  - ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''}${over}`);
     }
     lines.push('');
   }
@@ -544,9 +552,14 @@ function askDecision(reason) {
 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`;
+/**
+ * Copilot's `preToolUse` verdict: the same `ask` Claude reads, but top-level rather than under
+ * `hookSpecificOutput` (docs.github.com/en/copilot/reference/hooks-configuration). An older
+ * emit wired a `toolCall` event answered with `{"block": true}`; Copilot no longer has that
+ * event, so those gates never ran.
+ */
+function copilotAskDecision(reason) {
+  return `${jsonDumpsCompact({ permissionDecision: 'ask', permissionDecisionReason: reason })}\n`;
 }
 
 /**
@@ -557,18 +570,15 @@ function blockDecision(reason) {
 const BOB_DENY_EXIT = 2;
 
 /**
- * On a host with no ask tier, which rules are worth a hard block. Laws I and IV: a
+ * On Bob, which has 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
+ * block would make Bob 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.
  *
@@ -603,27 +613,23 @@ function ledger(root, verb, rule) {
 
 /**
  * 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. On `--host bob` 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 (HOST === 'bob') {
     if (!BLOCK_RULES.has(rule)) {
-      // Neither host has an ask tier; a stderr line is the nudge, and the call goes through.
+      // No 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;
+    // 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;
   }
   ledger(args && args.root, verb, rule);
-  out(askDecision(reason));
+  out(HOST === 'copilot' ? copilotAskDecision(reason) : askDecision(reason));
   return 0;
 }
 
@@ -651,10 +657,11 @@ export function guardGate(fn, verb = 'gate') {
 /**
  * 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.
+ * Copilot spells the same payload in camelCase — `toolName`/`toolArgs` where Claude sends
+ * `tool_name`/`tool_input` — and `toolArgs` may arrive as a JSON STRING rather than an object.
+ * Both are folded to Claude's shape so every gate reads one. (`toolInput` and the `after`
+ * phase are the retired `toolCall` event's spelling, kept so an install not yet re-emitted
+ * still reads right.) A `toolArgs` string that is not JSON throws: fail closed.
  */
 function readPayload() {
   const raw = readStdin();
@@ -667,8 +674,12 @@ function readPayload() {
   }
   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;
+  if (payload.tool_input === undefined) {
+    let ta = payload.toolArgs !== undefined ? payload.toolArgs : payload.toolInput;
+    if (typeof ta === 'string') {
+      try { ta = JSON.parse(ta); } catch { throw new Error('the payload\'s toolArgs is not JSON'); }
+    }
+    if (ta !== undefined) payload.tool_input = ta;
   }
   return payload;
 }
@@ -685,7 +696,9 @@ function gitDecide(args, payload) {
     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;
+  // `--no-consent`: the process pack (or process 5 alone) is off, so the commit/push ask has
+  // no rule behind it — but Law IV above is universal and has already run.
+  if (args.noConsent || !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');
 }
@@ -739,9 +752,10 @@ 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 : '';
+  // Write carries `content`, Edit carries `new_string` (Copilot: `file_text`, `new_str`);
+  // any of them can plant a credential.
+  const body = [ti.content, ti.new_string, ti.file_text, ti.new_str]
+    .find((v) => typeof v === '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 '
@@ -760,9 +774,9 @@ export const cmdRuleGate = guardGate(ruleGate, 'rule-gate');
 // ======================================================================================
 
 /**
- * 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
+ * Copilot's and Bob's PreToolUse entries carry no matcher over documented tool names, so
+ * neither can 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.
@@ -905,7 +919,8 @@ export function readNotes(raw) {
   if (s[0] === '{') {
     let payload;
     try { payload = JSON.parse(s); } catch { return raw; }
-    const tp = payload && payload.transcript_path;
+    // Copilot's agentStop/preCompact spell it `transcriptPath`.
+    const tp = payload && (payload.transcript_path || payload.transcriptPath);
     if (tp) return flattenTranscript(tp);
     return raw;
   }

package/js/hosts/hosts.mjs

@@ -26,6 +26,9 @@ 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';
 
+/** The gate ledger inside an install: the hooks append to it, `status` counts it. */
+export const GATE_LEDGER = path.join('notebook', 'gates.jsonl');
+
 /**
  * `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
@@ -248,11 +251,25 @@ export const HOSTS = [
  * Unknown host -> false, which is the shape that KEEPS the tables. The value arrives from a
  * user-editable `.geneseed-emit` marker, so an unrecognised one must degrade to the portable
  * bundle rather than raise.
+ *
+ * SPLIT PER KIND (2026-09): Bob reads `.bob/skills/<name>/SKILL.md` natively — verified
+ * against its docs in the Bob injection review — but has no markdown agents directory, so a
+ * single boolean was wrong both ways: `false` shipped the §4 Skills table on top of a
+ * catalogue Bob already had (~1.7k tokens twice), `true` would have stripped the §3 Agents
+ * table that is Bob's ONLY agent catalogue. Each CATALOG block in AGENT.md names its kind and
+ * resolves against its own flag. Copilot stays unverified and keeps both tables. Mirrored in
+ * `bin/build-driver.mjs` (which cannot import this module's spawning neighbours).
  */
-const NATIVE_CATALOG = { opencode: true, claude: true, bob: false, copilot: false };
+const NATIVE_CATALOG = {
+  opencode: { skills: true, agents: true },
+  claude: { skills: true, agents: true },
+  bob: { skills: true, agents: false },
+  copilot: { skills: false, agents: false },
+};
 
+/** `{ skills, agents }` for a known host, `false` for an unknown one. */
 export function hostCatalogsNatively(host) {
-  return Boolean(NATIVE_CATALOG[host]);
+  return NATIVE_CATALOG[host] || false;
 }
 
 /** `_harness_learn.MEMORY_DIR_NAMES` — the neutral name and the imperial theme's. */

package/js/hosts/mcp.mjs

@@ -24,9 +24,9 @@
  * `1` on the way back out. `readJsonc` already learned this; the strict-JSON fork has to
  * learn it separately, because it does not go through `readJsonc` at all.
  *
- * A JsonNumber IS AN OBJECT TO `typeof`, which is why `isDict` is spelled out rather than
- * written as `typeof v === 'object'`. Python's `isinstance(x, dict)` is false for a float;
- * the JS twin has to be false for its wrapper.
+ * A JsonNumber IS AN OBJECT TO `typeof`, which is why `isDict` (js/lib/json.mjs) excludes
+ * the wrapper rather than testing `typeof v === 'object'`. Python's `isinstance(x, dict)` is
+ * false for a float; the JS twin has to be false for its wrapper.
  */
 import { existsSync, mkdirSync, renameSync } from 'node:fs';
 import os from 'node:os';
@@ -35,20 +35,10 @@ import path from 'node:path';
 import { bobConfigDir, copilotConfigDir, resolvePath } from './hosts.mjs';
 import { installState, installTargets } from './installs.mjs';
 import { printOut, printErr, readText, writeText } from '../lib/fs.mjs';
-import { jsonDumpsIndent, parseJson } from '../lib/json.mjs';
+import { isDict, jsonDumpsIndent, parseJson } from '../lib/json.mjs';
 import { padEndToWidth } from '../lib/text.mjs';
 import { opencodeTarget, readJsonc } from './settings.mjs';
 
-/**
- * `isinstance(x, dict)` for a value that came out of `json.loads`.
- *
- * A JSON value is null, a boolean, a string, a NUMBER, an array or an object — and
- * `parseJson` hands numbers back wrapped, so `typeof v === 'object'` says yes to a float.
- * `constructor === Object` is the plain-object test, and every object `JSON.parse` builds
- * is one.
- */
-const isDict = (v) => v !== null && v !== undefined && typeof v === 'object'
-  && v.constructor === Object;
 
 /** `dict.get(key, default)`. */
 const dget = (obj, key, dflt) => (isDict(obj) && Object.hasOwn(obj, key) ? obj[key] : dflt);
@@ -184,8 +174,10 @@ export function mcpSetEnabled(config, name, enabled, host = 'opencode') {
  *
  * The host fork is the whole function. OpenCode is read comment-tolerantly because a
  * hand-maintained `opencode.jsonc` carries `//`; the other three are read STRICTLY, because
- * the comment stripper's trailing-comma pass is not string-aware and would silently drop a
- * comma from any string value containing `,]` — in a file that holds projects and history.
+ * their configs are plain JSON by contract, and a file that does not parse as such — for a
+ * Claude global install, one that holds projects and history — is not one to rewrite from a
+ * best-effort reading. (The comment stripper's trailing-comma pass IS string-aware; an older
+ * version of this note said otherwise, and `generate.test.mjs` pins the string-aware case.)
  */
 export function mcpLoad(p, host = 'opencode') {
   if (!existsSync(p)) return {};
@@ -244,10 +236,12 @@ 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', 'settings.json');
+    // Bob reads MCP servers from their OWN file, never from settings.json: `.bob/mcp.json` in
+    // the project, `~/.bob/settings/mcp.json` globally, each `{"mcpServers": …}`
+    // (bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob). Servers written into settings.json,
+    // as an older version did, never loaded.
+    return scope === 'project' ? path.join(root, '.bob', 'mcp.json')
+      : path.join(bobConfigDir(), 'settings', 'mcp.json');
   }
   if (host === 'copilot') {
     // The Copilot CLI reads MCP servers from ~/.copilot/mcp-config.json only — no per-repo

package/js/hosts/native.mjs

@@ -31,7 +31,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { writeText, copyFile, readText } from '../lib/fs.mjs';
-import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy } from '../lib/json.mjs';
+import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy, isDict } from '../lib/json.mjs';
 
 /** Mirrors `_build_core.VENDORED_SKILL_DIRS`. */
 export const VENDORED_SKILL_DIRS = new Set(['react-view-transitions', 'daydream', 'token-report']);
@@ -112,6 +112,57 @@ 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.
+ */
+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 + the trigger's FIRST sentence, the emitted `description:` of a skill. Every
+ * description is always-on context on a host that catalogues natively: at the earlier
+ * 900-char cap the catalogue weighed 22k chars (~5.6k tokens) across 51 skills, three times
+ * the figure the footprint page quoted. The first sentence says WHEN; the later sentences
+ * disambiguate, and the body — read as soon as the skill is chosen — still carries them.
+ * Cut at the last sentence end inside the cap, never mid-word.
+ */
+const DESCRIPTION_CAP = 320;
+function skillDescription(text) {
+  const desc = descOf(text);
+  const trig = triggerOf(text);
+  if (!trig) return desc;
+  const first = trig.match(/^.*?[.;](?=\s|$)/);
+  const full = `${desc} Use when: ${first ? first[0] : 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;
 
@@ -159,7 +210,7 @@ function isReadonly(text) {
  * 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) {
+function isUserInvokedOnly(text) {
   return USER_INVOKED_RE.test(text);
 }
 
@@ -171,8 +222,8 @@ export function stripSkillBodyLinks(body) {
 /** `_build_emit._agent_color_map` — validated, always a valid OpenCode slot. */
 function agentColorMap(theme) {
   let raw = null;
-  if (isPlainObject(theme)) raw = theme.AGENT_COLORS;
-  if (!isPlainObject(raw)) raw = AGENT_COLORS;
+  if (isDict(theme)) raw = theme.AGENT_COLORS;
+  if (!isDict(raw)) raw = AGENT_COLORS;
   const cleaned = {};
   // Insertion order matters: it is the order the warnings below are printed in, and the
   // parity gate compares the warning stream. Python dicts and JS objects agree on it for
@@ -197,10 +248,6 @@ function agentColor(stem, theme) {
   return Object.hasOwn(colors, stem) ? colors[stem] : colors._default;
 }
 
-function isPlainObject(v) {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-
 /** `is not None` — the test that lets a configured `temperature: 0` survive. */
 function given(v) {
   return v !== undefined && v !== null;
@@ -244,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]],
   },
 };
 
@@ -269,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;
@@ -294,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;
@@ -316,8 +370,8 @@ export function loadAgentOverrides(base) {
     // than reproduced — matching it means detecting a decode error Node does not report.
     return {};
   }
-  const agents = isPlainObject(data) ? data.agents : null;
-  return isPlainObject(agents) ? agents : {};
+  const agents = isDict(data) ? data.agents : null;
+  return isDict(agents) ? agents : {};
 }
 
 /** `Path.relative_to(base).as_posix()`. */
@@ -403,6 +457,12 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
     if (targetDir === undefined) continue;
 
     if (fname.startsWith('_')) {
+      // NOT the agent template: every host loads each `.md` in its agents dir as an agent,
+      // so shipping it there registered a phantom `_template` agent, and its authoring steps
+      // (theme tokens, README badge) are the source repo's, not an install's. Nothing in an
+      // installed harness points at it; the skill template, which AGENT.md and skill-forge
+      // do point at, still ships.
+      if (folder === 'agents') continue;
       // Authoring templates are shipped verbatim and FLAT — not wrapped as a native
       // skill — so an author following the `_template.md` note has the scaffold on disk.
       const dest = path.join(targetDir, fname);
@@ -435,7 +495,7 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
       // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
       // 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(descOf(text))}`];
+      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');

package/js/hosts/opencode.mjs

@@ -78,6 +78,20 @@ const AGENT_OVERRIDES_STUB = {
     + 'Host-specific; git-ignored. A future TUI screen edits this — rebuild to apply.'
   ),
   agents: {},
+  // Inert: `loadAgentOverrides` reads `agents` only. This is the starting point the README
+  // used to describe in prose — the seats whose work is read-and-summarise, where a smaller
+  // model loses little and a council convenes 3–6 of them at once.
+  _recommended: {
+    _comment: (
+      'Cheap-tier seats: copy the ones you want into "agents" with your host\'s cheap '
+      + 'model id (OpenCode: "anthropic/claude-haiku-4-5"; Claude Code / Copilot: "haiku"). '
+      + 'Read-and-summarise work — a council convenes several at once, so this is where '
+      + 'the savings compound. Nothing applies until you copy it.'
+    ),
+    'cheap-tier': ['explorer', 'researcher', 'tester', 'advocate', 'skeptic', 'pragmatist',
+      'steward', 'visionary', 'user-advocate', 'framer', 'empiricist', 'operator',
+      'historian'],
+  },
 };
 
 /** Mirrors `_build_emit.COMMAND_SET` — the hot skills worth a one-keystroke trigger. */