geneseed 5.3.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +31 -18
  5. package/adapters/claude-code/README.md +27 -22
  6. package/adapters/openclaude/README.md +18 -8
  7. package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
  8. package/adapters/opencode/plugins/geneseed-activity.js +20 -21
  9. package/adapters/opencode/plugins/geneseed-context.js +169 -62
  10. package/adapters/opencode/plugins/geneseed-guard.js +414 -202
  11. package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
  12. package/adapters/opencode/workflows/_runtime.js +3 -2
  13. package/bin/geneseed-hook.mjs +57 -9
  14. package/docs/concepts/enforcement-table.md +1 -1
  15. package/docs/concepts/exclusions.md +2 -2
  16. package/docs/concepts/footprint.md +10 -0
  17. package/docs/concepts/hook-gates.md +3 -3
  18. package/docs/concepts/host-matrix.md +22 -4
  19. package/docs/design-history.md +8 -0
  20. package/docs/extending.md +49 -7
  21. package/docs/guides/install-bob.md +2 -2
  22. package/docs/guides/install-openclaude.md +1 -1
  23. package/docs/guides/verify.md +12 -0
  24. package/docs/reference/environment.md +1 -0
  25. package/docs/reference/troubleshoot-doctor.md +1 -1
  26. package/docs/token-footprint.md +66 -2
  27. package/docs/understand/design-choices-hosts.md +1 -1
  28. package/docs/understand/design-choices-shape.md +1 -0
  29. package/docs/understand/enforced-vs-asked.md +1 -1
  30. package/docs/understand/machine-bob.md +1 -1
  31. package/docs/web-ui.md +5 -0
  32. package/harness.config.json +1 -1
  33. package/js/README.md +3 -2
  34. package/js/build/args.mjs +1 -1
  35. package/js/build/driver.mjs +1 -1
  36. package/js/build/emit-claude.mjs +1 -1
  37. package/js/build/generate.mjs +5 -14
  38. package/js/hosts/done-checks.mjs +6 -0
  39. package/js/hosts/geneseed-dir.mjs +3 -2
  40. package/js/hosts/gitref.mjs +5 -3
  41. package/js/hosts/hook-tap.mjs +104 -0
  42. package/js/hosts/hooks-context.mjs +4 -2
  43. package/js/hosts/hooks-learn.mjs +47 -16
  44. package/js/hosts/hooks.mjs +19 -13
  45. package/js/hosts/hosts.mjs +80 -12
  46. package/js/hosts/installs.mjs +7 -0
  47. package/js/hosts/native.mjs +14 -5
  48. package/js/hosts/owned.mjs +7 -6
  49. package/js/hosts/ownership-gate.mjs +14 -1
  50. package/js/hosts/settings.mjs +245 -103
  51. package/js/hosts/shim.mjs +4 -4
  52. package/js/hosts/usage.mjs +9 -3
  53. package/js/inspect/checks-probe.mjs +66 -5
  54. package/js/inspect/checks-repo.mjs +196 -2
  55. package/js/inspect/cost.mjs +34 -2
  56. package/js/inspect/doctor.mjs +6 -1
  57. package/js/lib/machine-dir.mjs +1 -1
  58. package/js/lib/node-floor.mjs +46 -6
  59. package/js/maintain/uninstall.mjs +42 -16
  60. package/js/web/actions.mjs +1 -9
  61. package/package.json +1 -1
  62. package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
  63. package/web/dist/assets/{ActivityDetail-BSzevynX.js → ActivityDetail-7rt04SkS.js} +1 -1
  64. package/web/dist/assets/{Bonsai-Bfpb6W-1.js → Bonsai-BBl4XXqs.js} +1 -1
  65. package/web/dist/assets/{CopyButton-ByIntFtB.js → CopyButton-Beven8yn.js} +1 -1
  66. package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
  67. package/web/dist/assets/{Docs-DvlMJhpu.js → Docs-B5aHp86J.js} +3 -3
  68. package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
  69. package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
  70. package/web/dist/assets/{Installs-BlGmVrFK.js → Installs-B1OsrHXF.js} +3 -3
  71. package/web/dist/assets/JournalView-CV4omyww.js +1 -0
  72. package/web/dist/assets/{Kits-DRwpxC-J.js → Kits-CW1e7xNa.js} +1 -1
  73. package/web/dist/assets/{Laws-CZkiNOWQ.js → Laws-1Ckf1lbs.js} +2 -2
  74. package/web/dist/assets/{LibRows-DEHjIoD-.js → LibRows-Dag1s0ZX.js} +1 -1
  75. package/web/dist/assets/Library-B3FuFLel.js +3 -0
  76. package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
  77. package/web/dist/assets/Markdown-CxkA7940.js +71 -0
  78. package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
  79. package/web/dist/assets/{Personal-Bp9nV4GR.js → Personal-DKLgLa7Z.js} +2 -2
  80. package/web/dist/assets/Settings-BwErnh-R.js +1 -0
  81. package/web/dist/assets/{Tabs-CWeQTADL.js → Tabs-8zsyEPSK.js} +1 -1
  82. package/web/dist/assets/{index-CsAZq0BQ.css → index-CRWqKxfY.css} +1 -1
  83. package/web/dist/assets/index-Ce6qF2nG.js +6 -0
  84. package/web/dist/index.html +2 -2
  85. package/adapters/claude-code/settings.json +0 -52
  86. package/web/dist/assets/Activity-CqJiquEq.js +0 -1
  87. package/web/dist/assets/Dashboard-DBOEi9lQ.js +0 -2
  88. package/web/dist/assets/Factories-Bpvv7L2H.js +0 -1
  89. package/web/dist/assets/GreenhouseView-GpBsYn50.js +0 -1
  90. package/web/dist/assets/JournalView-iLuLrOxE.js +0 -1
  91. package/web/dist/assets/Library-B4K-1iNF.js +0 -3
  92. package/web/dist/assets/Loops-BWSzaW8E.js +0 -2
  93. package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
  94. package/web/dist/assets/OperatorHudView-BAXwCEvY.js +0 -1
  95. package/web/dist/assets/Settings-CWWuaIp-.js +0 -1
  96. package/web/dist/assets/index-How7SzDZ.js +0 -6
