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
package/CHANGELOG.md CHANGED
@@ -8,6 +8,33 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [5.3.1] — 2026-11-12
12
+
13
+ **Upgrade note.** The fixed hook commands, matchers and plugins reach an install only when it is emitted again: run `geneseed rebuild-all` after the update.
14
+
15
+ ### Fixed
16
+ - **A gate that cannot run asks instead of letting the call through.** A gate verb that cannot parse its arguments, or runs on a Node below the floor, asks (Bob warns and exits 0, because an exit 2 there refuses every tool). An OpenClaude gate that cannot start asks. On OpenCode each guard gate runs alone, and a gate error asks on OpenCode 2.
17
+ - **A Bob call that carries text is a write, whatever the tool is called.** The check went by tool name only, so `create_file` to `user-rules.md` passed.
18
+ - **The OpenCode content scan reads `edits[]` and nested calls.** The ownership gate skips headless `geneseed-*` sessions, and its marker survives a restart.
19
+ - **A read-only agent cannot dispatch or open a shell monitor.** `Monitor` joins the shell matcher, and Bob spawns are counted.
20
+ - **Geneseed's hook handlers are recognised by signature** (shim, verb and this install's root), not by deep equality. A flag change no longer stacks a second group, a field you added such as `timeout` survives, and uninstall removes what it finds. A commented settings file gets the canonical groups printed.
21
+ - **A commented `opencode.json` is refused whatever its extension**, and uninstall removes the bash gates the manifest recorded.
22
+ - **Stop prints one document.** The change report was lost behind raw model output. The `learn` model call is bounded (`GENESEED_LLM_TIMEOUT`, default 120 s), and no lesson is keyed on a dispatch id.
23
+ - **The OpenCode context plugin keeps the prompt prefix stable**: reminders are appended, and the model line is pinned per session.
24
+ - Host docs: one dated "What is verified" block, and Bob's `learn` and `process-1` wording corrected.
25
+
26
+ ### Added
27
+ - **`GENESEED_HOOK_TAP`**, opt-in, records what a host really sends, every string redacted to its type and length. `doctor --probe` sends Bob its own payload shapes.
28
+ - **A ceiling on the skill listing**, gated by the doctor and drawn in the console on a Claude Code install's details row.
29
+ - `tool-gate` takes `--no-consent`.
30
+
31
+ ### Changed
32
+ - The host canary runs the OpenCode guard's deny on the real hosts against a scripted model on loopback. The twins tool writes every plugin copy that can be byte-identical (6 -> 48 rows).
33
+ - Console dependencies: marked 18.1.3, vite 8.3.7, @vitejs/plugin-react 6.3.0, vitest 5.1.0, jsdom 31.0.0, with `web/dist` rebuilt.
34
+
35
+ ### Removed
36
+ - The drifted `adapters/claude-code/settings.json` sample.
37
+
11
38
  ## [5.3.0] — 2026-11-11
12
39
 
13
40
  ### Added
package/README.md CHANGED
@@ -243,7 +243,7 @@ is **identical on every host**. What differs is how much of it the host can
243
243
  | **Skills** (byte-identical) | ✅ | ✅ | ✅ | ✅ |
244
244
  | **Memory & Notebook** | ✅ | ✅ | ✅ | ✅ |
245
245
  | **Context injection** | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
246
- | **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
246
+ | **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | ➖ wired, inert¹ | 🪝 hook³ |
247
247
  | **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ |
248
248
  | **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ (exit 2) | 🪝 hook³ |
249
249
  | **Laws I / IV at the boundary** | ⚙️ plugin (block) | 🪝 hook (ask) | 🪝 hook¹ (exit 2) | 🪝 hook³ (ask) |
@@ -252,7 +252,7 @@ is **identical on every host**. What differs is how much of it the host can
252
252
  | **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ |
253
253
  | **LSP · workflow runner · primary-agent · `/`-commands** | ✅ | ➖ | ➖ | ➖ |
254
254
 
