@groundtrack/hooks 0.1.12 → 0.1.14

package/README.md

@@ -67,6 +67,17 @@ hooks in `.codex/config.toml` are recognized and repaired without duplicating
 them. Claude's `CLAUDE.md` imports the shared `AGENTS.md` policy. The plugin is
 added to the existing OpenCode JSON/JSONC configuration.
 
+Claude setup also installs a synchronous `SessionStart` check in project settings.
+At startup, resume, clear, or fork it checks local MCP configuration and Claude's
+own `mcp get` status. If Groundtrack is missing, disabled, awaiting approval,
+unauthenticated, or not connected, Claude shows a warning with a repair command
+and gives the agent the same context. An incomplete OAuth flow can leave Claude
+in `Needs authentication` even when `mcp get` exits successfully; this state is
+not treated as connected. The check never starts OAuth or blocks the session on
+failure; its native probe has a five-second limit. It needs Claude project hooks
+to be enabled and trusted, and is not a replacement for a live tool call. Other
+clients still rely on their own setup and diagnostics.
+
 In each selected agent, ask:
 
 > Verify Groundtrack's connection and hook context with search_experiences.

package/dist/claude-session-health.d.ts

@@ -0,0 +1,13 @@
+import { type SetupEnvironment } from "./setup/agents.js";
+import { type ClientRunner } from "./setup/connections.js";
+type SessionStartOutput = {
+    systemMessage: string;
+    hookSpecificOutput: {
+        hookEventName: "SessionStart";
+        additionalContext: string;
+    };
+};
+/** Read-only, bounded probe; no OAuth side effects, network calls of our own, or persistent state. */
+export declare function claudeSessionHealth(context: SetupEnvironment, runner?: ClientRunner): Promise<SessionStartOutput | Record<string, never>>;
+export declare function claudeSessionHook(): Promise<SessionStartOutput | Record<string, never>>;
+export {};

package/dist/claude-session-health.js

