@litfamily/litgrok 1.0.0

package/.grok/hooks/lit-mark.mjs

@@ -0,0 +1,142 @@
+// Canonical rows and cell colors are generated from pinned Ignition B; do not edit glyphs.
+// BEGIN CANONICAL ROWS
+export const standard = Object.freeze([
+  "          ▄▖  ▄█▄     ",
+  "▗▄▄▖    ▄██▌  ▜█▛     ",
+  "▐██▌  ▄████████████▜▛ ",
+  "▐██▌ ▐█▀▀▀▀▀▀▀▀▀▀▀▀▘  ",
+  "▐██▌   ▄█▌█████████▌  ",
+  "▐██▌ ▄██▛▘  ▗▄▄  ▗    ",
+  "▐██▌▐█▛▘    ▐██  ▝▀   ",
+  "▐██▌▝       ▐██       ",
+  "▐██████▘    ▐██       ",
+  "▝▀▀▀▀▀      ▝▀▀       "
+]);
+
+export const banner = Object.freeze([
+  "                             ▄▄▄▄           ",
+  "                   ▗███▌   ▗██████▖         ",
+  " ▗▄▄▄▄▄          ▗▟████▌   ▝██████▘         ",
+  " ▐█████        ▗▟██████▌    ▝▀▜█▀▘          ",
+  " ▐█████      ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄  ",
+  " ▐█████    ▗▟█████████████████████████ ▐█▀  ",
+  " ▐█████    ████████████████████████████▀    ",
+  " ▐█████    ██▛▘   ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖     ",
+  " ▐█████    ▀    ▄██ ████▌█████████████▌     ",
+  " ▐█████       ▄████ ████▌█████████████▌     ",
+  " ▐█████     ▄█████▛                         ",
+  " ▐█████  ▗▟█████▀▘       ▄▄▄▄▄     ▗▖       ",
+  " ▐█████ ▐█████▀          █████     ▐▛▀      ",
+  " ▐█████ ▐███▀            █████              ",
+  " ▐█████ ▐█▀              █████              ",
+  " ▐█████ ▝                █████              ",
+  " ▐█████▄▄▄▄▄▄▄▖          █████              ",
+  " ▐███████████▛           █████              ",
+  " ▐██████████▀            █████              ",
+  "                                            "
+]);
+
+export const micro = Object.freeze([
+  "▗▖  ▄▄ █▌       ",
+  "▐▌▗█▀▀▀▀▀▀▘     ",
+  "▐▌ ▄▌▀▝▀▀▘      ",
+  "▐▌▛▘  ▐▌        ",
+  "▝▀▀▘  ▝▘        "
+]);
+
+const COLOR_KEYS = Object.freeze({
+  standard: Object.freeze([
+    "..........II..LLL.....",
+    "OOOO....IIII..LLL.....",
+    "OOOO..IIIIOOOOOOOOOOO.",
+    "OOOO.IIIOOOOOOOOOOOO..",
+    "OOOO...IIILLLIIIIIII..",
+    "OOOO.IIIII..III..I....",
+    "OOOOIIII....III..II...",
+    "OOOOI.......III.......",
+    "OOOOOOOO....III.......",
+    "OOOOOO......III......."
+  ]),
+  banner: Object.freeze([
+    ".............................LLLL...........",
+    "...................IIIII...LLLLLLLL.........",
+    ".OOOOOO..........IIIIIII...LLLLLLLL.........",
+    ".OOOOOO........IIIIIIIII....LLLLLL..........",
+    ".OOOOOO......IIIIIIIIIOOOOOOOOOOOOOOOOOOOO..",
+    ".OOOOOO....IIIIIIIIOOOOOOOOOOOOOOOOOOO.OOO..",
+    ".OOOOOO....IIIIIIOOOOOOOOOOOOOOOOOOOOOOO....",
+    ".OOOOOO....IIII...I.LLLLLIIIIIIIIIIIIII.....",
+    ".OOOOOO....I....III.LLLLLIIIIIIIIIIIIII.....",
+    ".OOOOOO.......IIIII.LLLLLIIIIIIIIIIIIII.....",
+    ".OOOOOO.....IIIIIII.........................",
+    ".OOOOOO..IIIIIIIII.......IIIII.....II.......",
+    ".OOOOOO.IIIIIII..........IIIII.....III......",
+    ".OOOOOO.IIIII............IIIII..............",
+    ".OOOOOO.III..............IIIII..............",
+    ".OOOOOO.I................IIIII..............",
+    ".OOOOOOOOOOOOOO..........IIIII..............",
+    ".OOOOOOOOOOOOO...........IIIII..............",
+    ".OOOOOOOOOOOO............IIIII..............",
+    "............................................"
+  ]),
+  micro: Object.freeze([
+    "OO..II.LL.......",
+    "OOIIIOOOOOO.....",
+    "OO.IILIIII......",
+    "OOII..II........",
+    "OOOO..II........"
+  ]),
+});
+// END CANONICAL ROWS
+
+const MARK_GLYPHS = new Set('█▀▄▌▐▖▗▘▝▙▛▜▟▚▞');
+const RESET = '\x1b[0m';
+const PALETTE = Object.freeze({ O: '255;99;55', L: '215;247;91', I: '242;239;223' });
+const INDEXED_PALETTE = Object.freeze({ O: 203, L: 191, I: 230 });
+
+function productLabel(productName) {
+  if (typeof productName !== 'string' || !/^[\p{L}\p{N} .·-]{1,80}$/u.test(productName)) throw new TypeError('Invalid product name');
+  return productName;
+}
+
+export function lockup(productName) {
+  const label = productLabel(productName);
+  return standard.map((row, index) => row.padEnd(28) + (index === 5 ? `  ${label}` : ''));
+}
+
+export function colorize(rows, { mode = 'none' } = {}) {
+  if (!['truecolor', '256', 'none'].includes(mode)) throw new TypeError('Invalid color mode');
+  if (mode === 'none') return [...rows];
+  const variants = { standard, banner, micro };
+  const variant = Object.keys(variants).find((name) => rows.length === variants[name].length && rows.every((row, index) => row.startsWith(variants[name][index])));
+  return rows.map((row, index) => {
+    return [...row].map((glyph, column) => {
+      if (!MARK_GLYPHS.has(glyph)) return glyph;
+      const key = variant ? COLOR_KEYS[variant][index][column] : 'I';
+      if (!Object.hasOwn(PALETTE, key)) return glyph;
+      const foreground = mode === '256' ? `\x1b[38;5;${INDEXED_PALETTE[key]}m` : `\x1b[38;2;${PALETTE[key]}m`;
+      return `${foreground}${glyph}${RESET}`;
+    }).join('');
+  });
+}
+
+function unicodeTerminal(env) {
+  return env.TERM !== 'dumb' && /utf-?8/iu.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '');
+}
+
+export function terminalMode({ env = process.env, isTTY = process.stdout.isTTY, args = [] } = {}) {
+  if (!isTTY || Object.hasOwn(env, 'NO_COLOR') || Object.hasOwn(env, 'CI') || args.includes('--json') || args.includes('--no-color') || !unicodeTerminal(env)) return 'none';
+  return /truecolor|24bit/iu.test(env.COLORTERM || '') ? 'truecolor' : '256';
+}
+
+export function renderMark({ size = 'standard', productName, env = process.env, isTTY = process.stdout.isTTY, args = [] } = {}) {
+  if (!Object.hasOwn({ standard, banner, micro }, size)) throw new TypeError('Invalid mark size');
+  const label = productName === undefined ? undefined : productLabel(productName);
+  if (!unicodeTerminal(env)) return label ? ['LIT', label] : ['LIT'];
+  const rows = { standard, banner, micro }[size];
+  const painted = colorize(rows, { mode: terminalMode({ env, isTTY, args }) });
+  if (!label) return painted;
+  const width = size === 'banner' ? 50 : size === 'standard' ? 28 : 16;
+  const labelRow = size === 'banner' ? 10 : size === 'standard' ? 5 : 2;
+  return painted.map((row, index) => row + ' '.repeat(width - rows[index].length) + (index === labelRow ? `  ${label}` : ''));
+}

