geneseed 3.3.0 → 3.5.0

package/adapters/copilot/README.md

@@ -9,8 +9,9 @@ Agent Skills), custom agents are markdown-with-frontmatter, and the repo-root
 a `host="copilot"` flag. Nothing to install by hand: `geneseed setup` (or
 `geneseed build --emit copilot` / `--emit copilot-global`) writes everything.
 
-Copilot is a **reduced host**: it has lifecycle hooks, but one command per event and
-no "ask the user" tier, so this page is mostly about what those hooks *can* and
+Copilot is a **reduced host** at project scope (no hooks there) and close to Claude
+Code at global scope: its lifecycle hooks have an "ask the user" tier, so the gates
+prompt as they do on Claude. This page is mostly about what those hooks *can* and
 *cannot* automate and why the harness still holds where they cannot.
 
 ## What the emit writes
@@ -23,7 +24,8 @@ no "ask the user" tier, so this page is mostly about what those hooks *can* and
   - `agents/<name>.agent.md` — Copilot's **custom-agent dialect** (`.agent.md`
     extension; a `tools:` **allowlist**, not Claude's denylist — a read-only
     agent lists the tool ids it keeps: `read, search, todo, agent`, plus
-    `execute` only when the spec opts in with `<!-- bash: allow -->`). Sibling
+    `execute` only when the spec opts in with `<!-- bash: allow -->`, `fetch` only
+    with `<!-- webfetch: allow -->`). Sibling
     agent links are rewritten to the `.agent.md` filename.
   - `skills/<name>/SKILL.md` — **byte-identical** to every other host.
 
@@ -38,42 +40,42 @@ no "ask the user" tier, so this page is mostly about what those hooks *can* and
   the preamble rides it as a managed block. (Unlike Bob, Copilot *has* a real
   personal instructions carrier, so no rules-folder workaround is needed.)
 - `agents/<name>.agent.md` + `skills/` under `~/.copilot`.
-- **`settings.json` hooks** — two entries under `hooks`, see below.
+- **`settings.json` hooks** — four entries under `hooks`, see below.
 
-## Hooks — one command per event, block or warn
+## Hooks — ask, as on Claude Code
 
 The Copilot CLI reads lifecycle hooks from **`~/.copilot/settings.json`** as a map of
