talking-stick 0.4.9 → 0.4.10

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI coordination tool that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.4.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
+**Version:** 0.4.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, Grok Build, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
 
 ## Quickstart
 
@@ -166,13 +166,14 @@ For harnesses that only notice completed subprocesses, run `tt events --wait --a
 - Claude Code: copied or linked into `~/.claude/skills/talking-stick`
 - Codex: copied or linked into `~/.codex/skills/talking-stick`
 - Gemini: installed with `gemini skills install ... --scope user` or linked with `gemini skills link ... --scope user`
+- Grok Build: copied or linked into `~/.grok/skills/talking-stick`, plus a trusted global session hook at `~/.grok/hooks/talking-stick-session.json`
 - OpenCode: copied or linked into `~/.opencode/skills/talking-stick`
 
 By default, `tt install` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
-Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
+Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Grok Build has no Talking Stick MCP registration path; install is native skill plus hook only. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
 
-Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
+Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, Grok Build, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
 
 ## Human CLI
 
@@ -189,7 +190,7 @@ tt state [path]                                           # full room state
 tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
 tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]  # send an OOB message
 tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]  # receive OOB messages
-tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]  # show collaboration prompt
+tt instructions show [path] [--harness claude|codex|gemini|grok|opencode|all] [--scope effective|bundled|user|project]  # show collaboration prompt
 tt instructions edit [path] [--user|--project]             # edit user or project prompt
 tt instructions reset [path] (--user|--project)            # delete a user or project prompt
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
@@ -216,7 +217,8 @@ By default, `tt` behaves like a human CLI and resolves to `human:<username>` onl
 
 Harness-aware CLI identity is resolved before the human fallback:
 
-- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically.
+- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, `CMUX_AGENT_LAUNCH_KIND=grok`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically. The cmux Grok marker is optional; Grok Build also works without cmux by walking process ancestry for a `grok` root process.
+- Grok Build's installed hook records hook-only `GROK_SESSION_ID` context into `${TALKING_STICK_DATA_DIR}/grok-sessions.jsonl`, letting later Grok-launched `tt` calls upgrade from process identity to the real Grok session id. `GROK_SESSION_ID` by itself is not treated as a normal shell marker, and the hook is not required for basic Grok detection.
 - Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
 - Set `TT_HARNESS_EXPORT=1` only when you need ancestry-based harness detection without a known harness environment marker.
 

package/dist/cli/grok-session-hook.js

@@ -0,0 +1,69 @@
+import { createSystemProcessInspector } from "../process-utils.js";
+import { appendGrokSessionRecord } from "../grok-session-store.js";
+import { findHarnessRootInAncestry } from "../identity.js";
+export async function runGrokSessionHookCommand(options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const input = parseHookInput(options.stdin ?? await readStdin());
+        const sessionId = firstNonEmptyString(env.GROK_SESSION_ID, input.sessionId);
+        const workspaceRoot = firstNonEmptyString(env.GROK_WORKSPACE_ROOT, env.CLAUDE_PROJECT_DIR, input.workspaceRoot);
+        if (!sessionId || !workspaceRoot) {
+            return;
+        }
+        const event = firstNonEmptyString(env.GROK_HOOK_EVENT, input.hookEventName) ?? "unknown";
+        const inspector = options.inspector ?? createSystemProcessInspector();
+        const parentPid = options.parentPid ?? process.ppid;
+        const parentInspection = inspector.inspect(parentPid);
+        const grokRoot = findHarnessRootInAncestry("grok", parentPid, parentInspection, inspector, 20);
+        const record = {
+            source: "grok_hook",
+            grok_session_id: sessionId,
+            workspace_root: workspaceRoot,
+            cwd: firstNonEmptyString(input.cwd),
+            event,
+            observed_at: firstNonEmptyString(input.timestamp) ??
+                (options.now ?? new Date()).toISOString(),
+            grok_pid: grokRoot?.pid ?? null,
+            grok_process_started_at: grokRoot?.startTime ?? null
+        };
+        appendGrokSessionRecord(record, { logPath: options.logPath });
+    }
+    catch {
+        // Grok hooks must fail open. Identity can fall back to pid-root detection
+        // when the hook cannot record a session row.
+    }
+}
+function parseHookInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isObjectRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let raw = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            raw += chunk;
+        });
+        process.stdin.on("error", reject);
+        process.stdin.on("end", () => resolve(raw));
+    });
+}
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/cli/install-commands.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planUninstall, runAction } from "../install.js";
+import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planGrokSessionHookInstall, planGrokSessionHookUninstall, planUninstall, runAction } from "../install.js";
 import { planSkillInstall, planSkillUninstall } from "../skill-install.js";
 import { resolveDataDir } from "../config.js";
 import { FileAuditLog, defaultAuditLogPath } from "../install-audit.js";
@@ -145,7 +145,7 @@ function resolveSkillInstallLinkMode(parsed) {
     return true;
 }
 function planInstallActions(harnesses, installOptions) {
-    return harnesses.map((harness) => planSkillInstall(harness, installOptions));
+    return harnesses.flatMap((harness) => planInstallActionsForHarness(harness, installOptions));
 }
 function planUninstallActions(harnesses, installOptions) {
     return harnesses.flatMap((harness) => [
@@ -153,6 +153,14 @@ function planUninstallActions(harnesses, installOptions) {
             ...installOptions,
             skipMissing: false
         }),
+        ...(harness === "grok"
+            ? [
+                planGrokSessionHookUninstall({
+                    ...installOptions,
+                    skipMissing: false
+                })
+            ]
+            : []),
         planUninstall(harness, installOptions)
     ]);
 }
@@ -160,14 +168,31 @@ function planCleanupActions(harnesses, installOptions) {
     return harnesses.map((harness) => planUninstall(harness, installOptions));
 }
 async function runSkillInstall(harness, installOptions) {
-    const skillAction = planSkillInstall(harness, installOptions);
-    const skillResult = await runAction(skillAction, installOptions);
-    return [skillResult];
+    const actions = planInstallActionsForHarness(harness, installOptions);
+    return Promise.all(actions.map((action) => runAction(action, installOptions)));
 }
 async function runSkillUninstall(harness, installOptions) {
-    const skillAction = planSkillUninstall(harness, installOptions);
-    const skillResult = await runAction(skillAction, installOptions);
-    return [skillResult];
+    const actions = [
+        planSkillUninstall(harness, {
+            ...installOptions,
+            skipMissing: false
+        }),
+        ...(harness === "grok"
+            ? [
+                planGrokSessionHookUninstall({
+                    ...installOptions,
+                    skipMissing: false
+                })
+            ]
+            : [])
+    ];
+    return Promise.all(actions.map((action) => runAction(action, installOptions)));
+}
+function planInstallActionsForHarness(harness, installOptions) {
+    return [
+        planSkillInstall(harness, installOptions),
+        ...(harness === "grok" ? [planGrokSessionHookInstall(installOptions)] : [])
+    ];
 }
 async function runCleanup(harnesses, reason, installOptions) {
     const dataDir = resolveDataDir();

package/dist/cli/output.js

@@ -164,7 +164,7 @@ Commands:
   tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
   tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]
   tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]
-  tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]
+  tt instructions show [path] [--harness claude|codex|gemini|grok|opencode|all] [--scope effective|bundled|user|project]
   tt instructions edit [path] [--user|--project]
   tt instructions reset [path] (--user|--project)
   tt release [path] (--status TEXT --next-action TEXT | --stdin)

package/dist/cli/registry.js

@@ -1,4 +1,5 @@
 import { runGuardCommand } from "./guardian.js";
+import { runGrokSessionHookCommand } from "./grok-session-hook.js";
 import { runInstallCommand, runMcpMigrationCommand, runSelfUpdateCommand, runUninstallCommand } from "./install-commands.js";
 import { handleInstructionsCommand } from "./instructions-commands.js";
 import { handleMsgCommand } from "./msg-commands.js";
@@ -15,6 +16,15 @@ export const COMMAND_REGISTRY = [
         description: "Run an internal lease heartbeat guardian.",
         handler: ({ parsed }) => runGuardCommand(parsed)
     },
+    {
+        name: "grok-session-hook",
+        needsRuntime: false,
+        startupMaintenance: false,
+        internal: true,
+        usage: "tt grok-session-hook",
+        description: "Record Grok hook session context for identity resolution.",
+        handler: () => runGrokSessionHookCommand()
+    },
     {
         name: "install",
         needsRuntime: false,

package/dist/grok-session-store.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveDataDir } from "./config.js";
+export const DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS = 4 * 60 * 60 * 1000;
+export function resolveGrokSessionLogPath(options = {}) {
+    return path.join(resolveDataDir(options), "grok-sessions.jsonl");
+}
+export function appendGrokSessionRecord(record, options = {}) {
+    const logPath = options.logPath ?? resolveGrokSessionLogPath(options.dataDirOptions ?? {});
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+}
+export function readGrokSessionRecords(logPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(logPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const record = parseGrokSessionRecord(parsed);
+            if (record)
+                records.push(record);
+        }
+        catch {
+            // Hook logs are append-only and best-effort; one bad line should not
+            // break identity resolution for the whole session.
+        }
+    }
+    return records;
+}
+export function findGrokSessionRecord(input) {
+    const workspaceRoot = normalizeWorkspaceRoot(input.workspaceRoot);
+    if (!workspaceRoot)
+        return null;
+    const logPath = input.logPath ?? resolveGrokSessionLogPath();
+    const nowMs = input.now?.getTime() ?? Date.now();
+    const maxAgeMs = input.maxAgeMs ?? DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS;
+    const records = readGrokSessionRecords(logPath);
+    const endedSessionIds = new Set();
+    const workspaceCandidates = [];
+    for (const record of records.slice().reverse()) {
+        if (normalizeWorkspaceRoot(record.workspace_root) !== workspaceRoot) {
+            continue;
+        }
+        if (isStaleRecord(record, nowMs, maxAgeMs)) {
+            continue;
+        }
+        if (isGrokSessionEndEvent(record.event)) {
+            endedSessionIds.add(record.grok_session_id);
+            continue;
+        }
+        if (endedSessionIds.has(record.grok_session_id)) {
+            continue;
+        }
+        workspaceCandidates.push(record);
+        if (input.grokPid != null &&
+            input.grokProcessStartedAt != null &&
+            record.grok_pid === input.grokPid &&
+            record.grok_process_started_at === input.grokProcessStartedAt) {
+            return record;
+        }
+    }
+    const uniqueSessionIds = new Set(workspaceCandidates.map((record) => record.grok_session_id));
+    if (uniqueSessionIds.size === 1) {
+        return workspaceCandidates[0] ?? null;
+    }
+    return null;
+}
+export function isGrokSessionEndEvent(event) {
+    return normalizeEventName(event) === "sessionend";
+}
+function parseGrokSessionRecord(value) {
+    if (!isObjectRecord(value))
+        return null;
+    if (value.source !== "grok_hook")
+        return null;
+    const grokSessionId = nonEmptyString(value.grok_session_id);
+    const workspaceRoot = nonEmptyString(value.workspace_root);
+    const event = nonEmptyString(value.event);
+    const observedAt = nonEmptyString(value.observed_at);
+    if (!grokSessionId || !workspaceRoot || !event || !observedAt) {
+        return null;
+    }
+    return {
+        source: "grok_hook",
+        grok_session_id: grokSessionId,
+        workspace_root: workspaceRoot,
+        cwd: nullableString(value.cwd),
+        event,
+        observed_at: observedAt,
+        grok_pid: nullableInteger(value.grok_pid),
+        grok_process_started_at: nullableString(value.grok_process_started_at)
+    };
+}
+function isStaleRecord(record, nowMs, maxAgeMs) {
+    const observedAtMs = Date.parse(record.observed_at);
+    if (Number.isNaN(observedAtMs))
+        return true;
+    return nowMs - observedAtMs > maxAgeMs;
+}
+function normalizeWorkspaceRoot(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return fs.realpathSync.native(trimmed);
+    }
+    catch {
+        return path.resolve(trimmed);
+    }
+}
+function normalizeEventName(event) {
+    return event.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : null;
+}
+function nullableString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : null;
+}
+function nullableInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/identity.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import { findGrokSessionRecord, resolveGrokSessionLogPath } from "./grok-session-store.js";
+import { resolveContextPath } from "./path-resolution.js";
 import { createSystemProcessInspector } from "./process-utils.js";
 const HARNESS_CLI_EXPORT_ENV = "TT_HARNESS_EXPORT";
 const HARNESS_CLI_AGENT_ID_ENV = "TT_HARNESS_AGENT_ID";
@@ -41,7 +43,11 @@ export function deriveMcpHarnessIdentity(options = {}) {
     const signal = detectHarnessSignal(env);
     if (signal) {
         const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
-        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+            contextPath: options.contextPath,
+            grokSessionLogPath: options.grokSessionLogPath,
+            now: options.now
+        });
         const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
@@ -100,7 +106,9 @@ export function deriveHarnessCliIdentity(options = {}) {
     }
     let signal = detectHarnessSignal(env);
     if (!signal && !isHarnessCliExportEnabled(env)) {
-        return null;
+        signal = detectGrokViaAncestry(parentPid, parentInspection, inspector);
+        if (!signal)
+            return null;
     }
     if (!signal) {
         signal = detectHarnessViaAncestry(parentPid, inspector);
@@ -109,7 +117,11 @@ export function deriveHarnessCliIdentity(options = {}) {
         return null;
     const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
     const username = options.username ?? safeUsername();
-    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+        contextPath: options.contextPath,
+        grokSessionLogPath: options.grokSessionLogPath,
+        now: options.now
+    });
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
     const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
     return {
@@ -136,10 +148,16 @@ function harnessAgentId(harness, sessionId, hostId, username) {
         sanitizeIdentityComponent(username)
     ])}`;
 }