package/.grok/hooks/plan-gate.mjs

@@ -0,0 +1,81 @@
+// Stop plan gate: a planning turn must persist plans/<slug>.md with column-zero checkbox rows.
+//
+// Host contract (documented Stop decision control): stdout `{"decision":"block","reason"}` keeps
+// the agent working; empty stdout with exit 0 allows the stop; failures fail open. The prompt text
+// is never persisted, so the gate arms on `permissionMode === "plan"`, on the ledger's lit-plan
+// discipline marker for the turn, and on a plan file written this turn that carries zero rows. At
+// most two blocks per session; after that it passes with a stderr warning so a condition the model
+// cannot resolve never loops.
+
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { countImplementationRows } from '../skills/lit-plan/scripts/scaffold-plan.mjs';
+
+export const PLAN_GATE_SIGNAL = 'plan-gate-block';
+export const PLAN_GATE_MAX_BLOCKS = 2;
+const SCAFFOLD = '.grok/skills/lit-plan/scripts/scaffold-plan.mjs';
+const MAX_PLAN_BYTES = 256 * 1024;
+
+function ledgerRecords(ledgerFile, sessionId) {
+  if (!existsSync(ledgerFile)) return [];
+  return readFileSync(ledgerFile, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line))
+    .filter((record) => record.sessionId === sessionId);
+}
+
+function turnStart(records, promptId) {
+  const prompts = records.filter((record) => record.event === 'UserPromptSubmit');
+  const matching = typeof promptId === 'string' ? prompts.filter((record) => record.promptId === promptId) : [];
+  const start = (matching.length > 0 ? matching : prompts).at(-1);
+  return {
+    since: start ? Date.parse(start.recordedAt) : null,
+    litPlanTurn: start?.discipline === 'lit-plan',
+  };
+}
+
+function plansWrittenSince(workspaceRoot, since) {
+  const directory = join(workspaceRoot, 'plans');
+  if (!existsSync(directory) || lstatSync(directory).isSymbolicLink() || !statSync(directory).isDirectory()) return [];
+  const plans = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const path = join(directory, entry.name);
+    const status = statSync(path);
+    if (status.size > MAX_PLAN_BYTES) continue;
+    if (since !== null && status.mtimeMs < since) continue;
+    plans.push({ name: `plans/${entry.name}`, mtimeMs: status.mtimeMs, rows: countImplementationRows(readFileSync(path, 'utf8')) });
+  }
+  return plans.sort((left, right) => right.mtimeMs - left.mtimeMs);
+}
+
+/**
+ * Decide whether this Stop fire must block. Returns `{ block: false }`, `{ block: true, reason }`,
+ * or `{ block: false, warning }` when the per-session cap has been reached.
+ */
+export function evaluatePlanGate({ event, workspaceRoot, sessionId, ledgerFile }) {
+  if (event.reason !== undefined && event.reason !== 'end_turn') return { block: false };
+  if (event.subagentType !== undefined) return { block: false };
+
+  const records = ledgerRecords(ledgerFile, sessionId);
+  const { since, litPlanTurn } = turnStart(records, event.promptId);
+  const planMode = event.permissionMode === 'plan' || litPlanTurn;
+  const written = plansWrittenSince(workspaceRoot, since);
+  const newest = written[0];
+
+  let reason = null;
+  if (planMode && !newest) {
+    reason = `lit-plan must persist plans/<slug>.md before finishing this planning turn: run \`node ${SCAFFOLD} <slug>\` from the project root, append column-zero \`- [ ] N. <title>\` task rows under "## Todos", then run \`node ${SCAFFOLD} --check plans/<slug>.md\`.`;
+  } else if (newest && newest.rows === 0 && (planMode || since !== null)) {
+    reason = `${newest.name} was written this turn but has no column-zero \`- [ ] 1. <title>\` task row; start-work cannot execute it. Append the task rows under "## Todos", then run \`node ${SCAFFOLD} --check ${newest.name}\`.`;
+  }
+  if (reason === null) return { block: false };
+
+  const blocks = records.filter((record) => record.signal === PLAN_GATE_SIGNAL).length;
+  if (blocks >= PLAN_GATE_MAX_BLOCKS) {
+    return { block: false, warning: `LitGrok plan gate: ${blocks} blocks already issued this session; passing with a warning. ${reason}` };
+  }
+  return { block: true, reason };
+}

