geneseed 3.20.0 → 4.1.0

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

@@ -301,6 +301,23 @@ async function writeMemories(output, memDir, existing) {
   return written
 }
 
+// The distil's reply into the store: a child session's one agent lesson, else memory
+// files plus their MEMORY.md lines. Shared by the V1 and V2 runs.
+async function storeDistil(output, { isChild, memDir, agentName, existing }) {
+  if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
+  if (isChild) {
+    const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
+    if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
+    const f = await appendAgentLesson(memDir, agentName, lesson)
+    console.error(`[geneseed-learn] agent lesson -> ${f}`)
+    return
+  }
+  const written = await writeMemories(output, memDir, existing)
+  if (written.length) {
+    console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
+  }
+}
+
 export const GeneseedLearn = async (ctx) => {
   const { client } = ctx ?? {}
   const ours = new Set()       // throwaway distil sessions — never mine our own output
@@ -376,18 +393,7 @@ export const GeneseedLearn = async (ctx) => {
         if (newId) await client.session.delete({ path: { id: newId } }).catch(() => {})
       }
 
-      if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
-      if (isChild) {
-        const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
-        if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
-        const f = await appendAgentLesson(memDir, agentName, lesson)
-        console.error(`[geneseed-learn] agent lesson -> ${f}`)
-        return
-      }
-      const written = await writeMemories(output, memDir, existing)
-      if (written.length) {
-        console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
-      }
+      await storeDistil(output, { isChild, memDir, agentName, existing })
     } catch (err) {
       // Never break the session over a memory write.
       console.error(`[geneseed-learn] skipped: ${err?.message ?? err}`)
@@ -426,6 +432,113 @@ export const GeneseedLearn = async (ctx) => {
 
 // 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(GeneseedLearn, { writeMemories, resolveAgentName, appendAgentLesson })
+Object.assign(GeneseedLearn, { writeMemories, resolveAgentName, appendAgentLesson, flattenV2 })
+
+// ---- 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.
+//
+// What differs on V2:
+//   - The debounce re-arms on `session.execution.succeeded`: V2 core never publishes
+//     `session.idle` (deprecated in its schema), and the execution pair is its turn
+//     boundary. Events are `{ type, data }`, not `{ type, properties }`.
+//   - The transcript is `session.context()` — the messages after the last compaction —
+//     typed `user` (text) / `assistant` (content parts, `model: { providerID, id }`).
+//   - The distil is one stateless `generate.text({ prompt, model })` call with the
+//     session's own model: no throwaway session to create, guard against and delete.
+function flattenV2(messages) {
+  const lines = []
+  let model = null
+  for (const m of messages || []) {
+    if (m?.type === "user") {
+      const text = String(m.text ?? "").trim()
+      if (text) lines.push(`user: ${text}`)
+    } else if (m?.type === "assistant") {
+      const text = (m.content || [])
+        .filter((p) => p?.type === "text" && typeof p.text === "string")
+        .map((p) => p.text).join("\n").trim()
+      if (text) lines.push(`assistant: ${text}`)
+      if (m.model?.providerID && m.model?.id) model = m.model
+    }
+  }
+  return { notes: lines.join("\n\n"), model }
+}
+
+async function setupV2(ctx) {
+  const root = ctx?.location?.project?.directory || ctx?.location?.directory || process.cwd()
+  const timers = new Map()
+  const inFlight = new Set()
+  let warnedNoDir = false
+
+  async function runDistill(sid) {
+    if (await sovereignBypass(root)) return
+    if (inFlight.has(sid)) return
+    inFlight.add(sid)
+    try {
+      const meta = await ctx.session.get({ sessionID: sid }).catch(() => null)
+      if (String(meta?.title ?? "").startsWith("geneseed-")) return
+      const isChild = !!meta?.parentID
+      const agentName = isChild ? resolveAgentName(meta) : null
+      if (isChild && !agentName) return
+
+      const memDir = await resolveMemoryDir()
+      if (!memDir) {
+        if (!warnedNoDir) {
+          warnedNoDir = true
+          console.error("[geneseed-learn] no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY.")
+        }
+        return
+      }
+
+      let { notes, model } = flattenV2(await ctx.session.context({ sessionID: sid }))
+      if (notes.length < MIN_NOTES_CHARS) return
+      notes = notes.slice(-MAX_NOTES_CHARS)
+      if (!model) {
+        const env = envModel()
+        model = env ? { providerID: env.providerID, id: env.modelID } : null
+      }
+      if (!model) {
+        console.error("[geneseed-learn] could not determine a model — set $GENESEED_MODEL=provider/model.")
+        return
+      }
+
+      const existing = await existingSlugs(memDir)
+      const prompt = isChild
+        ? [AGENT_LESSON_PROMPT, "", "NOTES:", notes].join("\n")
+        : buildPrompt(notes, existing)
+      const reply = await ctx.generate.text({
+        prompt, model: { providerID: model.providerID, id: model.id, ...(model.variant ? { variant: model.variant } : {}) },
+      })
+      await storeDistil(String(reply?.text ?? ""), { isChild, memDir, agentName, existing })
+    } catch (err) {
+      console.error(`[geneseed-learn] skipped: ${err?.message ?? err}`)
+    } finally {
+      inFlight.delete(sid)
+    }
+  }
+
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      const sid = ev?.data?.sessionID
+      if (!sid) continue
+      if (ev.type === "session.deleted") {
+        const t = timers.get(sid)
+        if (t) clearTimeout(t)
+        timers.delete(sid)
+        continue
+      }
+      if (ev.type !== "session.execution.succeeded") continue
+      const prev = timers.get(sid)
+      if (prev) clearTimeout(prev)
+      timers.set(sid, setTimeout(() => { timers.delete(sid); runDistill(sid) }, DEBOUNCE_MS))
+    }
+  })().catch((err) => console.error(`[geneseed-learn] event stream ended: ${err?.message ?? err}`))
+  return () => {
+    controller.abort()
+    for (const t of timers.values()) clearTimeout(t)
+    timers.clear()
+  }
+}
 
