geneseed 3.20.0 → 4.1.0

package/CHANGELOG.md

@@ -8,6 +8,77 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [4.1.0] — 2026-10-13
+
+Minor: the planning, review, debugging and multi-agent skills take the lessons of Superpowers 7.0, and the host canary.
+
+### Changed
+- **brainstorm** asks which build choices (platform, language, key libraries) you want to own; one the agent makes goes in the decision list as its own call. It sizes the work: a quick task is just done, a small change keeps the confirmed list in chat as its spec, and only a project gets a spec file. A fresh subagent then reads that spec as the person who will build it and asks what they would have to guess, replacing the agent rereading its own spec.
+- **plan**: a step records decisions (files, signatures, the spec's values, the test, the check command), not code. A step is marked done only once its check has run green, with the command on the line. A decision taken without asking gets a `Ruling:` line that is reported at the end, and the mid-run "stop for review" clause is gone. The plan file names its task and its spec, and the spec wins a conflict.
+- **debug**: compare against the nearest working twin, trace a bad value back to where it was born, cite evidence as `file:line`, and probe a secret's presence, never its value. The CI branch diffs against the last green run first and replaces guessed sleeps with bounded waits.
+- **Code review**: where the spec says nothing, a crash, hang or data loss on an input it implies is still blocking. Findings end with a *Set aside* list the caller rules on, and `ship` rules on it before pushing. The base is `origin/<default branch>` after a fetch. The reviewer never moves HEAD and never dispatches another reviewer.
+- **pipeline / parallel-agents**: the developer↔tester loop gets two repair rounds, then one fresh developer, then stops (it allowed five, against `bound-the-loop`). An ambiguity is decided and recorded rather than stalling, small edits of one kind run as one unit, no dispatched agent dispatches its own, and an empty diff counts as a failure. `worktree` never forces a refused removal.
+- The `cover-and-verify` doctrine and `develop` run the whole suite once at the end and name every failure, including ones the change did not cause; per step, only the affected tests still run.
+
+### Fixed
+- The daydream skill's cost line showed a mangled price on Claude Code, which replaces a dollar sign followed by a digit with the skill's arguments.
+- On OpenCode 2, the Activity view now names each tool call. OpenCode 2 sends a tool's name only when its input starts streaming, not with the call itself, so every tool card read "undefined".
+
+### Added
+- A host canary, `node tests/host_canary.mjs`. It installs the real OpenCode 1, OpenCode 2, Claude Code and OpenClaude from npm and points each at a throwaway home holding the Geneseed install. It fails when a host refuses one of our OpenCode plugins, reports one of our Claude settings as invalid, or never runs our session-start hook. It never calls a model and needs no account. It runs in CI every Monday against the latest releases and on every pull request that changes what Geneseed installs, so the next host release that breaks the contract is caught within a week rather than by a user. IBM Bob is not covered, because Bob Shell is not published on npm.
+
+## [4.0.2] — 2026-10-12
+
+Patch: none of the OpenCode plugins loaded on OpenCode 2, and MCP is read-only.
+
+### Fixed
+- The seven OpenCode plugins now load on OpenCode 2. OpenCode 2 rewrote the plugin API and refused every Geneseed plugin with *"Plugin must export a default definition with an id and an effect or setup function"*. It skipped them without crashing, so the context load, learn, notify, ponytail, activity and the `workflow` tool were all gone, and the guard's safety gates were silently off. Each plugin now carries both APIs in one file and works on OpenCode 1.3.4 or newer and on OpenCode 2. Plugins no longer load on OpenCode older than 1.3.4. On OpenCode 2 a guard block shows up as a failed tool call that gives the reason, and the Activity view shows no todo list or files-touched count, because OpenCode 2 sends no event for either. Run `geneseed rebuild-all` after updating to install the new plugin files.
+
+### Changed
+- MCP is read-only in the web console and in `geneseed mcp`. Each active install lists only the servers its config already holds, enabled or disabled, with its config path and an **Open folder** button. The **Add** button, the on/off switch and the three built-in presets are gone. Which servers to wire depends on you and on your host, so you edit the config yourself; [MCP servers](docs/guides/mcp.md) still has the blocks for MarkItDown, GitLab and Filesystem. Geneseed no longer writes any MCP config, and the `POST /api/mcp` endpoint is removed.
+
+## [4.0.1] — 2026-10-12
+
+Patch: the web console could not tell apart two project installs of the same host (#244).
+
+### Fixed
+- Two project installs of one host (two repos on Bob, say) are now separate rows in the web console. Both used to get the id `bob:project`, so the Installs table showed both as selected and the topbar harness selector always switched back to the first. The id now carries the install root, and the selector names a project install by its folder. All four hosts had the bug and all four are covered by a test. Nothing is re-emitted; run `geneseed web restart` after updating.
+
+## [4.0.0] — 2026-10-11
+
+Major: a host-compatibility pass against the current IBM Bob, Claude Code, OpenCode and OpenClaude docs (#240), the host opportunities and a root-scan guard (#241), and author notes kept out of what the agent reads (#242). It is a major because three behaviours change visibly: Claude Code gates now block when they cannot run, OpenCode no longer falls back to `~/.claude/CLAUDE.md`, and the silent *process 8* migration is gone.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating: nothing on a machine changes until an install is re-emitted.
+- An install built before the comms pack (3.7.0) is now skipped by `rebuild-all`, `migrate` and `upgrade`; run `geneseed setup` for it.
+- If a Claude Code session suddenly refuses every Bash or Write call, the machine-wide hook shim is missing or stale: run `! geneseed rebuild-all` (see docs/reference/troubleshoot-hooks.md).
+
+### Added
+- A Claude Code plugin marketplace: `/plugin marketplace add Arylmera/Geneseed`, then `/plugin install geneseed@geneseed`. The plugin carries one skill, `/geneseed:setup`, which asks for scope and theme and runs the published CLI (`npm install -g geneseed`, `geneseed build --emit claude-global` or `--emit claude`). It carries no harness of its own, so nothing in it can drift from the build.
+- Bob gets `/`-commands: each skill alias and each user-only skill is a `.bob/commands/<name>.md`, and a user-only skill writes no SKILL.md on Bob, so the model cannot start it there.
+- OpenCode hides user-only skills from the model: each one gets a `permission.skill` deny in `opencode.json`, and `/name` still runs it. Geneseed records the denies it writes in its manifest (`skill_denies`); a rebuild removes a recorded deny once the skill is no longer user-only, and uninstall takes the recorded ones back. A deny you set yourself, even on a Geneseed skill, is never touched.
+- A root-scan check in the shell gate: a recursive scan whose argument is a whole filesystem root (`find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse`) now asks on Claude Code and OpenClaude and is refused on Bob and by the OpenCode guard plugin, citing *Commands Must Return* (ops 2), which gains a sentence saying so in both halves. In Git Bash `/` mounts every drive and share: a `find / … | head -5` ran for 3.5 hours on 2026-10-10. A deeper path, `ls /` without `-R`, a quoted argument, a comment, and the remote half of an `ssh` command pass. It runs inside `git-gate`/`tool-gate`, so no emitted hook command changes. Separators inside quotes and heredoc bodies are data, so a commit message that names such a scan is not one.
+- A dedicated author-note prefix: an HTML comment in `src/` whose body starts with `note:` (`<!-- note: ... -->`, single or multi-line) is stripped before any render sees it — `resolveRuleIds` in `js/build/source.mjs` is the one function every text file threads through (and `parseBrick` in `js/loop/catalog.mjs` calls the same `stripAuthorNotes` directly, since a brick body is handed to the model raw and never goes through `resolveRuleIds` at all), so the strip covers the carrier, the on-disk `laws/`/`doctrines/` copies, every skill, and every brick alike. A comment shown only as a literal example — inside a fenced code block or an inline code span — is left un-stripped, via `blankCodeSpans` (`js/lib/text.mjs`, shared with the doctor arm below so the two can never disagree about what counts as "shown as an example"). Maintainer-only prose that used to ship verbatim (`src/laws/universal.md`'s "Amend BOTH halves", `src/skills/herdr.md`'s "Authoring note") is migrated to the prefix and no longer reaches the agent; the full carrier gains ~176 characters of headroom against its ceiling (unchanged, not lowered), lean is unaffected. `js/inspect/checks-authoring.mjs`'s new `authorNoteProblems` (wired into `doctor --all`) flags any other bare HTML comment in `src/` that is not the `note:` prefix and not a known functional marker (`LEAN:`/`CATALOG:`/`INCLUDE:`, `invocation: user`, `aliases:`, `webfetch: allow`, `harness:` followed by one or more of OpenCode/Claude Code/OpenClaude/Bob's ids, `bash: allow`), the same fence/code-span exemption applied, and separately refuses a `note:` comment whose own prose quotes a literal `<!--`/`-->` — HTML comments do not nest, so such a comment closes at its own inner marker and leaks the rest as live text (the landmine `src/skills/_template.md` hit once, fixed there by rewording the example to prose).
+
+### Changed
+- Claude Code gates now block the tool call when the gate itself fails: `git-gate` and `rule-gate` carry `onFailure: "block"`, so a dead or missing shim, a gate process that crashes or a timeout refuses every Bash, PowerShell, Write, Edit and NotebookEdit call instead of letting it through. This needs Claude Code v2.1.295 or later; whether an older version ignores the key or rejects the settings file is unverified. `doctor` and `status` now report a deleted shim. To recover from inside a blocked session, see [Troubleshoot hooks](docs/reference/troubleshoot-hooks.md). OpenClaude and Bob are unchanged.
+
+### Removed
+- The automatic *process 8* migration. An install built before the comms pack (3.7.0, 2026-09-27) used to be silently rewritten on every rebuild: `doctrinesOfDir` added `comms` so the codes rule it carried inside `process` was not lost, and `excludedRulesOfDir` re-addressed any `process 7`/`process 8` exclusion. Both relied on sniffing `process 8` in the rendered carrier, which breaks the day the process pack ever regains an eighth rule for an unrelated reason — it would then fire on a current install and rewrite data nobody asked rewritten. 4.0.0 removes the rewrite: a pre-comms carrier is now read exactly as written, and reading it (`doctor`, `diff`, `status`, `uninstall`) prints a warning on stderr instead, once per process. `rebuild-all` (and `upgrade`, which shells into it) now **skips** a pre-comms install entirely rather than re-emitting it — re-emitting would have written a fresh carrier that still drops `comms` and still carries unaddressed `process 7`/`process 8` exclusions, except now permanently, with no `process 8` text left for anything to ever catch again. **Upgrading:** if your install predates 3.7.0 and still names `process 8` in its carrier, run `geneseed setup` for it — `rebuild-all`/`upgrade` will skip it and name it in their summary until you do.
+
+### Fixed
+- Bob gates read Bob's own payload (`{event, tool, input}`); they used to read only `tool_input`, so on Bob no gate ever fired. Bob also scans `apply_diff` and `search_and_replace` bodies.
+- The Claude Code and OpenClaude git gate also matches the PowerShell tool (`Bash|PowerShell`); on Windows a destructive git command run through PowerShell used to pass unchecked. Read-only agents deny PowerShell too.
+- A hook argv error never exits 2: a stale machine-wide shim handed a newer flag used to block every tool call.
+- Windows without Git Bash: Claude Code runs hooks under PowerShell, where the emitted command was a parse error. The emit now detects Git Bash and writes a PowerShell form when it is absent; `doctor` and `status` warn when the machine changes after the emit.
+- `CLAUDE_CONFIG_DIR` is honoured. A global hook stands down only for a live project install in `$CLAUDE_PROJECT_DIR` whose settings file still runs the same hook, never for a parent folder, another global install, a deactivated install or a manifest alone.
+- The destructive-git gate also covers `clean --force`, `restore`, `push --delete` and `:branch`, `checkout -f`, `switch -f`, `stash drop/clear`, `worktree remove --force`, `reflog expire` and `gc --prune`, in the hook, the OpenCode guard and OpenCode's permissions.
+- OpenCode: the guard checks every path an `apply_patch` touches (the only edit tool of gpt-* models) and scans written content for secrets; per-repo builds honour `--footprint lean`; plugins, workflows and themes are claimed on create, so a same-named user file survives emit and uninstall; a one-line managed `AGENTS.md` stops OpenCode loading the harness a second time through `~/.claude/CLAUDE.md`; a shadowed install under `OPENCODE_CONFIG_DIR` is reported. The dead `permission.ask` loop exemption is removed; pushes to `loop/*` are allowed by a static rule, and force, delete, an extra refspec and commits still ask.
+- Settings are read back per host, so `rebuild-all`, `upgrade` and the console keep an OpenClaude per-repo install's theme, posture, packs and exclusions, also in a repo shared with another host.
+- Uninstalling one host from a shared repo hands the root marker to the surviving host instead of deleting it; `migrate` reads the settings file the install really wired.
+- `learn` cannot recurse through `claude -p`, reads nothing when `GENESEED_LLM` is unset, and returns at once on Bob, which sends no transcript.
+- `learn` on `SubagentStop` reads the subagent's own transcript (`agent_transcript_path`); it used to distil a lesson from the main session's. When the transcript cannot be read, or lags behind the final turn, it falls back to or appends `last_assistant_message`.
+
 ## [3.20.0] — 2026-10-09
 
 ### Changed

package/README.md

@@ -90,6 +90,14 @@ npm install -g geneseed       # then plain `geneseed <command>` from any directo
 npm install -g geneseed@latest   # …and that is also the update
 ```
 
+Already in Claude Code? Add the plugin marketplace and let Claude run the install:
+
+```
+/plugin marketplace add Arylmera/Geneseed
+/plugin install geneseed@geneseed
+/geneseed:setup
+```
+
 Every other route (Claude Code, Bob, OpenClaude, plain `AGENT.md`, per-repo installs) is in the **[install guide](docs/guides/install.md)**.
 
 ### 🧬 The long way — a git checkout
@@ -238,7 +246,7 @@ is **identical on every host**. What differs is how much of it the host can
 | **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ |
 | **LSP · workflow runner · primary-agent · `/`-commands** | ✅ | ➖ | ➖ | ➖ |
 
-<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 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 rule gate is a one-shot speed bump there rather than a prompt. · ³ 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>
+<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 rule gate is a one-shot speed bump there rather than a prompt. · ³ 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>
 
 **Reading the matrix.** Everything above the divider is at full parity — no host
 drops an Agent, Skill, or the memory convention. The asymmetry is entirely in

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.20.0**.
+> string. Current label: **4.1.0**.
 
 ## Capabilities
 

package/adapters/bob/README.md

@@ -99,16 +99,22 @@ What the global emit writes into `~/.bob/settings/settings.json`:
 | event | verb | how the verdict travels |
 | --- | --- | --- |
 | `SessionStart` | `context --host bob` | plain stdout, as on Claude |
-| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV: **exit 2**, reason on stderr; process 1/5: a stderr line, exit 0 |
+| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr; process 1/5: a stderr line, exit 0 |
 | `Stop` | `learn` | never a verdict |
 
-No matcher on `PreToolUse` because Bob's tool names are undocumented (its IDE and its
-Shell differ); `tool-gate` reads the payload's shape instead — a `command` field gets
-the git checks, a path gets the rule checks — and defers on anything it does not
-recognise. Bob has **no "ask the user" tier**, so the two Laws that admit no judgement
-call are refused outright and the two consent rules become a warning. Because that
-warning is all process 5 can be here, the `process` pack toggle changes nothing in
-Bob's hooks: the one group only ever exits 2 for Laws I and IV, which every build carries.
+No matcher on `PreToolUse`, deliberately: Bob's tools page already drifts from its own
+changelog (`web_fetch`, the 2.1.0 Office/IBM-docs tools are undocumented there), so an
+allow-list built from it would fail open on the next tool Bob adds, and a deny-list needs a
+regex dialect (lookahead) the docs never confirm — bob-verdict.md O1 rates the matcher's own
+upside "low, performance only", not worth either risk. `tool-gate` reads the payload's shape
+instead — a `command` field gets the git checks, a path gets the rule checks — and defers on
+anything it does not recognise. Bob has **no "ask the user" tier**, so the Laws and checks
+that admit no judgement call — Laws I and IV, rigor-5 (External Gate, when a project
+opts in) and ops-2 (Commands Must Return: a recursive scan rooted at a whole filesystem) —
+are refused outright, and the two consent rules become a warning. Because that
+warning is all process 5 can be here, the `process` pack toggle changes nothing in Bob's
+hooks: the one group only ever exits 2 for Laws I and IV, rigor-5 and ops-2, which every build
+carries.
 
 **Migration.** A re-emit over an older install unwires Geneseed's groups from the flat
 `~/.bob/settings.json` (your own keys there are kept) and writes the new set to the
@@ -140,10 +146,23 @@ MCP servers are wired at runtime (web console, listed by `geneseed mcp`) into th
 `~/.bob/settings/mcp.json` global — never `settings.json`, which Bob does not read
 servers from ([Bob docs](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob)).
 
+## Slash commands
+
+Bob documents `.bob/commands/*.md` (project) and `~/.bob/commands/*.md` (global), with
+`description` frontmatter (bob-docs.md §6 — no use for `argument-hint` yet: no Geneseed
+skill takes positional arguments). Geneseed writes one command per merged skill's OLD name
+(`/old-name`, the same alias problem OpenCode's `command/` layer solves) and one per
+genuinely user-only skill (host-compat O2/R1): Bob's skills page documents only
+`name`/`description`, no model-invocation key, so a user-only skill gets **no** SKILL.md on
+Bob at all — `/its-name` is the only way to run it, and the model never sees it in its
+`use_skill` catalogue. Claim-on-create and manifest-owned like every other native file;
+uninstall removes them the same way.
+
 ## What Bob does not get
 
 Bob rides the Claude engine, so — like Claude — it has no OpenCode-only extras:
-colour themes, JS plugins, the saved-workflow runner, the primary-agent
-orchestrator, LSP enablement, or the `/`-command layer. Those capabilities have
-no analogue on a Claude-shaped host; the harness discipline is carried by the
-preamble and skills instead. See the [host matrix](../../README.md#-supported-harnesses).
+colour themes, JS plugins, the saved-workflow runner, the primary-agent orchestrator,
+LSP enablement, or OpenCode's full `/`-command layer (`COMMAND_SET`, `/ponytail`) — only
+the narrow alias/user-only-skill commands above. Those capabilities have no analogue on a
+Claude-shaped host; the harness discipline is carried by the preamble and skills instead.
+See the [host matrix](../../README.md#-supported-harnesses).

package/adapters/claude-code/README.md

@@ -14,7 +14,7 @@ bin/geneseed-hook.mjs …` — so at user scope they would fire and fail in ever
 repo that doesn't vendor the harness. A generated global install wires
 absolute-path hooks instead — `geneseed setup` does that for you.) It:
 
-- on **PreToolUse** (matcher `Bash`), runs `geneseed-hook git-gate` — the tool-boundary
+- on **PreToolUse** (matcher `Bash|PowerShell`), runs `geneseed-hook git-gate` — the tool-boundary
   half of Doctrine process 5 (*consent before every commit and push*) and of the
   destructive-git Rule. Drop the `process` pack (or exclude process 5) and the hook stays,
   wired with `--no-consent`: commits and pushes pass without asking, while the
@@ -27,22 +27,27 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
   next time regardless. Every other Bash command (and any unreadable payload) is
   deferred to the normal permission flow — the hook never blocks unrelated work.
 
-  **Caveat — the GitHub MCP vector.** The hook matches the `Bash` tool only. If your
-  session has the GitHub MCP server, an agent can commit/push via `push_files` /
-  `create_or_update_file` / `merge_pull_request`, which bypass Bash. To gate those too,
-  widen the matcher to `"Bash|mcp__github__.*"` — `git-gate` ignores any payload it
-  doesn't recognise as a commit/push, so over-matching the tool surface is harmless.
-- on **PreToolUse** (matcher `Write|Edit|MultiEdit|NotebookEdit`), runs
+  **Caveat — the GitHub MCP vector.** The hook matches the `Bash` and `PowerShell` tools
+  only. If your session has the GitHub MCP server, an agent can commit/push via
+  `push_files` / `create_or_update_file` / `merge_pull_request`, which bypass both. To
+  gate those too, widen the matcher to `"Bash|PowerShell|mcp__github__.*"` —
+  `git-gate` ignores any payload it doesn't recognise as a commit/push, so
+  over-matching the tool surface is harmless.
+- on **PreToolUse** (matcher `Write|Edit|NotebookEdit`), runs
   `geneseed-hook rule-gate` — refuses a write that would put a credential into a tracked
   file, and asks first on the first write to `user-rules.md` or a memory file (whether
   something you want kept is a rule or a fact is your call). Ordinary edits pass.
-- on **SessionStart** (`startup`/`clear` only — a fresh context), prints `AGENT.md`
-  so the harness is in context from the first turn, then runs `geneseed-hook context` to
-  **inject the project context** directly into the session — so the project-context load is
-  by the hook, not left to the agent to remember (lazy entries are only listed). On
-  **`resume`** it runs `geneseed-hook context` *without* re-`cat`ting `AGENT.md`: the resumed
-  conversation already carries the harness, so re-injecting the static file each resume
-  is pure token waste — only the (possibly changed) project context is refreshed;
+  (`MultiEdit` is not a Claude Code tool and is not in the matcher; the gate reads
+  `edits[].new_string` as a cheap guard regardless.)
+- on **SessionStart**, every source (`startup`, `resume`, `clear`, `compact`, `fork`), runs
+  `geneseed-hook context` to **inject the project context** directly into the session — so
+  the project-context load is by the hook, not left to the agent to remember (lazy entries
+  are only listed). This is one matcher-less group, exactly as a generated install wires it:
+  a matcher list is one more place to miss a source (`fork` once was). A second group,
+  `startup`/`clear` only — a fresh context — prints `AGENT.md` so the vendored harness is in
+  context from the first turn. A generated install has no such group: its root file is
+  `CLAUDE.md`, which Claude Code loads by itself. A resumed or forked conversation already
+  carries the harness, so re-printing the static file there is pure token waste;
 - on **Stop**, runs `geneseed-hook learn` over the session to capture durable memories.
   Claude Code pipes the hook payload (with the session's `transcript_path`) to the
   command on stdin; `learn` reads that, flattens the transcript, distils new
@@ -59,12 +64,14 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
 - on **PreCompact**, runs the same `geneseed-hook learn` once more. `learn` distils the
   *tail* of the transcript, so per-turn Stop is a sliding window over the session —
   and auto-compaction is the moment that window is about to be summarised away.
-  This captures memory *before* the summary; the SessionStart `compact` matcher
-  re-seeds context *after* it.
+  This captures memory *before* the summary; the SessionStart `context` hook (which
+  also fires on the `compact` source) re-seeds context *after* it.
 
   This step is **opt-in on a model CLI**: set `GENESEED_LLM` (e.g. `claude -p`,
   `llm`, `ollama run …`) for `learn` to actually distil. With it unset the hook is
-  a harmless no-op that just prints the prompt. Geneseed never embeds an API key.
+  a harmless no-op — it returns immediately rather than reading the transcript for
+  nothing; running `learn` by hand with notes piped in still prints the prompt it
+  would have sent. Geneseed never embeds an API key.
   If your bundle's `memory/` is not at `./memory` or `./Harness/memory`, point at
   it with `GENESEED_MEMORY=/abs/path/to/memory`.
 

package/adapters/claude-code/settings.json

@@ -2,13 +2,13 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           { "type": "command", "command": "node bin/geneseed-hook.mjs git-gate" }
         ]
       },
       {
-        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           { "type": "command", "command": "node bin/geneseed-hook.mjs rule-gate" }
         ]
@@ -16,16 +16,14 @@
     ],
     "SessionStart": [
       {
-        "matcher": "startup|clear",
         "hooks": [
-          { "type": "command", "command": "node -e \"process.stdout.write(require('fs').readFileSync('AGENT.md','utf8'))\"" },
           { "type": "command", "command": "node bin/geneseed-hook.mjs context" }
         ]
       },
       {
-        "matcher": "resume|compact",
+        "matcher": "startup|clear",
         "hooks": [
-          { "type": "command", "command": "node bin/geneseed-hook.mjs context" }
+          { "type": "command", "command": "node -e \"process.stdout.write(require('fs').readFileSync('AGENT.md','utf8'))\"" }
         ]
       }
     ],

package/adapters/openclaude/README.md

@@ -12,14 +12,21 @@ There is nothing to install by hand: `geneseed setup` (or `geneseed-build --emit
 openclaude` / `--emit openclaude-global`) writes everything.
 
 **OpenClaude never reads `~/.claude`, a project `.claude/`, or `$CLAUDE_CONFIG_DIR`.**
-A Claude Code install is invisible to it, so it gets its own. The two coexist on one
-machine and in one repo without touching each other.
+A Claude Code install is invisible to it, so it gets its own, and neither emit
+overwrites the other's files. On one machine the two coexist cleanly. In one
+repo they do not fully: OpenClaude also reads the root `CLAUDE.md`/`AGENTS.md`
+a Claude Code or Bob per-repo install already wrote there, on top of its own
+`.openclaude/CLAUDE.md` — both harnesses load, and there is no clean exclusion
+(excluding the root file would hide your own content in it too). `geneseed status`
+and `geneseed doctor` warn when this is happening in your repo.
 
 ## What the emit writes
 
 ### Per-repo (`--emit openclaude`)
 
-Everything lives under **`.openclaude/`**. Nothing is written at the repo root.
+Everything lives under **`.openclaude/`**, except the `.geneseed-emit`/
+`.geneseed-footprint` markers and `.mcp.json` below, which the driver writes at the
+repo root like every other host.
 
 - `CLAUDE.md`: the harness preamble as a delimited **managed block**. OpenClaude
   loads the root `AGENTS.md`, or the root `CLAUDE.md` only when `AGENTS.md` is
@@ -47,8 +54,9 @@ global config file.
 
 ## Hooks
 
-The Claude group set, unchanged: `PreToolUse` (git gate on `Bash`, rule gate on
-writes), `SessionStart` (context on `startup|clear` and `resume|compact`), `Stop`,
+The Claude group set, unchanged: `PreToolUse` (git gate on `Bash|PowerShell`, rule gate on
+writes), `SessionStart` (context on every source — one matcher-less group covers
+`startup`, `resume`, `clear`, `compact` and `fork` alike), `Stop`,
 `SubagentStop` and `PreCompact` (learn). OpenClaude reads Claude's
 `hookSpecificOutput.permissionDecision`, so the gates **ask** where Claude asks.
 The context hook carries `--host openclaude` for one reason. It tells the hook

package/adapters/opencode/HOW-OPENCODE-LOADS.md

@@ -64,6 +64,41 @@ export const MyPlugin = async ({ client, $, directory, worktree }) => ({
   **without** triggering a reply with `client.session.prompt({ path, body: { noReply: true, parts } })`.
 - **`$`** — a shell executor for running commands.
 
+### OpenCode 2 — a different plugin API
+
+OpenCode 2 (the `@opencode/cli` package; V1 is still `opencode-ai`) still auto-loads every
+`.js`/`.ts` in `plugins/` (or `plugin/`), but it accepts **only** a default-exported
+definition: `export default { id, setup(ctx) }`. A V1 plugin fails to load with *"Plugin
+must export a default definition with an id and an effect or setup function"*. Each one
+is marked failed on its own and OpenCode carries on, so nothing warns you.
+
+V1 (>= 1.3.4) also accepts an object default, `{ id, server }`, and each loader ignores
+the other's key. So every Geneseed plugin exports **one object for both majors**:
+`export default { id: "<file stem>", server: <V1 factory>, setup: <V2 setup> }`. On V1
+older than 1.3.4 the plugins no longer load.
+
+`setup(ctx)` gets domains instead of hooks returned in a map. Hooks register by name
+(`ctx.tool.hook("execute.before")`, `ctx.session.hook("context" | "prompt" |
+"compaction")`), tools through `ctx.tool.transform`, and events come from
+`ctx.event.subscribe()` as `{ type, created, data }` (not `{ type, properties }`). What
+changed for each plugin:
+
+| V1 | V2 |
+| --- | --- |
+| `session.idle` | not published by core (deprecated). The turn ends with `session.execution.succeeded` / `failed` / `interrupted` |
+| `experimental.chat.messages.transform` / `chat.system.transform` | `session.hook("context")`: mutable `system` parts and `LLM.Message` instances, on every request |
+| `command.execute.before` | none. A markdown command's expanded template arrives through `session.hook("prompt")` |
+| `client.session.messages` | `ctx.session.context({ sessionID })`: `user` / `assistant` messages after the last compaction |
+| throwaway session + `prompt` to distil | `ctx.generate.text({ prompt, model })`: one stateless call |
+| a hook throws to block a tool | a throw is a **defect that fails the whole step**. The guard renames the call instead (see `geneseed-guard.js`) |
+| `@opencode-ai/plugin` `tool()` helper | `@opencode/plugin`; a plain JSON-schema `input` needs no helper |
+| `todo.updated`, session `summary` diffs | no V2 event. The activity cards show no todos or files on V2 |
+| tool part carries its name | `session.tool.called` has no name; it rides on `session.tool.input.started` |
+| tools `bash`, `apply_patch`, `task` | renamed `shell`, `patch`, `subagent` (the old ids are aliases). The guard's substring classes cover both spellings |
+
+None of this is checked by a mock alone: `node tests/host_canary.mjs` starts the real V1 and V2
+and fails on the host's own `failed to load plugin` log line.
+
 ## 4. Subagents, skills & commands
 
 Subdir names are **plural** canonically (`agents/`, `skills/`, `commands/`,

package/adapters/opencode/plugins/geneseed-activity.js

@@ -425,6 +425,109 @@ export const GeneseedActivity = async () => {
 
 // ponytail: OpenCode treats every export as a plugin and rejects non-functions; hang
 // the test helpers off the factory instead — reachable via import, invisible to the loader.
-Object.assign(GeneseedActivity, { sidOf, nextStatus, applyEvent, acctTotals, errStr, snip, safeName, activityDir, enabledFromFlag })
+Object.assign(GeneseedActivity, { sidOf, nextStatus, applyEvent, acctTotals, errStr, snip, safeName, activityDir, enabledFromFlag, toV1Events })
 
-export default GeneseedActivity
+// --- OpenCode 2 --------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// V2's event stream is a different vocabulary (`{ type, created, data }`, the turn as an
+// execution, a message as steps, tool calls as called/success/failed), but every fact the
+// cards show is still in it. Rather than a second reducer, `toV1Events` translates each
+// V2 event into the V1 event(s) the handler above already reduces, so both majors write
+// the same files. Not carried: todos (V2 publishes no todo event) and files-touched (the
+// V1 session summary has no V2 event).
+
+// A V2 SessionError ({ type, message }) in the V1 error union errStr reads.
+const v1Error = (e) => (e ? { name: e.type, data: { message: e.message || e.type } } : undefined)
+
+// V2 event -> the V1 events it means ([] for one the cards ignore). `tools` remembers each
+// running call's name and start (callID -> { name, start }) so its end can say both.
+// Pure but for `tools`; exported for tests.
+function toV1Events(ev, tools) {
+  const d = ev?.data ?? {}
+  const sessionID = d.sessionID
+  if (!sessionID) return []
+  const t = typeof ev.created === "number" ? ev.created : Date.now()
+  const msg = (info) => ({ type: "message.updated", properties: { info: { role: "assistant", sessionID, ...info } } })
+  const part = (p) => ({ type: "message.part.updated", properties: { part: { sessionID, ...p } } })
+  switch (ev.type) {
+    case "session.created":
+      return [{ type: "session.created", properties: { info: {
+        id: sessionID, title: d.title, parentID: d.parentID, directory: d.location?.directory } } }]
+    case "session.renamed":
+      return [{ type: "session.updated", properties: { info: { id: sessionID, title: d.title } } }]
+    case "session.deleted":
+      return [{ type: "session.deleted", properties: { sessionID } }]
+    case "session.execution.started":
+      return [{ type: "session.status", properties: { sessionID, status: { type: "busy" } } }]
+    case "session.execution.succeeded":
+      return [{ type: "session.idle", properties: { sessionID } }]
+    case "session.execution.failed":
+      return [{ type: "session.error", properties: { sessionID, error: v1Error(d.error) } },
+        { type: "session.idle", properties: { sessionID } }]
+    case "session.execution.interrupted":
+      return [{ type: "session.status", properties: { sessionID, status: { type: "idle" } } }]
+    case "session.retry.scheduled":
+      return [{ type: "session.status", properties: { sessionID, status: { type: "retry" } } }]
+    case "session.step.started":
+      return [msg({ id: d.assistantMessageID, mode: d.agent, modelID: d.model?.id, time: { created: t } })]
+    case "session.step.ended":
+      return [msg({ id: d.assistantMessageID, cost: d.cost, tokens: d.tokens, time: { completed: t } })]
+    case "session.step.failed":
+      return [msg({ id: d.assistantMessageID, cost: d.cost, tokens: d.tokens, error: v1Error(d.error), time: { completed: t } })]
+    // The name rides only on `input.started`; `called` carries the input but no name.
+    case "session.tool.input.started":
+      tools.set(d.id, { name: d.name, start: undefined })
+      return []
+    case "session.tool.called": {
+      const name = tools.get(d.id)?.name ?? "tool"
+      tools.set(d.id, { name, start: t })
+      return [part({ type: "tool", callID: d.id, tool: name, messageID: d.assistantMessageID,
+        state: { status: "running", title: name, time: { start: t } } })]
+    }
+    case "session.tool.success":
+    case "session.tool.failed": {
+      const call = tools.get(d.id) ?? { name: "tool", start: undefined }
+      tools.delete(d.id)
+      const failed = ev.type === "session.tool.failed"
+      return [part({ type: "tool", callID: d.id, tool: call.name, messageID: d.assistantMessageID,
+        state: { status: failed ? "error" : "completed", title: call.name,
+          error: failed ? d.error?.message || d.error?.type : undefined, time: { start: call.start, end: t } } })]
+    }
+    case "session.reasoning.started":
+    case "session.reasoning.ended":
+      return [part({ type: "reasoning", id: `r:${d.assistantMessageID}:${d.ordinal}`, text: d.text ?? "" })]
+    case "session.text.ended":
+      return [part({ type: "text", id: `t:${d.assistantMessageID}:${d.ordinal}`, messageID: d.assistantMessageID, text: d.text })]
+    case "permission.asked":
+      return [{ type: "permission.updated", properties: { sessionID, id: d.id, title: d.message || d.action } }]
+    case "permission.replied":
+      return [{ type: "permission.replied", properties: { sessionID, permissionID: d.requestID } }]
+    default:
+      return []
+  }
+}
+
+async function setupV2(ctx) {
+  const hooks = await GeneseedActivity()
+  const tools = new Map()
+  // The user's prompt, as V1's chat.message hook received it.
+  await ctx.session.hook("prompt", async (event) => {
+    try {
+      await hooks["chat.message"]({ sessionID: event?.sessionID, messageID: event?.messageID },
+        { parts: [{ type: "text", text: event?.prompt?.text }] })
+    } catch (err) { log(`prompt hook failed: ${err?.message ?? err}`) }
+  })
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      for (const event of toV1Events(ev, tools)) {
+        try { await hooks.event({ event }) } catch (err) { log(`event ${event.type} failed: ${err?.message ?? err}`) }
+      }
+    }
+  })().catch((err) => log(`event stream ended: ${err?.message ?? err}`))
+  return () => controller.abort()
+}
+
+export default { id: "geneseed-activity", server: GeneseedActivity, setup: setupV2 }

package/adapters/opencode/plugins/geneseed-context.js

@@ -989,4 +989,99 @@ export const GeneseedContext = async (ctx) => {
   }
 }
 
-export default GeneseedContext
+// ---- OpenCode 2 ----------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// V2 has no `messages.transform`: `session.hook("context")` is its stable per-request
+// equivalent (the outgoing system + messages, mutable), so the invisible delivery needs
+// no fallback detection there. Messages are `LLM.Message` class instances, not V1's
+// `{info, parts}`. A V2 hook that throws is a defect that fails the whole request,
+// so every callback below swallows its own errors.
+
+// Build a user message the request will accept: reuse the class of a message already in
+// it (LLM.Message validates on construction), else a plain object of the same shape.
+function v2UserMessage(messages, text) {
+  const content = [{ type: "text", text }]
+  const Ctor = messages.find((m) => m && m.constructor && m.constructor !== Object)?.constructor
+  if (Ctor) { try { return new Ctor({ role: "user", content }) } catch {} }
+  return { role: "user", content }
+}
+const v2HasMarker = (messages) => messages.some((m) =>
+  (m?.content ?? []).some((p) => typeof p?.text === "string" && p.text.includes(MARKER)))
+const v2Model = (ref) => (ref?.providerID && ref?.id ? `${ref.providerID}/${ref.id}` : null)
+
+async function setupV2(ctx) {
+  const root = repoRoot({ worktree: ctx?.location?.project?.directory, directory: ctx?.location?.directory })
+  const blockCache = { text: null, at: 0 }
+  // Same scope rule as V1's skipSession: child/subagent sessions inherit the parent's
+  // context, geneseed-* sessions stay clean. A failed lookup is not cached.
+  const sessionSkip = new Map()
+  async function skipSession(sid) {
+    if (!sid) return false
+    const hit = sessionSkip.get(sid)
+    if (hit !== undefined) return hit
+    try {
+      const info = await ctx.session.get({ sessionID: sid })
+      const skip = Boolean(info?.parentID) || String(info?.title ?? "").startsWith("geneseed-")
+      sessionSkip.set(sid, skip)
+      return skip
+    } catch {
+      return false
+    }
+  }
+
+  if (!VISIBLE) {
+    await ctx.session.hook("context", async (event) => {
+      if (INJECT_OFF) return
+      try {
+        if (await sovereignBypass(root)) return
+        if (!Array.isArray(event?.messages) || v2HasMarker(event.messages)) return
+        if (await skipSession(event.sessionID)) return
+        const cached = await cachedBlockText(root, blockCache)
+        if (!cached) return
+        event.messages.unshift(v2UserMessage(event.messages, withModel(cached, v2Model(event.model) || envModelStr())))
+        log("context hook: injected context invisibly")
+      } catch (err) {
+        log(`context hook error: ${err?.message ?? err}`)
+      }
+    })
+    return
+  }
+
+  // Visible delivery (GENESEED_CONTEXT_VISIBLE): one synthetic message when a session is
+  // created, re-pushed into the compaction request so it outlives the summary.
+  await ctx.session.hook("compaction", async (event) => {
+    if (INJECT_OFF) return
+    try {
+      if (await sovereignBypass(root)) return
+      if (!Array.isArray(event?.messages) || await skipSession(event.sessionID)) return
+      const { block } = await resolveBlock(root)
+      if (block) event.messages.unshift(v2UserMessage(event.messages, block.text))
+    } catch (err) {
+      log(`compaction error: ${err?.message ?? err}`)
+    }
+  })
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      if (ev?.type !== "session.created" || INJECT_OFF) continue
+      const d = ev.data ?? {}
+      try {
+        if (d.parentID || String(d.title ?? "").startsWith("geneseed-")) continue
+        if (await sovereignBypass(root)) continue
+        const { block } = await resolveBlock(root)
+        if (!block) continue
+        await ctx.session.synthetic({
+          sessionID: d.sessionID, text: withModel(block.text, v2Model(d.model) || envModelStr()),
+          description: "Geneseed project context", resume: false,
+        })
+      } catch (err) {
+        log(`visible injection error: ${err?.message ?? err}`)
+      }
+    }
+  })().catch((err) => log(`event stream ended: ${err?.message ?? err}`))
+  return () => controller.abort()
+}
+
+export default { id: "geneseed-context", server: GeneseedContext, setup: setupV2 }