@@ -124,8 +124,9 @@ function isolationReport(stats) {
124
124
  // every depth and would hide `bricks/x.md` even under `!bricks/`. Create-if-absent (`wx`): a
125
125
  // user's own edit survives; its failure never costs the trace. The same string lives in
126
126
  // `workflows/_runtime.js` (a plugin cannot share a file — V2 loads every .js here as a
127
- // plugin — and the runtime is imported lazily, from a configurable dir); tests pin both.
128
- const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
127
+ // plugin — and the runtime is imported lazily, from a configurable dir). Both are
128
+ // js/hosts/geneseed-dir.mjs's line, kept by `node tests/twins.mjs --write`.
129
+ const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
129
130
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
130
131
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
131
132
  async function writeGitignore(file) {
@@ -197,8 +197,9 @@ async function runChildSession(client, { prompt, agent, model, title, directory
197
197
  // so neither the worktrees nor the traces show up as untracked files, with the team paths
198
198
  // (bricks, loops, check lists) allowed back. Anchored `/*`, because a bare `*` matches at
199
199
  // every depth and would hide `bricks/x.md` even under `!bricks/`. Same string as
200
- // GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
201
- const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
200
+ // GENESEED_GITIGNORE in plugins/geneseed-workflow.js: both are js/hosts/geneseed-dir.mjs's
201
+ // line, kept by `node tests/twins.mjs --write`.
202
+ const GENESEED_GITIGNORE = '/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n';
202
203
  // Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
203
204
  // never a user edit, so it is upgraded. Any other content is the user's. Never throws.
204
205
  async function writeGitignore(file) {
@@ -69,9 +69,10 @@ const gates = () => import('../js/hosts/hooks.mjs');
69
69
  // Verbs PreToolUse/PostToolUse actually gate a tool call with. The machine-wide, last-writer-wins
70
70
  // shim (this file's header) means a stale checkout can be handed a flag only a newer install
71
71
  // knows (e.g. `--no-consent`); on Claude Code, exit 2 from one of THESE verbs blocks the tool
72
- // outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 instead —
73
- // a gate's own decision still exits 0 and signals through stdout (`askDecision`), so this only
74
- // changes what used to be a hard lockout into "the gate is silent this one call" (see I3/B1).
72
+ // outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 and the
73
+ // gate-error ask instead (a stderr warning on Bob) — a gate's own decision exits 0 and signals
74
+ // through stdout too (`askDecision`), so what used to be a hard lockout is a question the person
75
+ // can answer, never "the gate is silent this one call" (see I3/B1).
75
76
  const GATE_VERBS = new Set(['git-gate', 'rule-gate', 'tool-gate']);
76
77
  const VERBS = {
77
78
  context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
@@ -101,6 +102,8 @@ const VERBS = {
101
102
  '--no-deletion-gate': 'noDeletionGate', '--no-secrets-gate': 'noSecretsGate',
102
103
  '--no-ownership-gate': 'noOwnershipGate', '--no-external-gate': 'noExternalGate',
103
104
  '--no-test-note': 'noTestNote', '--no-rule-store': 'noRuleStore', '--no-root-scan': 'noRootScan',
105
+ // Bob's commit/push warning, when process 5 is off: `gitDecide` reads it as on git-gate.
106
+ '--no-consent': 'noConsent',
104
107
  },
105
108
  },
106
109
  learn: {
@@ -163,6 +166,21 @@ async function trackActivity(verb, args) {
163
166
  } catch { /* the activity view is best-effort; a hook that fails is a tool call that fails */ }
164
167
  }
165
168
 
169
+ /**
170
+ * The tap (js/hosts/hook-tap.mjs): with `GENESEED_HOOK_TAP=<dir>` in the host's environment,
171
+ * the payload the verb just answered is written there as a fixture, values replaced by their
172
+ * shape. After the verdict, like `trackActivity`, and on the same cached stdin. The caller tests
173
+ * the variable, so an untapped hook never imports the module; a terminal sends no payload.
174
+ * Never prints, never changes the exit code.
175
+ */
176
+ async function tapHook(verb, args) {
177
+ try {
178
+ if (isatty(0)) return;
179
+ const { tapPayload } = await import('../js/hosts/hook-tap.mjs');
180
+ tapPayload(process.env.GENESEED_HOOK_TAP, readStdin(), { verb, host: args.host || 'claude' });
181
+ } catch { /* a capture is a favour to a maintainer; a hook that fails is a tool call that fails */ }
182
+ }
183
+
166
184
  /**
167
185
  * A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
168
186
  * once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
@@ -199,6 +217,20 @@ function die(code, msg) {
199
217
  return code;
200
218
  }
201
219
 
220
+ /**
221
+ * The `--host` an argv names, in both spellings `parse` takes, the last one winning as it does
222
+ * there. For the argv-error path only: `parse` returns no args with an error, and the gate-error
223
+ * answer still has to know whether its reader is Bob.
224
+ */
225
+ function hostNamed(argv) {
226
+ let host = null;
227
+ argv.forEach((tok, i) => {
228
+ if (tok.startsWith('--host=')) host = tok.slice('--host='.length);
229
+ else if (tok === '--host' && argv[i + 1] !== undefined) host = argv[i + 1];
230
+ });
231
+ return host;
232
+ }
233
+
202
234
  /**
203
235
  * `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
204
236
  * `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
@@ -278,11 +310,20 @@ async function main(argv) {
278
310
  const parsed = parse(spec, argv.slice(1));
279
311
  if (parsed.error) {
280
312
  // A gate verb must never exit 2 on an argv error: that is indistinguishable, to Claude's
281
- // PreToolUse, from the gate deliberately blocking (see I3/B1 above). Print the same message
282
- // to stderr for a human debugging the shim, but return 0 with no stdout, exactly like a gate
283
- // that chose not to act.
284
- // `activity` too: it runs on UserPromptSubmit, where exit 2 erases the user's prompt.
285
- if (GATE_VERBS.has(verb) || verb === 'activity') {
313
+ // PreToolUse, from the gate deliberately blocking (see I3/B1 above). It must not exit 0 with
314
+ // stdout empty either: that reads as "the gate deferred", so a stale shim handed a newer flag
315
+ // let every call through unjudged. It answers as a gate whose module failed to load does
316
+ // (`verbFailed`): an ask on Claude and OpenClaude, where the person can still allow the call —
317
+ // so no lockout — and is told the gate is broken; a stderr warning and exit 0 on Bob, whose
318
+ // PreToolUse has no matcher, so exit 2 there would refuse every tool, reads included. The
319
+ // stderr line stays for a human debugging the shim.
320
+ if (GATE_VERBS.has(verb)) {
321
+ printErr(`geneseed-hook: error: ${parsed.error}\n`);
322
+ return verbFailed(verb, { host: hostNamed(argv.slice(1)) }, new Error(parsed.error));
323
+ }
324
+ // `activity` decides nothing, and it runs on UserPromptSubmit, where exit 2 erases the
325
+ // user's prompt: the stderr line, exit 0, stdout empty.
326
+ if (verb === 'activity') {
286
327
  printErr(`geneseed-hook: error: ${parsed.error}\n`);
287
328
  return 0;
288
329
  }
@@ -296,8 +337,14 @@ async function main(argv) {
296
337
  // `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
297
338
  // event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
298
339
  // is cached, so `trackActivity` reuses it. A terminal sends no payload.
340
+ // The same parse hands `context` the payload's `cwd`, its project root on a host that sets no
341
+ // `$CLAUDE_PROJECT_DIR` (`hookProjectDir`).
299
342
  if (verb === 'context' && !isatty(0)) {
300
- try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
343
+ try {
344
+ const payload = JSON.parse(readStdin() || '{}');
345
+ parsed.args.event = payload.hook_event_name ?? null;
346
+ parsed.args.cwd = typeof payload.cwd === 'string' ? payload.cwd : null;
347
+ } catch { /* not JSON: SessionStart */ }
301
348
  }
302
349
  let rc;
303
350
  try {
@@ -307,6 +354,7 @@ async function main(argv) {
307
354
  }
308
355
  await trackActivity(verb, parsed.args);
309
356
  await baselineStores(verb, parsed.args);
357
+ if (process.env.GENESEED_HOOK_TAP) await tapHook(verb, parsed.args);
310
358
  return rc;
311
359
  }
312
360
 
@@ -26,7 +26,7 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
26
26
  | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
27
27
  | `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
28
28
  | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
- | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (**unverified live**: a frozen fork, and no check runs a model turn) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
29
+ | `verify-before-asserting` | law | block at Stop, once per turn: the done gate in `learn` (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)) | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
30
30
  | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
31
31
 
32
32
  Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
@@ -44,7 +44,7 @@ What "dormant" means per host:
44
44
 
45
45
  **Git worktrees.** A linked worktree of an excluded repo (`git worktree add`) is excluded too, wherever it sits on disk: the hooks and plugins follow its `.git` file back to the main repository. The global `CLAUDE.md` is the exception on Claude Code and OpenClaude: `settings.local.json` is gitignored, so a worktree never gets it. Geneseed writes no tracked file in a repo you told it to leave alone, so `exclude add` and `exclude list` print the snippet to commit yourself in the repo's tracked `.claude/settings.json` (`.openclaude/` for OpenClaude): `"claudeMdExcludes": ["<path to the global CLAUDE.md>"]`.
46
46
 
47
- **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
47
+ **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. That makes an exclusion a poor way to save tokens: the listings stay on Claude Code and OpenClaude, and on OpenCode the global instructions file still loads (see [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode)). And a global install created *after* you added exclusions is silent in those folders at once, through the shared list, and its next emit applies the repo-side wiring there. Until that emit, `geneseed exclude list` flags it.
48
48
 
49
49
  The web console has the same controls in the **Excluded folders** card on the Installs page, shown once a global install exists.
50
50
 
@@ -95,7 +95,7 @@ What stops asking, per host: the real-loss check of `git-gate` (Claude Code, Ope
95
95
  Limits:
96
96
  - **OpenCode reads the switch at start.** The guard plugin reads `Deletion gate:` from the install's `AGENT.md` once, when OpenCode loads it: restart OpenCode after flipping it.
97
97
  - **A global install beside a project install.** On Claude Code and OpenClaude the global `git-gate` stands down for a project install, so the project's switch decides. Bob's `tool-gate` and the OpenCode guard do not stand down: an armed global install still refuses real loss inside a project whose own install is off.
98
- - **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.jsonc` is never rewritten: the build names the entries to remove.
98
+ - **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.json` or `opencode.jsonc` is never rewritten: the build names the entries to remove.
99
99
  - **An older hook shim silences the whole gate.** The flag is new. While the machine's shared hook shim still points at an older checkout, that checkout refuses the flag and the gate verb lets every call through on a disarmed install — on Claude Code and OpenClaude the root-scan and consent checks too, on Bob also *Sealed Secrets* and *External Gate*. Update the checkout the shim points at (`geneseed rebuild-all`) before switching the gate off.
100
100
 
101
101
  ### Law I secrets gate and Law III done gate — on or off
@@ -32,6 +32,16 @@ Everything else is identical at both settings — the same agents, skills, plugi
32
32
 
33
33
  For measured numbers per host, see [docs/token-footprint.md](../token-footprint.md).
34
34
 
35
+ ### There is no chat mode
36
+
37
+ Footprint is the only token dial. There is no command that switches the harness off for a quick question, and that is deliberate.
38
+
39
+ - **What it costs.** Measured on 2026-11-12, the harness adds about 11–14k tokens to a session at lean and 18–21k at full, depending on the host. Where the provider caches prompts, that is billed at the full price once per session and at the cached rate on every later message.
40
+ - **Why not a command in the chat.** The harness is in the context before your first message, and no host can take it back out of a running conversation. A command could only tell the agent to ignore the rules, which saves nothing.
41
+ - **Why not a toggle on resume.** On Claude Code and OpenCode 2, resuming a conversation without the harness keeps it in the history, and resuming with it again loads it a second time.
42
+
43
+ So the harness stays in place in every session. For a single session without it, each host has its own launch option; the launch lines, their limits and every measurement are in [Why there is no chat mode](../token-footprint.md#why-there-is-no-chat-mode).
44
+
35
45
  ### How to set it
36
46
 
37
47
  Footprint is stored in a `.geneseed-footprint` marker in the install and kept across every rebuild and upgrade, on every host.
@@ -37,11 +37,11 @@ The merge is surgical. Every other key and every hook of your own survive, and t
37
37
  **Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher or `SubagentStop`. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet. So Bob gets four hooks:
38
38
 
39
39
  - `SessionStart` → `geneseed-hook context`.
40
- - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push check and a shell write to a rule store become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
41
- - `Stop` → `geneseed-hook learn`.
40
+ - `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md). The commit/push check and a shell write to a rule store become a warning line, because a hard block would leave Bob unable to commit at all. The [ownership](ownership.md) gate also exits 2, but only once per session and repo: the same write passes after the developer answers.
41
+ - `Stop` → `geneseed-hook learn`. Bob's `Stop` carries no transcript, so nothing is learned there; the [change report](hooks.md#the-change-report) still runs.
42
42
  - `UserPromptSubmit` → `geneseed-hook activity`, which records the turn for the Activity view.
43
43
 
44
- Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
44
+ What was checked against each host itself is in [What is verified](host-matrix.md#what-is-verified). If a hook does not fire, the same rules still reach the agent through the instructions file.
45
45
 
46
46
  ## The hook shim
47
47
 
@@ -14,7 +14,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
14
14
  | Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
15
15
  | Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
16
16
  | Your `user-rules.md` handed to each sub-agent | — (later) | 🪝 hook | — (no `SubagentStart`) | 🪝 hook² |
17
- | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
17
+ | Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | ➖ wired, inert: Bob's `Stop` carries no transcript¹ | 🪝 hook² |
18
18
  | Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook, files per subagent, context size | 🪝 hook, per tool call only (no transcript, no context size, subagent files not attributed)¹ | 🪝 hook, files per subagent, context size² |
19
19
  | Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
20
20
  | Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
@@ -28,16 +28,34 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
28
28
 
29
29
  ✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
30
30
 
31
- ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the rules that admit no judgement call — secrets, real data loss, a recursive scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off — and turns the two consent checks into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them yet, so learn runs on `Stop` only. **What is verified:** the payload shape (Claude's keys plus `cwd`), the event list and the strict settings schema were read in Bob 2.2.3's shipped bundle on the authoring machine, and a live prompt on 2026-10-25 wrote an Activity snapshot from `UserPromptSubmit`. The gates' block-by-exit-code behaviour is Bob's documented contract, not yet observed live; the rules preamble still holds if a hook does not fire.
32
- ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
31
+ ¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks exactly the rules whose Bob cell says *block* in [Rule enforcement, by host](enforcement-table.md), and turns the commit/push consent into a logged warning. It has no `SubagentStop` event. Bob 2.2.3 does have `PreCompact` and `PostCompact`, but Geneseed does not wire them. The `Stop` hook is wired and runs the [change report](hooks.md#the-change-report), but learns nothing: Bob's `Stop` payload carries no transcript, and the group is kept so that learning starts if Bob ever sends one. The rules preamble still holds if a hook does not fire. For what was checked against Bob itself, see [What is verified](#what-is-verified).
32
+ ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). See [What is verified](#what-is-verified).
33
33
  ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so a standing-rule write gets OpenCode's own prompt, and the guard refuses a file-tool write where no prompt can run. Shell is not a boundary on any host: only parsed forms are read, and the host's command permission is the backstop. A real data loss is blocked outright (as on Bob) rather than asked; `GENESEED_GUARD=warn` turns a block into a logged warning.
34
34
  ⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
35
35
  ⁵ A linked git worktree of an excluded repo is excluded too: the hooks and plugins follow its `.git` file back to the main repository. `claudeMdExcludes` is the exception — it lives in the gitignored `settings.local.json`, which a worktree never gets — so `geneseed exclude add` and `exclude list` print the snippet to commit yourself. See [Exclusions](exclusions.md).
36
36
 
37
+ ## What is verified
38
+
39
+ This is the one place that says what was checked against each host itself, how, and when. Every other page links here and states nothing of its own; `geneseed doctor` fails a page that does.
40
+
41
+ | Host | Method | Date | Scope | Not covered |
42
+ | --- | --- | --- | --- | --- |
43
+ | Claude Code | canary: `tests/host_canary.mjs` installs the host from npm and starts it in a throwaway home | weekly in CI, at npm `latest` | `claude doctor` lists no invalid setting in the emitted `settings.json`; a logged-out `-p` run shows `SessionStart` running the context hook | hooks that need a model turn: the `PreToolUse` gates, `Stop` |
44
+ | OpenClaude | canary, the same run | weekly in CI, at npm `latest` | the emitted settings load; `SessionStart` runs the context hook. Its `doctor` checks only the auto-updater, so there is no settings verdict to read | hooks that need a model turn |
45
+ | OpenClaude | source read | 2026-09 | the config directory, the root files it loads, the settings and hook types (`src/utils/envUtils.ts`, `claudemd.ts`, `config.ts`, `src/types/hooks.ts`) | |
46
+ | Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader | whether Bob lists agents to the model; a sub-agent depth cap |
47
+ | Bob | live session, Bob IDE | 2026-10-23 | a `tool-gate` refusal (exit 2) stopped the call and its reason reached the model; Bob ignores Claude's `disallowedTools`, which is why a read-only agent carries `groups:`; the first-reply override | the `Stop` hook; the ownership gate's sub-agent deferral |
48
+ | Bob | live session | 2026-10-25 | a prompt wrote an Activity snapshot from `UserPromptSubmit` | |
49
+ | Bob | canary | never | nothing: IBM does not publish Bob Shell on npm, so the canary reports Bob as `skip` | everything above is a one-time read, not a standing check. [Verify it works](../guides/verify.md) has the by-hand steps |
50
+ | OpenCode V1 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and the workflow plugin's banner shows `.server` ran | the guard's refusal, which needs a model turn |
51
+ | OpenCode V2 | canary | weekly in CI, at npm `latest` (log lines measured 2026-10-12) | no `failed to load plugin` line names a Geneseed plugin, and a `loading plugin` line is logged for each | the guard's refusal, which needs a model turn |
52
+
53
+ No check on any host calls a model. `geneseed doctor --probe` covers the other half on your own machine: it runs the installed gates through each host's shell on calls they must refuse and calls they must let through.
54
+
37
55
  ## The one conditional row
38
56
 
39
57
  The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
40
58
 
41
- One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way, and uninstall takes those back too; uninstall leaves the `permission.bash` gates.
59
+ One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way. Uninstall takes back both: every recorded deny and every recorded `permission.bash` gate that still reads as Geneseed wrote it. A gate you changed, and one with no record, stays.
42
60
 
43
61
  In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
@@ -1347,6 +1347,14 @@ Geneseed did make are listed in [Why Geneseed works this way](understand/design-
1347
1347
  anchor stays. A runtime toggle that works beside the anchor, without replacing it, remains
1348
1348
  possible. See
1349
1349
  [Foreman mode](concepts/foreman-mode.md).
1350
+ - **A chat mode that switches the harness off for a quick question** (2026-11-12): a slash
1351
+ command, a ready-made excluded folder, or a `geneseed chat` verb. Measured on the real hosts,
1352
+ the harness adds 11–14k tokens per session at lean and 18–21k at full, billed in full once
1353
+ where the provider caches prompts. No host can unload it inside a conversation, an excluded
1354
+ folder leaves the skill listings (and removes nothing on OpenCode), and on Claude Code and
1355
+ OpenCode 2 a toggle on resume loads the harness twice. The hosts' own launch switches differ
1356
+ per host and per version, so a verb would have to track them. See
1357
+ [Token footprint](token-footprint.md#why-there-is-no-chat-mode).
1350
1358
 
1351
1359
  ---
1352
1360
 
package/docs/extending.md CHANGED
@@ -535,7 +535,7 @@ every pack, so a kit there would switch itself on in every install built before
535
535
 
536
536
  ---
537
537
 
538
- ## 4 — Adding a PLUGIN, a HOOK verb, or a doc page
538
+ ## 4 — Adding a PLUGIN, a HOOK verb, a doc page, or a HOST
539
539
 
540
540
  ### 4a — An OpenCode plugin
541
541
 
@@ -606,6 +606,54 @@ the page renders, wrong, with nothing red.
606
606
 
607
607
  ---
608
608
 
609
+ ### 4d — A host
610
+
611
+ **A host is not one row.** `HOSTS` (`js/hosts/hosts.mjs`) is the table two maps are derived
612
+ from (`EMIT_HOST_SCOPE` and `EMIT_FOR` in `js/hosts/installs.mjs`, and `CLAUDE_STYLE`). Every
613
+ other site below is typed by hand. `tests/unit/host_tables.test.mjs` fails for the tables marked
614
+ *(pinned)*; the rest have no gate, which is why this list exists.
615
+
616
+ Decide first: is the host **Claude-shaped** (a settings file that runs hook commands, a root
617
+ instruction file, `SKILL.md` skills) or does it need its own engine, as OpenCode does? A
618
+ Claude-shaped host rides `js/build/emit-claude.mjs`; anything else is a new emitter and a much
619
+ larger change than this list.
620
+
621
+ 1. `HOSTS` in `js/hosts/hosts.mjs`: the row (`host`, `family`, `configDir`, `projectMarker`,
622
+ `agentFile`, `catalog`), a `<host>ConfigDir()` beside the others, and `CARRIERS` /
623
+ `carriersFor` if the root file sits somewhere new. Set `catalog.agents` only for what you
624
+ have seen the host list to the model by itself.
625
+ 2. `EMITS` in `js/build/args.mjs` *(pinned)*: `<host>` and `<host>-global`.
626
+ 3. `CLAUDE_SHAPED` and the two dispatch tables under it in `js/build/driver.mjs`: one row per
627
+ scope, with the summary line the emit prints. Name the settings file by its real path.
628
+ 4. `claudeHookGroups` in `js/hosts/settings.mjs`: the hook groups in the host's own events and
629
+ verdict dialect, and `--host <id>` on each command. A host that cannot ask (Bob) needs its
630
+ block set decided in `BLOCK_RULES` (`js/hosts/hooks.mjs`).
631
+ 5. `js/hosts/native.mjs`: the agent and skill frontmatter dialect, and how a user-only skill
632
+ is hidden from the model.
633
+ 6. The gate-config markers: `GATE_CONFIG_MARKERS` in `js/hosts/hooks.mjs` *(pinned)* and its
634
+ hand copy in `adapters/opencode/plugins/geneseed-guard.js`, which leaves out `.opencode`.
635
+ A write under the new host's project layer can switch a gate off.
636
+ 7. `NATIVE_ROOT` in `js/hosts/hooks-context.mjs` *(pinned)*: the root file the host loads by
637
+ itself, so the context hook does not inject it a second time.
638
+ 8. `mcpConfigFor` in `js/hosts/mcp.mjs` *(pinned)*: where the host reads MCP servers from.
639
+ 9. `PROBED_VERB` and `probeShell` in `js/inspect/checks-probe.mjs` *(pinned)*: which verb
640
+ refuses on this host, under which shell, and `probesFor` if the host sends its own payload
641
+ shapes.
642
+ 10. `HOST_LABELS` in `js/inspect/checks-repo.mjs` *(pinned)*, then a column in
643
+ `docs/concepts/host-matrix.md` and `docs/concepts/enforcement-table.md` (`geneseed doctor`
644
+ fails without them), and a row in `## What is verified` saying how the host was checked.
645
+ 11. `DOC_HOSTS` in `js/web/docs.mjs` *(pinned)*: the Docs selector's entry and family.
646
+ 12. The setup menu, `js/maintain/setup.mjs`: `EMIT_OPTIONS` *(pinned)*, appended after the
647
+ last entry because the menu is answered by number; the host's display name, and its row in
648
+ the "is it installed" detection table.
649
+ 13. `js/inspect/cost.mjs` (`userOnlyTest`, `catalogueChars`), `js/inspect/excludes.mjs` and
650
+ `js/inspect/status.mjs`: each branches on the host id.
651
+ 14. `tests/host_canary.mjs`: a `HOSTS` entry if the host is on npm. If it is not, say so in
652
+ the docblock and in `## What is verified`, and write the by-hand steps into
653
+ `docs/guides/verify.md`. `GENESEED_HOOK_TAP` records what the host really sends.
654
+ 15. `tests/golden.mjs`: the emit cells. `adapters/<host>/README.md`, a
655
+ `docs/guides/install-<host>.md`, and the README's matrix.
656
+
609
657
  ## 4bis — Adding a RUNTIME DEPENDENCY
610
658
 
611
659
  **Short answer: you vendor it, or you do not add it.** A dependency arrives as tracked source under
@@ -737,7 +785,6 @@ only, at best, on its presence.
737
785
  | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
738
786
  | `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
739
787
  | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
740
- | The hand-wiring copy of the Claude hooks | `adapters/claude-code/settings.json` — it ships (`files[]` takes `adapters/` whole), and `js/hosts/settings.mjs` sends a user whose `settings.json` has comments to it | nothing compares it with what `claudeHookGroups` emits (§7) |
741
788
  | The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs` (`const CEILING`) | a hand-transcribed measurement |
742
789
 
743
790
  ---
@@ -747,11 +794,6 @@ only, at best, on its presence.
747
794
  Each is small, and each costs a contributor a wrong turn until it is done. What was found and
748
795
  fixed here before is recorded in [design history](design-history.md).
749
796
 
750
- - **`adapters/claude-code/settings.json` has no gate.** It ships, and the refusal for a commented
751
- `settings.json` tells users to copy hooks from it. It writes `node bin/geneseed-hook.mjs <verb>`,
752
- a path that resolves only from a checkout root, and none of the `--no-*-gate` flags
753
- `claudeHookGroups` emits. Nothing compares the two. Either gate it against the emitter, or point
754
- the refusal at an emitted file and delete it.
755
797
  - **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
756
798
  extractability; this one's parity test was retired. Reformat the declaration in
757
799
  `geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
@@ -13,9 +13,9 @@ geneseed build --emit bob-global # ~/.bob
13
13
  geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
14
14
  ```
15
15
 
16
- Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events.
16
+ Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2. Bob has no `SubagentStop` event; Bob 2.2.3 does have `PreCompact` and `PostCompact`, which Geneseed does not wire.
17
17
 
18
- Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. That much was checked by hand in the Bob IDE (2026-10); the rest of the Bob support has not been verified against a live install.
18
+ Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. For what was checked against Bob itself, and when, see [What is verified](../concepts/host-matrix.md#what-is-verified); [Verify it works](verify.md) has the steps to check your own install by hand.
19
19
 
20
20
  ---
21
21
 
@@ -18,7 +18,7 @@ geneseed build --emit openclaude --out /path/to/repo --root /path/to/repo # one
18
18
  - Per repo, the preamble is written to `.openclaude/CLAUDE.md` rather than a root file, and the hooks go into `.openclaude/settings.local.json`.
19
19
  - `$OPENCLAUDE_CONFIG_DIR` moves the global directory (default `~/.openclaude`).
20
20
 
21
- OpenClaude support has not yet been verified against a live install.
21
+ For what was checked against OpenClaude itself, see [What is verified](../concepts/host-matrix.md#what-is-verified).
22
22
 
23
23
  ---
24
24
 
@@ -52,6 +52,18 @@ Start a session with `GENESEED_DEBUG=1` set. The context plugin then logs what i
52
52
  At session start, the context hook adds the repo's docs to the conversation. Ask the agent what project context it received. It should name your `README.md` and list your `docs/`.
53
53
  <!--/harness-->
54
54
 
55
+ ## Bob, by hand
56
+
57
+ No automated check runs IBM Bob: it is not published on npm, so the host canary cannot install it ([What is verified](../concepts/host-matrix.md#what-is-verified)). `geneseed doctor --probe` runs Bob's installed gate through Bob's shell, which proves the gate. Only Bob can prove that Bob calls it. Five steps, in a scratch repository:
58
+
59
+ 1. **The hooks are loaded.** Type `/hooks` in Bob Shell. For a global install it lists four groups from `~/.bob/settings/settings.json`: `SessionStart`, `PreToolUse`, `Stop` and `UserPromptSubmit`. If Geneseed's are missing, Bob is reading another file.
60
+ 2. **A credential write is refused.** Ask Bob to write a file holding an AWS access key id (the example one from the AWS documentation will do). The write does not happen, and Bob shows the gate's reason, which says that no confirmation in the chat lifts it.
61
+ 3. **A destructive git command is refused.** Ask Bob to run `git reflog expire --expire=now --all`. It is refused the same way.
62
+ 4. **A commit warns.** Ask Bob to commit a change. The commit goes through, and Bob's hook log has a Geneseed line about consent: Bob cannot ask, so this rule is a warning there.
63
+ 5. **Record what Bob sends.** Start Bob with `GENESEED_HOOK_TAP` set to an absolute directory outside any repository, for example `GENESEED_HOOK_TAP=$HOME/geneseed-tap`. Then start a session, send a prompt, let Bob run one command and edit one file, and let the turn end. Each hook call writes one file, `bob-<event>-<n>.json`.
64
+
65
+ A tap file holds the payload's shape and not its content. Every key is kept; every string is replaced by its type and length, except the event name and the tool name. Your prompt, file contents, commands and paths are not in it. Read the files before you send them all the same, then attach them to an issue at <https://github.com/Arylmera/Geneseed/issues>, with your Bob version. One file per event is enough. Unset the variable afterwards: nothing is written without it, and Geneseed never puts it in a settings file. The tap works the same way on Claude Code and OpenClaude.
66
+
55
67
  ## Dry-run a build before you write it
56
68
 
57
69
  `geneseed validate` takes the same flags as `geneseed build`. It renders into a throwaway sandbox and runs every doctor check against the result. Nothing is written under the real `--out` or `--root`: no marker files, no settings merge, no registry record.
@@ -20,6 +20,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
20
20
  | --- | --- | --- |
21
21
  | `GENESEED_HOME` | build / hooks | Directory holding the hook shim `bin/geneseed-hook` (default `~/.geneseed`). Change it, then rebuild, so the emitted hooks point at the new location. |
22
22
  | `GENESEED_ACTIVITY` | hooks, OpenCode plugin | `off` (or `0`, `false`, `no`) stops the activity writer; the hooks then load none of its code. Absent means on. See [geneseed-activity](plugin-activity.md). |
23
+ | `GENESEED_HOOK_TAP` | hooks | An absolute directory outside any repository. Every hook call then writes one file there, `<host>-<event>-<n>.json`, holding the payload's shape: keys kept, every string replaced by its type and length. For recording what a host really sends; unset, nothing is written. A directory inside a git worktree is refused. See [Verify it works](../guides/verify.md#bob-by-hand). |
23
24
  | `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
24
25
  | `OPENCODE_CONFIG_DIR` | OpenCode emits, `diff`, plugins | OpenCode's config dir — where the global install is written. OpenCode still loads `$XDG_CONFIG_HOME/opencode` beside it, so `status` and `doctor` warn when both hold a Geneseed install. |
25
26
  | `XDG_CONFIG_HOME` | every emit, hooks, plugins, web console | The base of the [shared tier](../concepts/shared-tier.md), `$XDG_CONFIG_HOME/geneseed` (default `~/.config/geneseed`), on every host. Also used when `OPENCODE_CONFIG_DIR` is unset: the install goes to `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). |
@@ -44,7 +44,7 @@ settings spell it, through the host's own shell, on `git reflog expire --expire=
44
44
  and `git status` (which must go through). A gate wired with `--no-deletion-gate` lets the first one
45
45
  through by design, so it is probed on `find / -name geneseed-probe` instead — a root-wide scan it
46
46
  must still refuse. `--no-secrets-gate`, `--no-done-gate`, `--no-ownership-gate`, `--no-external-gate` and
47
- `--no-test-note` change nothing here: none judges either probe command. An OpenCode install's guard plugin has no command to
47
+ `--no-test-note` change nothing here: none judges either probe command. A Bob gate is asked twice more, in Bob's own shapes: the same two commands in its older `{event, tool, input}` payload, and a `write_file` carrying a made-up credential, which it must refuse. A problem line from one of those ends with the shape in brackets, and a gate wired `--no-secrets-gate` is not asked the last one. An OpenCode install's guard plugin has no command to
48
48
  run: the probe imports it and calls its hook through both plugin APIs (V1 and V2), with `rm -rf /`
49
49
  as the call it must refuse. `GENESEED_GUARD=off` or `warn` in your terminal makes that a note,
50
50
  not a failure.
@@ -8,8 +8,9 @@ chars/4 estimates and shift a little with theme and version.
8
8
  the default doctrine packs, 47 skills (plus 12 alias stubs) and 18 agents, and nothing
9
9
  re-measures this page automatically. For a
10
10
  live figure on your own install, ask the agent for the `token-report` skill —
11
- that is what it is for. A `--footprint full` build runs roughly 5k tokens
12
- heavier on the root file.
11
+ that is what it is for. A `--footprint full` build ran about 7k tokens heavier
12
+ when the whole request was captured on 2026-11-12 (see
13
+ [Why there is no chat mode](#why-there-is-no-chat-mode)).
13
14
 
14
15
  ## Always-on cost per session
15
16
 
@@ -101,6 +102,69 @@ until 2026-09 it did, and the whole harness was paid twice per session.
101
102
  - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
102
103
  never enters the context window.
103
104
 
105
+ ## Why there is no chat mode
106
+
107
+ A "chat mode" would switch the harness off for a quick question, so a "hey, how are you?"
108
+ does not load the rules. It was measured on 2026-11-12 and turned down: the harness stays
109
+ loaded in every session.
110
+
111
+ **What was measured.** Each host was installed from npm and pointed at a local endpoint that
112
+ captured the request it sent for one short prompt, in an empty folder, with and without a
113
+ default global install. Sizes are characters of the request; tokens are chars/4.
114
+
115
+ | Host | No harness | Lean (default) | Full | Harness share, lean | Harness share, full |
116
+ |---|---|---|---|---|---|
117
+ | Claude Code 2.1.322 | 45,964 | 89,935 | 118,486 | ~11k tokens | ~18k tokens |
118
+ | OpenClaude 0.32.0 | 86,122 | 128,457 | 157,003 | ~11k tokens | ~18k tokens |
119
+ | OpenCode 1.19.5 | 30,435 | 86,811 | 115,599 | ~14k tokens | ~21k tokens |
120
+ | OpenCode 2.2.7 | 22,654 | 70,506 | 99,054 | ~12k tokens | ~19k tokens |
121
+
122
+ Bob was not measured: IBM does not publish Bob Shell on npm.
123
+
124
+ **Why the saving is small.** The harness share is 5–10% of a 200k window. The host re-sends
125
+ it with every message, but where the provider caches prompts it is billed at the full input
126
+ price once per session and at the cached rate after that. A chat mode would save that one
127
+ payment on sessions that stay small talk, and nothing else.
128
+
129
+ **Why it cannot be a command inside the chat.** The harness is in the context before the
130
+ first message, and no host can take text back out of a running conversation. A slash command
131
+ can only tell the model to ignore the rules, which saves no tokens. Switching on a resumed
132
+ conversation was measured too (harness on, resumed without it, resumed with it again):
133
+
134
+ | Host | Resumed without the harness | Resumed with it again |
135
+ |---|---|---|
136
+ | OpenClaude | sheds it (86,390) | back to normal (128,963) |
137
+ | OpenCode 1 | sheds it (30,606) | back to normal (87,250) |
138
+ | Claude Code | keeps it in the history (91,213) | loads it a second time (126,697) |
139
+ | OpenCode 2 | keeps it in the system prompt (68,273) | loads it a second time (118,720) |
140
+
141
+ On Claude Code and OpenCode 2 a toggle therefore costs more than it saves. A plain resume,
142
+ with the same configuration, adds only the new message on all four hosts.
143
+
144
+ **Why not a ready-made excluded folder.** An [excluded folder](concepts/exclusions.md) is for a
145
+ repo that brings its own setup, not for saving tokens. On Claude Code and OpenClaude it
146
+ removes the instructions file but leaves the skill and agent listings (about 3k tokens). On
147
+ OpenCode the request was byte-identical with and without the exclusion.
148
+
149
+ **If you want a session without the harness anyway**, each host has its own launch switch.
150
+ These are the hosts' options, not Geneseed's: they were checked on the versions above, in
151
+ non-interactive mode with an API key, and a host update can change them.
152
+
153
+ | Host | Launch line | Measured |
154
+ |---|---|---|
155
+ | Claude Code | `claude --setting-sources project,local` | 45,963 — the no-harness size |
156
+ | OpenClaude | `openclaude --setting-sources project,local` | 86,124 — the no-harness size |
157
+ | OpenCode 1 | `XDG_CONFIG_HOME=<empty dir> opencode` | 30,435 — the no-harness size |
158
+ | OpenCode 2 | `OPENCODE_CONFIG_DIR=<empty dir> opencode --standalone` | 22,654 — the no-harness size |
159
+
160
+ Such a session has no rules and no gates, and on Claude Code and OpenCode 2 they cannot be
161
+ added back to the same conversation cleanly. `XDG_CONFIG_HOME` is inherited by every program
162
+ the session starts, so git and other tools lose their own configuration too. On OpenCode 1,
163
+ `OPENCODE_CONFIG_DIR` changes nothing. Whether a subscription login survives
164
+ `--setting-sources` on Claude Code was not checked.
165
+
166
+ The decision is recorded in [Considered and refused](design-history.md#considered-and-refused).
167
+
104
168
  ## Why your session may show more
105
169
 
106
170
  The always-on figures above are the *harness's* share. A real session's
@@ -17,5 +17,5 @@ How Geneseed treats each host it installs into. Part of [Why Geneseed works this
17
17
  - **OpenCode gets a one-line managed `AGENTS.md` when that file is missing.** OpenCode falls back to `~/.claude/CLAUDE.md` when `AGENTS.md` is absent, which would load the harness twice beside a Claude install. An existing `AGENTS.md` is left alone. See [Install for OpenCode](../guides/install-opencode.md).
18
18
  - **Per-repo hooks go into the untracked `settings.local.json`.** The hook commands hold paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks. See [Hook gates](../concepts/hook-gates.md).
19
19
  - **The manifest records which settings file holds the hooks.** Uninstall and the gate stand-down read the manifest's `settings_file` back (`settingsFile` in `js/hosts/hosts.mjs`) rather than assume a path, since the file differs by host and scope (Bob's global one is nested). See [Hook gates](../concepts/hook-gates.md).
20
- - **Copilot was removed in one pass.** It was never verified live, its hook output never reached the model, and it shared no surface with the other hosts. See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) and [Candidate hosts](../candidate-hosts.md).
20
+ - **Copilot was removed in one pass.** Nobody had ever run it against a real Copilot, its hook output never reached the model, and it shared no surface with the other hosts. See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) and [Candidate hosts](../candidate-hosts.md).
21
21
  - **What belongs to the host stays with the host.** Compaction, sandboxing and the plugin runtime are each host's own territory; Geneseed configures them where a host allows and builds no replacement. See [Hosts](../concepts/hosts.md).
@@ -19,3 +19,4 @@ How the generated harness is assembled, ranked and sized. Part of [Why Geneseed
19
19
  - **Marker lines (`Excluded rules:`, `Excluded skills:`) are written only when non-empty.** A default build then stays byte-identical to one from before the option existed. See [DESIGN.md](../../DESIGN.md) and [Exclusions](../concepts/exclusions.md).
20
20
  - **Session files are injected at start unless still identical to their seed, and the root file is never injected a second time.** The host already loads the root file itself; injecting it again paid for the whole harness twice per session. See [Token footprint](../token-footprint.md).
21
21
  - **The context hook keeps its whole output under `OUTPUT_BUDGET`, counting each line's Windows line ending.** Claude Code moves a longer hook output to a file and shows the model a short preview, so everything past the cut is lost without a warning. Splitting the hook into two commands was measured and turned down (see [Considered and refused](../design-history.md#considered-and-refused)). See [Token footprint](../token-footprint.md).
22
+ - **The harness loads in every session; there is no chat mode.** It adds about 11–14k tokens at lean, billed in full once per session where the provider caches prompts, and no host can unload it inside a conversation. A mode that switches it off was measured and turned down (see [Considered and refused](../design-history.md#considered-and-refused)). See [Token footprint](../token-footprint.md#why-there-is-no-chat-mode).
@@ -33,7 +33,7 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
33
33
 
34
34
  If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
35
35
 
36
- **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory checks become a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
36
+ **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules whose Bob cell says *block* in [Rule enforcement, by host](../concepts/enforcement-table.md). The commit/push check becomes a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. For what was checked against Bob itself, see [What is verified](../concepts/host-matrix.md#what-is-verified).
37
37
 
38
38
  <!--/harness-->
39
39
  <!--harness:opencode-->
@@ -8,7 +8,7 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
8
8
  ---
9
9
  Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
10
10
 
11
- **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
11
+ **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Geneseed wires four: context at session start, one combined gate before each tool call, the Activity record on each prompt, and learn at the end of a turn (wired, but Bob sends it no transcript, so only the change report runs). Bob has no "ask" prompt, so the gate refuses outright, and only for the rules whose Bob cell says *block* in [Rule enforcement, by host](../concepts/enforcement-table.md). The commit/push question becomes a log line. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
12
12
 
13
13
  **Shared by every host.** A global Bob install reads and writes the same machine-wide folder as the other hosts, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md).
14
14
 
package/docs/web-ui.md CHANGED
@@ -191,6 +191,11 @@ budget, measured without project context, for the install whose content was cut,
191
191
  largest. It turns amber at 85% of the budget or whenever content was cut, and Needs you adds one
192
192
  suggestion at the same point.
193
193
 
194
+ A row's details draw the skill list against its own ceiling (`SKILL_LISTING_CEILING`,
195
+ `js/inspect/cost.mjs`) under the cost breakdown, as the row draws the root file against its
196
+ ceiling: a bar, then `part / ceiling · share`, red past 100%. Only a Claude Code install has that
197
+ ceiling, so no other host's details show the bar.
198
+
194
199
  A global **Spotlight** search lives in the topbar — press <kbd>/</kbd> to focus it (or
195
200
  <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd>, which also works from inside a text field), type
196
201
  to jump to any agent, skill, doc, MCP server, or constitutional rule — the `laws`
@@ -2,5 +2,5 @@
2
2
  "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
3
3
  "theme": "neutral",
4
4
  "product": "Geneseed",
5
- "version": "5.3.0"
5
+ "version": "5.3.1"
6
6
  }