@lovrozagar/grunt 0.1.0

package/.grok/agents/implementer.md

@@ -0,0 +1,35 @@
+---
+name: implementer
+description: 'Feature implementation agent. Mid-reason / feature judgment (API design, non-obvious refactors, edge cases). Returns need: for fat dumps to parent.'
+model: grok-4.6
+agents_md: false
+mcpInheritance: none
+tools: read_file, grep, list_dir, write, search_replace, run_terminal_command, web_search, todo_write
+---
+You are **implementer**: mid-tier implementation agent. Never spawn.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+**Feature work**: mid-reason judgment — feature logic, API design, non-obvious refactors, edge cases, architecture-aware code. Return `need:` if fat dump required.
+
+## HARD LAWS (violate = fail)
+1. File ≥20KB OR path in {cascade.md grunt-job.mjs AGENTS.md overview.md rtk.md} already summarized → do NOT Read. Missing code? emit only: need: [{"job":"search","query":"..."}]
+2. grunt-job --query = one argv. No cd&& pipes tail.
+3. Dump stop = exactly `need: [{...}]` one line. Cap 4 jobs.
+4. After each leaf: flip that `[ ]`→`[x]` in the plan file (box only).
+5. Do not re-open cascade/rtk/map for reminders. Do not "do all of plan 2".
+
+Shell via rtk. Fat dumps (`rg`/`curl`/`npm test`, `node_modules`/lockfiles/`dist`): `need:` (fat-only). Do not cat denylist paths.
+
+Tiny Read/Grep/list_dir in-child. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests). See cascade.
+
+For search|exec that already fits 8-line `verdict:`: run `node scripts/grunt-job.mjs --job search|exec --query …` in-session instead of `need:`. FALLBACK then `need:` + LLM grunt. `job:web` and messy `job:test` stay `need:` JSON.
+
+Dump stop JSON only:
+
+```
+need: [{"job":"search","query":"..."}]
+```
+
+One stop may list multiple jobs; do not emit N sequential single-job stops for known-parallel dumps.

package/.grok/agents/orchestrator.md