-function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector) {
+function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector, options = {}) {
     if (signal.sessionId)
         return `harness:${signal.sessionId}`;
     const harnessRoot = findHarnessRootInAncestry(signal.harness, parentPid, parentInspection, inspector);
+    if (signal.harness === "grok") {
+        const grokSessionId = resolveGrokHookSessionId(env, harnessRoot, options);
+        if (grokSessionId) {
+            return `harness:${grokSessionId}`;
+        }
+    }
     if (harnessRoot) {
         return `pid:${harnessRoot.pid}@${harnessRoot.startTime}`;
     }
@@ -165,7 +183,7 @@ function resolveHarnessProcessRef(signal, processRef, inspector) {
 // process whose command matches the named harness. Anchoring session id to
 // that root keeps `tt` invocations stable whether they're spawned directly
 // by the harness (MCP subprocess) or through intermediate shells (CLI shell-out).
-function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
+export function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
     let result = null;
     let currentPid = startPid;
     let currentInspection = startInspection;
@@ -220,6 +238,7 @@ const HARNESS_COMMAND_MAPPING = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
     opencode: "opencode"
 };
 function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
@@ -231,10 +250,13 @@ function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
         if (!inspection)
             break;
         const label = deriveCommandLabel(inspection.command);
-        if (HARNESS_COMMAND_MAPPING[label]) {
+        const harness = HARNESS_COMMAND_MAPPING[label];
+        if (harness) {
             return {
-                harness: HARNESS_COMMAND_MAPPING[label],
-                sessionId: `pid:${inspection.pid}@${inspection.startTime}`,
+                harness,
+                sessionId: harness === "grok"
+                    ? null
+                    : `pid:${inspection.pid}@${inspection.startTime}`,
                 pidHint: null
             };
         }
@@ -267,8 +289,51 @@ function detectHarnessSignal(env) {
             pidHint: null
         };
     }
+    const cmuxHarness = resolveCmuxLaunchHarness(env);
+    if (cmuxHarness) {
+        return {
+            harness: cmuxHarness,
+            sessionId: null,
+            pidHint: null
+        };
+    }
     return null;
 }
