strom-research 1.3.0 → 1.4.1

package/README.md

@@ -1,7 +1,7 @@
 # Strom Research
 
 Research your family's history with an AI agent. `strom` turns an AI agent —
-Claude Code, OpenAI Codex, Google Antigravity or OpenCode — into a careful
+Claude Code, OpenAI Codex, Google Antigravity, OpenCode or xAI's Grok — into a careful
 genealogical researcher: the agent searches parish registers and archives, you
 decide, and only what a record proves goes into your family tree. The result is
 a GEDCOM file for the [Strom app](https://stromapp.info) or any other program.

package/assets/lang/cs.json

@@ -171,7 +171,7 @@
   "ui.run.stop.time": "časový limit",
   "ui.run.stop.empty": "žádné otevřené úkoly",
   "ui.run.stop.problems": "doklady mají problém – strom check",
-  "ui.run.stop.denied": "agent nesměl spouštět strom – má špatně nastavená oprávnění (.claude/settings.json rodokmenu); nic dalšího se nespustilo",
+  "ui.run.stop.denied": "agent nesměl spouštět strom – nepustila ho jeho oprávnění nebo sandbox; nic dalšího se nespustilo",
   "ui.run.stop.limit": "limit předplatného{resets}",
   "ui.run.stop.resets": " (obnoví se {at})",
   "ui.run.stop.auth": "agent není přihlášený – spusťte jednou {command} a přihlaste se",
@@ -209,6 +209,7 @@
   "ui.doc.yes": "ano",
   "ui.doc.default": "výchozí",
   "ui.doc.noagent": "není nainstalovaný žádný AI agent",
+  "ui.doc.agent.other": "žádný, kterého strom zná – strom teď ovládá jiný agent nebo program a výzkum dělá přes strom",
   "ui.doc.knows.yes": "ano, v jakékoli složce",
   "ui.doc.knows.no": "zatím ne: {agents}",
   "ui.doc.app.yes": "používáte ji",

package/assets/lang/de.json

@@ -171,7 +171,7 @@
   "ui.run.stop.time": "Zeitlimit",
   "ui.run.stop.empty": "keine offenen Aufgaben",
   "ui.run.stop.problems": "die Belege haben Probleme – strom check",
-  "ui.run.stop.denied": "der Agent durfte strom nicht starten – seine Berechtigungen sind falsch (.claude/settings.json des Stammbaums); nichts weiter wurde gestartet",
+  "ui.run.stop.denied": "der Agent durfte strom nicht starten – seine Berechtigungen oder seine Sandbox ließen es nicht zu; nichts weiter wurde gestartet",
   "ui.run.stop.limit": "Limit des Abonnements{resets}",
   "ui.run.stop.resets": " (erneuert sich {at})",
   "ui.run.stop.auth": "der Agent ist nicht angemeldet – starten Sie einmal {command} und melden Sie sich an",
@@ -209,6 +209,7 @@
   "ui.doc.yes": "ja",
   "ui.doc.default": "Standard",
   "ui.doc.noagent": "kein KI-Agent installiert",
+  "ui.doc.agent.other": "keiner, den strom kennt – strom wird gerade von einem anderen Agenten oder Programm bedient, das die Forschung über strom macht",
   "ui.doc.knows.yes": "ja, in jedem Ordner",
   "ui.doc.knows.no": "noch nicht: {agents}",
   "ui.doc.app.yes": "Sie nutzen sie",

package/assets/method/reading.md

@@ -1,5 +1,12 @@
 # Method: reading scans
 
+**Old handwriting is read by your strongest model** — you, or a subagent or
+reader on that same model; never a faster, cheaper or "quick" pass. A misread
+name sends the research to the wrong village. **A name or place the next
+search depends on** (a surname, a birthplace, a parish) is read again on a
+crop at full resolution before it is recorded; what stays unsure is recorded
+as unsure and said so.
+
 An image you open stays in your context and is paid for again on every turn.
 Look at as few pixels as the question needs, and write down what you saw at once.
 
@@ -22,7 +29,7 @@ Look at as few pixels as the question needs, and write down what you saw at once
   It waits for its readers (often ten minutes or more): run it in the
   foreground and let it finish — your session ends with your turn, and
   whatever is left running in the background ends with it.
-  (Your own subagents can read too, in batches of at most twelve — but what they
+  (Your own subagents can read too — on your own model, never a faster one — in batches of at most twelve — but what they
   report is lost with your session unless you write it down: record each
   report as it comes back, before you send the next readers.) Only the entries
   that will be cited need your own eyes, at full resolution.

package/assets/plugins/gates/README.md

@@ -61,7 +61,7 @@ Environment variables, besides the user's own:
 | `STROM_GATE` | the gate's name |
 | `STROM_TREE` | the family tree's folder |
 | `STROM_LANG` | the research language (cs, de, en…) |
-| `STROM_AGENT` | the agent: claude, codex, antigravity, opencode |
+| `STROM_AGENT` | the agent: claude, codex, antigravity, opencode, grok |
 | `STROM_MODEL` | the main model, when one is set |
 | `STROM_SESSIONS` | sessions this run has had |
 | `STROM_COST_USD` | what this run has cost so far (as the agent reported it) |

package/dist/agents/files.js

@@ -1,9 +1,10 @@
 // Instruction and permission files for the agents that work in a tree.
-// AGENTS.md is the single source every agent reads (Codex, Antigravity and
-// OpenCode natively; CLAUDE.md imports it) and holds nothing agent-specific;
-// each agent's own file adds what only that agent needs. .claude/settings.json
-// (and OpenCode's opencode.json) allow `strom` and deny direct access to the
-// evidence — the first line of defence; the seal is the one that always holds.
+// AGENTS.md is the single source every agent reads (Codex, Antigravity,
+// OpenCode and Grok natively; CLAUDE.md imports it) and holds nothing
+// agent-specific; each agent's own file adds what only that agent needs.
+// .claude/settings.json (and OpenCode's opencode.json, Grok's .grok/config.toml)
+// allow `strom` and deny direct access to the evidence — the first line of
+// defence; the seal is the one that always holds.
 import fs from "node:fs";
 import path from "node:path";
 import { langName } from "../core/lang.js";
@@ -25,7 +26,10 @@ the researcher; \`strom\` is your only way to read and change the research.
 1. Start with \`strom\` — it says where things stand and what to do next.
    \`strom guide\` explains the work; \`strom help <command>\` any command.
 2. Work in sessions: \`strom session start\` gives you the brief for the next
-   task; finish with \`strom session close --summary "…" --next "…"\`.
+   task; finish with \`strom session close --summary "…" --next "…"\`. The
+   next step is strom's queue (\`strom\` names it, \`strom plan\` lists it):
+   what the user wants instead becomes a task first — never search outside a
+   session and its task.
 3. Never create, edit or delete anything in \`data/\`, \`strom.json\` or \`.git\`,
    never read the files in \`data/\` (strom shows them better and shorter), and
    never run git yourself. strom detects changes and then refuses to write.
@@ -42,7 +46,7 @@ the researcher; \`strom\` is your only way to read and change the research.
    already short, listings take \`--limit\` and \`--page\`, and piped commands may
    be refused by your permissions.
 8. Other agents may work on this tree too (Claude Code, Codex, Antigravity,
-   OpenCode — the user's choice). \`strom\` shows who is working now; never take a task
+   OpenCode, Grok — the user's choice). \`strom\` shows who is working now; never take a task
    another one has started.
 
 ## Working with the user
@@ -130,76 +134,100 @@ export function permissionPath(abs) {
     return win ? `//${win[1].toLowerCase()}/${win[2]}` : `/${p}`;
 }
 /**
- * Permissions for Claude Code in this tree (paths of this computer). File rules are
- * Edit(…) only: Claude Code checks every file-editing tool against them (Write(…)
- * rules match nothing and are reported as a mistake).
+ * The tree's rules for Claude Code or Grok Build. Grok reads Claude Code's rules too, but an absolute
+ * path in Claude Code's words ("//Users/x") is plain text to it: its own file gets the path as it is.
+ * File rules are Edit(…) only: Claude Code checks every file-editing tool against them (Write(…) rules
+ * match nothing and are reported as a mistake); Grok's Edit covers Write as well.
  */
-export function claudeSettings(tree) {
+function treeRules(tree, agent) {
     const settings = new Settings(tree.env, {});
     const shared = settings.shared()?.value;
-    const keys = permissionPath(configDir(tree.env));
-    // Connectors of this tree whose images come through the user's browser: browser tools, for their sites only.
-    const browser = treeBrowserConnectors(tree, shared);
-    const sites = [...new Set(browser.flatMap((c) => c.manifest.hosts.map(chromeDomain)))];
-    const downloads = permissionPath(settings.downloads());
-    const lead = settings.models("claude", tree.config).lead;
-    // A rule for each of Claude Code's shells: Bash, and PowerShell (on Windows) — a Bash rule does not cover it.
-    const shell = (cmd) => [`Bash(${cmd})`, `PowerShell(${cmd})`];
+    const claude = agent === "claude";
+    const at = (abs) => (claude ? permissionPath(abs) : abs.replace(/\\/g, "/"));
+    const keys = at(configDir(tree.env));
+    // Connectors of this tree whose images come through the user's browser: browser tools (Claude in Chrome), for their sites only.
+    const sites = claude ? [...new Set(treeBrowserConnectors(tree, shared).flatMap((c) => c.manifest.hosts.map(chromeDomain)))] : [];
+    const downloads = at(settings.downloads());
+    // A rule for each of Claude Code's shells: Bash, and PowerShell (on Windows) — a Bash rule does not cover it. Grok has one.
+    const shell = (cmd) => (claude ? [`Bash(${cmd})`, `PowerShell(${cmd})`] : [`Bash(${cmd})`]);
     return {
-        permissions: {
-            allow: [
-                ...shell("strom:*"),
-                "Read(inputs/**)",
-                "Read(output/**)",
-                "Read(notes/**)",
-                "Read(.strom/views/**)",
-                // Files the user drops for the research; scans are seen through views only (strom media view).
-                ...(shared ? [`Read(${permissionPath(path.join(shared, "inbox"))}/**)`] : []),
-                "Edit(notes/**)",
-                // A connector it builds for an archive the research needs (strom connector new); strom runs it.
-                ...(shared ? ["Read", "Edit"].map((t) => `${t}(${permissionPath(path.join(shared, "plugins", "connectors"))}/**)`) : []),
-                "WebSearch",
-                "WebFetch",
-                ...(sites.length ? [...CHROME_ALLOW, ...sites] : []),
-            ],
-            deny: [
-                "Read(data/**)",
-                // The media store: images are looked at through views, so strom knows what was seen.
-                ...(shared ? [`Read(${permissionPath(path.join(shared, "media"))}/**)`] : []),
-                "Edit(data/**)",
-                "Edit(strom.json)",
-                "Edit(.git/**)",
-                ...shell("git:*"),
-                // A password is typed by the user in their own terminal, and so is installing a plugin; the seal is strom's.
-                // (Consents the agent may ask for — strom allow …: strom asks the person in a window.)
-                ...shell("strom login:*"),
-                ...shell("strom connector add:*"),
-                ...shell("strom connector remove:*"),
-                ...shell("strom seal:*"),
-                // The limiter's memory (pace, refusals).
-                ...(shared ? [`Edit(${permissionPath(path.join(shared, "net"))}/**)`] : []),
-                // A session ends with its turn: nothing wakes it up later (a live run waited for a wake-up that never came).
-                "ScheduleWakeup",
-                "CronCreate",
-                // The seal keys: an agent that could read them could forge the seal.
-                `Read(${keys}/**)`,
-                `Edit(${keys}/**)`,
-                // What the browser downloads is strom's to take over; the rest of the folder is the user's.
-                `Read(${downloads}/**)`,
-                ...CHROME_DENY,
-                // With full permissions only the deny rules count: what the allow list kept away is kept away here.
-                ...(settings.agentPermissions() === "full" ? BYPASS_DENY : []),
-            ],
-        },
+        allow: [
+            ...shell("strom:*"),
+            "Read(inputs/**)",
+            "Read(output/**)",
+            "Read(notes/**)",
+            "Read(.strom/views/**)",
+            // Files the user drops for the research; scans are seen through views only (strom media view).
+            ...(shared ? [`Read(${at(path.join(shared, "inbox"))}/**)`] : []),
+            "Edit(notes/**)",
+            // A connector it builds for an archive the research needs (strom connector new); strom runs it.
+            ...(shared ? ["Read", "Edit"].map((t) => `${t}(${at(path.join(shared, "plugins", "connectors"))}/**)`) : []),
+            "WebSearch",
+            "WebFetch",
+            ...(sites.length ? [...CHROME_ALLOW, ...sites] : []),
+        ],
+        deny: [
+            "Read(data/**)",
+            // The media store: images are looked at through views, so strom knows what was seen.
+            ...(shared ? [`Read(${at(path.join(shared, "media"))}/**)`] : []),
+            "Edit(data/**)",
+            "Edit(strom.json)",
+            "Edit(.git/**)",
+            ...shell("git:*"),
+            // A password is typed by the user in their own terminal, and so is installing a plugin; the seal is strom's.
+            // (Consents the agent may ask for — strom allow …: strom asks the person in a window.)
+            ...shell("strom login:*"),
+            ...shell("strom connector add:*"),
+            ...shell("strom connector remove:*"),
+            ...shell("strom seal:*"),
+            // The limiter's memory (pace, refusals).
+            ...(shared ? [`Edit(${at(path.join(shared, "net"))}/**)`] : []),
+            // A session ends with its turn: nothing wakes it up later (a live run waited for a wake-up that never came).
+            ...(claude ? ["ScheduleWakeup", "CronCreate"] : []),
+            // The seal keys: an agent that could read them could forge the seal.
+            `Read(${keys}/**)`,
+            `Edit(${keys}/**)`,
+            // What the browser downloads is strom's to take over; the rest of the folder is the user's.
+            `Read(${downloads}/**)`,
+            ...(claude ? CHROME_DENY : []),
+            // With full permissions only the deny rules count: what the allow list kept away is kept away here.
+            ...(settings.agentPermissions() === "full" ? BYPASS_DENY : []),
+        ],
+    };
+}
+/** Permissions for Claude Code in this tree (paths of this computer). */
+export function claudeSettings(tree) {
+    const lead = new Settings(tree.env, {}).models("claude", tree.config).lead;
+    return {
+        permissions: treeRules(tree, "claude"),
         // The user's model: the desktop app cannot be given one when it opens (the CLI is, with --model).
         ...(lead ? { model: lead } : {}),
     };
 }
+/**
+ * Grok Build's rules for this tree (.grok/config.toml, read once the folder is trusted — strom starts it
+ * so). It reads .claude/settings.json as well; this file says the same with paths it understands.
+ */
+export function grokConfig(tree) {
+    const { allow, deny } = treeRules(tree, "grok");
+    // A TOML basic string is written like a JSON one.
+    const list = (xs) => `[\n${xs.map((x) => `  ${JSON.stringify(x)},`).join("\n")}\n]`;
+    return `# strom: generated (strom agents sync) — Grok Build's rules for this family tree; changed by strom only\n[permission]\nallow = ${list(allow)}\ndeny = ${list(deny)}\n`;
+}
+/** Grok Build reads CLAUDE.md too (for Claude Code's projects): what in it is not for Grok. */
+const GROK_RULES = `# Grok Build in this family tree
+
+CLAUDE.md in this folder is written for Claude Code: its way of delegating (the
+Agent tool, the models opus, sonnet and haiku) is not yours. Follow AGENTS.md,
+and read scans yourself as it says under "Reading scans".
+`;
 /** Denied as well when the user lets the agent do everything else (agent.permissions full). */
 export const BYPASS_DENY = [
     // its own permissions and instructions
     "Edit(.claude/**)",
     ...["AGENTS.md", "CLAUDE.md"].map((f) => `Edit(${f})`),
+    // (Grok Build's own rules and instructions)
+    "Edit(.grok/**)",
     // downloads round strom's limiter
     "Bash(curl:*)",
     "Bash(wget:*)",
@@ -218,47 +246,63 @@ export function opencodeConfig(tree) {
     const abs = (p) => p.replace(/\\/g, "/");
     const full = settings.agentPermissions() === "full";
     const users = ["strom login *", "strom seal *", "strom connector add *", "strom connector remove *"];
+    // The user's model ("provider/model"): its conversation takes no --model, it reads it here.
+    const lead = settings.models("opencode", tree.config).lead;
+    const permission = {
+        bash: {
+            "*": "ask",
+            "strom *": "allow",
+            ...Object.fromEntries(users.map((c) => [c, "deny"])),
+            "git *": "deny",
+            ...(full ? { "curl *": "deny", "wget *": "deny" } : {}),
+        },
+        read: { "*": "allow", "data/*": "deny", ".git/*": "deny" },
+        edit: {
+            "*": "ask",
+            "notes/*": "allow",
+            "data/*": "deny",
+            ".git/*": "deny",
+            "strom.json": "deny",
+            // its own rules and instructions
+            "opencode.json": "deny",
+            ...Object.fromEntries(["AGENTS.md", "CLAUDE.md", ".claude/*"].map((f) => [f, "deny"])),
+        },
+        external_directory: {
+            "*": "ask",
+            ...(shared
+                ? {
+                    [`${abs(path.join(shared, "inbox"))}/*`]: "allow",
+                    [`${abs(path.join(shared, "plugins", "connectors"))}/*`]: "allow",
+                    // images are looked at through views, so strom knows what was seen; the limiter's memory is strom's
+                    [`${abs(path.join(shared, "media"))}/*`]: "deny",
+                    [`${abs(path.join(shared, "net"))}/*`]: "deny",
+                }
+                : {}),
+            // the seal keys, and what the browser downloads (strom's to take over)
+            [`${abs(configDir(tree.env))}/*`]: "deny",
+            [`${abs(settings.downloads())}/*`]: "deny",
+        },
+        webfetch: "allow",
+        websearch: "allow",
+    };
+    // What would ask is refused when nobody watches: OpenCode 2 ends a whole headless run at the first question
+    // it cannot ask (found live), where a refusal only fails that call.
+    const refused = (v) => v === "ask" ? "deny" : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, refused(x)])) : v;
     return {
         $schema: "https://opencode.ai/config.json",
-        permission: {
-            bash: {
-                "*": "ask",
-                "strom *": "allow",
-                ...Object.fromEntries(users.map((c) => [c, "deny"])),
-                "git *": "deny",
-                ...(full ? { "curl *": "deny", "wget *": "deny" } : {}),
-            },
-            read: { "*": "allow", "data/*": "deny", ".git/*": "deny" },
-            edit: {
-                "*": "ask",
-                "notes/*": "allow",
-                "data/*": "deny",
-                ".git/*": "deny",
-                "strom.json": "deny",
-                // its own rules and instructions
-                "opencode.json": "deny",
-                ...Object.fromEntries(["AGENTS.md", "CLAUDE.md", ".claude/*"].map((f) => [f, "deny"])),
-            },
-            external_directory: {
-                "*": "ask",
-                ...(shared
-                    ? {
-                        [`${abs(path.join(shared, "inbox"))}/*`]: "allow",
-                        [`${abs(path.join(shared, "plugins", "connectors"))}/*`]: "allow",
-                        // images are looked at through views, so strom knows what was seen; the limiter's memory is strom's
-                        [`${abs(path.join(shared, "media"))}/*`]: "deny",
-                        [`${abs(path.join(shared, "net"))}/*`]: "deny",
-                    }
-                    : {}),
-                // the seal keys, and what the browser downloads (strom's to take over)
-                [`${abs(configDir(tree.env))}/*`]: "deny",
-                [`${abs(settings.downloads())}/*`]: "deny",
+        ...(lead ? { model: lead } : {}),
+        permission,
+        agent: {
+            [OPENCODE_RUN_AGENT]: {
+                mode: "primary",
+                description: "strom run: the agent working alone, nobody to ask — what the rules do not allow is refused",
+                permission: refused(permission),
             },
-            webfetch: "allow",
-            websearch: "allow",
         },
     };
 }
+/** OpenCode's agent for a run nobody watches under ask and auto (opencode run --agent). */
+export const OPENCODE_RUN_AGENT = "strom-run";
 /** Files strom wrote for Gemini CLI (gone: Google ended it for personal accounts) — taken away when they are strom's. */
 const OBSOLETE = [
     ["GEMINI.md", (t) => t.startsWith("@./AGENTS.md") && t.includes(MARKER) && t.slice(t.indexOf(MARKER) + MARKER.length).trim() === ""],
@@ -277,7 +321,7 @@ function withUserPart(file, generated) {
     }
     return generated;
 }
-export const AGENT_FILES = ["AGENTS.md", "CLAUDE.md", path.join(".claude", "settings.json"), "opencode.json"];
+export const AGENT_FILES = ["AGENTS.md", "CLAUDE.md", path.join(".claude", "settings.json"), "opencode.json", path.join(".grok", "config.toml"), path.join(".grok", "rules", "strom.md")];
 export function syncAgentFiles(tree) {
     const written = [];
     const write = (rel, content) => {
@@ -300,6 +344,8 @@ export function syncAgentFiles(tree) {
     write("CLAUDE.md", claudeMd(tree));
     write(path.join(".claude", "settings.json"), JSON.stringify(claudeSettings(tree), null, 2) + "\n");
     write("opencode.json", JSON.stringify(opencodeConfig(tree), null, 2) + "\n");
+    write(path.join(".grok", "config.toml"), grokConfig(tree));
+    write(path.join(".grok", "rules", "strom.md"), GROK_RULES);
     for (const [rel, ours] of OBSOLETE) {
         const file = path.join(tree.root, rel);
         let text;

package/dist/agents/global.js

@@ -8,7 +8,9 @@
 // is the user's — a password, a consent — strom itself keeps for the user).
 // OpenCode gets a file of its own named in its global config (a global
 // AGENTS.md of strom's would hide the user's ~/.claude/CLAUDE.md, which
-// OpenCode reads when it has none) and `strom *` allowed there.
+// OpenCode reads when it has none) and `strom *` allowed there. Grok Build
+// gets a skill of its own, like Claude Code, and strom allowed in its
+// config.toml (a marked block; the user's own text around it is kept).
 import fs from "node:fs";
 import path from "node:path";
 import { userHome } from "../core/paths.js";
@@ -24,8 +26,12 @@ registers, archives, evidence, a family tree the Strom app can import.
 Use it whenever the user wants to research their ancestors or family, or
 mentions strom, a family tree or the Strom app.
 
-1. Run \`strom\` first. It says where the research stands and what to do next
-   (\`strom --json\` for the same as data; \`strom guide\` explains the work).
+1. Run \`strom\` first, and before each step: it says where the research
+   stands and what to do next (\`strom --json\` for the same as data). Read
+   \`strom guide\` before the first step — the rules and the way to work —
+   and work only in strom's sessions on its tasks.
+   Run each strom command on its own — no pipes, no \`;\` or \`&&\` chains: you
+   may run strom without asking, but not what is chained to it.
 2. Not set up yet: ask the user where to keep the research (suggest
    ~/Documents/Strom) and which language they want, then run
    \`strom setup --home "<folder>" --lang <code> --yes\`, then
@@ -43,10 +49,13 @@ mentions strom, a family tree or the Strom app.
 6. When strom needs the user's consent it opens a window on their screen —
    tell them to answer it; you cannot. Exit code 4 means the user must run
    the given command themselves.
-7. Scans come through strom. An archive the research needs has no
+7. Old handwriting is read by your strongest model — never a faster or
+   cheaper model, subagent or pass; a name or place the next search depends
+   on is read again on an enlarged crop before it is recorded.
+8. Scans come through strom. An archive the research needs has no
    downloader (connector) yet: build one yourself, unasked
    (\`strom connector new\`), and tell the user in a sentence.
-8. The Strom app (https://stromapp.info) is strom's companion: a free family
+9. The Strom app (https://stromapp.info) is strom's companion: a free family
    tree app, no account, the data stay on the user's computer. The research's
    result (\`output/tree-strom.ged\`) opens in it. When the user wants to see
    the tree (or \`strom\` says to offer it — once), suggest it gently — best installed as an app from the browser,
@@ -66,7 +75,46 @@ function allowRules(agent) {
     if (agent === "antigravity")
         return ["command(strom)"];
     const commands = ["strom", ...(installation().launchers ?? [])];
-    return commands.flatMap((c) => [`Bash(${c}:*)`, `PowerShell(${c}:*)`]);
+    // Grok Build: one shell tool (its rules know no PowerShell)
+    return commands.flatMap((c) => (agent === "grok" ? [`Bash(${c}:*)`] : [`Bash(${c}:*)`, `PowerShell(${c}:*)`]));
+}
+/**
+ * Grok Build's config.toml, strom's lines marked: a [permission] table of strom's when there is none,
+ * else strom's allow list in the user's table — when it has no allow list of its own (strom does not
+ * rewrite the user's list: Grok then asks before it runs strom, as the user set it).
+ */
+const TOML_BEGIN = "# strom: begin (strom agents install; removed by strom agents uninstall)";
+const TOML_END = "# strom: end";
+function grokWithout(text) {
+    const lines = text.split("\n");
+    const out = [];
+    let inside = false;
+    for (const l of lines) {
+        if (l.trim() === TOML_BEGIN)
+            inside = true;
+        else if (l.trim() === TOML_END)
+            inside = false;
+        else if (!inside)
+            out.push(l);
+    }
+    return out.join("\n");
+}
+function grokWith(text) {
+    const rest = grokWithout(text);
+    const allow = `allow = [${allowRules("grok").map((r) => JSON.stringify(r)).join(", ")}]`;
+    const lines = rest.split("\n");
+    const header = lines.findIndex((l) => /^\s*\[permission\]\s*(#.*)?$/.test(l));
+    if (header < 0) {
+        const body = rest.replace(/\s+$/, "");
+        return `${body ? `${body}\n\n` : ""}${TOML_BEGIN}\n[permission]\n${allow}\n${TOML_END}\n`;
+    }
+    // the user's table: up to the next table
+    let end = lines.findIndex((l, i) => i > header && /^\s*\[/.test(l));
+    if (end < 0)
+        end = lines.length;
+    if (lines.slice(header + 1, end).some((l) => /^\s*allow\s*=/.test(l)))
+        return undefined;
+    return [...lines.slice(0, header + 1), TOML_BEGIN, allow, TOML_END, ...lines.slice(header + 1)].join("\n");
 }
 /** A rule of strom's in Claude Code's or Antigravity's settings, whichever installation wrote it. */
 function isStromRule(agent, rule) {
@@ -74,6 +122,10 @@ function isStromRule(agent, rule) {
         return rule === "command(strom)";
     return /^(?:Bash|PowerShell)\((?:.*[\\/])?strom(?:\.exe|\.cmd)?:\*\)$/.test(rule);
 }
+/** Grok Build's folder (GROK_HOME, else ~/.grok). */
+function grokDir(env) {
+    return env.GROK_HOME ?? path.join(userHome(env), ".grok");
+}
 /** OpenCode: the rule that lets it run strom without asking. */
 const OPENCODE_STROM = "strom *";
 /** OpenCode's global config folder (it follows XDG on every system). */
@@ -101,6 +153,8 @@ export function globalTargets(env) {
         { agent: "antigravity", file: path.join(home, ".gemini", "antigravity-cli", "settings.json"), kind: "allow" },
         { agent: "opencode", file: path.join(opencodeDir(env), "strom.md"), kind: "own" },
         { agent: "opencode", file: path.join(opencodeDir(env), "opencode.json"), kind: "allow" },
+        { agent: "grok", file: path.join(grokDir(env), "skills", "strom", "SKILL.md"), kind: "own" },
+        { agent: "grok", file: path.join(grokDir(env), "config.toml"), kind: "allow" },
     ];
 }
 const SKILL = `---
@@ -209,7 +263,13 @@ function removeAllow(t, s) {
 export function installGlobal(t) {
     const cur = read(t.file);
     let next;
-    if (t.kind === "allow") {
+    if (t.kind === "allow" && t.agent === "grok") {
+        const with_ = grokWith(cur ?? "");
+        if (with_ === undefined)
+            return false;
+        next = with_;
+    }
+    else if (t.kind === "allow") {
         const s = settingsOf(cur);
         if (!s || hasAllow(t, s))
             return false;
@@ -217,7 +277,7 @@ export function installGlobal(t) {
         next = JSON.stringify(s, null, 2) + "\n";
     }
     else if (t.kind === "own")
-        next = t.agent === "claude" ? SKILL : GLOBAL_TEXT;
+        next = t.agent === "claude" || t.agent === "grok" ? SKILL : GLOBAL_TEXT;
     else {
         const rest = cur ? withoutBlock(cur).replace(/\s+$/, "") : "";
         next = `${rest ? `${rest}\n\n` : ""}${BEGIN}\n${GLOBAL_TEXT}${END}\n`;
@@ -233,6 +293,16 @@ export function uninstallGlobal(t) {
     const cur = read(t.file);
     if (cur === undefined)
         return false;
+    if (t.kind === "allow" && t.agent === "grok") {
+        if (!cur.includes(TOML_BEGIN))
+            return false;
+        const rest = grokWithout(cur);
+        if (rest.trim())
+            writeFileAtomic(t.file, rest.replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n"));
+        else
+            fs.rmSync(t.file);
+        return true;
+    }
     if (t.kind === "allow") {
         const s = settingsOf(cur);
         // Any of strom's rules, also those another installation of strom wrote.
@@ -244,8 +314,8 @@ export function uninstallGlobal(t) {
         return true;
     }
     if (t.kind === "own") {
-        // The skill is a folder of its own; OpenCode's instructions one file among the user's.
-        if (t.agent === "claude")
+        // A skill is a folder of its own; OpenCode's instructions one file among the user's.
+        if (t.agent === "claude" || t.agent === "grok")
             fs.rmSync(path.dirname(t.file), { recursive: true, force: true });
         else
             fs.rmSync(t.file, { force: true });
@@ -272,6 +342,8 @@ export function isInstalled(t) {
     const cur = read(t.file);
     if (cur === undefined)
         return false;
+    if (t.kind === "allow" && t.agent === "grok")
+        return cur.includes(TOML_BEGIN) && grokWith(cur) === cur;
     if (t.kind === "allow")
         return hasAllow(t, settingsOf(cur) ?? {});
     return t.kind === "own" || cur.includes(BEGIN);

package/dist/agents/launch.js

@@ -11,11 +11,15 @@
 // --dangerously-skip-permissions; `strom` is allowed in its settings (strom agents install).
 // OpenCode: ask and auto — the tree's rules (opencode.json), anything else it
 // asks (it has no review of its own); full — --auto, everything the rules do not deny.
+// Grok Build: always --trust (the tree folder: else it reads neither AGENTS.md nor
+// the tree's rules); ask — its own mode; auto — --permission-mode auto (its own
+// review); full — --always-approve (only the deny rules count).
 //
 // Claude Code always gets the tree's allow and deny lists (--settings); Codex
-// works in its sandbox on the tree folder with the shared folder added and the
-// network on (strom fetches).
+// works in its sandbox on the tree folder with its .git (strom commits) and the
+// shared folder writable and the network on (strom fetches).
 import { claudeArgs } from "../runners/claude.js";
+import { codexWritable } from "../runners/codex.js";
 /** The command line of a conversation with this agent. */
 export function conversationArgs(agent, o) {
     if (agent === "claude")
@@ -23,14 +27,17 @@ export function conversationArgs(agent, o) {
     if (agent === "codex") {
         const args = o.level === "full"
             ? ["--dangerously-bypass-approvals-and-sandbox"]
-            : [...(o.level === "auto" ? ["--approve-for-me"] : ["--sandbox", "workspace-write", "--ask-for-approval", "on-request"]), "-c", "sandbox_workspace_write.network_access=true", ...(o.shared ? ["--add-dir", o.shared] : [])];
+            : [...(o.level === "auto" ? ["--approve-for-me"] : ["--sandbox", "workspace-write", "--ask-for-approval", "on-request"]), "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(o.root, o.shared)];
         return [...args, "--search", ...(o.model ? ["--model", o.model] : []), o.kickoff];
     }
     if (agent === "antigravity") {
         const mode = o.level === "full" ? ["--dangerously-skip-permissions"] : o.level === "auto" ? ["--mode", "accept-edits"] : [];
         return [...mode, ...(o.shared ? ["--add-dir", o.shared] : []), ...(o.model ? ["--model", o.model] : []), "--prompt-interactive", o.kickoff];
     }
+    // (its TUI takes no --model: the model is in the tree's opencode.json)
     if (agent === "opencode")
-        return [...(o.level === "full" ? ["--auto"] : []), ...(o.model ? ["--model", o.model] : []), "--prompt", o.kickoff];
+        return [...(o.level === "full" ? ["--auto"] : []), "--prompt", o.kickoff];
+    if (agent === "grok")
+        return ["--trust", ...(o.level === "full" ? ["--always-approve"] : o.level === "auto" ? ["--permission-mode", "auto"] : []), ...(o.model ? ["--model", o.model] : []), o.kickoff];
     throw new Error(`no conversation launcher for agent "${agent}"`);
 }

package/dist/agents/profiles.js

@@ -20,13 +20,17 @@ const DELEGATION_RULES = `- Browsing a book, an index or a range of images ("is
 - Delegates never write to the research. You record their findings through
   strom; a negative result of a delegate is recorded as a search "by reader".
 - Only entries that will get a citation need your own eyes.`;
-/** For agents that cannot pick a model for a subagent (Codex, Antigravity, OpenCode): read yourself, in small batches. */
-export const SELF_READING = `## Reading scans (Codex, Antigravity, OpenCode)
+/** For agents that cannot pick a model for a subagent (Codex, Antigravity, OpenCode, Grok): read yourself, in small batches. */
+export const SELF_READING = `## Reading scans (Codex, Antigravity, OpenCode, Grok)
 
-Read the images yourself, in batches of at most ten: open a batch, write down
-what it gave (strom search add … for what was not found, facts for what was),
-then open the next. Images stay in your context and are paid for on every turn,
-so never keep more than one batch open.
+Read the images yourself, with your strongest model — never hand old
+handwriting to a faster or cheaper model, subagent or pass. Read them
+in batches of at most ten: open a batch, write down what it gave (strom
+search add … for what was not found, facts for what was), then open the
+next. Images stay in your context and are paid for on every turn, so never
+keep more than one batch open. A name or place the next search depends on:
+read it again on a crop at full resolution (\`strom media view … --crop\`)
+before you record it.
 `;
 export const PROFILES = {
     claude: {
@@ -85,6 +89,17 @@ ${DELEGATION_RULES}
         models: {},
         instructions: () => SELF_READING,
     },
+    // xAI's Grok Build: its subagents take only its own models (no cheaper reader worth the images): it reads itself.
+    grok: {
+        id: "grok",
+        name: "Grok Build",
+        command: "grok",
+        exit: "/quit",
+        url: "https://x.ai/cli",
+        delegation: "strom",
+        models: {},
+        instructions: () => SELF_READING,
+    },
 };
 export const DEFAULT_AGENT = "claude";
 export function profile(id) {

package/dist/cli/registry.js

@@ -22,7 +22,7 @@ export const GLOBAL_OPTIONS = [
     { name: "home", type: "string", value: "<dir>", description: "Strom home folder (default from config)" },
     { name: "shared", type: "string", value: "<dir>", description: "shared data folder (media, catalog, tools)" },
     { name: "trees", type: "string", value: "<dir>", description: "folder holding the trees" },
-    { name: "agent", type: "string", value: "<agent>", description: "AI agent: claude, codex, antigravity, opencode (default from config)" },
+    { name: "agent", type: "string", value: "<agent>", description: "AI agent: claude, codex, antigravity, opencode, grok (default from config)" },
     { name: "yes", type: "boolean", description: "accept suggested defaults, never ask" },
     { name: "debug", type: "boolean", description: "show technical details on errors" },
     { name: "version", type: "boolean", description: "print the version of strom" },

package/dist/cli/ui.js

@@ -154,7 +154,7 @@ export const UI = {
     "ui.run.stop.time": "time limit",
     "ui.run.stop.empty": "no open tasks",
     "ui.run.stop.problems": "the evidence has problems — strom check",
-    "ui.run.stop.denied": "the agent was not allowed to run strom — its permissions are wrong (.claude/settings.json of the tree); nothing more was started",
+    "ui.run.stop.denied": "the agent was not allowed to run strom — its permissions or its sandbox kept it away; nothing more was started",
     "ui.run.stop.limit": "subscription limit{resets}",
     "ui.run.stop.resets": " (resets {at})",
     "ui.run.stop.auth": "the agent is not logged in — run {command} once and log in",
@@ -187,6 +187,7 @@ export const UI = {
     "ui.doc.yes": "yes",
     "ui.doc.default": "default",
     "ui.doc.noagent": "no AI agent installed",
+    "ui.doc.agent.other": "none strom knows is installed — strom is run by another agent or program now, which does the research through strom",
     "ui.doc.knows.yes": "yes, in any folder",
     "ui.doc.knows.no": "not yet: {agents}",
     "ui.doc.app.yes": "you use it",

package/dist/commands/guide.js

@@ -32,6 +32,12 @@ HARD RULES
    the research needs has none yet: build one first (strom connector new,
    its DISCOVERY.md) and tell the user in a sentence. The user saves images
    by hand only where the archive does not allow automation.
+8. Old handwriting is read by your strongest model — you, or a subagent on
+   that same model; never a faster, cheaper or "quick" pass. A name or place
+   the next search depends on is read again on a crop at full resolution
+   (strom media view … --crop) before it is recorded; unsure stays unsure.
+9. A find is told to the user only once it is recorded (the source with its
+   transcript, the facts citing it), and told from strom: strom person card.
 ${language}
 
 GETTING STARTED (once)
@@ -42,14 +48,20 @@ GETTING STARTED (once)
   strom intake --text "<what the user told you, in their words>"
   strom intake <file or folder>        documents, photos, a GEDCOM or Strom tree
 
-EVERY SESSION
-  strom session start                  the brief: task, what is known, method
-  … work; record every finding at once …
+THE WORK, STEP BY STEP (every agent — also one strom did not start: a
+conversation opened anywhere, a bot on its own server)
+  strom                                where things stand and the next step — run it before each step
+  strom session start                  the next task of the queue (or: strom session start T0003, the one
+                                       the user chose): its brief — the task, what is known, the method
+  … work on that task only; record every finding at once …
   strom task done T0001 --result "…"   a complete negative search is a result
-  strom session close --summary "…" --next "…"    (not finished: --continue)
-  in a conversation, the next task is best begun in a fresh context (Claude Code: /clear) —
-  suggest it to the user; many tasks waiting: the agent working on its own (strom run, the
-  user starts it from strom's menu), every task in a fresh session
+  strom session close --summary "…" --next "…"    (not finished: --continue) — it proposes the next tasks
+  then tell the user what was found (strom person card …) and what comes next (strom plan), and ask
+  before the next session. The next step is strom's queue: what the user wants instead becomes a
+  task first (strom task add …, or strom research new …) — never search outside a session and its task.
+  In a conversation the next task is best begun in a fresh context (Claude Code: /clear) — suggest
+  it to the user; many tasks waiting: the agent working on its own (strom run, the user starts it
+  from strom's menu), every task in a fresh session
 
 RECORDING
 A record (register entry, certificate) — the source first, then its facts:

package/dist/commands/meta.js

@@ -20,6 +20,7 @@ import { currentSession, openSessions } from "../core/session.js";
 import { readByOtherModels } from "../core/review.js";
 import { liveHolder } from "../core/lock.js";
 import { isAgent } from "../core/which.js";
+import { agentsHere } from "../core/apps.js";
 import { taskQueue, waitingForUser, waitingLines } from "./tasks.js";
 import { liveWorkers, runAlive } from "../core/workers.js";
 import { label } from "../core/people.js";
@@ -114,10 +115,13 @@ function orientation(ctx) {
     const open = currentSession(tree, ctx.env) ?? sessions.find((s) => !busy(s) && !(s.worker && s.worker !== ctx.env.STROM_WORKER && !human));
     const queued = taskQueue(tree).length;
     // An agent outside the tree that strom did not start (it set strom up from the web page, or was
-    // opened in some folder): the research goes on in its own conversation, where the tree lives.
+    // opened in some folder): the research goes on in its own conversation, where the tree lives — when
+    // strom can start one here (the research's agent is on this computer; not so for a bot on its own
+    // server, e.g. Grok Bot: it goes on where it is).
     const rel = path.relative(tree.root, ctx.cwd);
     const inTree = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-    const elsewhere = isAgent(ctx.env) && !ctx.env.STROM_WORKER && !ctx.env.STROM_SESSION && !inTree;
+    const chosen = ctx.settings.agent(tree.config).value;
+    const elsewhere = isAgent(ctx.env) && !ctx.env.STROM_WORKER && !ctx.env.STROM_SESSION && !inTree && agentsHere(ctx.env).some((a) => a.id === chosen);
     if (base.tree.errors > 0)
         base.next = { why: t("ui.why.check"), command: "strom check" };
     else if (elsewhere)

package/dist/commands/session.js

@@ -25,7 +25,7 @@ import { syncAgentFiles } from "../agents/files.js";
 import { setTreeSetting } from "./setup.js";
 import { RUNNERS } from "../runners/index.js";
 import { PROFILES } from "../agents/profiles.js";
-import { AGENTS, detectAgent, isAgent, which } from "../core/which.js";
+import { AGENTS, detectAgent, isAgent, which, withoutAgentMarks } from "../core/which.js";
 import { askGate, ensureGatesDir, loadGate } from "../core/gate.js";
 import { keepAwake } from "../core/awake.js";
 import { deadlineOf, WRAP_UP_MS } from "../core/clock.js";
@@ -385,7 +385,7 @@ register({
         "the tree's permissions (anything else is denied), or with the terminal (--interactive). Stops at the\n" +
         "subscription limit, when the queue is empty, or at --until (a session already running finishes, within\n" +
         "--minutes). The agent knows when its session is stopped (the brief; strom's output counts down its last\n" +
-        "10 minutes, a short session its last quarter); at --minutes it is stopped, and Claude Code, Codex and OpenCode\n" +
+        "10 minutes, a short session its last quarter); at --minutes it is stopped, and Claude Code, Codex, OpenCode and Grok\n" +
         "get 5 minutes more to write down what they found and close (an unfinished task goes back to the queue); a task\n" +
         "that comes back twice in a row with nothing recorded is parked. --task picks the tasks (one session each, in that order;\n" +
         "one done or held by another agent meanwhile is left out). --loop: session after session for as long as there\n" +
@@ -578,7 +578,7 @@ register({
                     brief.text;
                 const kickoff = `You are the researcher in strom session ${session.id}. Run \`strom brief\` and follow it; work only through strom; finish with \`strom session close\`.`;
                 const env = {
-                    ...prependPath(runEnv, bin),
+                    ...prependPath(withoutAgentMarks(runEnv), bin),
                     STROM_SESSION: session.id,
                     STROM_DEADLINE: new Date(deadline).toISOString(),
                     STROM_MINUTES: String(minutes),
@@ -603,7 +603,9 @@ register({
                     shared: ctx.settings.shared()?.value,
                     ...(models.lead ? { model: models.lead } : {}),
                     ...(opts.interactive ? { interactive: true } : {}),
-                    ...(runnerId === "claude" ? { chrome: browser.length > 0, permissions, remote: ctx.settings.agentRemote() } : {}),
+                    // the level for every agent (each maps it to its own switches); the browser and Remote Control are Claude Code's
+                    permissions,
+                    ...(runnerId === "claude" ? { chrome: browser.length > 0, remote: ctx.settings.agentRemote() } : {}),
                     ...(extra?.length ? { extraArgs: extra } : {}),
                     onProgress: (l) => out(`  · ${l}`),
                     signal: stop.signal,
@@ -760,7 +762,7 @@ function costText(m) {
     return m?.costUsd !== undefined ? `$${m.costUsd.toFixed(2)}` : "";
 }
 /** How the user clears the agent's context, in the agent's own words. */
-const CLEAR = { claude: "/clear", codex: "/new", opencode: "/new" };
+const CLEAR = { claude: "/clear", codex: "/new", opencode: "/new", grok: "/new" };
 /** The hint after a session in a conversation: the next task in a fresh context (images stay in a context and are paid on every turn). */
 function freshContext(ctx, tree, s) {
     const since = Date.parse(s.started);

package/dist/commands/setup.js

@@ -176,7 +176,11 @@ function diagnose(ctx) {
     const found = here.map((a) => a.id);
     const tree = ctx.hasTree() ? ctx.tree().config : undefined;
     const chosen = ctx.settings.agent(tree).value;
-    if (!found.length)
+    // None strom knows, and no person at a terminal: another agent or program runs strom (a bot on its own
+    // server, found live: Grok Bot) — it does the research through strom, nothing is missing for it.
+    if (!found.length && (isAgent(ctx.env) || !ctx.io.tty))
+        add("agent", "ok", t("ui.doc.agent.other"));
+    else if (!found.length)
         add("agent", "fail", t("ui.doc.noagent"), `${FIX}  (${researchUrl(lang, "agents")})`, "agent");
     else {
         const names = found.map((id) => `${PROFILES[id]?.name ?? id}${id === chosen ? ` (${t("ui.doc.default")})` : ""}`).join(", ");

package/dist/commands/start.js

@@ -13,7 +13,7 @@ import { PROFILES } from "../agents/profiles.js";
 import { conversationArgs } from "../agents/launch.js";
 import { globalTargets, installGlobal, isInstalled, uninstallGlobal } from "../agents/global.js";
 import { syncAgentFiles } from "../agents/files.js";
-import { AGENTS, findAgent, isAgent } from "../core/which.js";
+import { AGENTS, findAgent, isAgent, withoutAgentMarks } from "../core/which.js";
 import { DESKTOP_APPS, agentsHere, whereToTalk } from "../core/apps.js";
 import { assertIntact } from "../core/integrity.js";
 import { treeBrowserConnectors } from "../core/connector.js";
@@ -63,7 +63,7 @@ register({
         "(agent.permissions: ask, auto, full), your model, and asks you what matters. Where you talk (agent.where): the\n" +
         "agent's desktop app when it is installed (Claude, ChatGPT/Codex, OpenCode — the tree folder and the first message\n" +
         "filled in; you confirm the folder and send it), else its CLI in this terminal (Claude Code, Codex, Antigravity,\n" +
-        "OpenCode). The first message is yours to give (--say); without it the agent reports where things\n" +
+        "OpenCode, Grok). The first message is yours to give (--say); without it the agent reports where things\n" +
         "stand and suggests what next.",
     options: [
         { name: "say", type: "string", value: "<text>", description: "your first message to the agent" },
@@ -124,6 +124,7 @@ register({
             return { text: ui(lang, opened ? "ui.chat.handover" : "ui.chat.handover.failed", { agent: profile.name }), data: { agent, handover: opened ? "window" : "none", cwd: tree.root } };
         }
         const base = {
+            root: tree.root,
             kickoff,
             level,
             model: ctx.settings.models(agent, tree.config).lead,
@@ -154,7 +155,7 @@ register({
         // Claude Code asks once whether the folder is to be trusted — its own safety step, kept; the user knows what to answer.
         if (agent === "claude" && !claudeTrusts(tree.root, ctx.env))
             ctx.io.stdout(ui(lang, "ui.chat.trust") + "\n");
-        const env = { ...prependPath(ctx.env, shimDir(tree)), STROM_WORKER: worker, ...(base.model ? { STROM_MODEL: base.model } : {}) };
+        const env = { ...prependPath(withoutAgentMarks(ctx.env), shimDir(tree)), STROM_WORKER: worker, ...(base.model ? { STROM_MODEL: base.model } : {}) };
         delete env.STROM_HANDOVER;
         let code;
         try {

package/dist/core/config.js

@@ -24,7 +24,7 @@ export const SETTINGS = [
     { key: "shared", env: "STROM_SHARED", tree: false, kind: "path", description: "shared data: scans, catalog, tools (default <home>/shared)" },
     { key: "trees", env: "STROM_TREES", tree: false, kind: "path", description: "folder holding the trees (default <home>)" },
     { key: "lang", env: "STROM_LANG", tree: true, kind: "lang", description: "research language: the agent talks and writes in it" },
-    { key: "agent", env: "STROM_AGENT", tree: true, kind: "agent", description: "AI agent doing the research: claude, codex, antigravity, opencode" },
+    { key: "agent", env: "STROM_AGENT", tree: true, kind: "agent", description: "AI agent doing the research: claude, codex, antigravity, opencode, grok" },
     ...TIERS.map((t) => ({
         key: `model.${t}`,
         env: t === "lead" ? "STROM_MODEL" : `STROM_MODEL_${t.toUpperCase()}`,

package/dist/core/install.js

@@ -22,7 +22,8 @@ export function runInstaller(inst, env) {
  */
 export function agentBinDirs(env, platform = process.platform) {
     const home = userHome(env);
+    // Grok Build's installer: ~/.grok/bin (on PATH through the shell's profile; Windows: added by hand)
     if (platform === "win32")
-        return [path.join(home, ".local", "bin"), path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "npm")];
-    return [path.join(home, ".local", "bin"), path.join(home, ".claude", "local")];
+        return [path.join(home, ".local", "bin"), path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "npm"), path.join(home, ".grok", "bin")];
+    return [path.join(home, ".local", "bin"), path.join(home, ".claude", "local"), path.join(home, ".grok", "bin")];
 }

package/dist/core/shortcut.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { configDir, desktopDir, userHome } from "./paths.js";
 import { stromLauncher } from "./self.js";
+import { isAgentMark } from "./which.js";
 import { assetPath } from "./assets.js";
 /** Strom Research's icon, as each system takes it. */
 export const ICON = { png: assetPath("icon", "icon-512.png"), ico: assetPath("icon", "icon.ico") };
@@ -96,10 +97,6 @@ export function createShortcut(name, env, platform = process.platform) {
  */
 /** One handover window at a time: another asked within this long is not opened. */
 export const HANDOVER_GAP_MS = 15_000;
-/** What says an agent runs strom (core/which.ts detectAgent) — not the user's own settings of an agent (…_HOME). */
-function isAgentMark(k) {
-    return ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "AI_AGENT", "OPENCODE", "OPENCODE_PID"].includes(k) || (/^(CODEX|ANTIGRAVITY)_/.test(k) && !/_HOME$/.test(k));
-}
 export function openInNewTerminal(argv, cwd, env, platform = process.platform) {
     if (env.STROM_NO_OPEN === "1")
         return false;

package/dist/core/tree.js

@@ -23,7 +23,7 @@ import * as git from "./git.js";
 import { commitSeal, createKey, fingerprint, loadKey, sha256, signOp } from "./seal.js";
 import { stringifyCanonical } from "./json.js";
 export const TREE_FILE = "strom.json";
-export const VERSION = "1.3.0";
+export const VERSION = "1.4.1";
 const GITIGNORE = `# Strom Research — local state and large files are not versioned
 .strom/
 /media/

package/dist/core/which.js

@@ -26,9 +26,13 @@ export const AGENTS = [
     { id: "codex", command: "codex", name: "OpenAI Codex CLI" },
     { id: "antigravity", command: "agy", name: "Antigravity CLI" },
     { id: "opencode", command: "opencode", name: "OpenCode" },
+    { id: "grok", command: "grok", name: "Grok Build" },
 ];
 /** Which AI agent's shell tool runs strom? (they set these variables) */
 export function detectAgent(env) {
+    // Grok first: it passes on the environment it was started from (a Claude Code terminal's too).
+    if (env.GROK_AGENT === "1")
+        return "grok";
     if (env.CLAUDECODE)
         return "claude";
     if (Object.keys(env).some((k) => k.startsWith("ANTIGRAVITY_")))
@@ -37,10 +41,24 @@ export function detectAgent(env) {
         return "codex";
     if (env.OPENCODE === "1" || env.OPENCODE_PID)
         return "opencode";
+    // Cursor's agents — also xAI's Grok Bot, on Cursor's platform (found live): not one strom starts, but an agent
+    if (env.CURSOR_AGENT)
+        return "cursor";
     if (env.AI_AGENT)
         return env.AI_AGENT.toLowerCase();
     return undefined;
 }
+/** What says an agent runs strom (detectAgent) — not the user's own settings of an agent (…_HOME). */
+export function isAgentMark(k) {
+    return ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "AI_AGENT", "OPENCODE", "OPENCODE_PID", "GROK_AGENT", "GROK_SESSION_ID", "CURSOR_AGENT"].includes(k) || (/^(CODEX|ANTIGRAVITY)_/.test(k) && !/_HOME$/.test(k));
+}
+/**
+ * The environment for an agent strom starts: without the marks of the agent strom itself was run
+ * from (a terminal of Grok's passes them on), so strom in the new agent's shell knows which one it is.
+ */
+export function withoutAgentMarks(env) {
+    return Object.fromEntries(Object.entries(env).filter(([k]) => !isAgentMark(k)));
+}
 /** Is an agent running strom — its shell tool, or an agent strom run started? */
 export function isAgent(env) {
     return Boolean(detectAgent(env) || env.STROM_SESSION);

package/dist/runners/codex.js

@@ -1,15 +1,24 @@
 // OpenAI Codex CLI runner. Headless: `codex exec --json` in the tree folder
 // with the brief on stdin. The user's level decides the sandbox: ask and auto
-// work in Codex's sandbox on the tree folder (the shared folder added, the
-// network on — strom fetches), where what the sandbox refuses simply fails —
+// work in Codex's sandbox on the tree folder (its .git and the shared folder
+// writable too, the network on — strom fetches), where what the sandbox refuses simply fails —
 // nothing asks, as with Claude Code's dontAsk; full runs without the sandbox.
 // Interactive conversations are started by strom chat (agents/launch.ts).
+import path from "node:path";
 import { runJsonLines } from "./jsonl.js";
+/**
+ * What Codex's sandbox lets it write besides the tree folder: the tree's .git — its sandbox keeps a .git
+ * read-only even inside the folder it works in, and every change strom makes is a commit (found live:
+ * `strom session note` failed on .git/index.lock) — and the shared folder (inbox, plugins).
+ */
+export function codexWritable(root, shared) {
+    return ["-c", `sandbox_workspace_write.writable_roots=${JSON.stringify([path.join(root, ".git"), ...(shared ? [shared] : [])])}`];
+}
 /** Command-line arguments of a headless run (exported for tests). */
 export function codexArgs(opts) {
     const sandbox = opts.permissions === "full"
         ? ["--dangerously-bypass-approvals-and-sandbox"]
-        : ["--sandbox", "workspace-write", "-c", "sandbox_workspace_write.network_access=true", ...(opts.shared ? ["--add-dir", opts.shared] : [])];
+        : ["--sandbox", "workspace-write", "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
     return ["exec", "--json", "--skip-git-repo-check", ...sandbox, ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), "-"];
 }
 /**
@@ -19,7 +28,7 @@ export function codexArgs(opts) {
 export function codexResumeArgs(id, opts) {
     const sandbox = opts.permissions === "full"
         ? ["--dangerously-bypass-approvals-and-sandbox"]
-        : ["-c", 'sandbox_mode="workspace-write"', "-c", "sandbox_workspace_write.network_access=true", ...(opts.shared ? ["-c", `sandbox_workspace_write.writable_roots=[${JSON.stringify(opts.shared)}]`] : [])];
+        : ["-c", 'sandbox_mode="workspace-write"', "-c", "sandbox_workspace_write.network_access=true", ...codexWritable(opts.cwd, opts.shared)];
     return ["exec", "resume", "--json", "--skip-git-repo-check", ...sandbox, ...(opts.model ? ["--model", opts.model] : []), id, "-"];
 }
 export const codexRunner = {
@@ -39,7 +48,7 @@ export const codexRunner = {
             }
             // The sandbox refused a command (a write outside the tree, the network off): counted like a denial.
             if (msg.type === "item.completed" && item?.type === "command_execution" && item.exit_code !== 0 && /operation not permitted|sandbox|read-only file system/i.test(item.aggregated_output ?? ""))
-                heard.denied.push(`Bash: ${String(item.command ?? "").slice(0, 120)}`);
+                heard.denied.push(`Bash: ${String(item.command ?? "").replace(/^\S*sh -lc '(.*)'$/s, "$1").slice(0, 120)}`);
             if (msg.type === "turn.completed") {
                 const u = (msg.usage ?? {});
                 const m = heard.metrics;

package/dist/runners/grok.js

@@ -0,0 +1,108 @@
+// Grok Build runner (xAI's `grok`). Headless: `grok --trust --prompt-file <brief>
+// --output-format streaming-json` in the tree folder — it reads no stdin, so the
+// brief goes in a file beside the run's log. --trust: the tree folder's own files
+// (AGENTS.md, .grok/config.toml with the tree's rules) load only in a trusted
+// folder. The level: ask and auto — --permission-mode dontAsk (what the rules do
+// not allow is refused; Grok still lets harmless commands of its own judgement
+// through, so the deny rules are what holds); full — --always-approve (only the
+// deny rules count). strom names the session (-s <uuid>) and resumes it by that
+// id at the time limit (-r). Events are JSON lines: text, tool_call,
+// tool_call_update, end (usage, cost) and error.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { runJsonLines } from "./jsonl.js";
+/** Command-line arguments of a headless run (exported for tests). */
+export function grokArgs(opts, prompt, session) {
+    return [
+        "--trust",
+        ...prompt,
+        "--output-format",
+        "streaming-json",
+        ...(opts.permissions === "full" ? ["--always-approve"] : ["--permission-mode", "dontAsk"]),
+        ...session,
+        ...(opts.model ? ["--model", opts.model] : []),
+        "--no-auto-update",
+        ...(opts.extraArgs ?? []),
+    ];
+}
+/**
+ * The environment of a headless run: a command may take as long as the session and is never sent to the
+ * background when its time is up (a headless run ends with its turn, and what it left in the background with it).
+ */
+export function grokEnv(env, timeoutMs) {
+    const secs = Math.max(Math.round((timeoutMs ?? 0) / 1000), 30 * 60);
+    return { ...env, GROK_CONFIG: JSON.stringify({ toolset: { bash: { timeout_secs: secs, max_timeout_secs: secs, auto_background_on_timeout: false } } }) };
+}
+/** What a tool call was, in one line: its command, else the tool and its file. */
+function describe(e) {
+    const input = (e.rawInput ?? {});
+    if (typeof input.command === "string")
+        return `$ ${input.command.split("\n")[0].slice(0, 140)}`;
+    const file = input.target_file ?? input.file_path ?? input.path ?? input.target_directory;
+    return typeof file === "string" ? `${String(e.toolName ?? e.title ?? "tool")} ${file}` : String(e.toolName ?? e.title ?? "tool");
+}
+export const grokRunner = {
+    id: "grok",
+    command: "grok",
+    run(opts) {
+        const promptFile = opts.logFile.replace(/\.log$/, "") + ".prompt.md";
+        fs.mkdirSync(path.dirname(promptFile), { recursive: true });
+        fs.writeFileSync(promptFile, opts.prompt);
+        const id = randomUUID();
+        const env = grokEnv(opts.env, opts.timeoutMs);
+        // Its text comes in pieces; the last message (after the last tool call) is its answer.
+        let said = "";
+        const calls = new Map();
+        const resume = (sid, message) => ({ args: grokArgs(opts, ["-p", message], ["--resume", sid]), input: "" });
+        return runJsonLines("grok", grokArgs(opts, ["--prompt-file", promptFile], ["--session-id", id]), env, opts, resume, (msg, heard) => {
+            heard.sessionId ??= id;
+            const type = msg.type;
+            if (type === "text" && typeof msg.data === "string") {
+                said += msg.data;
+                heard.text = said.trim();
+            }
+            else if (type === "tool_call") {
+                if (said.trim())
+                    opts.onProgress?.(said.trim().split("\n")[0].slice(0, 160));
+                said = "";
+                const what = describe(msg);
+                if (typeof msg.toolCallId === "string")
+                    calls.set(msg.toolCallId, `${msg.toolName === "run_terminal_command" ? "Bash" : String(msg.toolName ?? "tool")}: ${what.replace(/^\$ /, "").slice(0, 120)}`);
+                opts.onProgress?.(what);
+            }
+            else if (type === "tool_call_update" && msg.status === "failed") {
+                // Refused by the rules ("Denied by permission policy") or by dontAsk ("User cancelled the execution").
+                const content = JSON.stringify(msg.content ?? "");
+                if (/denied by permission|permission policy|user cancelled|not allowed/i.test(content))
+                    heard.denied.push(calls.get(String(msg.toolCallId)) ?? "tool");
+            }
+            else if (type === "end") {
+                if (typeof msg.sessionId === "string")
+                    heard.sessionId = msg.sessionId;
+                const u = (msg.usage ?? {});
+                const m = heard.metrics;
+                // (a resumed session adds its own)
+                m.inputTokens = (m.inputTokens ?? 0) + (u.input_tokens ?? 0);
+                m.outputTokens = (m.outputTokens ?? 0) + (u.output_tokens ?? 0) + (u.reasoning_tokens ?? 0);
+                m.cacheReadTokens = (m.cacheReadTokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+                if (typeof msg.num_turns === "number")
+                    m.turns = (m.turns ?? 0) + msg.num_turns;
+                // A cost only when Grok knows it whole (a subscription often does not say it).
+                if (typeof msg.total_cost_usd === "number")
+                    m.costUsd = (m.costUsd ?? 0) + msg.total_cost_usd;
+                else if (msg.cost_is_partial === true || msg.usage_is_incomplete === true)
+                    m.costPartial = true;
+                const models = Object.keys((msg.modelUsage ?? {}));
+                if (models[0])
+                    m.model = models[0];
+                if (msg.stopReason === "refusal")
+                    heard.isError = true;
+            }
+            else if (type === "error") {
+                heard.isError = true;
+                heard.text = String(msg.message ?? "error");
+            }
+        });
+    },
+};

package/dist/runners/index.js

@@ -2,12 +2,14 @@ import { claudeRunner } from "./claude.js";
 import { codexRunner } from "./codex.js";
 import { antigravityRunner } from "./antigravity.js";
 import { opencodeRunner } from "./opencode.js";
+import { grokRunner } from "./grok.js";
 import { scriptRunner } from "./script.js";
 export const RUNNERS = {
     claude: claudeRunner,
     codex: codexRunner,
     antigravity: antigravityRunner,
     opencode: opencodeRunner,
+    grok: grokRunner,
     script: scriptRunner,
 };
 export const DEFAULT_RUNNER = "claude";

package/dist/runners/opencode.js

@@ -1,15 +1,18 @@
 // OpenCode runner. Headless: `opencode run --format json "<kickoff>"` in the tree
 // folder with the brief on stdin (it joins what is piped in with the message).
 // The tree's rules are its project config (opencode.json: strom allowed, the
-// evidence and git denied); what they would ask about is refused in a run
-// nobody watches — under ask and auto that is all; full adds --auto
+// evidence and git denied); under ask and auto a run nobody watches is its
+// agent "strom-run" there — the same rules, what would ask refused (OpenCode 2
+// ends a headless run at the first question it cannot ask); full adds --auto
 // (everything the rules do not deny). Events are JSON lines: text, tool_use,
 // step_start, step_finish (tokens and cost of a step), error; each names its
 // session (sessionID), which `--session` resumes.
 import { runJsonLines } from "./jsonl.js";
+import { OPENCODE_RUN_AGENT } from "../agents/files.js";
 /** Command-line arguments of a headless run (exported for tests). */
 export function opencodeArgs(opts) {
-    return ["run", "--format", "json", ...(opts.permissions === "full" ? ["--auto"] : []), ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), opts.kickoff];
+    const level = opts.permissions === "full" ? ["--auto"] : ["--agent", OPENCODE_RUN_AGENT];
+    return ["run", "--format", "json", ...level, ...(opts.model ? ["--model", opts.model] : []), ...(opts.extraArgs ?? []), opts.kickoff];
 }
 export const opencodeRunner = {
     id: "opencode",
@@ -28,8 +31,9 @@ export const opencodeRunner = {
                 const input = state.input ?? {};
                 const what = typeof input.command === "string" ? `$ ${input.command}` : typeof input.filePath === "string" ? `${String(part.tool)} ${input.filePath}` : String(part.tool ?? "tool");
                 opts.onProgress?.(what.split("\n")[0].slice(0, 140));
+                // (its shell tool: "bash", "shell" from OpenCode 2 — named "Bash" like Claude Code's, so a refused strom stops the run)
                 if (state.status === "error" && /reject|denied|not allowed|permission/i.test(state.error ?? ""))
-                    heard.denied.push(`${String(part.tool)}: ${what.slice(0, 120)}`);
+                    heard.denied.push(typeof input.command === "string" ? `Bash: ${input.command.slice(0, 120)}` : `${String(part.tool)}: ${what.slice(0, 120)}`);
             }
             if (msg.type === "text" && typeof part.text === "string" && part.text.trim())
                 heard.text = part.text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strom-research",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Genealogical research toolkit for AI coding agents",
   "type": "module",
   "bin": {