geneseed 3.20.0 → 4.0.0

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

@@ -4,6 +4,7 @@
 // "enforce by injection, don't just instruct" stance as the context plugin:
 //   - Sealed Secrets:  block writes to private-key / credential files.
 //   - Deletion Is Deliberate:  block catastrophic shell commands.
+//   - Commands Must Return:  block a recursive scan rooted at a whole filesystem (find /).
 //   - Persist Insight (rule vs memory):  speed-bump the first write to user-rules.md
 //     memory file — that choice belongs to the user, via the rule skill.
 //   - Wiki (AGENT.md §8):  block mutations under a declared wiki's `protected`
@@ -17,21 +18,30 @@
 // Install: dropped into the plugins dir by `build --emit opencode[-global]` (the *.js
 // glob), exactly like the context and learn plugins. Errors never break a tool call.
 //
-// `permission.ask` — the loop/* exemption (Consent Before Push). OpenCode's static
-// `permission.bash` globs (`git commit*`/`git push*` = "ask", written by
-// js/hosts/settings.mjs) cannot see which branch is checked out — they are a build-time
-// string match with no request-time context. This hook is the ONLY seam where Geneseed can
-// look at the live branch, and it only DOWNGRADES an ask to allow: only a fixed set of
-// commit/push forms (see `loopExempt` below, the twin of js/hosts/hooks.mjs's) on a `loop/*`
-// branch a loop was actually LAUNCHED on — not just named `loop/...`. It is a WHITELIST, not
-// a blacklist: a false ask costs one prompt, a false allow publishes. It never raises the
-// bar: anything not on the whitelist, anything off a launched loop branch, a status this hook
-// did not itself leave as the default "ask", or any non-bash permission leaves `output.status`
-// untouched and OpenCode's own ask (or another hook's deny) stands. A host version that never
-// fires `permission.ask` simply never reaches this hook — the static ask still fires, so the
-// failure mode is one extra prompt, never a silent allow.
+// No `permission.ask` hook (OpenCode verdict I-2). Upstream declares one in its plugin
+// types but never triggers it: `Permission.ask` evaluates the rules and publishes the
+// `permission.asked` bus event with no plugin hook in between. The loop/* exemption this
+// plugin once hung there (downgrade the static `git commit*`/`git push*` ask to allow on a
+// launched loop branch, the twin of js/hosts/hooks.mjs's `loopExempt`) therefore never ran,
+// and is gone. Lost behaviour, stated plainly: an OpenCode loop's COMMIT gets the static ask
+// every time — that fails safe, one prompt, never a silent allow. The `permission.asked`
+// event + SDK reply route was not taken: it races the TUI's own prompt and is unverified from
+// inside a plugin.
+//
+// The PUSH half is recovered differently (user decision, 2026-10-10): pushing a `loop/*`
+// branch is not pushing `main`/`master`, so it is allowed STATICALLY rather than dynamically —
+// js/hosts/settings.mjs's `LOOP_PUSH_ALLOW` wires an unconditional `permission.bash` allow for
+// the loop engine's own refspec shapes (`git push [-u] <remote> HEAD:loop/*` and its
+// `refs/heads/` spelling), ordered so a force push, a `+refspec`, or a `--delete`/bare-`:`
+// push to `loop/*` still asks (`LAW_IV_BASH` comes after it, and `findLast` wins on the last
+// match). This plugin has no part in that — it is a `permission.bash` key, read before any
+// `tool.execute.before` hook runs — so there is nothing to change here for the push half; this
+// comment only keeps this file's account in step. The commit still has no static equivalent:
+// a commit's content cannot be named by a glob the way a push's target branch can, so the
+// upgrade path there is still a session-level `permission` ruleset set by the loop launcher
+// when it creates the loop session (`session.create` accepts one).
 
-import { promises as fs, realpathSync, existsSync, statSync, lstatSync, readFileSync, openSync, readSync, closeSync } from "node:fs"
+import { promises as fs, realpathSync, existsSync, readFileSync } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath } from "node:url"
 import { homedir } from "node:os"
@@ -123,9 +133,25 @@ const SECRET_RE = [
   /(^|\/)\.npmrc$/i,
   /(^|\/)\.pypirc$/i,
 ]
