@lovrozagar/grunt 0.2.0 → 0.3.1

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

@@ -1,30 +1,54 @@
 #!/usr/bin/env node
-/** Parent-orchestrator gate: spawn/peek/kill/todo + persistPlan writes.
+/** Parent-orchestrator gate: spawn/peek/kill/todo + persistPlan/persistHandoff writes.
 Parent Read/Grep/Glob/Bash/Web denied unless parent-escape (fat-gate still).
 SubagentStop intercepts need: search|exec with grunt-job verdicts.
-Stop: [agent]: recap | parent-escape once; else block. MAX_STOP=3. No isCheap/trivia.
-Fail-open: parse/crash → empty stdout, exit 0. Explicit JSON only when denying.
+Stop: any-line [orchestrator]:/[grunt]:/[implementer]:/[thinker]:/[handoff]: recap
+| parent-escape once; else block. MAX_STOP=3. No isCheap/trivia.
+Empty lastAssistantMessage → transcript_path tail-scan. Fail-open: parse/crash → empty stdout, exit 0.
 */
 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 {
+  MAX_PROMPT_CHARS,
+  rewriteSpawnToolInput,
+  spawnCapReason,
+} from "../../scripts/scrub-spawn-prompt.mjs";
+import {
+  denyResponse,
   fatHookOutput,
   fileSizeBytes,
   isWorkspaceGruntJob,
   processFatTools,
   resolveReadPath,
+  rewriteGruntScratchPath,
   subagentTypeOf,
 } from "../../scripts/gate-fat-tools.mjs";
 import { persistPlan } from "../../scripts/persist-plan.mjs";