+function detectGrokViaAncestry(parentPid, parentInspection, inspector) {
+    const grokRoot = findHarnessRootInAncestry("grok", parentPid, parentInspection, inspector, 20);
+    return grokRoot
+        ? { harness: "grok", sessionId: null, pidHint: null }
+        : null;
+}
+function resolveGrokHookSessionId(env, harnessRoot, options) {
+    const workspaceRoot = resolveGrokWorkspaceRoot(env, options.contextPath);
+    const record = findGrokSessionRecord({
+        logPath: options.grokSessionLogPath ??
+            resolveGrokSessionLogPath({ env }),
+        workspaceRoot,
+        grokPid: harnessRoot?.pid ?? null,
+        grokProcessStartedAt: harnessRoot?.startTime ?? null,
+        now: options.now
+    });
+    return record?.grok_session_id ?? null;
+}
+function resolveGrokWorkspaceRoot(env, contextPath) {
+    const explicit = nonEmpty(env.GROK_WORKSPACE_ROOT) ??
+        nonEmpty(env.CLAUDE_PROJECT_DIR);
+    if (explicit)
+        return path.resolve(explicit);
+    const candidate = contextPath ?? nonEmpty(env.PWD) ?? process.cwd();
+    try {
+        return resolveContextPath(candidate).workspace_root;
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+function resolveCmuxLaunchHarness(env) {
+    const launchKind = normalizeEnvValue(env.CMUX_AGENT_LAUNCH_KIND);
+    return launchKind ? HARNESS_COMMAND_MAPPING[launchKind] ?? null : null;
+}
 function resolveSignalProcessRef(signal, fallbackPid, fallbackInspection, inspector) {
     if (signal.pidHint && signal.pidHint !== fallbackPid) {
         const hintedInspection = inspector.inspect(signal.pidHint);
@@ -294,6 +359,10 @@ function parsePositiveInteger(value) {
 function nonEmpty(value) {
     return value && value.trim().length > 0 ? value : null;
 }
+function normalizeEnvValue(value) {
+    const nonBlank = nonEmpty(value);
+    return nonBlank ? nonBlank.toLowerCase() : null;
+}
 function deriveCommandLabel(command) {
     if (!command) {
         return "harness";

package/dist/index.js

@@ -5,7 +5,8 @@ export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
 export { DEFAULT_MAX_INSTRUCTION_FILE_BYTES, DEFAULT_INSTRUCTIONS_MARKDOWN, editInstructions, extractHarnessInstructions, normalizeInstructionHarness, parseInstructionScope, resetInstructions, resolveInstructionHarness, resolveInstructionPaths, showInstructions } from "./instructions.js";
-export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { SUPPORTED_HARNESSES, buildGrokSessionHookConfig, DEFAULT_GROK_SESSION_HOOK_COMMAND, GROK_SESSION_HOOK_EVENTS, GROK_SESSION_HOOK_FILE, MissingHarnessError, detectHarness, parseHarnessList, planGrokSessionHookInstall, planGrokSessionHookUninstall, planUninstall, resolveGrokSessionHookPath, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS, appendGrokSessionRecord, findGrokSessionRecord, isGrokSessionEndEvent, readGrokSessionRecords, resolveGrokSessionLogPath } from "./grok-session-store.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
 export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";

package/dist/install.js

@@ -2,9 +2,17 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "opencode"];
+export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "grok", "opencode"];
 export const DEFAULT_SERVER_NAME = "talking-stick";
 export const DEFAULT_SERVER_COMMAND = ["tt", "mcp"];
+export const GROK_SESSION_HOOK_FILE = "talking-stick-session.json";
+export const DEFAULT_GROK_SESSION_HOOK_COMMAND = ": talking-stick-grok-session-hook; if command -v tt >/dev/null 2>&1; then tt grok-session-hook >/dev/null 2>/dev/null || true; fi";
+export const GROK_SESSION_HOOK_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "SessionEnd"
+];
 export class MissingHarnessError extends Error {
     constructor(message) {
         super(message);
@@ -96,11 +104,21 @@ export function resolveHarnessConfigDir(harness, options = {}) {
     const resolved = resolveOptions(options);
     return resolveHarnessConfigDirFromResolved(harness, resolved);
 }
+export function resolveGrokSessionHookPath(options = {}) {
+    const resolved = resolveOptions(options);
+    return path.join(resolveGrokConfigDirFromResolved(resolved), "hooks", GROK_SESSION_HOOK_FILE);
+}
 function resolveOpencodeConfigDirFromResolved(resolved) {
     const xdg = resolved.env.XDG_CONFIG_HOME?.trim();
     const base = xdg && xdg.length > 0 ? xdg : path.join(resolved.homeDir, ".config");
     return path.join(base, "opencode");
 }
+function resolveGrokConfigDirFromResolved(resolved) {
+    const grokHome = resolved.env.GROK_HOME?.trim();
+    return grokHome && grokHome.length > 0
+        ? grokHome
+        : path.join(resolved.homeDir, ".grok");
+}
 function resolveHarnessConfigDirFromResolved(harness, resolved) {
     switch (harness) {
         case "claude-code":
@@ -109,6 +127,8 @@ function resolveHarnessConfigDirFromResolved(harness, resolved) {
             return path.join(resolved.homeDir, ".codex");
         case "gemini":
             return path.join(resolved.homeDir, ".gemini");
+        case "grok":
+            return resolveGrokConfigDirFromResolved(resolved);
         case "opencode":
             return resolveOpencodeConfigDirFromResolved(resolved);
         default:
@@ -157,6 +177,8 @@ export function planUninstall(harness, options = {}) {
                 operation: "uninstall",
                 serverName: resolved.serverName
             };
+        case "grok":
+            return skipAction(harness, "legacy Talking Stick cleanup is not applicable for grok");
         case "opencode": {
             const filePath = resolveOpencodeConfigPath(options);
             const configDir = path.dirname(filePath);
@@ -189,6 +211,76 @@ export function skipAction(harness, message) {
         message
     };
 }
+export function planGrokSessionHookInstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `write Grok session hook ${filePath}`,
+        inspect: () => inspectGrokSessionHook(filePath, resolved),
+        apply: () => writeGrokSessionHook(filePath, resolved)
+    };
+}
+export function planGrokSessionHookUninstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `remove Grok session hook ${filePath}`,
+        inspect: () => resolved.hooks.readFile(filePath) === null ? "absent" : "present",
+        apply: () => removeGrokSessionHook(filePath, resolved)
+    };
+}
+export function buildGrokSessionHookConfig() {
+    const hook = {
+        type: "command",
+        command: DEFAULT_GROK_SESSION_HOOK_COMMAND,
+        timeout: 5
+    };
+    const hooks = Object.fromEntries(GROK_SESSION_HOOK_EVENTS.map((event) => [
+        event,
+        [
+            {
+                hooks: [hook]
+            }
+        ]
+    ]));
+    return JSON.stringify({ hooks }, null, 2) + "\n";
+}
+function inspectGrokSessionHook(filePath, resolved) {
+    const existing = resolved.hooks.readFile(filePath);
+    if (existing === null)
+        return "absent";
+    return existing === buildGrokSessionHookConfig() ? "present" : "different";
+}
+function writeGrokSessionHook(filePath, resolved) {
+    resolved.hooks.ensureDir(path.dirname(filePath));
+    resolved.hooks.writeFile(filePath, buildGrokSessionHookConfig());
+}
+function removeGrokSessionHook(filePath, resolved) {
+    void resolved;
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
 function patchOpencodeConfig(filePath, resolved, mode) {
     const existing = resolved.hooks.readFile(filePath);
     if (resolved.skipMissing) {
@@ -305,6 +397,15 @@ export function detectHarness(harness, options = {}) {
                 return { harness, detected: true, evidence: configDir };
             return { harness, detected: false, evidence: "gemini not on PATH and no config directory" };
         }
+        case "grok": {
+            const bin = resolved.hooks.which("grok");
+            if (bin)
+                return { harness, detected: true, evidence: bin };
+            const configDir = resolveHarnessConfigDirFromResolved(harness, resolved);
+            if (resolved.hooks.pathExists(configDir))
+                return { harness, detected: true, evidence: configDir };
+            return { harness, detected: false, evidence: "grok not on PATH and no config directory" };
+        }
         case "opencode": {
             const bin = resolved.hooks.which("opencode");
             if (bin)
@@ -534,6 +635,8 @@ function mcpConfigLocation(action) {
             return "Codex global config";
         case "gemini":
             return "Gemini user config";
+        case "grok":
+            return "Grok config";
         case "opencode":
             return "OpenCode config";
         default:

package/dist/instructions.js

@@ -30,6 +30,10 @@ Lean into adversarial review, convergence, precise implementation, edge-case swe
 
 Use broad context review and exploration conservatively until the project has stronger Gemini-specific dogfood. Keep handoffs concrete and do not assume responsibility that the operator assigned to another harness.
 
+## Grok
+
+Use Grok Build as a first-class local coding harness. Keep coordination safety ahead of speed, rely on the native Grok skill and session hook when installed, and keep handoffs concrete when another harness is better positioned to implement or review.
+
 ## OpenCode
 
 Use terminal-native local exploration and implementation conservatively until the project has stronger OpenCode-specific dogfood. Keep coordination safety ahead of speed.
@@ -41,6 +45,8 @@ const HARNESS_ALIASES = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
+    "grok-build": "grok",
     opencode: "opencode"
 };
 export function resolveInstructionPaths(options = {}) {
@@ -108,7 +114,7 @@ export function resolveInstructionHarness(explicitHarness, identity) {
 export function normalizeInstructionHarness(value) {
     const normalized = HARNESS_ALIASES[normalizeKey(value)];
     if (!normalized) {
-        throw new Error(`--harness must be one of claude, codex, gemini, opencode, all (got ${value}).`);
+        throw new Error(`--harness must be one of claude, codex, gemini, grok, opencode, all (got ${value}).`);
     }
     return normalized;
 }
@@ -208,6 +214,8 @@ function parseHarnessHeader(line) {
         return "codex";
     if (key.startsWith("gemini"))
         return "gemini";
+    if (key.startsWith("grok"))
+        return "grok";
     if (key.startsWith("opencode"))
         return "opencode";
     return null;

package/dist/skill-install.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { MissingHarnessError, resolveHarnessConfigDir, skipAction } from "./install.js";
 export const DEFAULT_SKILL_NAME = "talking-stick";
-const FILE_SKILL_HARNESSES = ["claude-code", "codex", "opencode"];
+const FILE_SKILL_HARNESSES = ["claude-code", "codex", "grok", "opencode"];
 export function resolveBundledSkillPath(options = {}) {
     return options.sourcePath ?? path.resolve(currentPackageDir(), "skills", DEFAULT_SKILL_NAME);
 }
@@ -15,6 +15,8 @@ export function resolveSkillTargetPath(harness, options = {}) {
             return path.join(homeDir, ".claude", "skills", options.skillName ?? DEFAULT_SKILL_NAME);
         case "codex":
             return path.join(homeDir, ".codex", "skills", options.skillName ?? DEFAULT_SKILL_NAME);
+        case "grok":
+            return path.join(resolveHarnessConfigDir("grok", options), "skills", options.skillName ?? DEFAULT_SKILL_NAME);
         case "opencode":
             return path.join(homeDir, ".opencode", "skills", options.skillName ?? DEFAULT_SKILL_NAME);
         default:

package/docs/releases/0.4.10.md

@@ -0,0 +1,17 @@
+# Talking Stick 0.4.10
+
+Date: 2026-06-08
+
+## Added
+- **Grok Build harness support.** `tt install grok` now installs the native `~/.grok/skills/talking-stick` skill and a trusted global `~/.grok/hooks/talking-stick-session.json` hook. Grok-launched `tt` calls work without cmux by detecting a `grok` root process in ancestry; `CMUX_AGENT_LAUNCH_KIND=grok` remains optional fast evidence when present. The hook records `GROK_SESSION_ID` context in `${TALKING_STICK_DATA_DIR}/grok-sessions.jsonl` so identity can upgrade from pid-root identity to the real Grok session id when the record matches the workspace and harness process.
+
+## Verification
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+npm pack --dry-run
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: talking-stick
-description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker.
+description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, Grok, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker.
 ---
 
 This skill teaches a harness how to behave in a Talking Stick workspace.
@@ -49,7 +49,7 @@ Some workspaces may also have sibling receive processes running `tt events --fol
 
 If coordination is required and `tt` is unavailable, say so briefly and ask the user whether they want to install or enable Talking Stick first. Do not pretend coordination is active.
 
-Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install gemini` when needed.
+Human CLI runs silently keep already-installed Claude Code, Codex, Grok, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install gemini` when needed.
 
 ### 2. Join The Workspace Room Once