-event → one `{command}` object (no matcher groups, no list). The global emit wires
-two of them, each calling the machine-wide `geneseed-hook` shim with `--host copilot`
-so the verdict is spoken in Copilot's dialect:
+event → **array** of `{type: "command", command}` entries
+([reference](https://docs.github.com/en/copilot/reference/hooks-configuration)). The
+global emit adds one entry to each of four events, each calling the machine-wide
+`geneseed-hook` shim:
 
 | event | verb | what it does |
 | --- | --- | --- |
 | `sessionStart` | `context` | eager project-context injection, as on Claude Code, returned as `{"additionalContext": …}` |
-| `toolCall` | `tool-gate` | the git gate and the rule gate **fused** — one command is all the event allows — dispatched on the payload: a `command` gets the git checks, a path gets the rule checks; the `after` phase is ignored |
+| `preToolUse` | `tool-gate --host copilot` | the git gate and the rule gate **fused** — entries carry no matcher — dispatched on the payload: a `command` gets the git checks, a path gets the rule checks |
+| `agentStop` | `learn` | distils the session transcript (`transcriptPath`) into memory, as Claude's `Stop` |
+| `preCompact` | `learn` | the same, once more before compaction summarises the window away |
 
-Copilot's `toolCall` has **no "ask the user" tier** — its stdout contract is
-`{"block": true|false}` — so the verdict tiers are:
+`preToolUse` has an ask tier, so every rule **asks** exactly where it asks on Claude
+Code — Laws I and IV, process 1 and process 5 — answered top-level as
+`{"permissionDecision": "ask", "permissionDecisionReason": …}`. A gate error asks
+too (fail closed). `toolArgs` is read whether Copilot sends it as an object or as a
+JSON string.
 
-- **Laws I and IV block.** A credential-shaped string headed for a tracked file, or
-  a history-discarding git act (`reset --hard`, `clean -f`, `branch -D`,
-  `checkout --`, `push --force`), is refused outright with the reason. Same stance
-  as the OpenCode guard plugin, whose `tool.execute.before` can only allow or throw.
-- **Process 1 and process 5 warn.** The two consent rules are the *user's* calls; a
-  hard block would make Copilot unable to commit at all. They log a `[geneseed] …`
-  line on stderr (which Copilot records) and allow. A gate error warns the same way
-  rather than locking every tool call behind a block nobody can clear.
+**Your own hooks on those events stay**: Geneseed's entry goes beside them in the
+array, and uninstall removes exactly the entries it claimed. Comments in the file
+mean it is never rewritten.
 
-**A hook you already set on one of those events is left alone**, and that event is
-not claimed — one slot per event means Geneseed could only displace it. Uninstall
-removes exactly the hooks it claimed. Comments in the file mean it is never
-rewritten.
+**Migration.** Before this, the emit wired a single-object `toolCall` hook — an event
+Copilot no longer fires, so the gates never ran. A re-emit removes those recorded
+entries (your own keys stay) and writes the array shape.
+
+**Unverified live.** No Copilot CLI on the authoring machine; this is the documented
+contract.
 
 **What is not wired, and why:**
 
-- **no `learn`** — Copilot's `sessionEnd` and `agentStop` payloads carry no
-  `transcript_path`, so a distiller would have nothing to read. The memory
-  convention rides the preamble's instructions (the agent writes its own memories);
 - **no hooks at project scope** — the CLI documents hooks in the personal settings
   file only, and a machine-absolute command committed into a shared `.github/`
   would fail on every teammate's machine;

package/adapters/opencode/GLOBAL-HARNESS-SPEC.md

@@ -185,7 +185,7 @@ repo's layout defeats the convention.
 
 ### 3.5 Injection block format (mirror `harness.py cmd_context`)
 
-Byte-identical structure to [harness.py:237-263](../../rituals/harness.py) so both
+Byte-identical structure to the retired Python `harness.py` (lines 237-263) so both
 enforcement paths read the same. Adds a machine marker (first line) for §4.
 
 ```

package/adapters/opencode/README.md

@@ -57,7 +57,8 @@ your-repo/
 - Read-only agents (their spec says *Read-only*) get an OpenCode `permission` block
   — `edit: deny`, `webfetch: deny`, and `bash: deny`, so a read-only agent can't
   mutate via the shell either. One that must run read-only commands (tests, linters,
-  scanners) declares `<!-- bash: allow -->` in its spec, which gates bash to `ask`
+  scanners) declares `<!-- bash: allow -->` in its spec, which gates bash to `ask`;
+  `<!-- webfetch: allow -->` (the researcher) re-opens web fetch the same way
   instead. The rest keep edit access.
 - OpenCode invokes a subagent via the task tool, e.g. `subagent_type: "reviewer"`.
 - **Skills are native, not slash commands** — model-invoked via the `skill` tool
@@ -357,7 +358,10 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
   { "agents": { "reviewer": { "model": "anthropic/claude-haiku-4-5", "temperature": 0.1, "variant": "high", "steps": 20 } } }
   ```
   Re-emit to apply. (A future TUI screen will edit this map.) Unlisted keys are omitted,
-  so the agent inherits OpenCode's defaults.
+  so the agent inherits OpenCode's defaults. The stub also carries an inert
+  `_recommended.cheap-tier` list — the read-and-summarise seats (explorer, researcher,
+  tester, and the council bench) worth routing to a cheaper model; copy the names you
+  want into `agents`, nothing applies by itself.
 - **Agent colours.** Each capability agent is emitted with a `color:` set to an OpenCode
   *named theme slot*, sourced from the active harness theme's `AGENT_COLORS` map
   (`themes/_TEMPLATE.json`; the shipped default — architect=`primary`, reviewer=`warning`,
@@ -376,8 +380,8 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
   `tokyonight`, `rosepine`, `gruvbox`, `nord`, `everforest`, `kanagawa`, `dracula` — each
   in a **solid** (opaque) and a **transparent** (terminal-background-through) flavour.
   These are decoupled from the voice theme: any voice theme can run any colour theme.
-  Authored under `themes/opencode/` (see its README and
-  [the spec](../../docs/specs/2026-06-17-opencode-color-themes.md)).
+  Authored under `themes/opencode/` (see its README; the design record was the
+  `2026-06-17-opencode-color-themes` spec).
 - **Runtime guard plugin** (`geneseed-guard.js`, installed with the others). Enforces
   the safety Laws at the tool boundary: **blocks** writes to private-key/credential
   files (Law I), catastrophic shell like `rm -rf /` (Law IV), and any mutation under

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

@@ -138,10 +138,12 @@ let fallbackVisible = false
 function log(msg) { if (DEBUG) console.error(`[geneseed-context] ${msg}`) }
 
 // ---- convention --------------------------------------------------------------
-// Root-level files injected in full. Agent-directed rules + canonical entry docs.
+// Root-level files injected in full. Canonical entry docs + agent-directed rules OpenCode
+// does not read by itself. AGENT.md (opencode.json `instructions`), AGENTS.md and CLAUDE.md
+// (OpenCode's own native roots) are deliberately absent: OpenCode already has them, and
+// injecting them again re-sent the whole harness on every request until 2026-09.
 const EAGER_ROOT = new Set([
-  "AGENTS.md", "AGENT.md", "CLAUDE.md", ".cursorrules",
-  "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
+  ".cursorrules", "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
 ])
 // Doc trees walked recursively; everything found is lazy (listed, not injected).
 const LAZY_DIRS = ["docs", "doc", "documentation", "architecture", "adr", "ADR"]

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

@@ -17,6 +17,7 @@
 // Quiet by default; GENESEED_DEBUG=1 logs to stderr. GENESEED_WORKFLOWS_DIR overrides
 // where saved workflows are loaded from.
 
+import { execFile } from "node:child_process"
 import { promises as fs } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
@@ -63,6 +64,17 @@ function nowStamp() {
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
 }
 
+// The runtime's git executor, for `isolation: "worktree"`. argv only, never a shell string:
+// branch and directory names derive from agent labels a script author wrote.
+function git(argv, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", argv, { cwd, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`git ${argv[0]}: ${String(stderr || err.message).trim()}`))
+      else resolve(String(stdout))
+    })
+  })
+}
+
 function safeJson(v) {
   try { return JSON.stringify(v, null, 2) } catch { return String(v) }
 }