+import { persistHandoff } from "../../scripts/persist-handoff.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";
+export const STOP_REASONS = [
+  "Violation: parent replied without a recap tag.\n" +
+    "DO NOT stop. Continue IN THIS RESPONSE:\n" +
+    "1. Spawn grunt|implementer|thinker if work remains.\n" +
+    "2. Recap with `[orchestrator]:` or the child role tag (`[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`).\n" +
+    "If every spawned child already returned and the turn is done, recap now.",
+  "Second violation: still no recap tag.\n" +
+    "DO NOT stop. Right now, in this same response:\n" +
+    "1. Spawn grunt|implementer|thinker if needed.\n" +
+    "2. Then recap only with `[orchestrator]:` or the matching child role tag.\n" +
+    "Already done and every child returned? Send that recap immediately.",
+  "Third violation: recap still missing.\n" +
+    "This is the last check before fail-open. DO NOT stop:\n" +
+    "1. Spawn the correct agent for remaining work if needed.\n" +
+    "2. Reply with `[orchestrator]:` or the child role tag only, nothing else.\n" +
+    "Complete with all children returned? Send the recap now.",
+];
+const TRANSCRIPT_TAIL_BYTES = 512 * 1024;
 const PARENT_TOOLS = new Set([
   "todowrite",
   "getcommandorsubagentoutput",
@@ -43,6 +67,10 @@ const READ_TOOLS = new Set(["readfile", "read"]);
 const INTERCEPT_JOBS = new Set(["search", "exec"]);
 const MAX_STOP = 3;
 const MAX_INTERCEPT = 3;
+/** `/solo` enters single-agent mode; `/cascade` restores the orchestrator. */
+const SOLO_RE = /^\s*\/solo\s*$/;
+const CASCADE_RE = /^\s*\/cascade\s*$/;
+const SOLO_STAMP = "grunt-off";
 
 
 function main() {
@@ -76,8 +104,16 @@ function preToolUse(data) {
     const code = emitFat(data);
     return code == null ? 0 : code;
   }
+  if (isSoloMode(data)) {
+    // Single-agent session: no parent-deny, no spawn rewrite. Fat gate still applies.
+    const fatCode = emitFat(data);
+    if (fatCode !== null) return fatCode;
+    emit({ decision: "allow" });
+    return 0;
+  }
   if (SPAWN_TOOLS.has(toolKey)) {
-    const updated = rewriteSpawn(toolInput);
+    const updated = rewriteSpawn(toolInput, data);
+    if (updated && updated.__denied) return 0;
     if (updated) {
       emit({
         hookSpecificOutput: {
@@ -107,6 +143,16 @@ function preToolUse(data) {
   return 0;
 }
 
+/** Session flag, not one-turn. Fail-closed: an unreadable stamp keeps grunt on. */
+export function isSoloMode(data) {
+  try {
+    const p = soloStampPath(data);
+    return Boolean(p && fs.existsSync(p));
+  } catch {
+    return false;
+  }
+}
+
 function hasParentEscape(data) {
   const p = stampPath(data, "parent-escape");
   return Boolean(p && fs.existsSync(p));
@@ -146,21 +192,32 @@ function emitFat(data) {
 function workspaceRootOf(data) {
   return (
     process.env.GROK_WORKSPACE_ROOT ||
-    (data && (data.workspaceRoot || data.workspace_root || data.cwd)) ||
+    (data && (data.workspaceRoot || data.workspace_root)) ||
+    (data && data.cwd) ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.cwd() ||
     ""
   );
 }
 
-export function isUnderPlans(filePath, workspaceRoot) {
+function isUnderDir(filePath, workspaceRoot, segments) {
   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);
+  const dir = path.resolve(workspaceRoot, ...segments);
+  const rel = path.relative(dir, abs);
   return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 
+export function isUnderPlans(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "plans"]);
+}
+
+export function isUnderHandoffs(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "grunt", "handoffs"]);
+}
+
 export function isAllowedParentGruntJob(command, workspaceRoot) {
   return isWorkspaceGruntJob(command, workspaceRoot, ["search", "exec"]);
 }
@@ -171,22 +228,26 @@ function parentWrite(data, toolInput) {
     return 0;
   }
   const ws = workspaceRootOf(data);
-  const rawPath =
+  let rawPath =
     toolInput.file_path ||
     toolInput.filePath ||
     toolInput.path ||
     toolInput.target_file ||
     "";
-  if (!isUnderPlans(rawPath, ws)) {
+  const rewritten = rewriteGruntScratchPath(rawPath, ws);
+  if (rewritten) rawPath = rewritten;
+  const handoff = isUnderHandoffs(rawPath, ws);
+  if (!handoff && !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 });
+  const persist = handoff ? persistHandoff : persistPlan;
+  const result = persist({ workspaceRoot: ws, content });
   if (!result.ok) {
     emit({
       decision: "deny",
-      reason: result.error || "invalid plan",
+      reason: result.error || (handoff ? "invalid handoff" : "invalid plan"),
     });
     return 0;
   }
@@ -203,9 +264,20 @@ function parentWrite(data, toolInput) {
   return 0;
 }
 
-function rewriteSpawn(toolInput) {
+function rewriteSpawn(toolInput, data) {
   // Type default + intent-scrub in one updatedInput (last-wins with scrub-spawn).
-  return rewriteSpawnToolInput(toolInput, { defaultGrunt: true });
+  const updated = rewriteSpawnToolInput(toolInput, { defaultGrunt: true });
+  const prompt =
+    updated && typeof updated.prompt === "string"
+      ? updated.prompt
+      : toolInput && typeof toolInput.prompt === "string"
+        ? toolInput.prompt
+        : "";
+  if (prompt.length > MAX_PROMPT_CHARS) {
+    emit(denyResponse(spawnCapReason(workspaceRootOf(data))));
+    return { __denied: true };
+  }
+  return updated;
 }
 
 function postToolUse(data) {
@@ -229,7 +301,18 @@ function isParentEscapePrompt(prompt) {
 function userPromptSubmit(data) {
   unlinkQuiet(stampPath(data, "tools-used"));
   unlinkQuiet(stampPath(data, "stop-block"));
-  if (isParentEscapePrompt(userPromptOf(data))) {
+  const prompt = userPromptOf(data);
+  // Sticky: only /solo and /cascade move it. Every other prompt leaves it alone.
+  if (SOLO_RE.test(prompt)) {
+    const solo = soloStampPath(data);
+    if (solo) {
+      fs.mkdirSync(path.dirname(solo), { recursive: true });
+      fs.writeFileSync(solo, "1");
+    }
+  } else if (CASCADE_RE.test(prompt)) {
+    unlinkQuiet(soloStampPath(data));
+  }
+  if (isParentEscapePrompt(prompt)) {
     const p = stampPath(data, "parent-escape");
     if (p) {
       fs.mkdirSync(path.dirname(p), { recursive: true });
@@ -241,25 +324,147 @@ function userPromptSubmit(data) {
   return 0;
 }
 
-function isChildRecap(msg) {
-  return /^\s*\[(?:grunt|implementer|thinker)\]:/.test(String(msg || ""));
+const RECAP_TAG_RE =
+  /^\[(?:orchestrator|grunt|implementer|thinker|handoff)\]:/;
+
+export function isRecap(msg) {
+  const lines = String(msg || "").split("\n");
+  for (const line of lines) {
+    const stripped = line.replace(/^[\s`*_>]+/, "");
+    if (RECAP_TAG_RE.test(stripped)) return true;
+  }
+  return false;
+}
+
+function payloadAssistantMessage(data) {
+  if (!data || typeof data !== "object") return "";
+  const camel = data.lastAssistantMessage;
+  if (camel != null && String(camel) !== "") return String(camel);
+  const snake = data.last_assistant_message;
+  if (snake != null && String(snake) !== "") return String(snake);
+  return "";
+}
+
+function isAssistantRecord(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const type = String(obj.type || "").toLowerCase();
+  if (type === "user" || type === "human" || type === "tool" || type === "tool_result") {
+    return false;
+  }
+  if (type === "assistant") return true;
+  const role = String(
+    obj.role || (obj.message && obj.message.role) || "",
+  ).toLowerCase();
+  if (role === "user" || role === "human") return false;
+  return role === "assistant";
+}
+
+function assistantTextFromRecord(obj) {
+  if (!isAssistantRecord(obj)) return null;
+  const msg = obj.message && typeof obj.message === "object" ? obj.message : obj;
+  const content = msg.content ?? obj.content;
+  if (Array.isArray(content)) {
+    const texts = [];
+    for (const part of content) {
+      if (!part || typeof part !== "object") continue;
+      const pt = String(part.type || "");
+      if (pt === "tool_use" || pt === "tool_result" || pt === "function_call") continue;
+      if (typeof part.text === "string" && part.text) texts.push(part.text);
+    }
+    const joined = texts.join("\n").trim();
+    return joined ? joined : null;
+  }
+  if (typeof content === "string" && content.trim()) return content;
+  if (typeof obj.text === "string" && obj.text.trim()) return obj.text;
+  return null;
+}
+
+export function lastAssistantFromTranscript(filePath) {
+  try {
+    if (!filePath) return "";
+    const st = fs.statSync(filePath);
+    const start = Math.max(0, st.size - TRANSCRIPT_TAIL_BYTES);
+    const fd = fs.openSync(filePath, "r");
+    try {
+      const buf = Buffer.alloc(st.size - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      const text = buf.toString("utf8");
+      const lines = text.split("\n");
+      if (start > 0 && lines.length) lines.shift();
+      let last = "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t) continue;
+        let rec;
+        try {
+          rec = JSON.parse(t);
+        } catch {
+          continue;
+        }
+        const extracted = assistantTextFromRecord(rec);
+        if (extracted) last = extracted;
+      }
+      return last;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+function logParentStop(data, fields) {
+  logTelemetry("parent-stop", fields, workspaceRootOf(data));
 }
 
 function stop(data) {
   if (data.subagentType || data.subagent_type) {
     return interceptNeed(data, "Stop");
   }
+  if (data.stopHookActive || data.stop_hook_active) {
+    logParentStop(data, {
+      recap: false,
+      recapSource: "none",
+      attempt: 0,
+      failOpen: true,
+      stopHookActive: true,
+    });
+    return 0;
+  }
   const reason = String(data.reason || "");
   if (reason && reason !== "end_turn") return 0;
 
+  // Before the parent-escape consume: solo must never burn the one-turn stamp.
+  if (isSoloMode(data)) 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 (isChildRecap(msg)) return 0;
+  const payloadMsg = payloadAssistantMessage(data);
+  let recapSource = "none";
+  let msg = "";
+  if (payloadMsg) {
+    msg = payloadMsg;
+    recapSource = "payload";
+  } else {
+    const tp = data.transcript_path || data.transcriptPath || "";
+    msg = lastAssistantFromTranscript(tp);
+    if (msg) recapSource = "transcript";
+  }
+
+  if (isRecap(msg)) {
+    logParentStop(data, {
+      recap: true,
+      recapSource,
+      attempt: 0,
+      failOpen: false,
+      stopHookActive: false,
+    });
+    return 0;
+  }
 
   const stopStamp = stampPath(data, "stop-block");
   let n = 0;
@@ -267,12 +472,29 @@ function stop(data) {
     n = parseInt(fs.readFileSync(stopStamp, "utf8"), 10);
     if (!Number.isFinite(n) || n < 0) n = 0;
   }
-  if (n >= MAX_STOP) return 0;
+  if (n >= MAX_STOP) {
+    logParentStop(data, {
+      recap: false,
+      recapSource,
+      attempt: n,
+      failOpen: true,
+      stopHookActive: false,
+    });
+    return 0;
+  }
   if (stopStamp) {
     fs.mkdirSync(path.dirname(stopStamp), { recursive: true });
     fs.writeFileSync(stopStamp, String(n + 1));
   }
-  emit({ decision: "block", reason: STOP_REASON });
+  logParentStop(data, {
+    recap: false,
+    recapSource,
+    attempt: n + 1,
+    failOpen: false,
+    stopHookActive: false,
+  });
+  const reasonText = STOP_REASONS[Math.min(n, STOP_REASONS.length - 1)];
+  emit({ decision: "block", reason: reasonText });
   return 0;
 }
 
@@ -368,7 +590,6 @@ function interceptNeed(data, hookEventName) {
   );
   emit({
     decision: "block",
-    reason,
     hookSpecificOutput: {
       hookEventName,
       additionalContext: reason,
@@ -379,14 +600,27 @@ function interceptNeed(data, hookEventName) {
 
 function stampPath(data, prefix) {
   const root = workspaceRootOf(data);
-  const sid =
-    process.env.GROK_SESSION_ID ||
-    (data && (data.sessionId || data.session_id)) ||
-    "default";
+  const sid = sessionIdOf(data) || "default";
   if (!root) return null;
   return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
 }
 
+function sessionIdOf(data) {
+  return String(
+    process.env.GROK_SESSION_ID ||
+      (data && (data.sessionId || data.session_id)) ||
+      "",
+  );
+}
+
+/** Solo is a mode: never share a `default` stamp across sid-less sessions. */
+function soloStampPath(data) {
+  const root = workspaceRootOf(data);
+  const sid = sessionIdOf(data);
+  if (!root || !sid) return null;
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, SOLO_STAMP + "-" + sid);
+}
+
 function unlinkQuiet(p) {
   if (!p) return;
   try {

package/.grok/skills/commit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never pushes.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message. Never push.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Never `git push`.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.grok/skills/commit-and-push/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: commit-and-push
+description: >
+  Commit like /commit, then push to the current branch's upstream. Use for
+  /commit-and-push, "commit and push", "commit this and push".
+---
+Run commit skill rules first (`.rulesync/skills/commit/SKILL.md`). Then push.
+
+If on default branch, create/switch to a feature branch first — never push default directly.
+
+Push upstream; if no upstream `git push -u origin <current-branch>`.
+
+Never force-push.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.grok/skills/handoff/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: handoff
+description: >
+  Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user
+  to continue in a fresh session. Use for /handoff, "context is getting long",
+  "hand this off", "start a new session". Not a plan, not a design doc.
+---
+# handoff
+
+One turn, in-parent. Parent authors from its own transcript — no child sees this session, so **do not spawn**. Write once, report path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/grunt/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Done / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Parent `write`s under `.tmp/grunt/handoffs/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-handoff.mjs`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `node scripts/persist-handoff.mjs --workspace {repo}` and use its `path`.
+
+## Report
+
+```
+[handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; first action = read that path
+```
+
+Do not dump the handoff body.
+
+## Picking one up
+
+New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+
+## Rules
+
+- No spawn. One write. `/handoff` is not a mode.
+- Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
+- Never rewrite or renumber an existing handoff; new session = new serial.
+- Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

package/.grok/skills/solo/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: solo
+description: >
+  Session mode. /solo disables the grunt cascade for this session — one normal
+  agent, no spawn, no orchestrator. /cascade restores it. Unlike /parent and
+  /explain this IS a mode: it persists until /cascade or session end.
+---
+Session mode, not one-turn. Persists until `/cascade` or session end.
+
+This session: cascade suspended. You are one normal agent.
+
+- Do not spawn. No grunt|implementer|thinker.
+- No recap tags. Do not recap `[orchestrator]:`. Answer the user directly.
+- No spawn-first rule. No `need:`/`verdict:` grammar.
+- Voice unchanged: `.rulesync/reference/output.md`. `/explain` is still the voice escape.
+
+Fat-tool caps stay on — token guards, not cascade.
+
+Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
+
+For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.rulesync/hooks.jsonc

@@ -11,8 +11,9 @@
         "timeout": 5
       },
       {
-        // Fat Read/Grep/Glob/Bash: inject limits, path denylist, implementer dump deny.
-        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command",
+        // Fat Read/Grep/Glob/Bash + Write/Edit scratch rewrite (never deny writes).
+        // Parent-deny stays Grok-only (orchestrate-parent.js).
+        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command|Write|Edit|write|search_replace",
         "type": "command",
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/gate-fat-tools.mjs\"",
         "timeout": 5
@@ -20,7 +21,7 @@
     ],
     // Parent Stop + /parent stamp. PreToolUse parent-deny stays Grok-only
     // (child subagentType/agent_type unverified on these hosts).
-    "userPromptSubmit": [
+    "beforeSubmitPrompt": [
       {
         "type": "command",
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
@@ -33,6 +34,13 @@
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
         "timeout": 30
       }
+    ],
+    "subagentStop": [
+      {
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+        "timeout": 30
+      }
     ]
   }
 }

package/.rulesync/reference/cascade.md

@@ -28,10 +28,11 @@ Every 60s peek is real host status (no `sleep` then guess). `timeout_ms=60000` e
 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.
+Then print recap as `[orchestrator]: …` (or the child role tag) with real child output. Do not redo the child's work.
 
-Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Allow only `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
-`/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. Skills point here; do not paste this file.
+Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Allow any-line `[orchestrator|grunt|implementer|thinker|handoff]:` recap, or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
+`/handoff` is the other in-parent turn: context large + work unfinished → parent writes one `.tmp/grunt/handoffs/` file from its own transcript (no child sees the session), recaps `[handoff]: serial=… path=…`, tells the user to continue in a new session. No spawn, one write, not a mode.
+`/solo` is the session mode (not one-turn): `beforeSubmitPrompt` writes `.tmp/orchestrator-logs/grunt-off-{sid}`, every gate short-circuits while it exists, `/cascade` unlinks it. Everything above resumes next turn. Antigravity: skill-only, no stamp create (see hooks.md). `/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. Skills point here; do not paste this file.
 
 Host mapping (in-tree only; do not invent peek/kill APIs). GAP rows: no fake peeks, no auto-kill.
 

package/.rulesync/reference/hooks.md

@@ -12,7 +12,11 @@ Claude / Codex / Antigravity PreToolUse still run `scripts/scrub-spawn-prompt.mj
 
 Parent `run_terminal_command` is deny-by-default except `node` (optional leading `rtk`) invoking `{workspace}/scripts/grunt-job.mjs` with `--job search|exec` and `--query`. Optional `--path` `--glob` (repeatable) `--cwd`. Not `web|test`, not other scripts. META strips `--query` value first so `|` inside query is allowed; pipes/`&&` outside query still deny. Never `cd &&`. Exec shell-meta in query is grunt-job FALLBACK (exit 2), not a parent-bash allow. Unknown flags → FALLBACK.
 
-SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Allow only `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once (`/parent`). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent `write` is deny-by-default except `.tmp/plans/` (`persist-plan.mjs`) and `.tmp/grunt/handoffs/` (`persist-handoff.mjs`); both validate + rewrite path/content, invalid body denies. Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Allow any-line `[orchestrator|grunt|implementer|thinker|handoff]:` recap, or consume `parent-escape-{sid}` once (`/parent`). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+
+`/solo` writes `grunt-off-{sid}`; `/cascade` unlinks it (`beforeSubmitPrompt`, exact-match only). While set: PreToolUse allows parent tools (fat gate still runs) and skips the `defaultGrunt` spawn rewrite; Stop returns 0 **before** the `parent-escape` consume, so solo never burns the one-turn stamp. Session-scoped, fail-closed.
+
+rulesync canonical event is `beforeSubmitPrompt` (→ Claude/Codex `UserPromptSubmit`), not `userPromptSubmit` — an unknown key makes Zod reject the whole `.rulesync/hooks.jsonc`, emitting nothing while `--check` still reports up to date. Antigravity supports neither `beforeSubmitPrompt` nor `subagentStop`; `/solo` degrades there to the skill body alone.
 
 Stop and SubagentStop timeout is 30s (grunt-job cap is 20s). PreToolUse / PostToolUse / UserPromptSubmit stay at 5s. If the intercept times out, the hook fail-opens and the child stops without verdicts.