-// .env files are often edited legitimately → WARN, don't hard-block.
+// .env files are often edited legitimately → WARN, don't hard-block. Considered aligning this
+// with js/hosts/hooks.mjs's DOTENV_RE (`/(^|[\\/])\.env(\.[^\\/]*)?$/`) the way SECRET_CONTENT_RE
+// is aligned with SECRET_RE below — but the two diverge beyond case/slash-style: DOTENV_RE's
+// suffix is `*` (zero-or-more, any non-slash char — matches `.env.` and `.env!`), this one's is
+// `+` over `[\w.-]` (one-or-more, word/dot/hyphen only). Widening to DOTENV_RE's shape would
+// change which filenames warn instead of block on THIS host, not just fold case, so it is left
+// as-is rather than silently changing guard behaviour for a parity task.
 const SECRET_WARN_RE = [/(^|\/)\.env(\.[\w.-]+)?$/i]
 
+// Twin of js/hosts/hooks.mjs's SECRET_RE (Law I's boundary half) — scans WRITE CONTENT for a
+// credential-shaped string, not the target path (SECRET_RE above is the path twin, file names
+// only). High-precision vendor prefixes only, same rationale as the Node side: a generic
+// "looks like entropy" scan fires on every hash and lockfile. Kept byte-identical by the parity
+// test in tests/plugins/guard.test.mjs — simple enough to literally diff, unlike SHELL_WARN_RE's
+// hand-mirrored git acts. `.env*` is exempt (SECRET_WARN_RE above already names it as where a
+// secret may legitimately live) via the same path check used for the WARN tier.
+const SECRET_CONTENT_RE =
+  /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9_-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/
+
 // Catastrophic, effectively irreversible shell → BLOCK. Both Unix and Windows shells,
 // since OpenCode runs natively on Windows and the agent may emit cmd / PowerShell.
 const SHELL_BLOCK_RE = [
@@ -142,16 +168,217 @@ const SHELL_BLOCK_RE = [
   /\bremove-item\b[^\n]*-recurse\b[^\n]*-force\b/i,                  // PowerShell rm -rf
   /\bremove-item\b[^\n]*-force\b[^\n]*-recurse\b/i,                  // (either flag order)
 ]
-// History-rewriting / irreversible git ops → WARN.
-const SHELL_WARN_RE = [/\bgit\s+push\b[^\n]*(--force\b|-f\b)/, /\bgit\s+reset\s+--hard\b/]
+// History-rewriting / irreversible git ops (Deletion Is Deliberate) → WARN, never BLOCK:
+// `tool.execute.before` has no ask tier, so these are a speed bump rather than a wall. The
+// same acts js/hosts/hooks.mjs's `DESTRUCTIVE_GIT_RE` asks about — mirrored by hand rather
+// than shared, since this plugin is copied whole into an OpenCode install, outside this
+// repo's module graph. `clean`
+// and `--delete` need `--force` alongside them to count, EITHER order (`--force --delete` is
+// the same act as `--delete --force`) — an un-forced `clean`/`branch --delete` already refuses
+// or only removes what is reproducible. `-D --force`/`--delete -f`/`-d --force`/`-df` are the
+// same act again and are a known ceiling this does not chase. `git switch -h` lists `-f,
+// --force` and `--discard-changes` as two SEPARATE options, not one flag's long/short spelling,
+// so both are listed. `restore` and `stash drop`/`clear` are anchored to the VERB position
+// (`\bgit\s+restore\b`, not `\bgit\s+.*restore\b`) — every other row needs a flag that is
+// vanishingly unlikely in a commit message or filename, but `restore` needs none and
+// `drop`/`clear` are ordinary English, so a message like "restore working behavior" or "clear
+// old state" must never warn. `restore` matches UNLESS `--staged` appears on the line, EXCEPT
+// `--staged --worktree` together, which restores the working tree too and so discards exactly
+// like plain `restore` (see the twin rationale and tests in js/hosts/hooks.mjs).
+const SHELL_WARN_RE = [
+  /\bgit\s+push\b[^\n]*(--force\b|-f\b|\+\S|\s--delete\b|\s:\S)/,   // forced, mirror, or delete push
+  /\bgit\s+reset\s+--hard\b/,
+  /\bgit\s+clean\b[^\n]*\s(-[a-zA-Z]*f|--force\b)/,
+  /\bgit\s+branch\b[^\n]*\s(-D\b|--delete\b[^\n]*--force\b|--force\b[^\n]*--delete\b)/,
+  /\bgit\s+checkout\s+--\s/,
+  /\bgit\s+checkout\b[^\n]*\s(-[a-zA-Z]*f\b|--force\b)/,
+  /\bgit\s+switch\b[^\n]*\s(-[a-zA-Z]*f\b|--force\b|--discard-changes\b)/,
+  /\bgit\s+restore\b(?:(?![^\n]*--staged\b)|(?=[^\n]*--staged\b)(?=[^\n]*--worktree\b))/,
+  /\bgit\s+stash\s+(drop|clear)\b/,
+  /\bgit\s+worktree\b[^\n]*\bremove\b[^\n]*(-[a-zA-Z]*f\b|--force\b)/,
+  /\bgit\s+reflog\b[^\n]*\bexpire\b/,
+  /\bgit\s+gc\b[^\n]*--prune\b/,
+]
+
+// A recursive scan rooted at a whole filesystem (Commands Must Return) → BLOCK. Twin of
+// js/hosts/hooks.mjs's `rootScan` — keep in step; tests/plugins/guard.test.mjs diffs the
+// constants below against it. In Git Bash `/` mounts every drive and share: on 2026-10-10 a
+// `find / … | head -5` ran 3.5 h (`| head` stops nothing). Exempt: a segment whose program is ssh, a quoted argument, any path
+// deeper than a root, a scanner word that is not the program. Backslash is never an escape in
+// the tokeniser, so `C:\ -Recurse` stays two tokens.
+const SCAN_ALWAYS = new Set(["find", "du", "tree", "rg", "fd", "where.exe"])
+const SCAN_GREP_R = new Set(["grep", "egrep"])
+const SCAN_LS_R = new Set(["ls", "dir"])
+const SCAN_PS_R = new Set(["get-childitem", "gci"])
+// `-r` recurses for grep only; for ls it is reverse, so ls/dir need an uppercase `R` cluster.
+const GREP_RECURSE_RE = /^(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)$/
+const LS_RECURSE_RE = /^(?:-[a-zA-Z]*R[a-zA-Z]*|--recursive)$/
+const PS_RECURSE_RE = /^-r(?:e(?:c(?:u(?:r(?:s(?:e)?)?)?)?)?)?$/i
+const FS_ROOT_RE = /^(?:\/|\/[a-z]\/?|\/mnt\/[a-z]\/?|[a-z]:[\\/]?)\*?$/i
+const SCAN_WORD_RE = /\b(?:find|du|tree|rg|fd|where\.exe|grep|egrep|ls|dir|get-childitem|gci)\b/i
+const SCAN_TOKEN_RE = /(?:[^\s"']+|"[^"]*"?|'[^']*'?)+/g
+const SCAN_WRAPPERS = new Set(["sudo", "command", "\\builtin", "time", "nice"])
+// A comment (`#` starting a word), a quoted run (its `;`/`|` is data), a separator, or a heredoc
+// opener (never the `<<<` here-string).
+const SCAN_SPLIT_RE = /(?<![^\s;|&(])#[^\n]*|"[^"]*"?|'[^']*'?|\|\||&&|[|;\n]|(?<!<)<<(?!<)(-?)[ \t]*(["']?)([A-Za-z_]\w*)\2/g
+// Cut at separators OUTSIDE quotes and drop every heredoc body (to its TAG line; `<<-` allows
+// tabs): a commit message that names a root scan is data, not a command to block.
+function scanSegments(command) {
+  const segs = []
+  const tags = []
+  const re = new RegExp(SCAN_SPLIT_RE)
+  let start = 0
+  let m
+  while ((m = re.exec(command))) {
+    if (m[3]) { tags.push([m[1], m[3]]); continue }
+    if (m[0][0] === '"' || m[0][0] === "'") continue
+    segs.push(command.slice(start, m.index))
+    start = re.lastIndex
+    // A comment is cut OUT of its segment; the newline after it is the next separator.
+    if (m[0][0] === "#") continue
+    while (m[0] === "\n" && tags.length) {
+      const end = command.indexOf("\n", start)
+      const line = command.slice(start, end < 0 ? command.length : end).replace(/\r$/, "")
+      start = end < 0 ? command.length : end + 1
+      if ((tags[0][0] ? line.replace(/^\t+/, "") : line) === tags[0][1]) tags.shift()
+      if (end < 0) break
+    }
+    re.lastIndex = start
+  }
+  segs.push(command.slice(start))
+  return segs
+}
+function rootScan(command) {
+  // A segment whose program is ssh passes (its remote command is ssh's argument): ssh is in no
+  // scanner set below. Only that segment — `ssh h true; find /` still blocks.
+  if (!SCAN_WORD_RE.test(command)) return null
+  for (const seg of scanSegments(command)) {
+    // Quotes kept until the root test, so a quoted "a:" is told from a bare C:.
+    let toks = (seg.match(SCAN_TOKEN_RE) || []).filter((t) => !/^\w+=/.test(t))
+    while (toks.length && SCAN_WRAPPERS.has(unquote(toks[0]))) toks = toks.slice(1)
+    if (!toks.length) continue
+    // The program word without its path (either slash) or an `.exe` suffix.
+    const word = unquote(toks[0]).split(/[\\/]/).pop().toLowerCase()
+    const prog = SCAN_ALWAYS.has(word) ? word : word.replace(/\.exe$/, "")
+    const always = SCAN_ALWAYS.has(prog)
+    const grep = SCAN_GREP_R.has(prog)
+    const ls = SCAN_LS_R.has(prog)
+    const ps = SCAN_PS_R.has(prog)
+    if (!always && !grep && !ls && !ps) continue
+    // `-Path=x` and PowerShell's colon binding `-Path:C:\` read as the path itself.
+    const argv = toks.slice(1).map((t) => {
+      const m = /^-path[=:](.+)$/i.exec(t)
+      return m ? m[1] : t
+    })
+    if (!always && !argv.some((a) => (grep && GREP_RECURSE_RE.test(a))
+      || (ls && (LS_RECURSE_RE.test(a) || (a.length >= 3 && PS_RECURSE_RE.test(a))))
+      || (ps && PS_RECURSE_RE.test(a)))) continue
+    if (argv.some(rootArg)) return seg.trim()
+  }
+  return null
+}
+// For ls/dir a `-Recurse` abbreviation counts from `-re` up: bare `-r` there is POSIX reverse.
+const unquote = (t) => t.replace(/^["']+|["']+$/g, "")
+// A QUOTED token is data (a grep pattern, a path named in a search), never a root target.
+const rootArg = (t) => !/^["']/.test(t) && FS_ROOT_RE.test(t)
+
+// `apply_patch`'s only argument is `patchText` (OpenCode verdict I-1): every gpt-5*
+// model gets ONLY this tool, never `edit`/`write`, so a path that lives inside the
+// patch text — not in `filePath`/`path`/etc — must still hit every gate below, or
+// Sealed Secrets, the protected-check gate, the rule store and the wiki gate all go
+// dark for that model class. Markers match upstream's own parser
+// (`packages/opencode/src/patch/index.ts` `parsePatchHeader`): `*** Add File:`,
+// `*** Update File:` (optionally followed by `*** Move to:`, both the old and the new
+// path count) and `*** Delete File:`. The `+`-prefixed body lines are the new file
+// content, never a path, and are not scanned here — no gate in this file inspects
+// write content, only the target path.
+function parsePatchPaths(patchText) {
+  const out = []
+  const lines = String(patchText).split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    let m = /^\*\*\* (?:Add|Delete) File:\s*(.+)$/.exec(line)
+    if (m) { out.push(m[1].trim()); continue }
+    m = /^\*\*\* Update File:\s*(.+)$/.exec(line)
+    if (m) {
+      out.push(m[1].trim())
+      const mv = /^\*\*\* Move to:\s*(.+)$/.exec(lines[i + 1] || "")
+      if (mv) { out.push(mv[1].trim()); i++ }
+    }
+  }
+  return out.filter(Boolean)
+}
 
-function pickPath(args) {
+// Returns every candidate path for this call, normalized (backslashes -> `/`) and,
+// for an `apply_patch` call, resolved against `cwd` (the session's `ctx.directory` —
+// the same root `apply_patch.ts:72` resolves against upstream) since a patch marker
+// is worktree-relative. Non-patch tools keep the single-path shape every other gate
+// already expects, just wrapped in an array.
+function pickPath(args, cwd) {
+  if (args && typeof args.patchText === "string") {
+    return parsePatchPaths(args.patchText)
+      .map((p) => path.resolve(cwd || process.cwd(), p).replace(/\\/g, "/"))
+  }
   for (const k of ["filePath", "path", "file", "target", "filename"]) {
     // Normalize Windows backslashes to `/` so the secret-path patterns (which use `/`
     // as the segment separator) match `C:\Users\me\.ssh\id_rsa` the same as a POSIX path.
-    if (args && typeof args[k] === "string") return args[k].replace(/\\/g, "/")
+    if (args && typeof args[k] === "string") return [args[k].replace(/\\/g, "/")]
   }
-  return ""
+  return []
+}
+// Per-FILE added content for an `apply_patch` call: `parsePatchPaths` flattens every marker
+// path into one list (right for the path-only gates, which must catch a secret/protected name
+// on either side of a `Move to`), but the CONTENT scan must not pool every file's `+` lines
+// into one string — a patch that touches a `.env` AND an ordinary file would then exempt the
+// ordinary file's own secret too, because the exemption was computed over the pool, not the
+// line's own file. One section per marker; a `Move to` target is where the `+` lines actually
+// land, so content is attributed to it, not the pre-move path. `*** Delete File:` sections
+// collect no `+` lines (nothing is being written).
+function parsePatchSections(patchText) {
+  const out = []
+  let current = null
+  const flush = () => { if (current) out.push(current) }
+  const lines = String(patchText).split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    let m = /^\*\*\* (?:Add|Delete) File:\s*(.+)$/.exec(line)
+    if (m) { flush(); current = { path: m[1].trim(), added: [] }; continue }
+    m = /^\*\*\* Update File:\s*(.+)$/.exec(line)
+    if (m) {
+      flush()
+      let p = m[1].trim()
+      const mv = /^\*\*\* Move to:\s*(.+)$/.exec(lines[i + 1] || "")
+      if (mv) { p = mv[1].trim(); i++ }
+      current = { path: p, added: [] }
+      continue
+    }
+    if (current && line.startsWith("+") && !line.startsWith("+++")) current.added.push(line.slice(1))
+  }
+  flush()
+  return out.filter((s) => s.path)
+}
+
+// The content a write/edit/apply_patch call would actually land on disk, per FILE — what the
+// content secret scan runs against, paired with the path it belongs to so the `.env` exemption
+// can be checked against that file alone. `write` carries `content`, `edit` carries `newString`
+// (OpenCode tool Parameters, packages/opencode/src/tool/{write,edit}.ts) — both single-path, so
+// one pair. For `apply_patch`, one pair per marker section; only the `+`-prefixed hunk lines are
+// NEW content — a `-` line is text being REMOVED, so a secret there is leaving the file, not
+// landing in it, and must not block the call.
+function pickAddedContentByPath(args, cwd) {
+  if (args && typeof args.patchText === "string") {
+    return parsePatchSections(args.patchText)
+      .filter((s) => s.added.length)
+      .map((s) => ({
+        path: path.resolve(cwd || process.cwd(), s.path).replace(/\\/g, "/"),
+        content: s.added.join("\n"),
+      }))
+  }
+  const [p] = pickPath(args, cwd)
+  if (!p) return []
+  if (typeof args.content === "string") return [{ path: p, content: args.content }]
+  if (typeof args.newString === "string") return [{ path: p, content: args.newString }]
+  return []
 }
 function pickCommand(args) {
   for (const k of ["command", "cmd", "script"]) {
@@ -319,130 +546,8 @@ function protectedCheck(p) {
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
 const WIKI_MUTATE_TOOLS = [...WRITE_TOOLS, "delete", "remove", "rename", "move", "trash"]
 
-// ---- the loop/* exemption (Consent Before Push) --------------------------------
-// Twin of js/hosts/gitref.mjs (currentBranch/loopLaunched) and js/hosts/hooks.mjs's
-// git-gate (the rest) — keep in step. Node's native sync `fs` (not the `fs.promises`
-// import above): a worktree's `.git` is read the same way the Claude/Bob hook reads it, so
-// the two decide the exemption identically. This plugin cannot import from `js/` at all
-// (it is copied whole into an OpenCode install, outside this repo's module graph), so it
-// keeps its own standalone copy rather than the single shared owner the Node side has.
-
-const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/
-
-// No newline, backtick, or `$(` substitution anywhere, no `<`/`>` redirect, and no single
-// `&` (a shell runs `a & b` as two commands exactly like `a && b`) — these can smuggle a
-// second command (or a shared-branch target) past every check below. `(?<!&)&(?!&)` matches
-// a lone `&` without matching either half of a doubled `&&`.
-const UNSAFE_CHARS_RE = /[\n`<>]|\$\(|(?<!&)&(?!&)/
-
-// The only three git shapes a loop's own automation ever needs — see js/hosts/hooks.mjs's
-// identically-named constants for the full rationale. The token class `[\w./:@^~=+,-]`
-// excludes quotes, braces, `!`, `*`, `$` and `&` — a brace/glob expansion is exactly how a
-// shell turns one whitelisted-looking token into several unknown ones, which is also why the
-// `-F`/`--file` path uses this same class rather than the looser `[^\s'"]+` it once did: that
-// loose class let `git commit -F {m,--amend}` brace-expand into an amend of the last commit.
-const ARG_RE = "[\\w./:@^~=+,-]+"
-const SEG_ADD_RE = new RegExp(`^git\\s+add(\\s+${ARG_RE})*$`)
-const SEG_COMMIT_RE = new RegExp(`^git\\s+commit(\\s+-q)?\\s+(-F\\s+|--file[=\\s])${ARG_RE}(\\s+-q)?$`)
-const SEG_READONLY_RE = new RegExp(`^git\\s+(status|diff|log|rev-parse|show)(\\s+${ARG_RE})*$`)
-
-/**
- * `git push`, exactly: `[-u|--set-upstream] <remote> HEAD:<branch>` or
- * `HEAD:refs/heads/<branch>` — the ONLY exempt form, same as js/hosts/hooks.mjs's
- * `pushSegmentOk`. An explicit refspec is immune to `push.default`/`remote.*.push`
- * redirection and refuses to coexist with a mirror/`+`/`:`-prefixed form; nothing else is.
- */
-function pushSegmentOk(seg, branch) {
-  const m = /^git\s+push(?:\s+(.*))?$/.exec(seg)
-  if (!m) return false
-  const rest = (m[1] || "").trim()
-  if (!rest) return false
-  const tokens = rest.split(/\s+/)
-  let i = 0
-  if (tokens[i] === "-u" || tokens[i] === "--set-upstream") i += 1
-  const remote = tokens[i]
-  if (remote === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(remote)) return false
-  i += 1
-  const ref = tokens[i]
-  i += 1
-  if (ref === undefined || i !== tokens.length) return false
-  return ref === `HEAD:${branch}` || ref === `HEAD:refs/heads/${branch}`
-}
-
-const LOOP_STATE_MARKER = "<!-- loop-state:begin -->"
-
-/**
- * Whether `<root>/LOOP.md` carries the engine's state marker — read at most 64 KB.
- * `lstatSync` (never `statSync`, which follows a link) must find an ordinary file: a FIFO
- * would block the read, a symlink could point anywhere outside the repo.
- */
-function loopLaunched(gitRoot) {
-  let fd
-  try {
-    const p = path.join(gitRoot, "LOOP.md")
-    if (!lstatSync(p).isFile()) return false
-    fd = openSync(p, "r")
-    const buf = Buffer.alloc(65536)
-    const n = readSync(fd, buf, 0, buf.length, 0)
-    return buf.toString("utf8", 0, n).includes(LOOP_STATE_MARKER)
-  } catch {
-    return false
-  } finally {
-    if (fd !== undefined) { try { closeSync(fd) } catch { /* already gone */ } }
-  }
-}
-
-/**
- * The branch checked out in `cwd`, and the directory holding `.git` for it, read from
- * .git/HEAD without spawning git — a worktree's `.git` is a FILE naming its gitdir, so both
- * shapes are followed. `{ branch: null, root: null }` on anything unexpected (detached HEAD,
- * no repo, unreadable): the caller then leaves the ask alone.
- */
-function currentBranch(cwd) {
-  try {
-    let dir = path.resolve(cwd)
-    for (;;) {
-      const dotgit = path.join(dir, ".git")
-      if (existsSync(dotgit)) {
-        let gitdir = dotgit
-        if (statSync(dotgit).isFile()) {
-          const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, "utf8"))
-          if (!m) return { branch: null, root: null }
-          gitdir = path.resolve(dir, m[1])
-        }
-        const ref = /^ref:\s*refs\/heads\/(.+?)\s*$/m.exec(readFileSync(path.join(gitdir, "HEAD"), "utf8"))
-        return { branch: ref ? ref[1] : null, root: dir }
-      }
-      const up = path.dirname(dir)
-      if (up === dir) return { branch: null, root: null }
-      dir = up
-    }
-  } catch {
-    return { branch: null, root: null }
-  }
-}
-
-/**
- * Consent Before Push's loop/* exemption — the twin of js/hosts/hooks.mjs's `loopExempt`.
- * True only when the command carries none of the unsafe characters, every `&&`/`;`/`||`/`|`
- * segment is one of the three whitelisted git shapes (every push segment also passing
- * `pushSegmentOk`), and the branch checked out in `cwd` starts with `loop/` AND its git root
- * carries a launched LOOP.md.
- */
-function loopExempt(command, cwd) {
-  if (typeof command !== "string" || UNSAFE_CHARS_RE.test(command)) return false
-  const { branch, root } = currentBranch(cwd)
-  if (!branch || !branch.startsWith("loop/")) return false
-  if (!root || !loopLaunched(root)) return false
-  const segments = command.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean)
-  if (!segments.length) return false
-  return segments.every((seg) => SEG_ADD_RE.test(seg) || SEG_COMMIT_RE.test(seg)
-    || SEG_READONLY_RE.test(seg) || pushSegmentOk(seg, branch))
-}
-
 export const GeneseedGuard = async (ctx) => {
-  // The session's working directory, the same resolution the context plugin uses — a
-  // worktree session's `.git` is a FILE, which `currentBranch` already follows.
+  // The session's working directory, the same resolution the context plugin uses.
   const root = () => ctx?.worktree || ctx?.directory || process.cwd()
   return {
     "tool.execute.before": async (input, output) => {
@@ -459,24 +564,47 @@ export const GeneseedGuard = async (ctx) => {
         throw new Error(`[geneseed-guard] blocked: ${why} — set GENESEED_GUARD=off to allow`)
       }
       try {
+        // `apply_patch`'s own tool resolves every marker path against `instance.directory`
+        // (`apply_patch.ts:72` in the verdict's evidence), NOT the worktree root `root()`
+        // uses for the sovereign-repo bypass above — a worktree session started in a
+        // subdirectory of its git root must see the same (narrower) root the write
+        // actually lands under, or a protected-check/wiki/secret hit one directory up
+        // would be missed.
+        const cwd = ctx?.directory || process.cwd()
         if (hasAny(tool, WRITE_TOOLS)) {
-          const p = pickPath(args)
-          if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Sealed Secrets)`, "law-1"); return }
-          if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
-          const sensor = p && protectedCheck(p)
-          if (sensor) { await deny(`${p} is a protected check (${sensor}, listed in ${SENSOR_LIST}) — a check the agent can edit is not a check (External Gate)`, "rigor-5"); return }
-          const store = p && ruleStoreTarget(p)
-          if (store && !RULE_STORE_BUMPED.has(p)) {
-            RULE_STORE_BUMPED.add(p)
-            await deny(`writing to ${store} — a standing rule, or a fact to remember? That ` +
-                 `choice is the user's (Persist Insight). Settle it through the rule skill, ` +
-                 `then re-issue this write`, "process-1")
-            return
+          // `apply_patch` (gpt-5*) can carry several marker paths in one call — every
+          // one of them is a write target, so every one runs every gate; the first hit
+          // blocks the whole call (see `pickPath` for why this is not a single path).
+          const paths = pickPath(args, cwd)
+          for (const p of paths) {
+            if (SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Sealed Secrets)`, "law-1"); return }
+            if (SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
+            const sensor = protectedCheck(p)
+            if (sensor) { await deny(`${p} is a protected check (${sensor}, listed in ${SENSOR_LIST}) — a check the agent can edit is not a check (External Gate)`, "rigor-5"); return }
+            const store = ruleStoreTarget(p)
+            if (store && !RULE_STORE_BUMPED.has(p)) {
+              RULE_STORE_BUMPED.add(p)
+              await deny(`writing to ${store} — a standing rule, or a fact to remember? That ` +
+                   `choice is the user's (Persist Insight). Settle it through the rule skill, ` +
+                   `then re-issue this write`, "process-1")
+              return
+            }
+          }
+          // Content scan (Sealed Secrets, the twin of js/hosts/hooks.mjs's ruleDecide): per
+          // FILE, not pooled — a patch touching `.env` AND an ordinary file must still catch a
+          // secret in the ordinary file; only the hunk whose OWN path is `.env`-shaped is
+          // exempt, same as the path WARN tier above.
+          for (const { path: cp, content } of pickAddedContentByPath(args, cwd)) {
+            if (SECRET_WARN_RE.some((re) => re.test(cp))) continue
+            if (SECRET_CONTENT_RE.test(content)) {
+              await deny(`${cp} would carry a credential-shaped string (Sealed Secrets) — secrets `
+                + "live in .env or a secret manager, never in a tracked file", "law-1")
+              return
+            }
           }
         }
         if (hasAny(tool, WIKI_MUTATE_TOOLS)) {
-          const p = pickPath(args)
-          if (p) {
+          for (const p of pickPath(args, cwd)) {
             const abs = (path.isAbsolute(p) ? p : path.resolve(p)).replace(/\\/g, "/").toLowerCase()
             const hit = (await protectedPrefixes()).find(
               (x) => abs.startsWith(x.prefix) || abs === x.prefix.slice(0, -1))
@@ -488,6 +616,12 @@ export const GeneseedGuard = async (ctx) => {
         if (hasAny(tool, SHELL_TOOLS)) {
           const c = pickCommand(args)
           if (c && SHELL_BLOCK_RE.some((re) => re.test(c))) { await deny(`catastrophic command (Deletion Is Deliberate): ${c.slice(0, 80)}`, "law-4"); return }
+          const scan = c && rootScan(c)
+          if (scan) {
+            await deny(`\`${scan.slice(0, 80)}\` recursively scans a whole filesystem root (Commands Must Return) — ` +
+              "search a specific directory instead: the project, node_modules, ~/.npm, %APPDATA%", "ops-2")
+            return
+          }
           if (c && SHELL_WARN_RE.some((re) => re.test(c))) log(`WARN: irreversible op — confirm intent (Deletion Is Deliberate): ${c.slice(0, 80)}`)
         }
       } catch (err) {
@@ -496,23 +630,6 @@ export const GeneseedGuard = async (ctx) => {
         log(`inspect error (ignored): ${err?.message ?? err}`)
       }
     },
-    "permission.ask": async (input, output) => {
-      // Never throw from a permission hook — leave `output.status` untouched on any
-      // error, exactly as a crashed check here must default to the static ask standing.
-      try {
-        if (OFF) return
-        // Never loosen anything but the plain "ask" this hook itself would otherwise leave
-        // alone — a deny (or any other status another hook already set) is never overwritten.
-        if (output?.status && output.status !== "ask") return
-        if (input?.type !== "bash") return
-        // ONLY `input.metadata?.command` — no pattern/title fallback. A value this hook did
-        // not itself read in full is a value it must not reason about.
-        const command = input?.metadata?.command
-        if (typeof command !== "string" || !command || !GIT_GATE_RE.test(command)) return
-        if (await sovereignBypass(root())) return
-        if (loopExempt(command, root())) output.status = "allow"
-      } catch { /* leave output.status untouched */ }
-    },
   }
 }
 

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 |