selftune 0.1.0

package/cli/selftune/evolution/validate-proposal.ts

@@ -0,0 +1,137 @@
+/**
+ * validate-proposal.ts
+ *
+ * Validates an evolution proposal by running trigger checks against an eval set.
+ * Compares trigger accuracy between the original and proposed skill descriptions
+ * to determine whether the proposal is an improvement.
+ */
+
+import type { EvalEntry, EvolutionProposal } from "../types.js";
+import { callLlm } from "../utils/llm-call.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  proposal_id: string;
+  before_pass_rate: number;
+  after_pass_rate: number;
+  improved: boolean;
+  regressions: EvalEntry[]; // passed before, fail after
+  new_passes: EvalEntry[]; // failed before, pass after
+  net_change: number; // after - before pass rate
+}
+
+// ---------------------------------------------------------------------------
+// Prompt building
+// ---------------------------------------------------------------------------
+
+/** Build the trigger check prompt for the LLM. */
+export function buildTriggerCheckPrompt(description: string, query: string): string {
+  return [
+    "Given this skill description, would the following user query trigger this skill?",
+    "Respond YES or NO only.",
+    "",
+    "Skill description:",
+    description,
+    "",
+    "User query:",
+    query,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Response parsing
+// ---------------------------------------------------------------------------
+
+/** Parse YES/NO from LLM response. */
+export function parseTriggerResponse(response: string): boolean {
+  const normalized = response.trim().toUpperCase();
+  if (normalized.startsWith("YES")) return true;
+  if (normalized.startsWith("NO")) return false;
+  return false; // conservative default
+}
+
+// ---------------------------------------------------------------------------
+// Proposal validation
+// ---------------------------------------------------------------------------
+
+/** Validate a proposal by running trigger checks against the eval set. */
+export async function validateProposal(
+  proposal: EvolutionProposal,
+  evalSet: EvalEntry[],
+  mode: "agent" | "api",
+  agent?: string,
+): Promise<ValidationResult> {
+  if (evalSet.length === 0) {
+    return {
+      proposal_id: proposal.proposal_id,
+      before_pass_rate: 0,
+      after_pass_rate: 0,
+      improved: false,
+      regressions: [],
+      new_passes: [],
+      net_change: 0,
+    };
+  }
+
+  const systemPrompt = "You are an evaluation assistant. Answer only YES or NO.";
+  const regressions: EvalEntry[] = [];
+  const newPasses: EvalEntry[] = [];
+  let beforePassed = 0;
+  let afterPassed = 0;
+
+  for (const entry of evalSet) {
+    // Check with original description
+    const beforePrompt = buildTriggerCheckPrompt(proposal.original_description, entry.query);
+    const beforeRaw = await callLlm(systemPrompt, beforePrompt, mode, agent);
+    const beforeTriggered = parseTriggerResponse(beforeRaw);
+    const beforePass =
+      (entry.should_trigger && beforeTriggered) || (!entry.should_trigger && !beforeTriggered);
+
+    // Check with proposed description
+    const afterPrompt = buildTriggerCheckPrompt(proposal.proposed_description, entry.query);
+    const afterRaw = await callLlm(systemPrompt, afterPrompt, mode, agent);
+    const afterTriggered = parseTriggerResponse(afterRaw);
+    const afterPass =
+      (entry.should_trigger && afterTriggered) || (!entry.should_trigger && !afterTriggered);
+
+    if (beforePass) beforePassed++;
+    if (afterPass) afterPassed++;
+
+    // Regression: passed before, fails after
+    if (beforePass && !afterPass) {
+      regressions.push(entry);
+    }
+
+    // New pass: failed before, passes after
+    if (!beforePass && afterPass) {
+      newPasses.push(entry);
+    }
+  }
+
+  const total = evalSet.length;
+  const beforePassRate = beforePassed / total;
+  const afterPassRate = afterPassed / total;
+  const netChange = afterPassRate - beforePassRate;
+
+  // A proposal is improved when ALL of:
+  //   - after_pass_rate > before_pass_rate
+  //   - regressions count < 5% of total eval entries
+  //   - Either net improvement >= 0.10 OR new_passes.length >= 2
+  const improved =
+    afterPassRate > beforePassRate &&
+    regressions.length < total * 0.05 &&
+    (netChange >= 0.1 || newPasses.length >= 2);
+
+  return {
+    proposal_id: proposal.proposal_id,
+    before_pass_rate: beforePassRate,
+    after_pass_rate: afterPassRate,
+    improved,
+    regressions,
+    new_passes: newPasses,
+    net_change: netChange,
+  };
+}

package/cli/selftune/grading/grade-session.ts

@@ -0,0 +1,459 @@
+#!/usr/bin/env bun
+/**
+ * grade-session.ts
+ *
+ * Rubric-based grader for Claude Code skill sessions.
+ * Migrated from grade_session.py.
+ *
+ * Two modes:
+ *   1. --use-agent  (default when no ANTHROPIC_API_KEY) — invokes installed agent CLI
+ *   2. --use-api    (default when ANTHROPIC_API_KEY set) — calls Anthropic API directly
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { TELEMETRY_LOG } from "../constants.js";
+import type {
+  ExecutionMetrics,
+  GraderOutput,
+  GradingResult,
+  SessionTelemetryRecord,
+} from "../types.js";
+import { readJsonl } from "../utils/jsonl.js";
+import {
+  detectAgent as _detectAgent,
+  stripMarkdownFences as _stripMarkdownFences,
+  callViaAgent,
+  callViaApi,
+} from "../utils/llm-call.js";
+import { readExcerpt } from "../utils/transcript.js";
+
+// Re-export for backward compatibility
+export { detectAgent, stripMarkdownFences } from "../utils/llm-call.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const MAX_TRANSCRIPT_LENGTH = 50000;
+
+// ---------------------------------------------------------------------------
+// Grader system prompt
+// ---------------------------------------------------------------------------
+
+export const GRADER_SYSTEM = `You are a rigorous skill session evaluator. You receive:
+1. Expectations to grade (things that should be true)
+2. Process telemetry: tool calls, bash commands, skills triggered, errors
+3. A transcript excerpt showing what happened
+
+Grade each expectation and output ONLY valid JSON matching this schema:
+{
+  "expectations": [
+    {"text": "...", "passed": true/false, "evidence": "specific quote or metric"}
+  ],
+  "summary": {"passed": N, "failed": N, "total": N, "pass_rate": 0.0},
+  "claims": [
+    {"claim": "...", "type": "factual|process|quality", "verified": true/false, "evidence": "..."}
+  ],
+  "eval_feedback": {
+    "suggestions": [{"assertion": "...", "reason": "..."}],
+    "overall": "one sentence"
+  }
+}
+
+Rules:
+- PASS only when there is clear, specific evidence — not assumptions
+- FAIL when evidence is absent or contradictory
+- Cite exact quotes or specific metric values
+- Extract 2-4 implicit claims from the transcript and verify them
+- Suggest eval improvements only for clear gaps`;
+
+// ---------------------------------------------------------------------------
+// Data lookup helpers
+// ---------------------------------------------------------------------------
+
+export function findSession(
+  records: SessionTelemetryRecord[],
+  sessionId: string,
+): SessionTelemetryRecord | null {
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (records[i].session_id === sessionId) return records[i];
+  }
+  return null;
+}
+
+export function latestSessionForSkill(
+  telemetry: SessionTelemetryRecord[],
+  skillName: string,
+): SessionTelemetryRecord | null {
+  for (let i = telemetry.length - 1; i >= 0; i--) {
+    if (telemetry[i].skills_triggered?.includes(skillName)) return telemetry[i];
+  }
+  return null;
+}
+
+export function loadExpectationsFromEvalsJson(evalsJsonPath: string, evalId: number): string[] {
+  let data: unknown;
+  try {
+    data = JSON.parse(readFileSync(evalsJsonPath, "utf-8"));
+  } catch (err) {
+    throw new Error(
+      `Failed to read or parse evals JSON at ${evalsJsonPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error(
+      `Invalid evals JSON at ${evalsJsonPath}: expected a top-level object, got ${Array.isArray(data) ? "array" : typeof data}`,
+    );
+  }
+
+  const record = data as Record<string, unknown>;
+  if (!Array.isArray(record.evals)) {
+    throw new Error(
+      `Invalid evals JSON at ${evalsJsonPath}: expected "evals" to be an array, got ${typeof record.evals}`,
+    );
+  }
+
+  for (const ev of record.evals) {
+    if (typeof ev !== "object" || ev === null || Array.isArray(ev)) {
+      throw new Error(
+        `Invalid eval entry in ${evalsJsonPath}: expected an object, got ${Array.isArray(ev) ? "array" : typeof ev}`,
+      );
+    }
+    const entry = ev as Record<string, unknown>;
+    if (entry.id === evalId) {
+      if (entry.expectations === undefined || entry.expectations === null) {
+        return [];
+      }
+      if (!Array.isArray(entry.expectations)) {
+        throw new Error(
+          `Invalid eval entry (id=${evalId}) in ${evalsJsonPath}: expected "expectations" to be an array, got ${typeof entry.expectations}`,
+        );
+      }
+      for (let i = 0; i < entry.expectations.length; i++) {
+        if (typeof entry.expectations[i] !== "string") {
+          throw new Error(
+            `Invalid eval entry (id=${evalId}) in ${evalsJsonPath}: expectations[${i}] must be a string, got ${typeof entry.expectations[i]}`,
+          );
+        }
+      }
+      return entry.expectations as string[];
+    }
+  }
+  throw new Error(`Eval ID ${evalId} not found in ${evalsJsonPath}`);
+}
+
+// ---------------------------------------------------------------------------
+// Execution metrics
+// ---------------------------------------------------------------------------
+
+export function buildExecutionMetrics(telemetry: SessionTelemetryRecord): ExecutionMetrics {
+  return {
+    tool_calls: telemetry.tool_calls ?? {},
+    total_tool_calls: telemetry.total_tool_calls ?? 0,
+    total_steps: telemetry.assistant_turns ?? 0,
+    bash_commands_run: (telemetry.bash_commands ?? []).length,
+    errors_encountered: telemetry.errors_encountered ?? 0,
+    skills_triggered: telemetry.skills_triggered ?? [],
+    transcript_chars: telemetry.transcript_chars ?? 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Prompt building
+// ---------------------------------------------------------------------------
+
+export function buildGradingPrompt(
+  expectations: string[],
+  telemetry: SessionTelemetryRecord,
+  transcriptExcerpt: string,
+  skillName: string,
+): string {
+  const toolSummary = JSON.stringify(telemetry.tool_calls ?? {}, null, 2);
+  const commands = telemetry.bash_commands ?? [];
+  const cmdSummary =
+    commands
+      .slice(0, 20)
+      .map((c) => `  $ ${c.slice(0, 120)}`)
+      .join("\n") || "  (none)";
+
+  const expectationsList = expectations.map((e, i) => `${i + 1}. ${e}`).join("\n");
+
+  const excerpt =
+    transcriptExcerpt.length > MAX_TRANSCRIPT_LENGTH
+      ? transcriptExcerpt.slice(0, MAX_TRANSCRIPT_LENGTH)
+      : transcriptExcerpt;
+
+  return `Skill: ${skillName}
+
+=== PROCESS TELEMETRY ===
+Skills triggered: ${JSON.stringify(telemetry.skills_triggered ?? [])}
+Assistant turns: ${telemetry.assistant_turns ?? "?"}
+Errors: ${telemetry.errors_encountered ?? "?"}
+Total tool calls: ${telemetry.total_tool_calls ?? "?"}
+
+Tool breakdown:
+${toolSummary}
+
+Bash commands:
+${cmdSummary}
+
+=== TRANSCRIPT EXCERPT ===
+${excerpt}
+
+=== EXPECTATIONS ===
+${expectationsList}
+
+Grade each expectation. Output JSON only.`;
+}
+
+// ---------------------------------------------------------------------------
+// Grading via agent subprocess
+// ---------------------------------------------------------------------------
+
+export async function gradeViaAgent(prompt: string, agent: string): Promise<GraderOutput> {
+  const raw = await callViaAgent(GRADER_SYSTEM, prompt, agent);
+  try {
+    return JSON.parse(_stripMarkdownFences(raw)) as GraderOutput;
+  } catch (err) {
+    throw new Error(
+      `gradeViaAgent: failed to parse LLM output as JSON. Raw (truncated): ${raw.slice(0, 200)}`,
+      { cause: err },
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Grading via direct Anthropic API
+// ---------------------------------------------------------------------------
+
+export async function gradeViaApi(prompt: string): Promise<GraderOutput> {
+  const raw = await callViaApi(GRADER_SYSTEM, prompt);
+  try {
+    return JSON.parse(_stripMarkdownFences(raw)) as GraderOutput;
+  } catch (err) {
+    throw new Error(
+      `gradeViaApi: failed to parse LLM output as JSON. Raw (truncated): ${raw.slice(0, 200)}`,
+      { cause: err },
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Result assembly
+// ---------------------------------------------------------------------------
+
+export function assembleResult(
+  graderOutput: GraderOutput,
+  telemetry: SessionTelemetryRecord,
+  sessionId: string,
+  skillName: string,
+  transcriptPath: string,
+): GradingResult {
+  return {
+    session_id: sessionId ?? "unknown",
+    skill_name: skillName ?? "unknown",
+    transcript_path: transcriptPath ?? "",
+    graded_at: new Date().toISOString(),
+    expectations: graderOutput?.expectations ?? [],
+    summary: graderOutput?.summary ?? { passed: 0, failed: 0, total: 0, pass_rate: 0 },
+    execution_metrics: buildExecutionMetrics(telemetry ?? ({} as SessionTelemetryRecord)),
+    claims: graderOutput?.claims ?? [],
+    eval_feedback: graderOutput?.eval_feedback ?? { suggestions: [], overall: "" },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Summary printer
+// ---------------------------------------------------------------------------
+
+function printSummary(result: GradingResult): void {
+  const { summary } = result;
+  const rate = summary.pass_rate ?? 0;
+  console.log(`\nResults: ${summary.passed}/${summary.total} passed (${Math.round(rate * 100)}%)`);
+  for (const exp of result.expectations ?? []) {
+    const icon = exp.passed ? "\u2713" : "\u2717";
+    console.log(`  ${icon} ${String(exp.text ?? "").slice(0, 70)}`);
+    if (!exp.passed) {
+      console.log(`      -> ${String(exp.evidence ?? "").slice(0, 100)}`);
+    }
+  }
+
+  const feedback = result.eval_feedback;
+  if (feedback.suggestions?.length) {
+    console.log(`\nEval feedback: ${feedback.overall}`);
+    for (const s of feedback.suggestions) {
+      console.log(`  * ${String(s.reason ?? "").slice(0, 100)}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+export async function cliMain(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      skill: { type: "string" },
+      expectations: { type: "string", multiple: true },
+      "evals-json": { type: "string" },
+      "eval-id": { type: "string" },
+      "session-id": { type: "string" },
+      transcript: { type: "string" },
+      "telemetry-log": { type: "string", default: TELEMETRY_LOG },
+      output: { type: "string", default: "grading.json" },
+      "use-agent": { type: "boolean", default: false },
+      "use-api": { type: "boolean", default: false },
+      agent: { type: "string" },
+      "show-transcript": { type: "boolean", default: false },
+    },
+    strict: true,
+  });
+
+  const skill = values.skill;
+  if (!skill) {
+    console.error("[ERROR] --skill is required");
+    process.exit(1);
+  }
+
+  // --- Determine mode ---
+  const hasApiKey = Boolean(process.env.ANTHROPIC_API_KEY);
+  let mode: "agent" | "api";
+  let agent: string | null = null;
+
+  if (values["use-api"]) {
+    mode = "api";
+  } else if (values["use-agent"]) {
+    mode = "agent";
+  } else {
+    const availableAgent = _detectAgent();
+    if (availableAgent) {
+      mode = "agent";
+    } else if (hasApiKey) {
+      mode = "api";
+    } else {
+      console.error(
+        "[ERROR] No agent CLI (claude/codex/opencode) found in PATH " +
+          "and ANTHROPIC_API_KEY not set.\n" +
+          "Install Claude Code, Codex, or OpenCode, or set ANTHROPIC_API_KEY.",
+      );
+      process.exit(1);
+    }
+  }
+
+  if (mode === "agent") {
+    const validAgents = ["claude", "codex", "opencode"];
+    if (values.agent && validAgents.includes(values.agent)) {
+      agent = values.agent;
+    } else {
+      agent = _detectAgent();
+    }
+    if (!agent) {
+      console.error(
+        "[ERROR] --use-agent specified but no agent found in PATH.\n" +
+          "Install claude, codex, or opencode, or use --use-api instead.",
+      );
+      process.exit(1);
+    }
+    console.error(`[INFO] Grading via agent: ${agent}`);
+  } else {
+    console.error("[INFO] Grading via direct Anthropic API");
+  }
+
+  // --- Resolve expectations ---
+  let expectations: string[] = [];
+  if (values["evals-json"] && values["eval-id"] != null) {
+    const evalIdNum = Number(values["eval-id"]);
+    if (!Number.isFinite(evalIdNum) || !Number.isInteger(evalIdNum)) {
+      console.error(`[ERROR] --eval-id must be a finite integer, got: ${values["eval-id"]}`);
+      process.exit(1);
+    }
+    expectations = loadExpectationsFromEvalsJson(values["evals-json"], evalIdNum);
+  } else if (values.expectations?.length) {
+    expectations = values.expectations;
+  } else {
+    console.error("[ERROR] Provide --expectations or --evals-json + --eval-id");
+    process.exit(1);
+  }
+
+  // --- Resolve session ---
+  let telemetry = {} as SessionTelemetryRecord;
+  let transcriptPath = "";
+  let sessionId = "unknown";
+
+  const telemetryLog = values["telemetry-log"] ?? TELEMETRY_LOG;
+  const telRecords = readJsonl<SessionTelemetryRecord>(telemetryLog);
+
+  if (values.transcript) {
+    transcriptPath = values.transcript;
+    for (let i = telRecords.length - 1; i >= 0; i--) {
+      if (telRecords[i].transcript_path === transcriptPath) {
+        telemetry = telRecords[i];
+        sessionId = telRecords[i].session_id ?? "unknown";
+        break;
+      }
+    }
+  } else if (values["session-id"]) {
+    sessionId = values["session-id"];
+    telemetry = findSession(telRecords, sessionId) ?? ({} as SessionTelemetryRecord);
+    transcriptPath = telemetry.transcript_path ?? "";
+  } else {
+    telemetry = latestSessionForSkill(telRecords, skill) ?? ({} as SessionTelemetryRecord);
+    if (telemetry.session_id) {
+      sessionId = telemetry.session_id;
+      transcriptPath = telemetry.transcript_path ?? "";
+      console.error(`[INFO] Grading most recent '${skill}' session: ${sessionId}`);
+    } else {
+      console.error(`[WARN] No telemetry for skill '${skill}'. Is session_stop_hook installed?`);
+    }
+  }
+
+  const transcriptExcerpt = transcriptPath ? readExcerpt(transcriptPath) : "(no transcript)";
+
+  if (values["show-transcript"]) {
+    console.log("=== TRANSCRIPT EXCERPT ===");
+    console.log(transcriptExcerpt);
+    console.log("==========================\n");
+  }
+
+  // --- Build prompt and grade ---
+  const prompt = buildGradingPrompt(expectations, telemetry, transcriptExcerpt, skill);
+
+  console.error(`Grading ${expectations.length} expectations for skill '${skill}'...`);
+
+  let graderOutput: GraderOutput;
+  try {
+    if (mode === "agent") {
+      graderOutput = await gradeViaAgent(prompt, agent as string);
+    } else {
+      graderOutput = await gradeViaApi(prompt);
+    }
+  } catch (e) {
+    console.error(`[ERROR] Grading failed: ${e}`);
+    process.exit(1);
+  }
+
+  const result = assembleResult(graderOutput, telemetry, sessionId, skill, transcriptPath);
+
+  const outputPath = values.output ?? "grading.json";
+  const outputDir = dirname(outputPath);
+  if (outputDir !== ".") {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  writeFileSync(outputPath, JSON.stringify(result, null, 2), "utf-8");
+
+  printSummary(result);
+  console.log(`\nWrote ${outputPath}`);
+}
+
+// Guard: only run when invoked directly
+if (import.meta.main) {
+  cliMain().catch((err) => {
+    console.error(`[FATAL] ${err}`);
+    process.exit(1);
+  });
+}

package/cli/selftune/hooks/prompt-log.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+/**
+ * Claude Code UserPromptSubmit hook: prompt-log.ts
+ *
+ * Fires on every user message before Claude processes it.
+ * Logs the query to ~/.claude/all_queries_log.jsonl so that
+ * hooks-to-evals can identify prompts that did NOT trigger
+ * a skill — the raw material for false-negative eval entries.
+ */
+
+import { QUERY_LOG, SKIP_PREFIXES } from "../constants.js";
+import type { PromptSubmitPayload, QueryLogRecord } from "../types.js";
+import { appendJsonl } from "../utils/jsonl.js";
+
+/**
+ * Core processing logic, exported for testability.
+ * Returns the record that was appended, or null if skipped.
+ */
+export function processPrompt(
+  payload: PromptSubmitPayload,
+  logPath: string = QUERY_LOG,
+): QueryLogRecord | null {
+  const query = (payload.user_prompt ?? "").trim();
+
+  if (!query) return null;
+
+  // Skip automated/tool messages
+  if (SKIP_PREFIXES.some((p) => query.startsWith(p))) return null;
+
+  // Skip very short noise (single chars, punctuation)
+  if (query.length < 4) return null;
+
+  const record: QueryLogRecord = {
+    timestamp: new Date().toISOString(),
+    session_id: payload.session_id ?? "unknown",
+    query,
+  };
+
+  appendJsonl(logPath, record);
+  return record;
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    const payload: PromptSubmitPayload = JSON.parse(await Bun.stdin.text());
+    processPrompt(payload);
+  } catch {
+    // silent — hooks must never block Claude
+  }
+  process.exit(0);
+}

package/cli/selftune/hooks/session-stop.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+/**
+ * Claude Code Stop hook: session-stop.ts
+ *
+ * Fires when a Claude Code session ends. Reads the session's transcript JSONL
+ * and extracts process-level telemetry (tool calls, errors, skills triggered, etc).
+ * Appends one record per session to ~/.claude/session_telemetry_log.jsonl.
+ */
+
+import { TELEMETRY_LOG } from "../constants.js";
+import type { SessionTelemetryRecord, StopPayload } from "../types.js";
+import { appendJsonl } from "../utils/jsonl.js";
+import { parseTranscript } from "../utils/transcript.js";
+
+/**
+ * Core processing logic, exported for testability.
+ * Returns the record that was appended.
+ */
+export function processSessionStop(
+  payload: StopPayload,
+  logPath: string = TELEMETRY_LOG,
+): SessionTelemetryRecord {
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+  const cwd = typeof payload.cwd === "string" ? payload.cwd : "";
+
+  const metrics = parseTranscript(transcriptPath);
+
+  const record: SessionTelemetryRecord = {
+    timestamp: new Date().toISOString(),
+    session_id: sessionId,
+    cwd,
+    transcript_path: transcriptPath,
+    source: "claude_code",
+    ...metrics,
+  };
+
+  appendJsonl(logPath, record);
+  return record;
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    const payload: StopPayload = JSON.parse(await Bun.stdin.text());
+    processSessionStop(payload);
+  } catch (err) {
+    // silent — hooks must never block Claude
+    if (process.env.DEBUG || process.env.NODE_ENV === "development") {
+      console.error("session-stop hook failed:", err);
+    }
+  }
+  process.exit(0);
+}