-export default GeneseedLearn
+export default { id: "geneseed-learn", server: GeneseedLearn, setup: setupV2 }

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

@@ -157,4 +157,49 @@ export const GeneseedNotify = async ({ client }) => {
 // off the factory instead — reachable via `import`, invisible to the loader.
 Object.assign(GeneseedNotify, { lastUserMs, shouldNotify, notifyCommand })
 
-export default GeneseedNotify
+// ---- 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 core never publishes `session.idle` (deprecated in its schema). The turn boundary is
+// the execution pair instead: `session.execution.started` stamps when the agent began,
+// `session.execution.succeeded`/`failed` ends it — so the turn length comes straight off
+// the events, no transcript read. An interrupted execution is the user's own doing (or a
+// shutdown) and is not announced. Events are `{ type, created, data }`, not V1's
+// `{ type, properties }`.
+async function setupV2(ctx) {
+  if (OFF) return
+  const started = new Map()
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      const sid = ev?.data?.sessionID
+      if (!sid) continue
+      if (ev.type === "session.execution.started") { started.set(sid, ev.created); continue }
+      if (ev.type === "session.execution.interrupted" || ev.type === "session.deleted") { started.delete(sid); continue }
+      if (ev.type !== "session.execution.succeeded" && ev.type !== "session.execution.failed") continue
+      const begin = started.get(sid) ?? null
+      started.delete(sid)
+      try {
+        let title = "", parentID
+        try {
+          const info = await ctx.session.get({ sessionID: sid })
+          title = info?.title ?? ""
+          parentID = info?.parentID
+        } catch {}
+        const now = typeof ev.created === "number" ? ev.created : Date.now()
+        if (!shouldNotify({ now, lastUserMs: begin, parentID, title, minMs: MIN_MS })) {
+          log(`skipped ${sid} (child/throwaway or turn under ${MIN_MS}ms)`)
+          continue
+        }
+        deliver(TITLE, title ? `Done: ${title}` : "Agent finished — your turn.")
+        log(`notified for ${sid}`)
+      } catch (err) {
+        log(`skipped: ${err?.message ?? err}`)
+      }
+    }
+  })().catch((err) => log(`event stream ended: ${err?.message ?? err}`))
+  return () => controller.abort()
+}
+
+export default { id: "geneseed-notify", server: GeneseedNotify, setup: setupV2 }

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

