@bridge_gpt/mcp-server 0.2.2 → 0.2.3

package/build/conductor/claude-hook.js

@@ -0,0 +1,251 @@
+/**
+ * Claude Code → conductor lifecycle hook writer.
+ *
+ * This is a dependency-light command-hook entrypoint registered into a spawned
+ * Claude worker's `.claude/settings.local.json` by `start-tickets`. Claude Code
+ * invokes it for lifecycle events (SessionStart, Stop, SubagentStop,
+ * Notification, optionally PreToolUse), passing the native hook JSON on stdin.
+ * The writer:
+ *
+ *   1. reads + parses the native Claude hook payload from stdin,
+ *   2. maps the Claude lifecycle event to a canonical conductor semantic type,
+ *   3. builds a normalized {@link ConductorEventInput} — Claude-native fields are
+ *      kept ONLY under `data.raw`, never promoted to the envelope or normalized
+ *      data fields,
+ *   4. shells out to the local `conductor emit-event` CLI using list-based
+ *      subprocess arguments (never `shell: true`) and writes the normalized
+ *      `data` object to the child's stdin via `--data-json-stdin`, so raw
+ *      payloads and possible secrets never appear in the process argument list.
+ *
+ * The hook is strictly non-blocking: unmapped events, missing conductor
+ * identity, parse failures, and emission failures all resolve to exit code `0`
+ * with at most a generic, secret-free warning so the Claude tool loop is never
+ * blocked or polluted with diagnostics.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+/** Generic, secret-free warning emitted when an emission attempt fails. */
+export const CONDUCTOR_HOOK_EMIT_FAILED_WARNING = "Warning: conductor hook emit failed.";
+/**
+ * Extract the Claude lifecycle event name from a hook payload. The verified
+ * Claude hook contract field (`hook_event_name`) takes priority; a small set of
+ * defensive alternatives is accepted only as internal parsing inputs in case the
+ * field name drifts. Returns `null` when no recognizable name is present.
+ */
+export function resolveClaudeHookEventName(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return null;
+    }
+    const record = payload;
+    // Verified contract field first, then defensive-only alternatives.
+    const candidates = ["hook_event_name", "hookEventName", "event_name", "event"];
+    for (const key of candidates) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+/**
+ * Map a Claude lifecycle event name to a canonical conductor semantic type.
+ * Unknown events map to `null` (the caller then skips emission).
+ */
+export function mapClaudeHookEventToSemanticType(eventName) {
+    switch (eventName) {
+        case "SessionStart":
+            return "run.started";
+        case "Stop":
+            return "run.stopped";
+        case "SubagentStop":
+            return "run.stopped";
+        case "Notification":
+            return "agent.notification";
+        case "PreToolUse":
+            return "tool.intent";
+        default:
+            return null;
+    }
+}
+/** Conductor identity env required before any worker event may be emitted. */
+const REQUIRED_IDENTITY_ENV = [
+    "BAPI_CONDUCTOR_RUN_ID",
+    "BAPI_CONDUCTOR_WORKER_ID",
+    "BAPI_CONDUCTOR_TICKET_KEY",
+    "BAPI_CONDUCTOR_WORKTREE_PATH",
+];
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Build a normalized {@link ConductorEventInput} from a Claude hook payload and
+ * the process environment, or `null` when the event is unmapped or the
+ * conductor identity is incomplete.
+ *
+ * Identity gating: requires `BAPI_CONDUCTOR_ENABLED=1` and all of
+ * {@link REQUIRED_IDENTITY_ENV}. Any missing value returns `null` WITHOUT
+ * emitting — this prevents accidental emissions from unrelated worktrees that
+ * happen to have the hook on PATH.
+ *
+ * Secret/normalization boundary: the COMPLETE native Claude payload is placed
+ * only under `data.raw`. No Claude-native field (session id, transcript path,
+ * tool name, tool input, notification text) is promoted to the envelope or to
+ * any normalized `data` field.
+ */
+export function buildClaudeHookConductorEvent(payload, env) {
+    const eventName = resolveClaudeHookEventName(payload);
+    const type = mapClaudeHookEventToSemanticType(eventName);
+    if (type === null) {
+        return null;
+    }
+    if (env.BAPI_CONDUCTOR_ENABLED !== "1") {
+        return null;
+    }
+    for (const key of REQUIRED_IDENTITY_ENV) {
+        if (!nonEmpty(env[key])) {
+            return null;
+        }
+    }
+    const ticketKey = env.BAPI_CONDUCTOR_TICKET_KEY.trim();
+    const worktreePath = env.BAPI_CONDUCTOR_WORKTREE_PATH.trim();
+    const details = {
+        ticket_key: ticketKey,
+        worktree_path: worktreePath,
+    };
+    if (nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME)) {
+        details.repo = env.BAPI_CONDUCTOR_REPO_NAME.trim();
+    }
+    // The native payload lives ONLY under data.raw. Wrap non-object payloads so the
+    // raw contract is always an object, never echoing native fields elsewhere.
+    const raw = payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : { payload };
+    return {
+        source: "claude-code",
+        type,
+        subject: ticketKey,
+        run_id: env.BAPI_CONDUCTOR_RUN_ID.trim(),
+        worker_id: env.BAPI_CONDUCTOR_WORKER_ID.trim(),
+        producer: "claude-code-hook",
+        observed_via: "claude-code-hook",
+        data: {
+            details,
+            raw,
+        },
+    };
+}
+/**
+ * Build the list-based `emit-event` arguments for a normalized event. The
+ * normalized `data` object is intentionally NOT serialized into the argument
+ * list — it is delivered to the child via stdin through `--data-json-stdin`, so
+ * raw payloads/secrets never reach the process table.
+ */
+export function buildConductorEmitEventArgs(event) {
+    const args = ["--type", event.type, "--source", event.source];
+    if (nonEmpty(event.subject ?? undefined))
+        args.push("--subject", event.subject);
+    if (nonEmpty(event.run_id ?? undefined))
+        args.push("--run-id", event.run_id);
+    if (nonEmpty(event.worker_id ?? undefined))
+        args.push("--worker-id", event.worker_id);
+    if (nonEmpty(event.producer ?? undefined))
+        args.push("--producer", event.producer);
+    if (nonEmpty(event.observed_via ?? undefined)) {
+        args.push("--observed-via", event.observed_via);
+    }
+    args.push("--data-json-stdin", "--json");
+    return args;
+}
+/**
+ * Resolve how to invoke `conductor emit-event`. Prefers `BAPI_CONDUCTOR_CLI_FILE`
+ * (run via the current Node executable so no global install is required),
+ * otherwise falls back to `BAPI_CONDUCTOR_BIN` or the bare `conductor` binary on
+ * PATH. `emitArgs` are appended after the `emit-event` subcommand.
+ */
+export function resolveConductorEmitCommand(env, emitArgs) {
+    const cliFile = env.BAPI_CONDUCTOR_CLI_FILE;
+    if (nonEmpty(cliFile)) {
+        return {
+            command: process.execPath,
+            args: [cliFile.trim(), "emit-event", ...emitArgs],
+        };
+    }
+    const bin = nonEmpty(env.BAPI_CONDUCTOR_BIN) ? env.BAPI_CONDUCTOR_BIN.trim() : "conductor";
+    return { command: bin, args: ["emit-event", ...emitArgs] };
+}
+const defaultConductorSpawn = (command, args, input) => {
+    const result = spawnSync(command, args, {
+        input,
+        encoding: "utf-8",
+        // Never use a shell: list args + stdin keep raw payloads/secrets out of any
+        // shell-interpreted command string.
+        shell: false,
+    });
+    return { status: result.status, error: result.error };
+};
+/**
+ * Emit a normalized conductor event by shelling to the local `conductor`
+ * CLI. The normalized `data` object is written to the child's stdin; envelope
+ * fields are passed as list arguments. Returns `true` on a clean exit, `false`
+ * on any spawn error or non-zero exit. Never throws.
+ */
+export function emitClaudeHookEventWithConductorCli(event, deps = {}) {
+    const env = deps.env ?? process.env;
+    const spawn = deps.spawn ?? defaultConductorSpawn;
+    const emitArgs = buildConductorEmitEventArgs(event);
+    const { command, args } = resolveConductorEmitCommand(env, emitArgs);
+    // Only the normalized data object crosses the stdin boundary (mirrors the
+    // CLI's --data-json-stdin contract); raw payload material is inside it.
+    const stdinPayload = JSON.stringify(event.data ?? {});
+    try {
+        const result = spawn(command, args, stdinPayload);
+        if (result.error)
+            return false;
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Full hook runner: read the native Claude payload from stdin, map/normalize it,
+ * and emit via the conductor CLI. ALWAYS returns `0` (success) — unmapped
+ * events, missing identity, invalid JSON, and emission failures are swallowed so
+ * the Claude tool loop is never blocked. Any warning is generic and secret-free.
+ */
+export function runClaudeConductorHookCli(deps = {}) {
+    const env = deps.env ?? process.env;
+    const readStdin = deps.readStdin ?? (() => readStdinSync());
+    const warn = deps.warn ?? ((m) => process.stderr.write(`${m}\n`));
+    let payload;
+    try {
+        const raw = readStdin();
+        payload = JSON.parse(raw);
+    }
+    catch {
+        // Invalid/empty hook JSON: warn generically (no raw fragment) and exit 0.
+        warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+        return 0;
+    }
+    let event;
+    try {
+        event = buildClaudeHookConductorEvent(payload, env);
+    }
+    catch {
+        warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+        return 0;
+    }
+    // Unmapped event or incomplete identity: nothing to emit, silently succeed.
+    if (event === null) {
+        return 0;
+    }
+    const ok = emitClaudeHookEventWithConductorCli(event, { env, spawn: deps.spawn });
+    if (!ok) {
+        warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+    }
+    return 0;
+}
+/** Blocking read of the full stdin contents (fd 0). */
+function readStdinSync() {
+    return readFileSync(0, "utf-8");
+}