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.
- package/CHANGELOG.md +27 -0
- package/README.md +2 -2
- package/SHIPPED.md +1 -1
- package/adapters/bob/README.md +31 -18
- package/adapters/claude-code/README.md +27 -22
- package/adapters/openclaude/README.md +18 -8
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
- package/adapters/opencode/plugins/geneseed-activity.js +20 -21
- package/adapters/opencode/plugins/geneseed-context.js +169 -62
- package/adapters/opencode/plugins/geneseed-guard.js +414 -202
- package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
- package/adapters/opencode/workflows/_runtime.js +3 -2
- package/bin/geneseed-hook.mjs +57 -9
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +2 -2
- package/docs/concepts/footprint.md +10 -0
- package/docs/concepts/hook-gates.md +3 -3
- package/docs/concepts/host-matrix.md +22 -4
- package/docs/design-history.md +8 -0
- package/docs/extending.md +49 -7
- package/docs/guides/install-bob.md +2 -2
- package/docs/guides/install-openclaude.md +1 -1
- package/docs/guides/verify.md +12 -0
- package/docs/reference/environment.md +1 -0
- package/docs/reference/troubleshoot-doctor.md +1 -1
- package/docs/token-footprint.md +66 -2
- package/docs/understand/design-choices-hosts.md +1 -1
- package/docs/understand/design-choices-shape.md +1 -0
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/understand/machine-bob.md +1 -1
- package/docs/web-ui.md +5 -0
- package/harness.config.json +1 -1
- package/js/README.md +3 -2
- package/js/build/args.mjs +1 -1
- package/js/build/driver.mjs +1 -1
- package/js/build/emit-claude.mjs +1 -1
- package/js/build/generate.mjs +5 -14
- package/js/hosts/done-checks.mjs +6 -0
- package/js/hosts/geneseed-dir.mjs +3 -2
- package/js/hosts/gitref.mjs +5 -3
- package/js/hosts/hook-tap.mjs +104 -0
- package/js/hosts/hooks-context.mjs +4 -2
- package/js/hosts/hooks-learn.mjs +47 -16
- package/js/hosts/hooks.mjs +19 -13
- package/js/hosts/hosts.mjs +80 -12
- package/js/hosts/installs.mjs +7 -0
- package/js/hosts/native.mjs +14 -5
- package/js/hosts/owned.mjs +7 -6
- package/js/hosts/ownership-gate.mjs +14 -1
- package/js/hosts/settings.mjs +245 -103
- package/js/hosts/shim.mjs +4 -4
- package/js/hosts/usage.mjs +9 -3
- package/js/inspect/checks-probe.mjs +66 -5
- package/js/inspect/checks-repo.mjs +196 -2
- package/js/inspect/cost.mjs +34 -2
- package/js/inspect/doctor.mjs +6 -1
- package/js/lib/machine-dir.mjs +1 -1
- package/js/lib/node-floor.mjs +46 -6
- package/js/maintain/uninstall.mjs +42 -16
- package/js/web/actions.mjs +1 -9
- package/package.json +1 -1
- package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
- package/web/dist/assets/{ActivityDetail-BSzevynX.js → ActivityDetail-7rt04SkS.js} +1 -1
- package/web/dist/assets/{Bonsai-Bfpb6W-1.js → Bonsai-BBl4XXqs.js} +1 -1
- package/web/dist/assets/{CopyButton-ByIntFtB.js → CopyButton-Beven8yn.js} +1 -1
- package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
- package/web/dist/assets/{Docs-DvlMJhpu.js → Docs-B5aHp86J.js} +3 -3
- package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
- package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
- package/web/dist/assets/{Installs-BlGmVrFK.js → Installs-B1OsrHXF.js} +3 -3
- package/web/dist/assets/JournalView-CV4omyww.js +1 -0
- package/web/dist/assets/{Kits-DRwpxC-J.js → Kits-CW1e7xNa.js} +1 -1
- package/web/dist/assets/{Laws-CZkiNOWQ.js → Laws-1Ckf1lbs.js} +2 -2
- package/web/dist/assets/{LibRows-DEHjIoD-.js → LibRows-Dag1s0ZX.js} +1 -1
- package/web/dist/assets/Library-B3FuFLel.js +3 -0
- package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
- package/web/dist/assets/Markdown-CxkA7940.js +71 -0
- package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
- package/web/dist/assets/{Personal-Bp9nV4GR.js → Personal-DKLgLa7Z.js} +2 -2
- package/web/dist/assets/Settings-BwErnh-R.js +1 -0
- package/web/dist/assets/{Tabs-CWeQTADL.js → Tabs-8zsyEPSK.js} +1 -1
- package/web/dist/assets/{index-CsAZq0BQ.css → index-CRWqKxfY.css} +1 -1
- package/web/dist/assets/index-Ce6qF2nG.js +6 -0
- package/web/dist/index.html +2 -2
- package/adapters/claude-code/settings.json +0 -52
- package/web/dist/assets/Activity-CqJiquEq.js +0 -1
- package/web/dist/assets/Dashboard-DBOEi9lQ.js +0 -2
- package/web/dist/assets/Factories-Bpvv7L2H.js +0 -1
- package/web/dist/assets/GreenhouseView-GpBsYn50.js +0 -1
- package/web/dist/assets/JournalView-iLuLrOxE.js +0 -1
- package/web/dist/assets/Library-B4K-1iNF.js +0 -3
- package/web/dist/assets/Loops-BWSzaW8E.js +0 -2
- package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
- package/web/dist/assets/OperatorHudView-BAXwCEvY.js +0 -1
- package/web/dist/assets/Settings-CWWuaIp-.js +0 -1
- 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)
|
|
128
|
-
|
|
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
|
|
201
|
-
|
|
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) {
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -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
|
|
73
|
-
// a gate's own decision
|
|
74
|
-
//
|
|
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).
|
|
282
|
-
//
|
|
283
|
-
//
|
|
284
|
-
// `
|
|
285
|
-
|
|
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 {
|
|
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 (
|
|
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)
|
|
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
|
-
|
|
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 |
|
|
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
|
|
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).
|
|
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
|
|
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).
|
package/docs/design-history.md
CHANGED
|
@@ -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,
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
package/docs/guides/verify.md
CHANGED
|
@@ -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.
|
package/docs/token-footprint.md
CHANGED
|
@@ -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
|
|
12
|
-
|
|
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.**
|
|
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
|
|
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`.
|
|
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`
|
package/harness.config.json
CHANGED
|
@@ -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.
|
|
5
|
+
"version": "5.3.1"
|
|
6
6
|
}
|