255
- <sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So Laws I/IV, rigor-5 (External Gate) and ops-2 (a recursive scan of a whole filesystem) exit 2, the consent rules are a stderr line, `SessionStart` context is plain stdout, `Stop` runs learn; `SubagentStop`/`PreCompact` are not Bob events and are not written. Unverified live (no Bob install on the authoring machine); the harness still holds via the rules preamble. · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the host's own prompt asks there, and the guard refuses a file-tool write that prompt cannot reach. Shell is not a boundary on any host; the host's command permission is the backstop, and a [change report](docs/concepts/hooks.md#the-change-report) tells you afterwards. · ³ OpenClaude is a Claude Code fork: Claude's hook groups and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). Unverified live (no OpenClaude install on the authoring machine).</sub>
255
+ <sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So the rules whose Bob cell says *block* in the [enforcement table](docs/concepts/enforcement-table.md) exit 2, the commit/push consent is a stderr line, and `SessionStart` context is plain stdout. `Stop` is wired but learns nothing, because Bob's `Stop` carries no transcript; only the change report runs there. `SubagentStop` is not a Bob event; Bob 2.2.3 has `PreCompact`/`PostCompact`, which Geneseed does not wire. The harness still holds via the rules preamble. What was checked against each host: [What is verified](docs/concepts/host-matrix.md#what-is-verified). · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the host's own prompt asks there, and the guard refuses a file-tool write that prompt cannot reach. Shell is not a boundary on any host; the host's command permission is the backstop, and a [change report](docs/concepts/hooks.md#the-change-report) tells you afterwards. · ³ OpenClaude is a Claude Code fork: Claude's hook groups and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). See [What is verified](docs/concepts/host-matrix.md#what-is-verified).</sub>
256
256
 
257
257
  **Reading the matrix.** Everything above the divider is at full parity — no host
258
258
  drops an Agent, Skill, or the memory convention. The asymmetry is entirely in
package/SHIPPED.md CHANGED
@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
20
20
  > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
21
21
  > human-readable label only. The canonical identity of an installed harness is the
22
22
  > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
23
- > string. Current label: **5.3.0**.
23
+ > string. Current label: **5.3.1**.
24
24
 
25
25
  ## Capabilities
26
26
 
@@ -9,7 +9,7 @@ Claude engine** verbatim — only the marker dir (`.bob`) and the instructions
9
9
  filename (`AGENTS.md`) change. There is nothing to install by hand: `geneseed
10
10
  setup` (or `geneseed build --emit bob` / `--emit bob-global`) writes everything.
11
11
 
12
- This page documents the two verified **Bob-isms** the engine handles, and one
12
+ This page documents the **Bob-isms** the engine handles, and one
13
13
  limitation to be aware of on a shared repo.
14
14
 
15
15
  ## What the emit writes
@@ -86,8 +86,7 @@ and fell back to searching the filesystem. The Bob emit therefore writes the dir
86
86
 
87
87
  ## Hooks — Bob's own protocol
88
88
 
89
- Bob documents lifecycle hooks (its hooks page and the 2.0.2 changelog; see
90
- `docs/reviews/bob-global-injection-2026-09.md` for the reading): **five events** —
89
+ Bob documents lifecycle hooks (its hooks page and the 2.0.2 changelog): **five events** —
91
90
  `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` — with Claude's
92
91
  names but **not Claude's protocol**, and the global file at the **nested**
93
92
  `~/.bob/settings/settings.json`. Two differences decide the emit:
@@ -105,8 +104,8 @@ What the global emit writes into `~/.bob/settings/settings.json`:
105
104
  | event | verb | how the verdict travels |
106
105
  | --- | --- | --- |
107
106
  | `SessionStart` | `context --host bob` | plain stdout, as on Claude |
108
- | `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr — it says no chat confirmation lifts the block, since Bob has no ask tier; process 1/5: a stderr line, exit 0; the ownership gate (the session's first write in an application repo with no `## Ownership` section in its root `AGENTS.md`): **exit 2 once**, the same write then passes — off with `--no-ownership-gate`, `mode: off`, or a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md` |
109
- | `Stop` | `learn` | never a verdict |
107
+ | `PreToolUse` | `tool-gate --host bob` — one group, no matcher | the rules whose Bob cell says *block* in the [enforcement table](../../docs/concepts/enforcement-table.md): **exit 2**, reason on stderr — it says no chat confirmation lifts the block, since Bob has no ask tier; the commit/push consent (process 5) and a parsed shell write to a rule store: a stderr line, exit 0; the ownership gate (the session's first write in an application repo with no `## Ownership` section in its root `AGENTS.md`): **exit 2 once**, the same write then passes — off with `--no-ownership-gate`, `mode: off`, or a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md` |
108
+ | `Stop` | `learn` | never a verdict. **Wired but inert:** Bob's `Stop` carries no transcript, so nothing is distilled; only the [change report](../../docs/concepts/hooks.md#the-change-report) runs (on stderr). The group is kept so that learning starts if Bob ever sends a transcript |
110
109
  | `UserPromptSubmit` | `activity --host bob` | never a verdict; records the turn for the web console's Activity view |
111
110
 
112
111
  Every hook also feeds the Activity view after it decides (off with `GENESEED_ACTIVITY=off`).
@@ -135,24 +134,38 @@ id), `cwd` (the root workspace, with a lower-case drive letter on Windows), and
135
134
  No matcher on `PreToolUse`, deliberately: Bob's tools page already drifts from its own
136
135
  changelog (`web_fetch`, the 2.1.0 Office/IBM-docs tools are undocumented there), so an
137
136
  allow-list built from it would fail open on the next tool Bob adds, and a deny-list needs a
138
- regex dialect (lookahead) the docs never confirm — bob-verdict.md O1 rates the matcher's own
139
- upside "low, performance only", not worth either risk. `tool-gate` reads the payload's shape
137
+ regex dialect (lookahead) the docs never confirm — and the matcher's own upside is low,
138
+ performance only, not worth either risk. `tool-gate` reads the payload's shape
140
139
  instead — a `command` field gets the git checks, a path gets the rule checks — and defers on
141
- anything it does not recognise. Bob has **no "ask the user" tier**, so the Laws and checks
142
- that admit no judgement call — Laws I and IV, rigor-5 (External Gate, when a project
143
- opts in) and ops-2 (Commands Must Return: a recursive scan rooted at a whole filesystem) —
144
- are refused outright, and the two consent rules become a warning. Because that
145
- warning is all process 5 can be here, the `process` pack toggle changes nothing in Bob's
146
- hooks: the one group only ever exits 2 for Laws I and IV, rigor-5 and ops-2, which every build
147
- carries.
140
+ anything it does not recognise. Bob has **no "ask the user" tier**, so the rules
141
+ that admit no judgement call are refused outright, and the commit/push consent becomes a
142
+ warning. Which rules those are is written in one place, the Bob column of the
143
+ [enforcement table](../../docs/concepts/enforcement-table.md); `geneseed doctor` holds that
144
+ column to `BLOCK_RULES` in `js/hosts/hooks.mjs`. A build without the `process` pack carries
145
+ `--no-rule-store`, which drops the standing-rule block, and `--no-consent` (also when process 5
146
+ alone is excluded): the commit/push warning stops, as Claude's ask does. Nothing else in the
147
+ group changes.
148
+
149
+ **When the hook cannot start** (the shim is gone, node will not load), Bob sees a non-zero
150
+ exit that is not 2 and lets the call through; nothing is added to the command to change that.
151
+ The two ways a command could answer are both wrong here: Bob ignores a `PreToolUse` hook's
152
+ stdout, so a printed ask says nothing, and a tail that exits 2 would refuse every tool call
153
+ with no prompt through which you could lift it. `geneseed doctor --probe` runs the gate and
154
+ reports one that does not start.
155
+
156
+ **What fires.** `tool-gate` also counts skill and sub-agent calls for the web console's
157
+ Overview: `spawn_subagent` by its `name`, `start_subtask` by its `mode`. A subtask's `title` is
158
+ never recorded: it is free text, and the count keeps no prompt.
148
159
 
149
160
  **Migration.** A re-emit over an older install unwires Geneseed's groups from the flat
150
161
  `~/.bob/settings.json` (your own keys there are kept) and writes the new set to the
151
162
  nested file.
152
163
 
153
- **Partly verified.** The payload field names are Claude's: Bob 2.2.3's bundle shows them,
154
- and a live Activity check on 2026-10-25 recorded a Bob session from them. The gates' own
155
- verdicts are still Bob's documented contract. If a field
164
+ **What is verified** about Bob — the bundle read, the two live sessions, and what neither
165
+ covers — is in one place:
166
+ [What is verified](../../docs/concepts/host-matrix.md#what-is-verified). To check your own
167
+ install by hand, and to record what your Bob really sends (`GENESEED_HOOK_TAP`), see
168
+ [Verify it works](../../docs/guides/verify.md). If a field
156
169
  name differs the gate defers rather than misfires, and the harness still holds through
157
170
  the `rules/geneseed.md` preamble — the same behaviour-contract parity every
158
171
  non-OpenCode host gets. `/hooks` in Bob Shell 2.0.2+ lists the hooks it loaded and
@@ -180,7 +193,7 @@ servers from ([Bob docs](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-b
180
193
  ## Slash commands
181
194
 
182
195
  Bob documents `.bob/commands/*.md` (project) and `~/.bob/commands/*.md` (global), with
183
- `description` frontmatter (bob-docs.md §6 — no use for `argument-hint` yet: no Geneseed
196
+ `description` frontmatter (Bob's slash-commands docs page — no use for `argument-hint` yet: no Geneseed
184
197
  skill takes positional arguments). Geneseed writes one command per merged skill's OLD name
185
198
  (`/old-name`, the same alias problem OpenCode's `command/` layer solves) and one per
186
199
  genuinely user-only skill (host-compat O2/R1): Bob's skills page documents only
@@ -8,13 +8,23 @@ self-discipline.
8
8
 
9
9
  ## Install
10
10
 
11
- Merge [`settings.json`](settings.json) into your repo's `.claude/settings.json`.
12
- (Not your *user* settings: the hook commands are repo-relative — `node
13
- bin/geneseed-hook.mjs …` — so at user scope they would fire and fail in every
14
- repo that doesn't vendor the harness. A generated global install wires
15
- absolute-path hooks instead — `geneseed setup` does that for you.) It:
11
+ `geneseed setup` (or a `--emit claude` build) merges the hooks into the install's settings
12
+ file: `.claude/settings.local.json` for a project install, `~/.claude/settings.json` for a
13
+ global one. There is no sample file to copy: each command carries this machine's shim path, the
14
+ install's own `--root` and the gate flags the build chose, so only the emit can write it. When
15
+ the settings file has comments the emit does not rewrite it, and prints the exact `hooks` object
16
+ to merge by hand instead.
16
17
 
17
- - on **PreToolUse** (matcher `Bash|PowerShell`), runs `geneseed-hook git-gate` — the tool-boundary
18
+ A re-emit recognises its own handlers by that signature (the shim, a hook verb, this install's
19
+ `--root`), replaces them where they sit and leaves everything else as found: your own hooks, a
20
+ hook you added inside one of these groups, and a field you set on one of ours, such as
21
+ `timeout`. Uninstall removes the same handlers and nothing else. A hook you write yourself that
22
+ runs the shim with this install's `--root` counts as Geneseed's.
23
+
24
+ The wiring:
25
+
26
+ - on **PreToolUse** (matcher `Bash|PowerShell|Monitor`, the three tools that run a shell
27
+ command), runs `geneseed-hook git-gate` — the tool-boundary
18
28
  half of Doctrine process 5 (*consent before every commit and push*) and of the
19
29
  destructive-git Rule. Drop the `process` pack (or exclude process 5) and the hook stays,
20
30
  wired with `--no-consent`: commits and pushes pass without asking (excluding process 1 or ops 2,
@@ -32,15 +42,16 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
32
42
  next time regardless. Every other Bash command (and any unreadable payload) is
33
43
  deferred to the normal permission flow — the hook never blocks unrelated work.
34
44
 
35
- **Caveat — the GitHub MCP vector.** The hook matches the `Bash` and `PowerShell` tools
36
- only. If your session has the GitHub MCP server, an agent can commit/push via
37
- `push_files` / `create_or_update_file` / `merge_pull_request`, which bypass both. To
38
- gate those too, widen the matcher to `"Bash|PowerShell|mcp__github__.*"` —
45
+ **Caveat — the GitHub MCP vector.** The hook matches the `Bash`, `PowerShell` and `Monitor`
46
+ tools only. If your session has the GitHub MCP server, an agent can commit/push via
47
+ `push_files` / `create_or_update_file` / `merge_pull_request`, which bypass all three. To
48
+ gate those too, widen the matcher to `"Bash|PowerShell|Monitor|mcp__github__.*"` —
39
49
  `git-gate` ignores any payload it doesn't recognise as a commit/push, so
40
- over-matching the tool surface is harmless.
50
+ over-matching the tool surface is harmless. A re-emit puts the matcher back as it
51
+ wrote it, so widen it again after a rebuild.
41
52
  - on **PreToolUse** (matcher `Write|Edit|NotebookEdit`), runs
42
- `geneseed-hook rule-gate` — refuses a write that would put a credential into a tracked
43
- file, and asks first on a write to `user-rules.md` or the rule draft (a standing rule is
53
+ `geneseed-hook rule-gate` — asks first on a write that would put a credential into a tracked
54
+ file, and on a write to `user-rules.md` or the rule draft (a standing rule is
44
55
  your call; memory is written freely, and you see it afterwards in the web console). In an application repo (a git
45
56
  root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, it also
46
57
  denies the session's first write once, with a reason addressed to the agent: propose the
@@ -54,12 +65,9 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
54
65
  - on **SessionStart**, every source (`startup`, `resume`, `clear`, `compact`, `fork`), runs
55
66
  `geneseed-hook context` to **inject the project context** directly into the session — so
56
67
  the project-context load is by the hook, not left to the agent to remember (lazy entries
57
- are only listed). This is one matcher-less group, exactly as a generated install wires it:
58
- a matcher list is one more place to miss a source (`fork` once was). A second group,
59
- `startup`/`clear` only — a fresh context — prints `AGENT.md` so the vendored harness is in
60
- context from the first turn. A generated install has no such group: its root file is
61
- `CLAUDE.md`, which Claude Code loads by itself. A resumed or forked conversation already
62
- carries the harness, so re-printing the static file there is pure token waste;
68
+ are only listed). This is one matcher-less group: a matcher list is one more place to miss
69
+ a source (`fork` once was). The harness itself is not printed here: the install's root file
70
+ is `CLAUDE.md`, which Claude Code loads by itself;
63
71
  - on **Stop**, runs `geneseed-hook learn` over the session to capture durable memories.
64
72
  Claude Code pipes the hook payload (with the session's `transcript_path`) to the
65
73
  command on stdin; `learn` reads that, flattens the transcript, distils new
@@ -96,9 +104,6 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
96
104
  `learn` finds a project install or bundle in the cwd or `./Harness`. Any other `memory/` is not a store until it is named:
97
105
  `--memory <dir>` or `GENESEED_MEMORY=/abs/path/to/memory`.
98
106
 
99
- Adjust the paths if your harness bundle is not at the repository root. On Windows
100
- the commands are identical (`node bin/geneseed-hook.mjs …`).
101
-
102
107
  Why inject rather than instruct? The constitution tells the agent to read the project
103
108
  context at startup, but startup rituals are exactly what agents skip. The
104
109
  `geneseed-hook context` hook removes the choice: the eager files' contents land in
@@ -55,22 +55,32 @@ global config file.
55
55
 
56
56
  ## Hooks
57
57
 
58
- The Claude group set, unchanged: `PreToolUse` (git gate on `Bash|PowerShell`, rule gate on
59
- writes), `SessionStart` (context on every source — one matcher-less group covers
58
+ The Claude group set: `PreToolUse` (git gate on `Bash|PowerShell|Monitor`, rule gate on
59
+ writes, and a counter on `Skill|Agent|Task` that judges nothing), `SessionStart` (context on every source — one matcher-less group covers
60
60
  `startup`, `resume`, `clear`, `compact` and `fork` alike), `Stop`,
61
61
  `SubagentStop` and `PreCompact` (learn), `SubagentStart` (`context`, which hands a sub-agent
62
62
  your `user-rules.md` layers as `hookSpecificOutput.additionalContext`; OpenClaude 0.32.0's
63
63
  bundle reads that field for this event), and `UserPromptSubmit` and `SessionEnd`
64
64
  (`activity`, which feeds the web console's Activity view). OpenClaude reads Claude's
65
65
  `hookSpecificOutput.permissionDecision`, so the gates **ask** where Claude asks.
66
- The context hook carries `--host openclaude` for one reason. It tells the hook
67
- which root file OpenClaude already loads (`AGENTS.md` when present, else
68
- `CLAUDE.md`), so that file is not injected a second time.
66
+
67
+ **When a gate cannot start** (the shim is gone, node will not load), Claude Code blocks the
68
+ call through `onFailure: "block"`. OpenClaude forked before that field existed and reads the
69
+ empty stdout as "nothing to say", so every call would go through unjudged. Its two gate
70
+ commands therefore end in `|| printf '%s' '<ask>'`: when the gate did not exit 0, the shell
71
+ itself prints a fixed ask, and you are prompted. OpenClaude always runs hooks under Git Bash or
72
+ sh, where that spelling is valid. The counter has no such tail: a counter that cannot start
73
+ must not ask.
74
+
75
+ The context hook carries `--host openclaude` to tell the hook which root file OpenClaude
76
+ already loads (`AGENTS.md` when present, else `CLAUDE.md`), so that file is not injected a
77
+ second time. The other hooks carry it so a relocated install stands down correctly and its
78
+ activity is filed under OpenClaude, not Claude.
69
79
 
70
80
  ## Not supported
71
81
 
72
82
  - **Workflows.** OpenClaude ships its `WorkflowTool` disabled, so the `workflow`
73
83
  skill falls back to parallel agents, as on Bob.
74
- - **Live verification.** The emit follows OpenClaude's source (`src/utils/envUtils.ts`,
75
- `src/utils/claudemd.ts`, `src/utils/config.ts`, `src/types/hooks.ts`) as of
76
- 2026-09. It has not been run against an installed OpenClaude yet.
84
+ - **Hooks that need a model turn** are checked on no host. What was checked against
85
+ OpenClaude itself, how and when, is in one place:
86
+ [What is verified](../../docs/concepts/host-matrix.md#what-is-verified).
@@ -103,7 +103,12 @@ changed for each plugin:
103
103
  The note exists only for the two asks the guard hands to the host: a rule write that reaches a host prompt, and a gate configuration file. Every other outcome here is a refusal, and a refusal goes to the model. A V2 refusal is the renamed tool, and core quotes that name in its `No tool named` error. The history keeps the original tool name, so several lines of text there reach no provider as a name (seen on 2.2.6 with a fake model, through `opencode run`).
104
104
 
105
105
  None of this is checked by a mock alone: `node tests/host_canary.mjs` starts the real V1 and V2
106
- and fails on the host's own `failed to load plugin` log line.
106
+ and fails on the host's own `failed to load plugin` log line. It then runs that refusal on both:
107
+ a scripted model on loopback (`tests/helpers/fake_model.mjs`) asks `opencode run` to write
108
+ `.ssh/id_rsa`, and the canary fails unless the file is absent, the next write lands, and the
109
+ model is sent the refusal — V1's thrown `[geneseed-guard] blocked:`, V2's `No tool named
110
+ "BLOCKED, not a missing tool: …"`. So a V2 that resolves the tool before `execute.before`, or
111
+ drops an unknown name without telling the model, turns the canary red.
107
112
 
108
113
  ## 4. Subagents, skills & commands
109
114
 
@@ -127,8 +132,8 @@ to native **skills**, not slash commands (same `SKILL.md` shape as Claude Code).
127
132
  | --- | --- |
128
133
  | `instructions` → `AGENT.md` | the rules, loaded every session |
129
134
  | `.opencode/agents/`, `.opencode/skills/` | capability agents and native skills |
130
- | plugin on `session.created` | **context plugin (v2)** — auto-discovers & injects the repo's `eager` docs |
131
- | plugin on `experimental.session.compacting` | **context plugin** — re-pushes the `eager` docs so they survive compaction |
135
+ | plugin on `experimental.chat.messages.transform` (V1) / `session.hook("context")` (V2) | **context plugin** — the default delivery: auto-discovers the repo's `eager` docs and prepends them to every request as one synthetic user message, so nothing shows in the conversation and compaction cannot drop it |
136
+ | plugin on `session.created` + `experimental.session.compacting` | **context plugin** — the visible delivery, only with `GENESEED_CONTEXT_VISIBLE=1` or when a V1 build lacks the transform hook: one visible message per session, re-pushed into the compaction context |
132
137
  | plugin on `session.idle` | **learn plugin** — distils memory into `memory/` (debounced to fire once, at session end) |
133
138
  | plugin on `experimental.chat.messages.transform` (V1) | **context plugin** — also adds the done gate's reminder when a check in `.geneseed/done-checks.txt` (or, without it, a check inferred from the root manifests) has not passed since the last edit (Verify Before Asserting); OpenCode 2 turns are not judged |
134
139
  | plugin on `tool.execute.before` | **guard plugin** — blocks secret-file writes and credential-shaped write content (Sealed Secrets), writes to a protected check or the done list (External Gate), catastrophic shell and every other real data loss, judged against the repository's state (Deletion Is Deliberate), a recursive whole-filesystem scan (Commands Must Return), a rule-store write the host cannot prompt for (Persist Insight), protected wiki folders, and the session's first write in an application repo with no `## Ownership` section in its root `AGENTS.md` (the ownership gate, once; a child session defers; off with `--no-ownership-gate` or a personal `Setup: declined <date>` line in `.geneseed/ownership.md`); logs each block to the gate ledger and counts skill/subagent use (`GENESEED_GUARD=off\|warn`) |
@@ -199,41 +199,40 @@ function ownRowsDeduped(turns, launchedIn) {
199
199
  d.by != null || !since.has(d.raw) || order(key) < since.get(d.raw)))
200
200
  }
201
201
 
202
- // The fs-only readers below are twins of js/hosts/gitref.mjs (gitRootOf, gitDirOf,
203
- // mainWorktreeOf): a plugin is copied whole into an install and cannot import js/.
204
- // tests/plugins/activity.test.mjs compares each with its original, quotes, semicolons and
205
- // layout aside; change one, change both.
202
+ // The fs-only readers below are js/hosts/gitref.mjs's (gitRootOf, gitDirOf, mainWorktreeOf),
203
+ // verbatim: a plugin is copied whole into an install and cannot import js/. Edit the original;
204
+ // `node tests/twins.mjs --write` copies it here, house style included.
206
205
  function gitRootOf(cwd) {
207
206
  try {
208
- let dir = path.resolve(cwd)
207
+ let dir = path.resolve(cwd);
209
208
  for (;;) {
210
- if (existsSync(path.join(dir, ".git"))) return dir
211
- const up = path.dirname(dir)
212
- if (up === dir) return null
213
- dir = up
209
+ if (existsSync(path.join(dir, '.git'))) return dir;
210
+ const up = path.dirname(dir);
211
+ if (up === dir) return null;
212
+ dir = up;
214
213
  }
215
214
  } catch {
216
- return null
215
+ return null;
217
216
  }
218
217
  }
219
218
  function gitDirOf(root) {
220
- const dotgit = path.join(root, ".git")
219
+ const dotgit = path.join(root, '.git');
221
220
  if (statSync(dotgit).isFile()) {
222
- const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, "utf8"))
223
- if (!m) throw new Error(`${dotgit} does not name a gitdir`)
224
- return path.resolve(root, m[1])
221
+ const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, 'utf8'));
222
+ if (!m) throw new Error(`${dotgit} does not name a gitdir`);
223
+ return path.resolve(root, m[1]);
225
224
  }
226
- return dotgit
225
+ return dotgit;
227
226
  }
228
227
  function mainWorktreeOf(cwd) {
229
228
  try {
230
- const root = gitRootOf(cwd)
231
- if (!root || !statSync(path.join(root, ".git")).isFile()) return null
232
- const gitdir = gitDirOf(root)
233
- const common = path.resolve(gitdir, readFileSync(path.join(gitdir, "commondir"), "utf8").trim())
234
- return path.basename(common) === ".git" ? path.dirname(common) : null
229
+ const root = gitRootOf(cwd);
230
+ if (!root || !statSync(path.join(root, '.git')).isFile()) return null;
231
+ const gitdir = gitDirOf(root);
232
+ const common = path.resolve(gitdir, readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
233
+ return path.basename(common) === '.git' ? path.dirname(common) : null;
235
234
  } catch {
236
- return null
235
+ return null;
237
236
  }
238
237
  }
239
238