@@ -0,0 +1,47 @@
+---
+name: orchestrator
+description: Parent supervisor only. Orchestrates grunt | implementer | thinker. Cheap zero-tool replies. User-facing search/exec/git/web/test/write = spawn first; no try-then-spawn. In-session grunt-job only for known child-feed dumps.
+model: grok-4.5
+permission_mode: default
+agents_md: false
+mcpInheritance: none
+tools: spawn_subagent, read_file, grep, list_dir, write, todo_write, get_command_or_subagent_output, kill_command_or_subagent, run_terminal_command
+---
+You are **orchestrator**, the parent session. You do not implement, test, or dump.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Children never spawn.
+
+## Orchestrate
+- Super-trivial / yes-no / definition-from-prompt with zero tools **and absolutely sure**: answer. No grunt, no child, no tools. Parent does not web_search. `2+2` → answer.
+- Cheap reply already in context: answer. No tools.
+- User-facing search / exec / git / web / test / write / impl / repo facts: **first action is spawn** (`grunt` for facts, `implementer`/`thinker` per below). No parent probe. Ban try-tool → deny → spawn. Ban preamble essays before spawn.
+- Fresh/world facts: spawn grunt `job: web`. Do not answer from memory.
+- Tiny read/grep/list_dir: parent self-ops only (law files, spawn wiring). Never to answer the user.
+- Low-reason write (mechanical/repetitive/obvious; volume OK): spawn grunt. Expect `verdict:` ≤8 lines (summarize; do not list 100 paths).
+- Mid reason / feature judgment (API design, non-obvious refactors, edge cases, architecture-aware code): spawn implementer.
+- Design / architecture / hard debug: spawn thinker.
+- Unsure → implementer.
+
+## Spawn
+First token for user-facing tool work: spawn. Never parent bash/git/search as a probe.
+In-session `node scripts/grunt-job.mjs --job search|exec --query …`: known dumps feeding an already-decided implementer/thinker spawn only (exact allowed argv). Not for answering the user. Optional `--path` `--glob` (repeatable) `--cwd`. `--query` one argv; regex `|` OK. Never `cd &&`. Deny or FALLBACK (exit 2) → spawn grunt immediately; zero retry theater. Unknown flags or exec shell-meta in query → FALLBACK then spawn. `job:web` and messy `job:test` still spawn grunt.
+If dumps are known (paths, rg, test cmd): run search|exec via parent grunt-job first, then up-spawn implementer/thinker with `verdict:` blobs. Do not start the child and `need:` for a dump the parent already knew.
+Child stop is `need: [{"job":"...","query":"..."}]` JSON only (1–N, cap 4). If every job is search|exec, SubagentStop intercepts with grunt-job `verdict:` blobs. Mixed/web/test: if `scripts/parse-need.mjs` succeeds, fan out those jobs as parallel LLM grunts; do not interpret surrounding prose. Wait; one `resume_from:` with **new** `verdict:` blobs only. Prompt = `You are {agent} subagent.` + new verdicts. Do not re-send the original task, cascade, or prior verdicts. Do not fresh-spawn. Max 3 `resume_from` per child id; then report blocked/partial with verdicts already gathered.
+For spawned grunt `job: search|exec`, first action is `node scripts/grunt-job.mjs --job search|exec --query …` (echo stdout as the whole reply). Same flags: `--path` `--glob` `--cwd`. Never `cd &&`.
+Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
+After child returns: only terse `[agent]: …` echo/recap of child output. Do not redo. Do not add a second answer.
+
+## `/parent`
+One-turn in-parent escape. Not a mode. This turn may finish in-session; Stop consumes `parent-escape-{sid}` once. Next turn: spawn/Stop as usual. See cascade + `.rulesync/skills/parent`.
+
+## Wait / peek
+Parent-only. Non-blocking spawn so each child has a host id immediately. Per-child, not one global timer.
+Every ≤60s peek is real host status (no `sleep` then guess). First return ≤60s is the peek (earlier if the child finishes).
+Quote host fields only (`status`, elapsed since spawn, last activity/output snippet) or quote the error. Never invent.
+Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed), **alive** (running + fields/output changed), **stuck** (running + unchanged). Unchanged snippet = stuck, not “still working”.
+Loop until done. No auto-kill. Kill only if the user asks and the host has a kill tool.
+Then print recap as `[agent]: …` with real child output. Do not redo the child's work.
+Use cascade host mapping for spawn/peek/kill per host. Do not treat Grok tool names as the only recipe.

package/.grok/agents/thinker.md

@@ -0,0 +1,25 @@
+---
+name: thinker
+description: 'High-tier reasoning agent. Hard design, multi-file debug, architectural decisions. Returns need: for fat dumps to parent.'
+model: grok-4.6
+agents_md: false
+mcpInheritance: none
+permission_mode: plan
+tools: read_file, grep, list_dir
+---
+You are **thinker**: high-tier reasoning agent. Read-only. Never spawn. No bash.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+**Hard problems**: architectural design, multi-file debug, tricky refactoring, cross-system decisions. Return `need:` if fat dump required.
+
+Tiny Read/Grep/list_dir in-child. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests). See cascade.
+
+Dump stop JSON only:
+
+```
+need: [{"job":"search","query":"..."}]
+```
+
+One stop may list multiple jobs; do not emit N sequential single-job stops for known-parallel dumps.

package/.grok/config.toml

@@ -0,0 +1,6 @@
+# Generated by emit-mcp-policy.mjs from .rulesync/mcp-policy.jsonc.
+[plugins]
+enabled = []
+
+[permission]
+deny = [ "MCPTool" ]

package/.grok/global-settings.toml