@@ -0,0 +1,89 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { MCP_URL, configPaths, environment, executable, isGroundtrack, readConfig, serverMap, } from "./setup/agents.js";
+import { at, readJson } from "./setup/config.js";
+import { claudeStatus, runClient } from "./setup/connections.js";
+const setupCommand = "npx --yes --package @groundtrack/hooks@latest groundtrack setup --agent claude";
+function readConfigText(path) {
+    try {
+        // A diagnostic may read the same symlinked profile path Claude accepts.
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+function warning(problem, repair) {
+    const message = `Groundtrack is unavailable in this Claude Code session (${problem}). Searches, events, and outcomes may not be recorded. From this project, run: ${repair}`;
+    return {
+        systemMessage: message,
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: message },
+    };
+}
+function settings(context) {
+    const userDir = context.env.CLAUDE_CONFIG_DIR || join(context.homeDir, ".claude");
+    return [
+        readJson(readConfigText(join(userDir, "settings.json"))),
+        readJson(readConfigText(join(context.repoDir, ".claude/settings.json"))),
+        readJson(readConfigText(join(context.repoDir, ".claude/settings.local.json"))),
+    ];
+}
+/** Read-only, bounded probe; no OAuth side effects, network calls of our own, or persistent state. */
+export async function claudeSessionHealth(context, runner = runClient) {
+    try {
+        const paths = configPaths("claude", context);
+        const project = readConfig("claude", readConfigText(paths.project));
+        const user = readConfig("claude", readConfigText(paths.user));
+        const local = at(user, ["projects", context.repoDir, "mcpServers"]);
+        const candidates = [local ?? {}, serverMap("claude", project), serverMap("claude", user)]
+            .flatMap((map) => Object.entries(map))
+            .filter(([alias, server]) => isGroundtrack(alias, server, MCP_URL));
+        if (!candidates.length)
+            return warning("MCP server missing", setupCommand);
+        const [alias, server] = candidates[0];
+        if (!/^[a-zA-Z0-9_.-]+$/.test(alias))
+            return warning("invalid server name", setupCommand);
+        const configs = [...settings(context), user, at(user, ["projects", context.repoDir])];
+        if (configs.some((config) => typeof config === "object" &&
+            config !== null &&
+            Array.isArray(config.disabledMcpServers) &&
+            config.disabledMcpServers.includes(alias)) ||
+            (typeof server === "object" &&
+                server !== null &&
+                (("disabled" in server && server.disabled === true) ||
+                    ("enabled" in server && server.enabled === false))))
+            return warning("MCP server disabled", `claude (then re-enable ${alias} in /mcp; rerun ${setupCommand})`);
+        const binary = executable("claude", context);
+        if (!binary)
+            return warning("connection could not be checked", setupCommand);
+        const status = claudeStatus(await runner({ binary, args: ["mcp", "get", alias] }, context, false));
+        switch (status) {
+            case "connected":
+                return {};
+            case "needs_auth":
+                return warning("MCP sign-in required", `claude mcp login ${alias}`);
+            case "pending":
+                return warning("MCP server awaiting project approval", "claude (then approve Groundtrack in /mcp)");
+            case "disabled":
+                return warning("MCP server disabled in Claude Code", "claude (then re-enable Groundtrack in /mcp)");
+            case "failed":
+                return warning("MCP connection failed", setupCommand);
+            case "unknown":
+                return warning("MCP connection could not be verified", setupCommand);
+        }
+    }
+    catch {
+        // A malformed config or failed probe must never prevent Claude from starting.
+        return warning("MCP connection could not be verified", setupCommand);
+    }
+}
+export async function claudeSessionHook() {
+    try {
+        return await claudeSessionHealth(environment());
+    }
+    catch {
+        return {};
+    }
+}

package/dist/groundtrack-hook.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { hookOutput } from "./enrich-store-event.js";
+import { claudeSessionHook } from "./claude-session-health.js";
 import { packageVersion } from "./version.js";
 async function main() {
     if (process.argv[2] === "version" || process.argv[2] === "--version") {
@@ -7,6 +8,10 @@ async function main() {
         process.stdout.write(process.argv.includes("--json") ? JSON.stringify({ version }) : version);
         return;
     }
+    if (process.argv[2] === "claude-session") {
+        process.stdout.write(JSON.stringify(await claudeSessionHook()));
+        return;
+    }
     let raw = "";
     for await (const chunk of process.stdin)
         raw += chunk;

package/dist/setup/connections.d.ts

@@ -6,6 +6,9 @@ export type CommandResult = {
     stdout: string;
     stderr: string;
 };
+export type ClaudeStatus = "connected" | "pending" | "disabled" | "needs_auth" | "failed" | "unknown";
+/** Claude's `mcp get` can exit successfully even when its cached status is unhealthy. */
+export declare function claudeStatus(probe: CommandResult): ClaudeStatus;
 export type ClientCommand = {
     binary: string;
     args: string[];

package/dist/setup/connections.js

@@ -3,6 +3,21 @@ import { stripVTControlCharacters } from "node:util";
 import { configPaths, executable, readConfig, serverMap } from "./agents.js";
 import { readFile } from "./files.js";
 import { activationSteps } from "./plan.js";
+/** Claude's `mcp get` can exit successfully even when its cached status is unhealthy. */
+export function claudeStatus(probe) {
+    const output = stripVTControlCharacters(`${probe.stdout}\n${probe.stderr}`);
+    if (/pending approval|awaiting approval/i.test(output))
+        return "pending";
+    if (/status:[^\n]*(?:disabled|rejected)/i.test(output))
+        return "disabled";
+    if (/status:[^\n]*(?:needs authentication|not authenticated|needs.auth)/i.test(output))
+        return "needs_auth";
+    if (/status:\s*[^a-z0-9\n]*connected\b/i.test(output) && probe.exitCode === 0)
+        return "connected";
+    if (/status:[^\n]*(?:failed to connect|connection failed)/i.test(output))
+        return "failed";
+    return "unknown";
+}
 /** Probe output can include headers. Keep it bounded and private; never persist or print it. */
 export const runClient = (command, context, interactive) => new Promise((resolve) => {
     const child = spawn(command.binary, command.args, {
@@ -75,12 +90,12 @@ async function prepareConnection(agent, context, url, runner) {
     }
     if (agent.agent === "claude") {
         const probe = await runner({ binary, args: ["mcp", "get", agent.alias] }, context, false);
-        const output = stripVTControlCharacters(`${probe.stdout}\n${probe.stderr}`);
-        if (/pending approval|awaiting approval/i.test(output))
+        const status = claudeStatus(probe);
+        if (status === "pending")
             return { ...base, status: "needs_project_approval" };
-        if (/status:\s*[^a-z0-9\n]*connected\b/i.test(output) && probe.exitCode === 0)
+        if (status === "connected")
             return { ...base, status: "authenticated" };
-        if (/status:[^\n]*disabled/i.test(output))
+        if (status === "disabled")
             return {
                 ...base,
                 status: "failed",
@@ -96,7 +111,7 @@ async function prepareConnection(agent, context, url, runner) {
             ...base,
             status: "ready",
             command,
-            offer: !agent.existingConnection || /needs authentication|not authenticated/i.test(output),
+            offer: !agent.existingConnection || status === "needs_auth",
         };
     }
     if (agent.agent === "codex") {

package/dist/setup/plan.js

@@ -43,6 +43,43 @@ function commandHook(command) {
         statusMessage: "Adding Groundtrack session metadata",
     };
 }
+const CLAUDE_SESSION_COMMAND = "groundtrack-hook claude-session";
+const CLAUDE_SESSION_MATCHER = "startup|resume|clear|fork";
+function hasClaudeSessionHook(config) {
+    return array(at(config, ["hooks", "SessionStart"]), "SessionStart hooks").some((entry) => {
+        const group = record(entry);
+        return (group?.matcher === CLAUDE_SESSION_MATCHER &&
+            array(group.hooks, "Hook commands").some((hook) => record(hook)?.type === "command" &&
+                record(hook)?.command === CLAUDE_SESSION_COMMAND &&
+                record(hook)?.async !== true));
+    });
+}
+function upsertClaudeSessionHook(text) {
+    const groups = array(at(readJson(text), ["hooks", "SessionStart"]), "SessionStart hooks");
+    let updated = text;
+    // Only replace our own command, even when it shares a group with other hooks.
+    for (let i = groups.length - 1; i >= 0; i--) {
+        const hooks = array(record(groups[i])?.hooks, "Hook commands");
+        for (let j = hooks.length - 1; j >= 0; j--)
+            if (record(hooks[j])?.command === CLAUDE_SESSION_COMMAND)
+                updated = setJson(updated, ["hooks", "SessionStart", i, "hooks", j], undefined);
+        if (hooks.length && hooks.every((hook) => record(hook)?.command === CLAUDE_SESSION_COMMAND))
+            updated = setJson(updated, ["hooks", "SessionStart", i], undefined);
+    }
+    if (at(readJson(updated), ["hooks", "SessionStart"]) === undefined)
+        updated = setJson(updated, ["hooks", "SessionStart"], []);
+    return setJson(updated, ["hooks", "SessionStart", -1], {
+        matcher: CLAUDE_SESSION_MATCHER,
+        hooks: [
+            {
+                type: "command",
+                command: CLAUDE_SESSION_COMMAND,
+                timeout: 8,
+                statusMessage: "Checking Groundtrack connection",
+            },
+        ],
+    });
+}
 function hasHook(config, aliases, command) {
     return array(at(config, ["hooks", "PreToolUse"]), "PreToolUse hooks").some((entry) => {
         const group = record(entry);
@@ -106,6 +143,8 @@ function planClaude(files, context, aliases) {
         !hasHook(local, aliases, "groundtrack-hook claude")) {
         files.set(projectPath, upsertCommandHook(files.read(projectPath) ?? "", aliases, "groundtrack-hook claude"));
     }
+    if (![user, local, jsonFile(files, projectPath)].some(hasClaudeSessionHook))
+        files.set(projectPath, upsertClaudeSessionHook(files.read(projectPath) ?? ""));
     const bridgePath = join(context.repoDir, "CLAUDE.md");
     const bridge = files.read(bridgePath);
     if (!claudeInstructionsAreCurrent(bridge)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",

package/dist/session-import/opencode-normalizer.d.ts

@@ -1,8 +0,0 @@
-import type { SessionNormalizer } from "./format.js";
-import type { AgentSessionMetadata } from "./types.js";
-export type DecodedOpenCodeSession = Readonly<{
-    metadata: AgentSessionMetadata;
-    records: readonly unknown[];
-}>;
-export declare function decodeOpenCodeSessionExport(value: unknown): DecodedOpenCodeSession | null;
-export declare function createOpenCodeSessionNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;

package/dist/session-import/opencode-normalizer.js

@@ -1,230 +0,0 @@
-import { isSessionRecord, sessionString, } from "./canonical.js";
-import { containsInternalInstructionText, redactCredentialText, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
-function unixMillisecondsDate(value) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        return null;
-    const date = new Date(value);
-    return Number.isNaN(date.getTime()) ? null : date;
-}
-function messageTimestamp(message) {
-    const info = isSessionRecord(message.info) ? message.info : {};
-    const time = isSessionRecord(info.time) ? info.time : {};
-    return (unixMillisecondsDate(time.completed)?.toISOString() ??
-        unixMillisecondsDate(time.created)?.toISOString() ??
-        null);
-}
-export function decodeOpenCodeSessionExport(value) {
-    if (!isSessionRecord(value) || !isSessionRecord(value.info) || !Array.isArray(value.messages))
-        return null;
-    const externalSessionId = sessionString(value.info.id);
-    if (!externalSessionId)
-        return null;
-    const time = isSessionRecord(value.info.time) ? value.info.time : {};
-    const startedAt = unixMillisecondsDate(time.created);
-    const endedAt = unixMillisecondsDate(time.updated);
-    return {
-        metadata: {
-            externalSessionId,
-            timestamp: endedAt ?? startedAt,
-            cwd: sessionString(value.info.directory),
-            repositoryUrl: null,
-            repositoryBranch: null,
-            repositoryCommitSha: null,
-            originator: "opencode",
-            isSubagent: sessionString(value.info.parentID) !== null,
-            startedAt,
-            endedAt,
-        },
-        records: [
-            {
-                type: "opencode_session",
-                timestamp: startedAt?.toISOString() ?? null,
-                info: {
-                    id: value.info.id,
-                    directory: value.info.directory,
-                    model: value.info.model,
-                    version: value.info.version,
-                },
-            },
-            ...value.messages.map((message) => isSessionRecord(message)
-                ? {
-                    type: "opencode_message",
-                    timestamp: messageTimestamp(message),
-                    info: message.info,
-                    parts: message.parts,
-                }
-                : message),
-        ],
-    };
-}
-function timestampIso(value) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        return null;
-    const date = new Date(value);
-    return Number.isNaN(date.getTime()) ? null : date.toISOString();
-}
-function modelName(value) {
-    if (typeof value === "string")
-        return value || null;
-    if (!isSessionRecord(value))
-        return null;
-    const provider = sessionString(value.providerID);
-    const model = sessionString(value.modelID) ?? sessionString(value.id);
-    return provider && model ? `${provider}/${model}` : model;
-}
-function containsInternalInstructions(value) {
-    if (typeof value === "string")
-        return containsInternalInstructionText(value);
-    if (Array.isArray(value))
-        return value.some(containsInternalInstructions);
-    if (!isSessionRecord(value))
-        return false;
-    return Object.values(value).some(containsInternalInstructions);
-}
-function redactHomePaths(value) {
-    if (typeof value === "string")
-        return value
-            .replace(/\/Users\/[^/\s"'`]+/g, "~")
-            .replace(/\/home\/[^/\s"'`]+/g, "~")
-            .replace(/[A-Za-z]:\\Users\\[^\\\s"'`]+/gi, "~");
-    if (Array.isArray(value))
-        return value.map(redactHomePaths);
-    if (!isSessionRecord(value))
-        return value;
-    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, redactHomePaths(nested)]));
-}
-function sanitizeOpenCodeValue(value) {
-    return redactHomePaths(sanitizeSessionValue(value));
-}
-function safeValue(value) {
-    return containsInternalInstructions(value)
-        ? "[REDACTED INTERNAL INSTRUCTIONS]"
-        : sanitizeOpenCodeValue(value);
-}
-function partTimestamp(part, key, fallback) {
-    const state = isSessionRecord(part.state) ? part.state : {};
-    const time = isSessionRecord(state.time) ? state.time : {};
-    return timestampIso(time[key]) ?? fallback;
-}
-function normalizeOpenCodeMessage(record, entryBudget) {
-    const info = isSessionRecord(record.info) ? record.info : null;
-    const role = info ? sessionString(info.role) : null;
-    if (!info || (role !== "user" && role !== "assistant") || !Array.isArray(record.parts))
-        return { entries: [], sensitive: false, unsupported: true };
-    const occurredAt = sessionString(record.timestamp);
-    const entries = [];
-    let sensitive = false;
-    let unsupported = false;
-    for (const part of record.parts) {
-        if (entries.length > entryBudget)
-            break;
-        if (!isSessionRecord(part)) {
-            unsupported = true;
-            continue;
-        }
-        const type = sessionString(part.type);
-        if (type === "reasoning" || type === "file" || type === "patch" || type === "snapshot") {
-            sensitive = true;
-            continue;
-        }
-        if (type === "text") {
-            const text = sessionString(part.text);
-            if (!text || part.ignored === true)
-                continue;
-            if (part.synthetic === true || containsInternalInstructionText(text))
-                sensitive = true;
-            else
-                entries.push({
-                    kind: role === "user" ? "user_message" : "assistant_message",
-                    occurredAt,
-                    payload: { text: sanitizeOpenCodeValue(text) },
-                });
-            continue;
-        }
-        if (type === "tool" && role === "assistant") {
-            const toolName = sessionString(part.tool);
-            const state = isSessionRecord(part.state) ? part.state : null;
-            if (!toolName || !state) {
-                unsupported = true;
-                continue;
-            }
-            const inputContainsInternalInstructions = containsInternalInstructions(state.input);
-            sensitive ||= inputContainsInternalInstructions;
-            entries.push({
-                kind: "tool_call",
-                occurredAt: partTimestamp(part, "start", occurredAt),
-                payload: {
-                    callId: sessionString(part.callID),
-                    toolName: redactCredentialText(toolName),
-                    input: inputContainsInternalInstructions
-                        ? "[REDACTED INTERNAL INSTRUCTIONS]"
-                        : sanitizeOpenCodeValue(state.input),
-                },
-            });
-            const status = sessionString(state.status);
-            if (status === "completed" || status === "error") {
-                const output = status === "completed" ? state.output : state.error;
-                const outputContainsInternalInstructions = containsInternalInstructions(output);
-                sensitive ||= outputContainsInternalInstructions;
-                entries.push({
-                    kind: "tool_result",
-                    occurredAt: partTimestamp(part, "end", occurredAt),
-                    payload: {
-                        callId: sessionString(part.callID),
-                        output: safeValue(output),
-                        ...(status === "error" ? { isError: true } : {}),
-                    },
-                });
-            }
-            continue;
-        }
-        if (type === "step-start" ||
-            type === "step-finish" ||
-            type === "retry" ||
-            type === "compaction")
-            continue;
-        if (type === "subtask" || type === "agent")
-            sensitive = true;
-        else
-            unsupported = true;
-    }
-    const overflowed = entries.length > entryBudget;
-    return {
-        entries: overflowed ? entries.slice(0, entryBudget) : entries,
-        sensitive,
-        unsupported,
-        overflowed,
-    };
-}
-export function createOpenCodeSessionNormalizer(metadata) {
-    let model = null;
-    return {
-        normalizeRecord: (record, entryBudget = Number.POSITIVE_INFINITY) => {
-            if (record.type === "opencode_session") {
-                const info = isSessionRecord(record.info) ? record.info : {};
-                model ??= modelName(info.model);
-                return { entries: [], sensitive: false, unsupported: false };
-            }
-            if (record.type !== "opencode_message")
-                return { entries: [], sensitive: false, unsupported: true };
-            const info = isSessionRecord(record.info) ? record.info : {};
-            const provider = sessionString(info.providerID);
-            const modelId = sessionString(info.modelID);
-            model ??= provider && modelId ? `${provider}/${modelId}` : modelId;
-            return normalizeOpenCodeMessage(record, entryBudget);
-        },
-        canonicalMetadata: () => metadata
-            ? {
-                type: "session",
-                version: 1,
-                externalSessionId: metadata.externalSessionId,
-                repositoryUrl: metadata.repositoryUrl,
-                repositoryBranch: metadata.repositoryBranch,
-                repositoryCommitSha: metadata.repositoryCommitSha,
-                workingDirectory: sanitizeWorkingDirectory(metadata.cwd),
-                originator: "opencode",
-                model: model ? redactCredentialText(model) : null,
-            }
-            : null,
-    };
-}