package/.grok/hooks/post-compact.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "post-compact.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/post-compact.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// No compaction-result or durable-goal payload is documented, so this records only the post-compaction boundary.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('PostCompact');

package/.grok/hooks/post-tool-use-failure.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "post-tool-use-failure.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/post-tool-use-failure.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// No failure-detail field is documented, so this records only the failing toolName and opaque toolInput digest.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('PostToolUseFailure');

package/.grok/hooks/post-tool-use.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "^(Edit|edit|Write|write)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "post-tool-use.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/post-tool-use.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// A documented edited-file path or tool-result field would make this ledger richer; neither is documented.
+// Record only toolName and a digest of the opaque documented toolInput, never its contents.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('PostToolUse');

package/.grok/hooks/pre-compact.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pre-compact.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/pre-compact.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// No compacted-context or durable-goal payload is documented, so this records only the pre-compaction boundary.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('PreCompact');

package/.grok/hooks/record-passive-event.mjs

@@ -0,0 +1,198 @@
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  writeSync,
+} from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+const MAX_EVENT_BYTES = 1024 * 1024;
+const MAX_LEDGER_BYTES = 8 * 1024 * 1024;
+const TOOL_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
+const RECORD_SCHEMA = 'litgrok.hook-event/v1';
+
+class RecorderError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+
+function requireString(value, code) {
+  if (typeof value !== 'string' || value.length === 0 || value.includes('\0')) throw new RecorderError(code);
+  return value;
+}
+
+function normalizedEventName(value) {
+  return requireString(value, 'EVENT_NAME_MISSING').replace(/[^A-Za-z0-9]/g, '').toLowerCase();
+}
+
+async function readEvent() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > MAX_EVENT_BYTES) throw new RecorderError('EVENT_TOO_LARGE');
+  }
+  try {
+    const event = JSON.parse(input);
+    if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error();
+    return event;
+  } catch {
+    throw new RecorderError('EVENT_INVALID_JSON');
+  }
+}
+
+function verifiedEnvironment(event, expectedEvent) {
+  const environmentHookEvent = process.env.GROK_HOOK_EVENT;
+  const stdinHookEvent = event.hookEventName;
+  const hookEvent = requireString(environmentHookEvent || stdinHookEvent, 'EVENT_NAME_MISSING');
+  const hookName = requireString(process.env.GROK_HOOK_NAME, 'ENV_HOOK_NAME_MISSING');
+  const sessionId = requireString(process.env.GROK_SESSION_ID, 'ENV_SESSION_ID_MISSING');
+  const workspaceRoot = requireString(process.env.GROK_WORKSPACE_ROOT, 'ENV_WORKSPACE_ROOT_MISSING');
+
+  if (normalizedEventName(hookEvent) !== normalizedEventName(expectedEvent)) throw new RecorderError('EVENT_NAME_MISMATCH');
+  if (environmentHookEvent && stdinHookEvent && normalizedEventName(environmentHookEvent) !== normalizedEventName(stdinHookEvent)) {
+    throw new RecorderError('EVENT_NAME_MISMATCH');
+  }
+  if (event.sessionId !== sessionId) throw new RecorderError('SESSION_ID_MISMATCH');
+  if (event.workspaceRoot !== workspaceRoot) throw new RecorderError('WORKSPACE_ROOT_MISMATCH');
+  if (!isAbsolute(workspaceRoot)) throw new RecorderError('WORKSPACE_ROOT_NOT_ABSOLUTE');
+
+  const eventCwd = requireString(event.cwd, 'EVENT_CWD_MISSING');
+  if (!isAbsolute(eventCwd)) throw new RecorderError('EVENT_CWD_NOT_ABSOLUTE');
+
+  let realWorkspaceRoot;
+  try {
+    realWorkspaceRoot = realpathSync(workspaceRoot);
+  } catch {
+    throw new RecorderError('WORKSPACE_ROOT_UNAVAILABLE');
+  }
+
+  return { eventCwd, hookName, realWorkspaceRoot, sessionId, workspaceRoot };
+}
+
+function ensureDirectory(path) {
+  if (!existsSync(path)) {
+    try {
+      mkdirSync(path, { mode: 0o700 });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  }
+  const status = lstatSync(path);
+  if (!status.isDirectory() || status.isSymbolicLink()) throw new RecorderError('LEDGER_DIRECTORY_UNSAFE');
+}
+
+function ledgerPath(realWorkspaceRoot, sessionId) {
+  const grokDirectory = join(realWorkspaceRoot, '.grok');
+  const productDirectory = join(grokDirectory, 'litgrok');
+  const ledgerDirectory = join(productDirectory, 'session-ledger');
+  for (const path of [grokDirectory, productDirectory, ledgerDirectory]) ensureDirectory(path);
+  const sessionKey = createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
+  return join(ledgerDirectory, `${sessionKey}.jsonl`);
+}
+
+export function claimSessionIgnition(event) {
+  const environment = verifiedEnvironment(event, 'SessionStart');
+  if (environment.sessionId.length > 512) throw new RecorderError('SESSION_ID_INVALID');
+  const path = ledgerPath(environment.realWorkspaceRoot, environment.sessionId).replace(/\.jsonl$/u, '.ignited');
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  try {
+    // An empty exclusive marker claims this session atomically, including replays.
+    closeSync(openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600));
+    return true;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    const status = lstatSync(path);
+    if (!status.isFile() || status.isSymbolicLink() || status.size !== 0) throw new RecorderError('IGNITION_MARKER_UNSAFE');
+    return false;
+  }
+}
+
+function validateExistingLedger(path, sessionId) {
+  if (!existsSync(path)) return;
+  const status = lstatSync(path);
+  if (!status.isFile() || status.isSymbolicLink() || status.size > MAX_LEDGER_BYTES) {
+    throw new RecorderError('LEDGER_FILE_UNSAFE');
+  }
+  const text = readFileSync(path, 'utf8');
+  for (const line of text.split(/\r?\n/).filter(Boolean)) {
+    try {
+      const record = JSON.parse(line);
+      if (record.schema !== RECORD_SCHEMA || record.sessionId !== sessionId) throw new Error();
+    } catch {
+      throw new RecorderError('LEDGER_IDENTITY_MISMATCH');
+    }
+  }
+}
+
+function toolRecord(event, expectedEvent) {
+  if (!TOOL_EVENTS.has(expectedEvent)) return undefined;
+  const name = requireString(event.toolName, 'TOOL_NAME_MISSING');
+  if (!Object.hasOwn(event, 'toolInput')) throw new RecorderError('TOOL_INPUT_MISSING');
+  return {
+    name,
+    inputSha256: createHash('sha256').update(JSON.stringify(event.toolInput)).digest('hex'),
+  };
+}
+
+function appendRecord(path, record) {
+  validateExistingLedger(path, record.sessionId);
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const descriptor = openSync(
+    path,
+    constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | noFollow,
+    0o600,
+  );
+  try {
+    if (!fstatSync(descriptor).isFile()) throw new RecorderError('LEDGER_FILE_UNSAFE');
+    writeSync(descriptor, `${JSON.stringify(record)}\n`);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function appendSessionRecord(ledgerFile, baseRecord, fields) {
+  appendRecord(ledgerFile, { ...baseRecord, ...fields, recordedAt: new Date().toISOString() });
+}
+
+export async function recordPassiveEvent(expectedEvent) {
+  try {
+    const event = await readEvent();
+    const environment = verifiedEnvironment(event, expectedEvent);
+    const record = {
+      schema: RECORD_SCHEMA,
+      event: expectedEvent,
+      sessionId: environment.sessionId,
+      cwd: environment.eventCwd,
+      workspaceRoot: environment.workspaceRoot,
+      hookName: environment.hookName,
+      recordedAt: new Date().toISOString(),
+    };
+    const tool = toolRecord(event, expectedEvent);
+    if (tool) record.tool = tool;
+    if (typeof event.promptId === 'string') record.promptId = event.promptId;
+    if (expectedEvent === 'UserPromptSubmit' && typeof event.prompt === 'string'
+      && /(?:^|[\s/])lit-plan(?:$|[^\w-])/iu.test(event.prompt)) {
+      record.discipline = 'lit-plan';
+    }
+    if (expectedEvent === 'Stop') record.signal = 'turn-ended';
+    const ledgerFile = ledgerPath(environment.realWorkspaceRoot, environment.sessionId);
+    appendRecord(ledgerFile, record);
+    return { environment, event, ledgerFile, record };
+  } catch (error) {
+    const code = error instanceof RecorderError ? error.code : 'RECORDER_FAILED';
+    process.stderr.write(`LitGrok passive hook recorder: ${code}\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}

package/.grok/hooks/session-start.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "session-start.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/session-start.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { pendingReviewState } from '../skills/skill-observer/scripts/skill-loop.mjs';
+import { renderMark } from './lit-mark.mjs';
+import { claimSessionIgnition } from './record-passive-event.mjs';
+
+let input = '';
+for await (const chunk of process.stdin) {
+  input += chunk;
+  if (Buffer.byteLength(input) > 1024 * 1024) break;
+}
+let event;
+try {
+  if (Buffer.byteLength(input) > 1024 * 1024) throw new Error('EVENT_TOO_LARGE');
+  event = JSON.parse(input);
+  if (claimSessionIgnition(event)) process.stdout.write(`${renderMark({ args: process.argv.slice(2) }).join('\n')}\n`);
+} catch (error) {
+  process.stderr.write(`LitGrok session-start: ${error.code || 'EVENT_INVALID'}\n`);
+  process.exitCode = 1;
+}
+
+process.stdout.write('LitGrok payload present: skills, project rules, hooks, and the npx installer.\n');
+
+try {
+  const sessionId = process.env.GROK_SESSION_ID || event.sessionId;
+  const workspaceRoot = process.env.GROK_WORKSPACE_ROOT || event.workspaceRoot;
+  if (!process.exitCode && sessionId && workspaceRoot && event.sessionId === sessionId && event.workspaceRoot === workspaceRoot) {
+    const state = pendingReviewState({
+      cwd: workspaceRoot,
+      env: { ...process.env, LITGROK_WORKSPACE_ROOT: workspaceRoot },
+      sessionId,
+    });
+    if (state.pending) process.stdout.write(`LitGrok: pending review for session ${sessionId} — run /skill-observer review\n`);
+  }
+} catch {
+  // The installed-payload banner is still useful when optional event state is unavailable.
+}

package/.grok/hooks/stop-failure.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "stop-failure.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/stop-failure.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// No API-error detail field is documented; StopFailure itself is the only recorded failure signal.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('StopFailure');

package/.grok/hooks/stop.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "stop.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/stop.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+// No completion-summary field is documented, so this records only the documented turn-end event and identity.
+import { appendSessionRecord, recordPassiveEvent } from './record-passive-event.mjs';
+import { recordTurnEnded } from '../skills/skill-observer/scripts/skill-loop.mjs';
+import { PLAN_GATE_SIGNAL, evaluatePlanGate } from './plan-gate.mjs';
+
+if (process.env.LITGROK_SKILL_REVIEW !== '1') {
+  const observed = await recordPassiveEvent('Stop');
+  if (observed) {
+    recordTurnEnded({
+      cwd: observed.environment.realWorkspaceRoot,
+      env: { ...process.env, LITGROK_WORKSPACE_ROOT: observed.environment.realWorkspaceRoot },
+      sessionId: observed.environment.sessionId,
+    });
+    // Plan gate: a planning turn must persist plans/<slug>.md; evaluated after the ledger record so a block is counted.
+    let gate;
+    try {
+      gate = evaluatePlanGate({
+        event: observed.event,
+        workspaceRoot: observed.environment.realWorkspaceRoot,
+        sessionId: observed.environment.sessionId,
+        ledgerFile: observed.ledgerFile,
+      });
+    } catch (error) {
+      process.stderr.write(`LitGrok plan gate: PLAN_GATE_FAILED ${error instanceof Error ? error.message : String(error)}\n`);
+      gate = { block: false };
+    }
+    if (gate.block) {
+      appendSessionRecord(observed.ledgerFile, observed.record, { signal: PLAN_GATE_SIGNAL, reason: gate.reason });
+      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: gate.reason })}\n`);
+    } else if (gate.warning) {
+      process.stderr.write(`${gate.warning}\n`);
+    }
+  }
+}

package/.grok/hooks/subagent-start.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "subagent-start.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}