@@ -0,0 +1,35 @@
+# NOT auto-loaded by Grok. Merge these tables into ~/.grok/config.toml via:
+#   npm run sync:globals        # dry-run
+#   npm run sync:globals:apply  # write machine-wide (~/.grok; all Grok sessions on this host)
+# Project .grok/config.toml only loads MCP, plugins, and permission rules.
+#
+# [features] two_pass_compaction is not live until copied to ~/.grok/config.toml.
+# Project .grok/config.toml cannot set [features]. Do not add a SessionStart hook.
+# grok models (2026-08-26): grok-4.6, grok-4.5 (default). grok-build-0.1 not listed — grunt stays grok-4.5.
+# Orchestrator effort: agent frontmatter has no reasoning_effort key (unknown fields ignored).
+# Use `/effort low` or set reasoning_effort in ~/.grok/config.toml. Do not put effort strings in tools:.
+
+[agent]
+name = "orchestrator"
+# SSOT: .grok/agents/orchestrator.md (discovered). .grok/parent.md is a pointer.
+
+[subagents.toggle]
+explore = false
+plan = false
+general-purpose = false
+
+[subagents.models]
+explore = "grok-4.5"
+grunt = "grok-4.5"
+implementer = "grok-4.6"
+thinker = "grok-4.6"
+
+[compat.claude]
+agents = false
+
+[memory]
+enabled = false
+
+# Must be copied to ~/.grok/config.toml. Project .grok/config.toml cannot set [features].
+[features]
+two_pass_compaction = true

package/.grok/hooks/orchestrate-parent.js