@@ -73,7 +85,22 @@ function summarize(name, result, stats, tracePath) {
     (stats.phases.length ? `, phases: ${stats.phases.join(" → ")}` : "")
   let body = safeJson(result)
   if (body.length > 2000) body = body.slice(0, 2000) + `\n… (truncated — full result in ${tracePath})`
-  return `${head}\n\nResult:\n${body}\n\nTrace: ${tracePath}`
+  return `${head}\n\nResult:\n${body}${isolationReport(stats)}\n\nTrace: ${tracePath}`
+}
+
+// Kept worktrees are work awaiting review, and an overlap is a conflict awaiting ONE
+// merger (process 8) — both are said out loud, never left for the trace to hold.
+function isolationReport(stats) {
+  const kept = stats.worktrees || []
+  if (!kept.length) return ""
+  const lines = ["", "", `Worktrees kept (${kept.length}) — review and merge them yourself; nothing was merged:`]
+  for (const w of kept) lines.push(`- ${w.label}: ${w.branch} at ${w.dir} — ${w.files.length} file(s)`)
+  const over = stats.overlaps || []
+  if (over.length) {
+    lines.push(`CONFLICTS — ${over.length} file(s) changed by more than one agent; merge these by hand or through one merge agent:`)
+    for (const o of over) lines.push(`- ${o.file}: ${o.labels.join(", ")}`)
+  }
+  return lines.join("\n")
 }
 
 async function writeTrace(rootDir, runId, lines) {
@@ -142,7 +169,7 @@ export const GeneseedWorkflow = async (ctx) => {
     try { ({ createRuntime } = await import(pathToFileURL(path.join(WORKFLOWS_DIR, "_runtime.js")).href + "?t=" + Date.now())) }
     catch (e) { return `Workflow runtime unavailable: ${e?.message || e}` }
 
-    const rt = createRuntime({ client, directory, worktree, args: normalizeArgs(argv?.args), log: sink })
+    const rt = createRuntime({ client, directory, worktree, git, runId, args: normalizeArgs(argv?.args), log: sink })
     let result, failed = null
     try { result = await wf.run(rt) }
     catch (e) { failed = e; sink(`✗ workflow error: ${e?.stack || e?.message || e}`) }
@@ -152,7 +179,7 @@ export const GeneseedWorkflow = async (ctx) => {
     if (!failed) sink(`# result:\n${safeJson(result)}`)
     const tracePath = await writeTrace(rootDir, runId, lines)
 
-    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}\nTrace: ${tracePath}`
+    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}${isolationReport(stats)}\nTrace: ${tracePath}`
     return summarize(name, result, stats, tracePath)
   }
 

package/adapters/opencode/workflows/_runtime.js

@@ -17,6 +17,7 @@
 // hard sandbox guard. See docs/specs/2026-06-09-opencode-workflow-primitive.md.
 
 import * as os from "node:os"
+import * as path from "node:path"
 
 const DEBUG = !!process.env.GENESEED_DEBUG
 function dlog(m) { if (DEBUG) console.error(`[geneseed-workflow] ${m}`) }
@@ -150,13 +151,17 @@ function usageFrom(res) {
   return { input: Number(tok?.input ?? 0) || 0, output: Number(tok?.output ?? 0) || 0 }
 }
 
-async function runChildSession(client, { prompt, agent, model, title }) {
+async function runChildSession(client, { prompt, agent, model, title, directory }) {
   if (!client?.session?.create || !client?.session?.prompt) {
     throw new Error("OpenCode SDK session API unavailable")
   }
   let created
-  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" } }) }
-  catch { created = await client.session.create() }
+  // `query.directory` routes the request to that directory's instance, and the session keeps
+  // it — so an isolated child runs in its worktree. Never retried without it: a child that
+  // asked for a worktree and silently ran in the shared tree is the failure isolation exists for.
+  const q = directory ? { query: { directory } } : {}
+  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" }, ...q }) }
+  catch (e) { if (directory) throw e; created = await client.session.create() }
   const sid = sessionId(created)
   if (!sid) throw new Error("could not create child session")
   try {
@@ -164,7 +169,7 @@ async function runChildSession(client, { prompt, agent, model, title }) {
     if (agent) body.agent = agent
     if (model) body.model = model
     let res = null
-    try { res = await client.session.prompt({ path: { id: sid }, body }) }
+    try { res = await client.session.prompt({ path: { id: sid }, body, ...q }) }
     catch (e) { dlog(`prompt failed: ${e?.message || e}`) }
     const r = unwrap(res)
     let text = partsText(r?.parts ?? r?.info?.parts ?? [])
@@ -175,9 +180,52 @@ async function runChildSession(client, { prompt, agent, model, title }) {
   }
 }
 
+// ---- worktree isolation ------------------------------------------------------
+// `agent(prompt, { isolation: "worktree" })` — the same option Claude Code's Workflow
+// takes. Parallel editors in one tree lose each other's writes (process 8, one writer per
+// file), so each isolated agent gets its own branch + worktree off the root's HEAD, and
+// the files it changed are recorded for `overlaps()`. A worktree with no change is
+// removed with its branch; one with changes is KEPT for the parent to review and merge —
+// the runtime never merges, commits, or deletes work. `git(argv, cwd)` is injected by the
+// plugin so this file stays pure and testable. The worktree has no untracked files from
+// the root (no node_modules, no .env): an agent that must run the project installs first.
+const slug = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "agent"
+
+export async function isolate(git, root, name) {
+  if (typeof git !== "function") throw new Error("worktree isolation unavailable — no git executor")
+  if (!root) throw new Error("worktree isolation unavailable — unknown working dir")
+  const base = (await git(["rev-parse", "HEAD"], root)).trim()
+  const branch = `geneseed-wf/${name}`
+  const dir = path.join(os.tmpdir(), "geneseed-wf", name)
+  await git(["worktree", "add", "-b", branch, dir, base], root)
+  return { dir, branch, base }
+}
+
+export async function changedFiles(git, w) {
+  const lines = (out) => String(out).split("\n").map((l) => l.trim()).filter(Boolean)
+  const tracked = lines(await git(["diff", "--name-only", w.base], w.dir))
+  const untracked = lines(await git(["ls-files", "--others", "--exclude-standard"], w.dir))
+  return [...new Set([...tracked, ...untracked])].sort()
+}
+
+// Files more than one isolated agent changed — the conflicts a merge would otherwise
+// settle by whoever landed last. [{ file, labels }], sorted by file.
+export function overlaps(worktrees) {
+  const by = new Map()
+  for (const w of worktrees || []) for (const f of w.files || []) {
+    if (!by.has(f)) by.set(f, [])
+    by.get(f).push(w.label)
+  }
+  return [...by].filter(([, l]) => l.length > 1).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([file, labels]) => ({ file, labels }))
+}
+
 // ---- the runtime ------------------------------------------------------------
 export function createRuntime(ctx) {
-  const { client, directory, worktree, log: sink } = ctx
+  const { client, directory, worktree, log: sink, git } = ctx
+  const root = worktree || directory
+  const runTag = slug(ctx.runId || "run")
+  const worktrees = []
   const args = ctx.args || {}
   const cap = ctx.concurrency || concurrencyCap()
   const limit = createLimiter(cap)
@@ -202,9 +250,32 @@ export function createRuntime(ctx) {
   async function spawn(prompt, opts) {
     return limit(() => runChildSession(client, {
       prompt, agent: opts.agent, model: opts.model, title: `geneseed-wf:${opts.label}`,
+      directory: opts.directory,
     }))
   }
 
+  // Git calls are serialised: concurrent `worktree add -b` calls contend for the same ref
+  // and worktree locks, and a lost lock fails an agent that did nothing wrong.
+  const gitQ = createLimiter(1)
+  const g = typeof git === "function" ? (argv, cwd) => gitQ(() => git(argv, cwd)) : undefined
+
+  // An isolated agent that changed nothing has its worktree and branch released; one that
+  // changed files is KEPT and recorded. A failed release is logged, never thrown.
+  async function settle(w, label) {
+    let files
+    try { files = await changedFiles(g, w) }
+    catch (e) { emit(`  ⚠ ${label}: could not list changes — worktree kept at ${w.dir}: ${e?.message || e}`); return }
+    if (files.length) {
+      worktrees.push({ label, dir: w.dir, branch: w.branch, base: w.base, files })
+      emit(`  ⎇ ${label}: ${files.length} file(s) changed — kept at ${w.dir} (branch ${w.branch})`)
+      return
+    }
+    try {
+      await g(["worktree", "remove", w.dir], root)
+      await g(["branch", "-D", w.branch], root)
+    } catch (e) { emit(`  ⚠ ${label}: could not release unchanged worktree — ${e?.message || e}`) }
+  }
+
   async function agent(prompt, opts = {}) {
     if (agentCount >= MAX_AGENTS) throw new Error(`workflow agent cap (${MAX_AGENTS}) exceeded`)
     if (budgetTotal != null && spent >= budgetTotal) {
@@ -213,8 +284,21 @@ export function createRuntime(ctx) {
     agentCount++
     const label = opts.label || String(prompt).slice(0, 40)
     emit(`· agent: ${label}`)
+    if (opts.isolation !== "worktree") return runAgent(prompt, { ...opts, label })
+    // The worktree wraps EVERY attempt, schema retries included — a retry that ran in the
+    // shared tree would undo the isolation it was asked for.
+    let w
+    try { w = await isolate(g, root, `${runTag}-${agentCount}-${slug(label)}`) }
+    catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
+    emit(`  ⎇ ${label}: worktree ${w.dir}`)
+    try { return await runAgent(prompt, { ...opts, label, directory: w.dir }) }
+    finally { await settle(w, label) }
+  }
+
+  async function runAgent(prompt, opts) {
+    const { label } = opts
     let out
-    try { out = await spawn(prompt, { ...opts, label }) }
+    try { out = await spawn(prompt, opts) }
     catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
     spent += out.usage?.output || 0
     if (!opts.schema) return out.text
@@ -270,7 +354,13 @@ export function createRuntime(ctx) {
 
   return {
     agent, parallel, pipeline, phase, log, budget, args, directory, worktree,
-    _stats: () => ({ agentCount, spent, cap, phases: [...phases], trace: [...trace] }),
+    // Isolated agents that changed something, and the files two or more of them touched.
+    worktrees: () => worktrees.map((w) => ({ ...w, files: [...w.files] })),
+    overlaps: () => overlaps(worktrees),
+    _stats: () => ({
+      agentCount, spent, cap, phases: [...phases], trace: [...trace],
+      worktrees: worktrees.map((w) => ({ ...w, files: [...w.files] })), overlaps: overlaps(worktrees),
+    }),
   }
 }