@@ -143,6 +143,48 @@ export const GeneseedPonytail = async () => ({
 // any that isn't a function — a bare helper export crashes startup ("null is not an
 // object") or logs "not a function". Hang the test helpers off the factory instead;
 // they ride along for `import`, invisible to the loader. Upgrade path: none needed.
-Object.assign(GeneseedPonytail, { normalizeMode, defaultMode, ponytailInstructions })
+Object.assign(GeneseedPonytail, { normalizeMode, defaultMode, ponytailInstructions, levelFromPrompt })
 
-export default GeneseedPonytail
+// --- 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 neither hook. `session.hook("context")` carries the outgoing system parts (the
+// ruleset is pushed there), and there is no `command.execute.before`: a markdown command
+// expands its template into the prompt, so the switch is read off the prompt instead —
+// the first line of PONYTAIL_COMMAND_BODY (js/hosts/opencode.mjs), `Ponytail level
+// requested: <args>`. Change that line and this pattern together.
+const PONYTAIL_PROMPT_RE = /^Ponytail level requested:[ \t]*(.*)$/m
+
+// The level a `/ponytail` prompt asks for: undefined when the text is not one, null
+// when its argument is no known level, else the level (empty argument = `full`).
+function levelFromPrompt(text) {
+  const m = PONYTAIL_PROMPT_RE.exec(String(text ?? ""))
+  if (!m || m.index !== 0) return undefined
+  const arg = m[1].trim()
+  return normalizeMode(arg) || (arg ? null : "full")
+}
+
+async function setupV2(ctx) {
+  await ctx.session.hook("prompt", (event) => {
+    try {
+      const mode = levelFromPrompt(event?.prompt?.text)
+      if (mode === undefined) return
+      if (!mode) { log("ignored unknown level"); return }
+      writeMode(mode)
+      log(`ponytail ${mode}`)
+    } catch (err) {
+      log(`prompt hook error: ${err?.message ?? err}`)
+    }
+  })
+  await ctx.session.hook("context", (event) => {
+    try {
+      const text = ponytailInstructions(readMode())
+      if (text && Array.isArray(event?.system)) event.system.push({ type: "text", text })
+    } catch (err) {
+      log(`context hook error: ${err?.message ?? err}`)
+    }
+  })
+}
+
+export default { id: "geneseed-ponytail", server: GeneseedPonytail, setup: setupV2 }

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

@@ -116,23 +116,10 @@ async function writeTrace(rootDir, runId, lines) {
   } catch (e) { dlog(`trace write failed: ${e?.message || e}`); return "(trace write failed)" }
 }
 
-export const GeneseedWorkflow = async (ctx) => {
-  const { client, directory, worktree } = ctx
+// The `workflow` tool's body, shared by the V1 and V2 registrations: `client` is the V1
+// SDK client, or on V2 the facade `v2Client` builds over the plugin context.
+function makeExecute({ client, directory, worktree }) {
   const rootDir = worktree || directory
-  let toolHelper
-  try { ({ tool: toolHelper } = await import("@opencode-ai/plugin")) }
-  catch { dlog("@opencode-ai/plugin tool helper unavailable — registering a raw tool def") }
-
-  // One-line load banner (always on) so a restart visibly confirms the plugin loaded
-  // and the `workflow` tool is registered — and WARNS if this OpenCode build lacks the
-  // custom-tool helper (the silent "tool never appears" failure).
-  try {
-    const names = await listWorkflows()
-    const warn = toolHelper ? ""
-      : " — WARN: @opencode-ai/plugin 'tool' helper missing; the workflow tool may NOT register on this OpenCode version"
-    console.error(`[geneseed-workflow] loaded — tool 'workflow' registered, ${names.length} workflow(s) [${names.join(", ") || "none"}] from ${WORKFLOWS_DIR}${warn}`)
-  } catch (e) { console.error(`[geneseed-workflow] loaded but could not list workflows: ${e?.message || e}`) }
-
   // Normalize the `args` parameter. OpenCode's tool layer can deliver a structured
   // object param as a JSON STRING (or drop it) when the schema is untyped — so coerce
   // a string back to an object and reject non-object shapes to `{}`. Without this, the
@@ -185,22 +172,52 @@ export const GeneseedWorkflow = async (ctx) => {
     return summarize(name, result, stats, tracePath)
   }
 
+  return execute
+}
+
+// The `workflow` tool as the model sees it, on both majors.
+const TOOL_DESCRIPTION =
+  "Run a saved, code-driven Geneseed workflow that orchestrates subagents " +
+  "deterministically (parallel fan-out, find→verify pipeline, phased handoff). " +
+  "Call with no name to list available workflows."
+const NAME_DESCRIPTION = "saved workflow name; omit to list available"
+const ARGS_DESCRIPTION = "inputs passed to the workflow script as `args` (object, or a JSON object string)"
+
+// One-line load banner (always on) so a restart visibly confirms the plugin loaded and the
+// `workflow` tool is registered. tests/host_canary.mjs reads it as V1's proof of load.
+async function loadBanner(warn = "") {
+  try {
+    const names = await listWorkflows()
+    console.error(`[geneseed-workflow] loaded — tool 'workflow' registered, ${names.length} workflow(s) [${names.join(", ") || "none"}] from ${WORKFLOWS_DIR}${warn}`)
+  } catch (e) { console.error(`[geneseed-workflow] loaded but could not list workflows: ${e?.message || e}`) }
+}
+
+export const GeneseedWorkflow = async (ctx) => {
+  const { client, directory, worktree } = ctx
+  let toolHelper
+  try { ({ tool: toolHelper } = await import("@opencode-ai/plugin")) }
+  catch { dlog("@opencode-ai/plugin tool helper unavailable — registering a raw tool def") }
+
+  // Warn when this OpenCode build lacks the custom-tool helper (the silent "tool never
+  // appears" failure).
+  await loadBanner(toolHelper ? ""
+    : " — WARN: @opencode-ai/plugin 'tool' helper missing; the workflow tool may NOT register on this OpenCode version")
+
+  const execute = makeExecute({ client, directory, worktree })
+
   const def = {
-    description:
-      "Run a saved, code-driven Geneseed workflow that orchestrates subagents " +
-      "deterministically (parallel fan-out, find→verify pipeline, phased handoff). " +
-      "Call with no name to list available workflows.",
+    description: TOOL_DESCRIPTION,
     args: toolHelper
       ? {
-          name: toolHelper.schema.string().optional().describe("saved workflow name; omit to list available"),
+          name: toolHelper.schema.string().optional().describe(NAME_DESCRIPTION),
           // Keep this `any()` — it's the only param shape known to register cleanly on
           // this OpenCode build (record()/object schemas wedged tool registration → every
           // session message stuck "queued"). The provider may still deliver the object as
           // a JSON string or empty; normalizeArgs() in execute() recovers both cases.
-          args: toolHelper.schema.any().optional().describe("inputs passed to the workflow script as `args` (object, or a JSON object string)"),
+          args: toolHelper.schema.any().optional().describe(ARGS_DESCRIPTION),
         }
       : {
-          name: { type: "string", description: "saved workflow name; omit to list available" },
+          name: { type: "string", description: NAME_DESCRIPTION },
           args: { type: "object", description: "inputs passed to the workflow script as `args`" },
         },
     async execute(argv) { return execute(argv) },
@@ -209,4 +226,87 @@ export const GeneseedWorkflow = async (ctx) => {
   return { tool: { workflow: toolHelper ? toolHelper(def) : def } }
 }
 
-export default GeneseedWorkflow
+// ---- 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 registers tools through `tool.transform` with a plain JSON-schema `input` (no
+// `@opencode-ai/plugin` helper — that package is `@opencode/plugin` there, and not
+// needed). The runtime (`_runtime.js`) and every saved workflow speak the V1 SDK client,
+// so `v2Client` presents that client's few calls over the V2 session domain instead of
+// forking the runtime:
+//   create  → session.create (a worktree directory becomes the session's location)
+//   prompt  → switchAgent/switchModel when asked, then session.prompt — which only
+//             admits the input on V2 — then session.wait for the loop to go idle, and the
+//             last assistant message read back from session.context
+//   messages → session.context, reshaped to V1's `{ info, parts }`
+//   delete  → session.remove
+function v2Message(m) {
+  if (m?.type === "assistant") {
+    return {
+      info: { role: "assistant", tokens: m.tokens },
+      parts: (m.content || []).filter((p) => p?.type === "text").map((p) => ({ type: "text", text: p.text })),
+    }
+  }
+  return { info: { role: m?.type }, parts: typeof m?.text === "string" ? [{ type: "text", text: m.text }] : [] }
+}
+function v2ModelRef(model) {
+  if (typeof model === "string" && model.includes("/")) {
+    const [providerID, ...rest] = model.split("/")
+    return { providerID, id: rest.join("/") }
+  }
+  const id = model?.id ?? model?.modelID
+  return model?.providerID && id ? { providerID: model.providerID, id } : null
+}
+function v2Client(ctx) {
+  const context = async (sid) => (await ctx.session.context({ sessionID: sid })) || []
+  return {
+    session: {
+      create: async ({ body, query } = {}) => ctx.session.create({
+        ...(body?.title ? { title: body.title } : {}),
+        ...(query?.directory ? { location: { directory: query.directory } } : {}),
+      }),
+      prompt: async ({ path: p, body } = {}) => {
+        const sessionID = p?.id
+        if (body?.agent) await ctx.session.switchAgent({ sessionID, agent: body.agent })
+        const model = v2ModelRef(body?.model)
+        if (model) await ctx.session.switchModel({ sessionID, model })
+        const text = (body?.parts || []).filter((x) => x?.type === "text").map((x) => x.text).join("\n")
+        await ctx.session.prompt({ sessionID, text })
+        await ctx.session.wait({ sessionID })
+        const last = (await context(sessionID)).filter((m) => m?.type === "assistant").pop()
+        return last ? v2Message(last) : null
+      },
+      messages: async ({ path: p } = {}) => (await context(p?.id)).map(v2Message),
+      delete: async ({ path: p } = {}) => ctx.session.remove({ sessionID: p?.id }),
+    },
+  }
+}
+
+async function setupV2(ctx) {
+  const directory = ctx?.location?.directory
+  const worktree = ctx?.location?.project?.directory
+  const execute = makeExecute({ client: v2Client(ctx), directory, worktree })
+  await loadBanner()
+  await ctx.tool.transform((editor) => {
+    editor.add({
+      name: "workflow",
+      description: TOOL_DESCRIPTION,
+      input: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: NAME_DESCRIPTION },
+          args: { description: ARGS_DESCRIPTION },
+        },
+      },
+      // A rejected promise here is a defect that fails the whole agent step, not the call:
+      // every failure comes back as text, as the V1 tool's do.
+      execute: async (input) => {
+        try { return { content: await execute(input) } }
+        catch (e) { return { content: `Workflow failed: ${e?.message || e}` } }
+      },
+    })
+  })
+}
+
+export default { id: "geneseed-workflow", server: GeneseedWorkflow, setup: setupV2 }

package/bin/geneseed-hook.mjs

@@ -38,7 +38,12 @@
  * subparsers (25 invocable names — `update` is an alias of `upgrade`); a hook entry that
  * silently accepted `doctor` and did nothing would be the worst available failure, because
  * every Geneseed hook returns 0 and signals through stdout — so "did nothing" and "worked"
- * are the same observation.
+ * are the same observation. That refusal exits **1**, never 2: on Claude Code and Bob, exit 2
+ * is the one code that blocks a tool call (or, on `Stop`/`SubagentStop`, keeps the turn going
+ * without running the hook again), so a verb this build does not know yet — the forward case,
+ * when a newer Geneseed names a verb this stale checkout has never heard of, under the
+ * machine-wide last-writer-wins shim (see I3/B1 below) — must not read as a block. Exit 1 still
+ * shows a `<hook name> hook error` notice; it just does not stop anything (see I3/B1).
  */
 // FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
 import '../js/lib/node-floor.mjs';
@@ -55,6 +60,13 @@ import { printErr } from '../js/lib/fs.mjs';
 // specifiers stay literal strings — `tests/unit/hook_cli.test.mjs`'s import walk reads them.
 const HOSTED = { '--root': 'root', '--host': 'host' };
 const gates = () => import('../js/hosts/hooks.mjs');
+// Verbs PreToolUse/PostToolUse actually gate a tool call with. The machine-wide, last-writer-wins
+// shim (this file's header) means a stale checkout can be handed a flag only a newer install
+// knows (e.g. `--no-consent`); on Claude Code, exit 2 from one of THESE verbs blocks the tool
+// outright, with no ask. `main` below answers an argv error on a gate verb with exit 0 instead —
+// a gate's own decision still exits 0 and signals through stdout (`askDecision`), so this only
+// changes what used to be a hard lockout into "the gate is silent this one call" (see I3/B1).
+const GATE_VERBS = new Set(['git-gate', 'rule-gate', 'tool-gate']);
 const VERBS = {
   context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
   'git-gate': {
@@ -65,7 +77,8 @@ const VERBS = {
   learn: {
     load: () => import('../js/hosts/hooks-learn.mjs'),
     fn: 'cmdLearn',
-    flags: { '--memory': 'memory' },
+    // `--host` only keys the global stand-down's marker (js/hosts/hosts.mjs); learn has no dialect.
+    flags: { '--memory': 'memory', '--host': 'host' },
     switches: { '--consolidate': 'consolidate' },
     positional: 'file',
   },
@@ -118,7 +131,9 @@ async function main(argv) {
 
   const verb = argv[0];
   if (!verb || verb === '-h' || verb === '--help') {
-    return die(2, `the following arguments are required: cmd (one of ${
+    // 1, not 2: see this file's header (I3/B1) — 2 is the one code that blocks a tool call on
+    // Claude Code and Bob, and a bare invocation is not a gate decision.
+    return die(1, `the following arguments are required: cmd (one of ${
       Object.keys(VERBS).join(', ')})`);
   }
   const spec = VERBS[verb];
@@ -130,7 +145,11 @@ async function main(argv) {
     // The COMMAND is not a table: `geneseed` is this package's `bin` entry for the CLI
     // (package.json), it answers every non-hook verb, and it survives the deletion of the
     // interpreter-plus-script invocation this line used to print.
-    return die(2, `invalid choice: '${verb}'. This entry point carries only the HOOK `
+    //
+    // 1, not 2 (I3/B1): the forward case is the one that matters — settings emitted by a NEWER
+    // Geneseed name a verb this stale checkout, running from the machine-wide last-writer-wins
+    // shim, has never heard of. That must not read as a block.
+    return die(1, `invalid choice: '${verb}'. This entry point carries only the HOOK `
       + `verbs (${Object.keys(VERBS).join(', ')}); every other harness subcommand lives `
       + 'elsewhere — run `geneseed ' + verb + '`.');
   }
@@ -146,7 +165,19 @@ async function main(argv) {
     if (rc !== null) return rc;
   }
   const parsed = parse(spec, argv.slice(1));
-  if (parsed.error) return die(2, parsed.error);
+  if (parsed.error) {
+    // A gate verb must never exit 2 on an argv error: that is indistinguishable, to Claude's
+    // PreToolUse, from the gate deliberately blocking (see I3/B1 above). Print the same message
+    // to stderr for a human debugging the shim, but return 0 with no stdout, exactly like a gate
+    // that chose not to act.
+    if (GATE_VERBS.has(verb)) { printErr(`geneseed-hook: error: ${parsed.error}\n`); return 0; }
+    // `context` and `learn` are not gate verbs, but their own argv errors are not a decision
+    // either, so still 1, not 2 (I3/B1): a `<hook name> hook error` notice, and nothing more.
+    // `learn` is the one that matters here — it runs on Stop/SubagentStop, where exit 2 ALSO has
+    // an effect (it sends Claude back to keep working instead of letting the turn end; docs
+    // `hooks.md`, "Stop, SubagentStop, TaskCompleted, and TeammateIdle").
+    return die(1, parsed.error);
+  }
   return (await spec.load())[spec.fn](parsed.args);
 }
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 [← Back to README](../README.md)
 
-**New to agent harnesses?** Read **Understand** first — a short track, about ten minutes, that every other page assumes. The same pages open the **Docs** tab of the web console (`geneseed web`), which groups each part into sections, adds an interactive map of your own install, and filters host-specific passages to the tool you use.
+**New to agent harnesses?** Read **Understand** first: the track every other page assumes. Its last section, *Why it works this way*, is reference, to consult when a question comes up. The same pages open the **Docs** tab of the web console (`geneseed web`), which groups each part into sections, adds an interactive map of your own install, and filters host-specific passages to the tool you use.
 
 ## 1 · Understand
 
@@ -12,6 +12,8 @@
 
 **Day to day** — [A day with the harness](understand/a-day.md): the moments you will actually meet · [Enforced vs. asked](understand/enforced-vs-asked.md): what is guaranteed by code, and what the model is only asked to do.
 
+**Why it works this way** — [Why Geneseed works this way](understand/design-choices.md): every decision already taken, one line each, and where it is argued · [The shape of the harness](understand/design-choices-shape.md) · [Gates](understand/design-choices-gates.md) · [Hosts](understand/design-choices-hosts.md) · [Install, uninstall, update](understand/design-choices-install.md) · [Engineering, skills and agents](understand/design-choices-engineering.md) · [Considered and refused](design-history.md#considered-and-refused).
+
 ## 2 · Guides
 
 | Section | Guide | When |

package/docs/candidate-hosts.md

@@ -66,14 +66,6 @@ skill catalogue for the price of one directory name, with no host-specific code
 A Gemini host would be the third verdict spelling in `js/hosts/hooks.mjs` (after Claude's
 ask and Bob's exit code 2), plus a resolver and a carrier.
 
-## Evaluated, dropped
-
-- **GitHub Copilot** — shipped as a host through 3.9.0, removed in 3.10.0. Dropped for lack
-  of support: its hooks were never verified live, its `postToolUse` output does not reach
-  the model, and it shared no cross-tool surface with the other hosts (camelCase payloads,
-  matcherless hook entries, its own agent dialect and carrier), so every feature needed a
-  Copilot-only decision.
-
 ## Not verified
 
 None of the three CLIs is installed on the reviewing machine. Every row above is from the

package/docs/concepts/enforcement-table.md

@@ -0,0 +1,66 @@
+---
+group: concepts
+order: 24
+title: "Rule enforcement, by host"
+kind: "concept"
+section: "Harness"
+description: "Every law and doctrine rule, and what each host actually does about it."
+---
+[Enforced vs. asked](../understand/enforced-vs-asked.md) names the two tiers. This page is the
+full cross-reference: every rule id, its pack, and what each host does at the tool boundary. A
+few rules are enforced; the rest are asked on every host, through the root rules file
+(`CLAUDE.md`, `AGENT.md`, `AGENTS.md`).
+
+Derived from the code, not from this project's own planning notes: `js/hosts/hooks.mjs`'s
+`BLOCK_RULES` and gate functions, `HOOK_PINNED` in `js/inspect/checks-constitution.mjs`,
+`LAW_IV_BASH` and `CONSENT_RULE` in `js/hosts/settings.mjs`, and
+`adapters/opencode/plugins/geneseed-guard.js`. `HOOK_PINNED` is what keeps this table from
+silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-stable-rule-ids.md).
+
+### The enforced rules
+
+| id | Pack | Claude Code | OpenClaude | OpenCode | Bob |
+|---|---|---|---|---|---|
+| `sealed-secrets` | law | ask: rule-gate (credential-shaped content outside `.env*`) | same as Claude Code | block: guard plugin (key/credential file path, or vendor-prefixed secret content); warns only on `.env*` | block (exit 2) |
+| `deletion-is-deliberate` | law | ask: git-gate (the destructive-git set in [Hooks](hooks.md): force-push and every history-discarding git act it lists) | same as Claude Code | ask: permission prompt (the same destructive-git set) **+** block: guard plugin (catastrophic shell: `rm -rf /`, fork bomb, `format`, `dd` over a raw disk) **+** warn only: guard plugin (the destructive-git set, as a backstop to the permission prompt) | block (exit 2) |
+| `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or the memory store) | same as Claude Code | ask once: guard plugin (refuses the *first* write to that path; a re-issued write goes through) | log only (warning, call goes through) |
+| `consent-before-push` | process | ask: git-gate (every `git commit`/`git push`). 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 | log only |
+| `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list) | same as Claude Code | block: guard plugin (same list) | block (exit 2) |
+| `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:\`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
+
+Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
+rule the other hosts only ask about either blocks outright on Bob or degrades to a log line.
+Never a silent pass; Bob runs every gate above through one fused command, `tool-gate`, dispatched
+on the payload shape rather than on separate matchers. OpenCode enforces through two separate
+mechanisms: its own permission prompt (`opencode.json`, static globs) and the guard plugin
+(`tool.execute.before`, pattern matching); a rule can use either or both.
+See [ADR 0008](../adr/0008-host-parity-ceiling-of-the-weakest-host.md) for why a gate that only
+one host can run still ships for every host it can.
+
+### Everything else: asked only, on every host
+
+Every other rule carries no gate on any host. A human reads them because the model was told to
+follow them, not because a tool call was ever inspected.
+
+**Laws** — `one-intent-one-act` · `verify-before-asserting` · `surface-failures` ·
+`data-not-orders` · `least-privilege` · `cure-the-cause` · `echo-the-intent`.
+
+**Doctrine: process** — `plan-before-acting` · `context-economy` · `read-the-docs-first` ·
+`bound-the-loop` · `one-writer-per-file`.
+
+**Doctrine: craft** — `automate-repetition` · `english-configuration` · `documentation-in-step` ·
+`search-before-creating` · `respect-conventions` · `smallest-viable-diff` · `one-writer-per-value`.
+
+**Doctrine: ops** — `tool-discovery` · `edit-the-source-not-the-surface` · `complete-the-teardown` ·
+`record-the-probe-not-the-snapshot` · `restart-is-not-reload` ·
+`serialize-against-a-rationed-resource`.
+
+**Doctrine: rigor** — `idempotent-by-default` · `honest-tests` · `cover-and-verify` ·
+`prove-the-gate`.
+
+**Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls`.
+
+---
+
+**Where next:** [Enforced vs. asked](../understand/enforced-vs-asked.md) · [Rules](rules.md) ·
+[Hook gates, settings and the shim](hook-gates.md)

package/docs/concepts/hook-gates.md

@@ -16,7 +16,7 @@ If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, w
 geneseed status
 ```
 
-In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
+In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context`, `git-gate` and `learn` hooks stand down when the session's project folder (the one the session started in, not a parent of it) has its own live per-repo install of the same host that wires the same hook, so nothing is injected, asked or learned twice. A per-repo install that is deactivated, or whose hooks were never wired, does not count: the global hook keeps running. `GENESEED_STACK_GLOBAL=1` keeps both.
 
 ## Where they are written
 
@@ -37,7 +37,7 @@ The merge is surgical. Every other key and every hook of your own survive, and t
 **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, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
 
 - `SessionStart` → `geneseed-hook context`.
-- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
+- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the checks that admit no judgement call: secrets, destructive git, a recursive scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
 - `Stop` → `geneseed-hook learn`.
 
 Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.