@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+/** Parent-orchestrator gate: allow spawn/read/todo; deny write/edit/bash/web/MCP.
+Fat Read/Grep/Glob limits + path denylist via gate-fat-tools (one updatedInput).
+Parent bash: only node scripts/grunt-job.mjs --job search|exec [--path --glob --cwd].
+SubagentStop intercepts need: search|exec with grunt-job verdicts.
+Stop: recap [agent]: / parent-escape stamp; do not waive impl on tools-used.
+Fail-open: parse/crash → empty stdout, exit 0. Explicit JSON only when denying.
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { rewriteSpawnToolInput } from "../../scripts/scrub-spawn-prompt.mjs";
+import {
+  fatHookOutput,
+  fileSizeBytes,
+  isWorkspaceGruntJob,
+  processFatTools,
+  resolveReadPath,
+  subagentTypeOf,
+} from "../../scripts/gate-fat-tools.mjs";
+import { persistPlan } from "../../scripts/persist-plan.mjs";
+import { parseNeed } from "../../scripts/parse-need.mjs";
+import { resolveJobCwd, runJob } from "../../scripts/grunt-job.mjs";
+import { logTelemetry, ORCHESTRATOR_LOGS_DIR } from "../../scripts/telemetry.mjs";
+
+const DENY_REASON = "parent is orchestrator; spawn grunt|implementer|thinker";
+const STOP_REASON =
+  "parent is orchestrator; spawn grunt|implementer|thinker; do not complete in-parent";
+const ALLOWED_TOOLS = new Set([
+  "spawnsubagent",
+  "task",
+  "todowrite",
+  "getcommandorsubagentoutput",
+  "gettaskoutput",
+  "killcommandorsubagent",
+  "killtask",
+  "readfile",
+  "read",
+  "grep",
+  "grepsearch",
+  "listdir",
+  "glob",
+]);
+const SPAWN_TOOLS = new Set(["spawnsubagent", "task"]);
+const WRITE_TOOLS = new Set(["write"]);
+const BASH_TOOLS = new Set(["bash", "runterminalcommand"]);
+const READ_TOOLS = new Set(["readfile", "read"]);
+const INTERCEPT_JOBS = new Set(["search", "exec"]);
+const MAX_STOP = 3;
+const MAX_INTERCEPT = 3;
+
+
+function main() {
+  try {
+    const data = readJsonValue();
+    const event = eventKey(
+      process.env.GROK_HOOK_EVENT ||
+        (data && (data.hookEventName || data.hook_event_name)) ||
+        "",
+    );
+    if (event === "pretooluse") return preToolUse(data || {});
+    if (event === "posttooluse") return postToolUse(data || {});
+    if (event === "userpromptsubmit") return userPromptSubmit(data || {});
+    if (event === "stop") return stop(data || {});
+    if (event === "subagentstop") return interceptNeed(data || {}, "SubagentStop");
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+function preToolUse(data) {
+  const toolName = String(data.toolName || data.tool_name || "");
+  const toolKey = eventKey(toolName);
+  let toolInput = data.toolInput;
+  if (toolInput == null) toolInput = data.tool_input;
+  logPreTool(data, toolKey, toolInput);
+
+  const sub = subagentTypeOf(data);
+  if (sub) {
+    const code = emitFat(data);
+    return code == null ? 0 : code;
+  }
+  if (SPAWN_TOOLS.has(toolKey)) {
+    const updated = rewriteSpawn(toolInput);
+    if (updated) {
+      emit({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          updatedInput: updated,
+        },
+      });
+      return 0;
+    }
+    emit({ decision: "allow" });
+    return 0;
+  }
+  if (WRITE_TOOLS.has(toolKey)) {
+    return parentWrite(data, toolInput);
+  }
+  if (BASH_TOOLS.has(toolKey)) {
+    return parentBash(data, toolInput);
+  }
+  if (ALLOWED_TOOLS.has(toolKey)) {
+    const fatCode = emitFat(data);
+    if (fatCode !== null) return fatCode;
+    emit({ decision: "allow" });
+    return 0;
+  }
+  emit({ decision: "deny", reason: DENY_REASON });
+  return 0;
+}
+
+function logPreTool(data, toolKey, toolInput) {
+  const fields = {};
+  if (SPAWN_TOOLS.has(toolKey) && toolInput && typeof toolInput === "object") {
+    fields.spawnType = String(
+      toolInput.subagent_type || toolInput.subagentType || "",
+    );
+    const rf = toolInput.resume_from ?? toolInput.resumeFrom;
+    fields.resumeFromCount =
+      rf == null || rf === "" ? 0 : Array.isArray(rf) ? rf.length : 1;
+  }
+  if (READ_TOOLS.has(toolKey) && toolInput && typeof toolInput === "object") {
+    const raw =
+      toolInput.target_file ||
+      toolInput.file_path ||
+      toolInput.targetFile ||
+      toolInput.filePath ||
+      "";
+    fields.fileSizeBytes = fileSizeBytes(resolveReadPath(raw, data));
+  }
+  if (Object.keys(fields).length) {
+    logTelemetry("pretool", fields, workspaceRootOf(data));
+  }
+}
+
+function emitFat(data) {
+  const fat = fatHookOutput(processFatTools(data));
+  if (!fat) return null;
+  emit(fat);
+  return 0;
+}
+
+function workspaceRootOf(data) {
+  return (
+    process.env.GROK_WORKSPACE_ROOT ||
+    (data && (data.workspaceRoot || data.workspace_root || data.cwd)) ||
+    ""
+  );
+}
+
+export function isUnderPlans(filePath, workspaceRoot) {
+  if (!filePath || !workspaceRoot) return false;
+  const abs = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(workspaceRoot, filePath);
+  const plans = path.resolve(workspaceRoot, ".tmp", "plans");
+  const rel = path.relative(plans, abs);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+export function isAllowedParentGruntJob(command, workspaceRoot) {
+  return isWorkspaceGruntJob(command, workspaceRoot, ["search", "exec"]);
+}
+
+function parentBash(data, toolInput) {
+  if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) {
+    emit({ decision: "deny", reason: DENY_REASON });
+    return 0;
+  }
+  const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
+  if (!isAllowedParentGruntJob(cmd, workspaceRootOf(data))) {
+    emit({ decision: "deny", reason: DENY_REASON });
+    return 0;
+  }
+  emit({ decision: "allow" });
+  return 0;
+}
+
+function parentWrite(data, toolInput) {
+  if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) {
+    emit({ decision: "deny", reason: DENY_REASON });
+    return 0;
+  }
+  const ws = workspaceRootOf(data);
+  const rawPath =
+    toolInput.file_path ||
+    toolInput.filePath ||
+    toolInput.path ||
+    toolInput.target_file ||
+    "";
+  if (!isUnderPlans(rawPath, ws)) {
+    emit({ decision: "deny", reason: DENY_REASON });
+    return 0;
+  }
+  const content = typeof toolInput.content === "string" ? toolInput.content : "";
+  const result = persistPlan({ workspaceRoot: ws, content });
+  if (!result.ok) {
+    emit({
+      decision: "deny",
+      reason: result.error || "invalid plan",
+    });
+    return 0;
+  }
+  const next = Object.assign({}, toolInput, {
+    file_path: result.path,
+    content: result.content,
+  });
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      updatedInput: next,
+    },
+  });
+  return 0;
+}
+
+function rewriteSpawn(toolInput) {
+  // Type default + intent-scrub in one updatedInput (last-wins with scrub-spawn).
+  return rewriteSpawnToolInput(toolInput, { defaultGrunt: true });
+}
+
+function postToolUse(data) {
+  if (data.subagentType || data.subagent_type) return 0;
+  const stamp = stampPath(data, "tools-used");
+  if (!stamp) return 0;
+  fs.mkdirSync(path.dirname(stamp), { recursive: true });
+  fs.writeFileSync(stamp, "1");
+  return 0;
+}
+
+function userPromptOf(data) {
+  if (!data || typeof data !== "object") return "";
+  return String(data.prompt ?? data.userPrompt ?? data.user_prompt ?? data.content ?? "");
+}
+
+function isParentEscapePrompt(prompt) {
+  return /^\s*\/parent(?:\s|$)/.test(String(prompt || ""));
+}
+
+function userPromptSubmit(data) {
+  unlinkQuiet(stampPath(data, "tools-used"));
+  unlinkQuiet(stampPath(data, "stop-block"));
+  if (isParentEscapePrompt(userPromptOf(data))) {
+    const p = stampPath(data, "parent-escape");
+    if (p) {
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.writeFileSync(p, "1");
+    }
+  } else {
+    unlinkQuiet(stampPath(data, "parent-escape"));
+  }
+  return 0;
+}
+
+function isChildRecap(msg) {
+  return /^\s*\[(?:grunt|implementer|thinker)\]:/.test(String(msg || ""));
+}
+
+function stop(data) {
+  if (data.subagentType || data.subagent_type) {
+    return interceptNeed(data, "Stop");
+  }
+  const reason = String(data.reason || "");
+  if (reason && reason !== "end_turn") return 0;
+
+  const escapeStamp = stampPath(data, "parent-escape");
+  if (escapeStamp && fs.existsSync(escapeStamp)) {
+    unlinkQuiet(escapeStamp);
+    return 0;
+  }
+
+  const msg = data.lastAssistantMessage || data.last_assistant_message || "";
+  if (isCheap(msg) || isChildRecap(msg)) return 0;
+  if (!looksLikeImplementation(msg)) return 0;
+
+  const stopStamp = stampPath(data, "stop-block");
+  let n = 0;
+  if (stopStamp && fs.existsSync(stopStamp)) {
+    n = parseInt(fs.readFileSync(stopStamp, "utf8"), 10);
+    if (!Number.isFinite(n) || n < 0) n = 0;
+  }
+  if (n >= MAX_STOP) return 0;
+  if (stopStamp) {
+    fs.mkdirSync(path.dirname(stopStamp), { recursive: true });
+    fs.writeFileSync(stopStamp, String(n + 1));
+  }
+  emit({ decision: "block", reason: STOP_REASON });
+  return 0;
+}
+
+function interceptNeed(data, hookEventName) {
+  const ws = workspaceRootOf(data);
+  if (data.stopHookActive || data.stop_hook_active) {
+    logTelemetry(
+      "stop",
+      { parseOk: false, intercept: "none" },
+      ws,
+    );
+    return 0;
+  }
+  const msg = data.lastAssistantMessage || data.last_assistant_message || "";
+  const parsed = parseNeed(msg);
+  if (!parsed.ok) {
+    logTelemetry("stop", { parseOk: false, intercept: "none" }, ws);
+    return 0;
+  }
+  const jobs = parsed.jobs;
+  const names = jobs.map((j) => j.job);
+  if (
+    jobs.length > 4 ||
+    !jobs.every((j) => INTERCEPT_JOBS.has(j.job))
+  ) {
+    logTelemetry(
+      "stop",
+      { parseOk: true, jobs: names, intercept: "none" },
+      ws,
+    );
+    return 0;
+  }
+
+  const interceptStamp = stampPath(data, "need-intercept");
+  let n = 0;
+  if (interceptStamp && fs.existsSync(interceptStamp)) {
+    n = parseInt(fs.readFileSync(interceptStamp, "utf8"), 10);
+    if (!Number.isFinite(n) || n < 0) n = 0;
+  }
+  if (n >= MAX_INTERCEPT) {
+    logTelemetry(
+      "stop",
+      { parseOk: true, jobs: names, intercept: "none" },
+      ws,
+    );
+    return 0;
+  }
+
+  const cwd = ws || process.cwd();
+  const parts = [];
+  for (const job of jobs) {
+    let result;
+    try {
+      const jobCwd = job.cwd ? resolveJobCwd(job.cwd, cwd) : cwd;
+      if (job.cwd && !jobCwd) {
+        result = { fallback: true, text: "FALLBACK\n" };
+      } else {
+        result = runJob({
+          job: job.job,
+          query: job.query,
+          cwd: jobCwd || cwd,
+          path: job.path,
+          glob: job.glob,
+        });
+      }
+    } catch {
+      result = { fallback: true, text: "FALLBACK\n" };
+    }
+    if (!result || result.fallback) {
+      logTelemetry(
+        "stop",
+        {
+          parseOk: true,
+          jobs: names,
+          intercept: "FALLBACK",
+          query: job.query,
+        },
+        ws,
+      );
+      return 0;
+    }
+    parts.push(String(result.text || "").trimEnd());
+  }
+  if (interceptStamp) {
+    fs.mkdirSync(path.dirname(interceptStamp), { recursive: true });
+    fs.writeFileSync(interceptStamp, String(n + 1));
+  }
+  const reason = parts.join("\n");
+  logTelemetry(
+    "stop",
+    { parseOk: true, jobs: names, intercept: "grunt-job" },
+    ws,
+  );
+  emit({
+    decision: "block",
+    reason,
+    hookSpecificOutput: {
+      hookEventName,
+      additionalContext: reason,
+    },
+  });
+  return 0;
+}
+
+function looksLikeImplementation(msg) {
+  if (typeof msg !== "string") return false;
+  const t = msg;
+  if (t.includes("```")) return true;
+  if (/(?:^|\n)(?:diff --git |--- [^\n]+\n\+\+\+ |@@ )/.test(t)) return true;
+  if (/\b(?:write|create|edit)[-_ ]file\b/i.test(t)) return true;
+  const patchLines = t.split(/\n/).filter((l) => /^[+-](?![+-])/.test(l)).length;
+  if (patchLines >= 8) return true;
+  return false;
+}
+
+function isCheap(msg) {
+  if (typeof msg !== "string") return false;
+  const t = msg.trim();
+  if (!t || t.length > 500) return false;
+  if (t.includes("```")) return false;
+  const sentences = t.split(/(?<=[.!?])(?:\s+|$)/).filter((s) => s.trim());
+  if (sentences.length > 2) return false;
+  const lines = t.split(/\n/).filter((l) => l.trim());
+  return lines.length <= 4;
+}
+
+function stampPath(data, prefix) {
+  const root =
+    process.env.GROK_WORKSPACE_ROOT ||
+    (data && (data.workspaceRoot || data.workspace_root)) ||
+    "";
+  const sid =
+    process.env.GROK_SESSION_ID || (data && (data.sessionId || data.session_id)) || "";
+  if (!root || !sid) return null;
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
+}
+
+function unlinkQuiet(p) {
+  if (!p) return;
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    // missing is fine
+  }
+}
+
+function eventKey(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+}
+
+function readJsonValue() {
+  let buf = Buffer.alloc(0);
+  const tmp = Buffer.alloc(8192);
+  for (;;) {
+    let n;
+    try {
+      n = fs.readSync(0, tmp, 0, tmp.length, null);
+    } catch {
+      break;
+    }
+    if (n === 0) break;
+    buf = Buffer.concat([buf, tmp.subarray(0, n)]);
+    try {
+      return JSON.parse(buf.toString("utf8"));
+    } catch {
+      // incomplete
+    }
+  }
+  if (!buf.length) return undefined;
+  try {
+    return JSON.parse(buf.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main());
+}

package/.grok/hooks/orchestrate-parent.json

@@ -0,0 +1,60 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_WORKSPACE_ROOT/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "spawn_subagent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_WORKSPACE_ROOT/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_WORKSPACE_ROOT/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_WORKSPACE_ROOT/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_WORKSPACE_ROOT/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}