selftune 0.2.15 → 0.2.18

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

@@ -7,7 +7,7 @@
  */
 
 import type { EvalEntry, EvolutionProposal, InvocationTypeScores } from "../types.js";
-import { callLlm } from "../utils/llm-call.js";
+import { callLlm, type EffortLevel } from "../utils/llm-call.js";
 import {
   buildBatchTriggerCheckPrompt,
   buildTriggerCheckPrompt,
@@ -52,6 +52,7 @@ export async function validateProposalSequential(
   evalSet: EvalEntry[],
   agent: string,
   modelFlag?: string,
+  effort?: EffortLevel,
 ): Promise<ValidationResult> {
   if (evalSet.length === 0) {
     return {
@@ -76,14 +77,14 @@ export async function validateProposalSequential(
   for (const entry of evalSet) {
     // Check with original description
     const beforePrompt = buildTriggerCheckPrompt(proposal.original_description, entry.query);
-    const beforeRaw = await callLlm(systemPrompt, beforePrompt, agent, modelFlag);
+    const beforeRaw = await callLlm(systemPrompt, beforePrompt, agent, modelFlag, effort);
     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, agent, modelFlag);
+    const afterRaw = await callLlm(systemPrompt, afterPrompt, agent, modelFlag, effort);
     const afterTriggered = parseTriggerResponse(afterRaw);
     const afterPass =
       (entry.should_trigger && afterTriggered) || (!entry.should_trigger && !afterTriggered);
@@ -208,6 +209,7 @@ export async function validateProposalBatched(
   evalSet: EvalEntry[],
   agent: string,
   modelFlag?: string,
+  effort?: EffortLevel,
 ): Promise<ValidationResult> {
   if (evalSet.length === 0) {
     return {
@@ -242,8 +244,8 @@ export async function validateProposalBatched(
     // Run VALIDATION_RUNS times in parallel and majority-vote to reduce LLM variance
     const allCalls: Promise<string>[] = [];
     for (let r = 0; r < VALIDATION_RUNS; r++) {
-      allCalls.push(callLlm(systemPrompt, beforePrompt, agent, modelFlag));
-      allCalls.push(callLlm(systemPrompt, afterPrompt, agent, modelFlag));
+      allCalls.push(callLlm(systemPrompt, beforePrompt, agent, modelFlag, effort));
+      allCalls.push(callLlm(systemPrompt, afterPrompt, agent, modelFlag, effort));
     }
     const allRaw = await Promise.all(allCalls);
 
@@ -353,6 +355,7 @@ export async function validateProposal(
   evalSet: EvalEntry[],
   agent: string,
   modelFlag?: string,
+  effort?: EffortLevel,
 ): Promise<ValidationResult> {
-  return validateProposalBatched(proposal, evalSet, agent, modelFlag);
+  return validateProposalBatched(proposal, evalSet, agent, modelFlag, effort);
 }

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

@@ -26,6 +26,7 @@ import type {
   GradingExpectation,
   GradingResult,
   SessionTelemetryRecord,
+  SessionType,
   SkillUsageRecord,
 } from "../types.js";
 import { CLIError, handleCLIError } from "../utils/cli-error.js";
@@ -420,6 +421,8 @@ export function buildExecutionMetrics(telemetry: SessionTelemetryRecord): Execut
     errors_encountered: telemetry.errors_encountered ?? 0,
     skills_triggered: telemetry.skills_triggered ?? [],
     transcript_chars: telemetry.transcript_chars ?? 0,
+    artifact_count: telemetry.artifact_count,
+    session_type: telemetry.session_type,
   };
 }
 
@@ -481,13 +484,30 @@ export function buildGradingPrompt(
       ? transcriptExcerpt.slice(0, MAX_TRANSCRIPT_LENGTH)
       : transcriptExcerpt;
 
+  const sessionType: SessionType = (telemetry.session_type as SessionType) ?? "mixed";
+  const SESSION_TYPE_CONTEXT: Record<SessionType, string> = {
+    dev: "This is a development session — code output and commits are expected productivity signals.",
+    research:
+      "This is a research session — information gathering and synthesis are the primary outputs, not code changes.",
+    content:
+      "This is a content/writing session — document creation is the primary output, not code commits.",
+    mixed:
+      "This is a mixed session — evaluate based on what was actually accomplished, not code-specific metrics.",
+  };
+  const sessionTypeContext = SESSION_TYPE_CONTEXT[sessionType] ?? SESSION_TYPE_CONTEXT.mixed;
+
   return `Skill: ${skillName}
 
+=== SESSION CONTEXT ===
+Session type: ${sessionType}
+${sessionTypeContext}
+
 === 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 ?? "?"}
+Artifacts produced: ${telemetry.artifact_count ?? "?"}
 
 Tool breakdown:
 ${toolSummary}

package/cli/selftune/hooks/commit-track.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse hook: commit-track.ts
+ *
+ * Detects git commits in Bash tool output and records commit SHA, title,
+ * branch, and session ID for session-to-commit traceability.
+ *
+ * Fail-open: exits 0 on all errors. Never blocks the host agent.
+ */
+
+import { execSync } from "node:child_process";
+
+import type { PostToolUsePayload } from "../types.js";
+
+// -- Regex patterns (pre-compiled at module load) ----------------------------
+
+/** Matches git commands that produce commits. */
+const GIT_COMMIT_CMD_RE = /\bgit\s+(commit|merge|cherry-pick|revert)\b/;
+
+/**
+ * Matches the standard git commit output format: [branch SHA] title
+ * Supports optional parenthetical like (root-commit).
+ * Branch names can contain word chars, slashes, dots, hyphens, plus signs.
+ */
+const COMMIT_OUTPUT_RE = /\[([\w/.+-]+)(?:\s+\([^)]+\))?\s+([a-f0-9]{7,40})\]\s+(.+)/;
+
+// -- Pure extraction functions (exported for testability) ---------------------
+
+/** Check if a command string contains a git commit/merge/cherry-pick/revert. */
+export function containsGitCommitCommand(command: string): boolean {
+  return GIT_COMMIT_CMD_RE.test(command);
+}
+
+/** Extract commit SHA from git output. */
+export function parseCommitSha(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[2] : undefined;
+}
+
+/** Extract commit title from git output. */
+export function parseCommitTitle(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[3].trim() : undefined;
+}
+
+/** Extract branch name from git output. */
+export function parseBranchFromOutput(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[1] : undefined;
+}
+
+/** Scrub credentials from a remote URL. Returns undefined for empty input. */
+export function scrubRemoteUrl(rawUrl: string): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    parsed.username = "";
+    parsed.password = "";
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    // SSH or non-URL format — safe as-is
+    return rawUrl;
+  }
+}
+
+// -- Commit tracking record shape --------------------------------------------
+
+export interface CommitTrackRecord {
+  session_id: string;
+  commit_sha: string;
+  commit_title?: string;
+  branch?: string;
+  repo_remote?: string;
+  timestamp: string;
+}
+
+// -- Core processing logic ---------------------------------------------------
+
+/**
+ * Process a PostToolUse payload for git commit tracking.
+ * Returns the record that was written, or null if skipped.
+ * Exported for testability.
+ */
+export async function processCommitTrack(
+  payload: PostToolUsePayload,
+): Promise<CommitTrackRecord | null> {
+  // Fast-path: only care about Bash tool
+  if (payload.tool_name !== "Bash") return null;
+
+  // Fast-path: if cwd is known and not inside a git repo, skip
+  const cwd = payload.cwd ?? "";
+  if (cwd) {
+    try {
+      execSync("git rev-parse --is-inside-work-tree", {
+        cwd,
+        timeout: 1000,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+    } catch {
+      return null; // Not inside a git repo
+    }
+  }
+
+  // Fast-path: check if the command is a git commit-producing operation
+  const command = typeof payload.tool_input?.command === "string" ? payload.tool_input.command : "";
+  if (!containsGitCommitCommand(command)) return null;
+
+  // Extract stdout from tool_response
+  const response = payload.tool_response ?? {};
+  const stdout = typeof response.stdout === "string" ? response.stdout : "";
+  if (!stdout) return null;
+
+  // Parse commit SHA — if we can't find one, nothing to track
+  const commitSha = parseCommitSha(stdout);
+  if (!commitSha) return null;
+
+  const commitTitle = parseCommitTitle(stdout);
+  const outputBranch = parseBranchFromOutput(stdout);
+  const sessionId = payload.session_id;
+  if (!sessionId) return null; // No session ID — skip insert (fail-open)
+
+  // Try to get branch from git if not parsed from output
+  let branch = outputBranch;
+  if (!branch && cwd) {
+    try {
+      branch =
+        execSync("git rev-parse --abbrev-ref HEAD", {
+          cwd,
+          timeout: 3000,
+          stdio: ["ignore", "pipe", "ignore"],
+        })
+          .toString()
+          .trim() || undefined;
+    } catch {
+      /* not a git repo or git not available */
+    }
+  }
+
+  // Try to get remote URL (scrub credentials)
+  let repoRemote: string | undefined;
+  if (cwd) {
+    try {
+      const rawRemote =
+        execSync("git remote get-url origin", {
+          cwd,
+          timeout: 3000,
+          stdio: ["ignore", "pipe", "ignore"],
+        })
+          .toString()
+          .trim() || undefined;
+      if (rawRemote) {
+        repoRemote = scrubRemoteUrl(rawRemote);
+      }
+    } catch {
+      /* no remote configured */
+    }
+  }
+
+  const record: CommitTrackRecord = {
+    session_id: sessionId,
+    commit_sha: commitSha,
+    commit_title: commitTitle,
+    branch,
+    repo_remote: repoRemote,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Write to SQLite (dynamic import to reduce hook startup cost)
+  try {
+    const { writeCommitTracking } = await import("../localdb/direct-write.js");
+    writeCommitTracking(record);
+  } catch {
+    /* hooks must never block */
+  }
+
+  return record;
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    const payload: PostToolUsePayload = JSON.parse(await Bun.stdin.text());
+    await processCommitTrack(payload);
+  } catch {
+    // silent — hooks must never block Claude
+  }
+  process.exit(0);
+}

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

@@ -226,7 +226,16 @@ export async function processPrompt(
 // --- stdin main (only when executed directly, not when imported) ---
 if (import.meta.main) {
   try {
-    const payload: PromptSubmitPayload = JSON.parse(await Bun.stdin.text());
+    const { readStdinWithPreview } = await import("./stdin-preview.js");
+    const { preview, full } = await readStdinWithPreview();
+
+    // Fast-path: prompt-log only handles UserPromptSubmit events.
+    // If the keyword is absent from the first 4 KiB we can skip JSON.parse entirely.
+    if (!preview.includes('"UserPromptSubmit"')) {
+      process.exit(0);
+    }
+
+    const payload: PromptSubmitPayload = JSON.parse(full);
     await processPrompt(payload);
   } catch {
     // silent — hooks must never block Claude

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

@@ -11,7 +11,7 @@
 import { execSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 
-import { CANONICAL_LOG, ORCHESTRATE_LOCK, TELEMETRY_LOG } from "../constants.js";
+import { CANONICAL_LOG, getOrchestrateLockPath, TELEMETRY_LOG } from "../constants.js";
 import {
   appendCanonicalRecords,
   buildCanonicalExecutionFact,
@@ -47,7 +47,7 @@ function hasFreshOrchestrateLock(lockPath: string): boolean {
  * Returns true if a process was spawned, false otherwise.
  */
 export async function maybeSpawnReactiveOrchestrate(
-  lockPath: string = ORCHESTRATE_LOCK,
+  lockPath: string = getOrchestrateLockPath(),
   deps: ReactiveSpawnDeps = {},
 ): Promise<boolean> {
   try {

package/cli/selftune/hooks/skill-eval.ts

@@ -359,7 +359,21 @@ async function processSkillToolUse(
 // --- stdin main (only when executed directly, not when imported) ---
 if (import.meta.main) {
   try {
-    const payload: PostToolUsePayload = JSON.parse(await Bun.stdin.text());
+    const { readStdinWithPreview } = await import("./stdin-preview.js");
+    const { preview, full } = await readStdinWithPreview();
+
+    // Fast-path: skill-eval only handles PostToolUse events.
+    if (!preview.includes('"PostToolUse"')) {
+      process.exit(0);
+    }
+
+    // Secondary fast-path: only Read and Skill tools are relevant.
+    // Most PostToolUse events are for Bash/Write/Edit — skip those entirely.
+    if (!preview.includes('"Read"') && !preview.includes('"Skill"')) {
+      process.exit(0);
+    }
+
+    const payload: PostToolUsePayload = JSON.parse(full);
     await processToolUse(payload);
   } catch {
     // silent — hooks must never block Claude

package/cli/selftune/hooks/stdin-preview.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared stdin preview utility for hook fast-path optimization.
+ *
+ * Reads all of stdin once, then exposes a small preview slice so callers
+ * can do cheap `.includes()` keyword checks before paying for JSON.parse().
+ * When the keyword is absent the hook can exit in <1ms.
+ */
+
+const STDIN_PREVIEW_BYTES = 4096;
+
+/**
+ * Read stdin and return both a preview slice and the full text.
+ *
+ * Bun's `stdin.text()` consumes the entire stream in one call, so this is
+ * not a true streaming preview. The win comes from avoiding `JSON.parse()`
+ * entirely when the preview slice already proves the payload is irrelevant.
+ *
+ * @param previewBytes  Number of leading characters to expose in `preview`.
+ *                      Defaults to 4096, which comfortably covers the
+ *                      envelope fields (`hook_event_name`, `tool_name`, etc.)
+ *                      of any Claude Code hook payload.
+ */
+export async function readStdinWithPreview(previewBytes: number = STDIN_PREVIEW_BYTES): Promise<{
+  preview: string;
+  full: string;
+}> {
+  const raw = await Bun.stdin.text();
+  return {
+    preview: raw.slice(0, previewBytes),
+    full: raw,
+  };
+}

package/cli/selftune/init.ts

@@ -45,7 +45,7 @@ import { installAgentFiles } from "./claude-agents.js";
 import { CLAUDE_CODE_HOOK_KEYS, SELFTUNE_CONFIG_DIR, SELFTUNE_CONFIG_PATH } from "./constants.js";
 import type { AgentCommandGuidance, AlphaIdentity, SelftuneConfig } from "./types.js";
 import { CLIError, handleCLIError } from "./utils/cli-error.js";
-import { hookKeyHasSelftuneEntry } from "./utils/hooks.js";
+import { hookKeyHasSelftuneEntry, isSelftuneCommand } from "./utils/hooks.js";
 import { detectAgent } from "./utils/llm-call.js";
 
 export { installAgentFiles } from "./claude-agents.js";
@@ -229,10 +229,13 @@ const SETTINGS_SNIPPET_PATH = resolve(
  *
  * - Creates settings.json if it does not exist
  * - Creates the hooks section if it does not exist
- * - Only adds hook entries for keys that don't already have a selftune entry
- * - Never overwrites existing user hooks
+ * - Adds hook entries for keys that don't already have a selftune entry
+ * - Updates existing selftune entries with new attributes from the snippet
+ *   (e.g. `if`, `statusMessage`, `async`, `timeout`) while preserving
+ *   the resolved `command` path from the existing entry
+ * - Never overwrites existing non-selftune hooks
  *
- * Returns the list of hook keys that were added.
+ * Returns the list of hook keys that were added or updated.
  */
 export function installClaudeCodeHooks(options?: {
   settingsPath?: string;
@@ -279,43 +282,211 @@ export function installClaudeCodeHooks(options?: {
   }
   const existingHooks = settings.hooks as Record<string, unknown[]>;
 
-  // Resolve the CLI hooks directory for path substitution
+  // Resolve the package root for path substitution
+  // cliPath points to cli/selftune/index.ts → package root is two levels up
   const cliPath = options?.cliPath;
-  const hooksDir = cliPath ? `${dirname(cliPath)}/hooks` : null;
+  const packageRoot = cliPath ? resolve(dirname(cliPath), "..", "..").replace(/\\/g, "/") : null;
 
-  const addedKeys: string[] = [];
+  const changedKeys: string[] = [];
 
   for (const key of Object.keys(snippetHooks)) {
-    // Skip if this key already has a selftune entry
-    if (hookKeyHasSelftuneEntry(existingHooks, key)) {
-      continue;
-    }
-
-    // Get the snippet entries for this key, replacing /PATH/TO/ with actual path
+    // Get the snippet entries for this key, replacing /PATH/TO/ with actual package root
     let entries = snippetHooks[key];
-    if (hooksDir) {
-      // Deep clone and substitute paths
-      const raw = JSON.stringify(entries).replace(/\/PATH\/TO\/cli\/selftune\/hooks/g, hooksDir);
+    if (packageRoot) {
+      // Deep clone and substitute all /PATH/TO/ references with the resolved package root
+      const raw = JSON.stringify(entries).replace(/\/PATH\/TO\//g, `${packageRoot}/`);
       entries = JSON.parse(raw);
     }
 
-    // Merge: append to existing array or create new one
-    if (Array.isArray(existingHooks[key])) {
-      existingHooks[key] = [...existingHooks[key], ...entries];
+    if (hookKeyHasSelftuneEntry(existingHooks, key)) {
+      // Key already has selftune hooks — update them in-place with new attributes
+      // while preserving non-selftune entries and the resolved command paths
+      if (updateExistingSelftuneHooks(existingHooks, key, entries)) {
+        changedKeys.push(key);
+      }
     } else {
-      existingHooks[key] = entries;
+      // No selftune entry yet — add the snippet entries
+      if (Array.isArray(existingHooks[key])) {
+        existingHooks[key] = [...existingHooks[key], ...entries];
+      } else {
+        existingHooks[key] = entries;
+      }
+      changedKeys.push(key);
     }
-
-    addedKeys.push(key);
   }
 
-  if (addedKeys.length > 0) {
+  if (changedKeys.length > 0) {
     // Ensure ~/.claude/ directory exists
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
   }
 
-  return addedKeys;
+  return changedKeys;
+}
+
+/**
+ * Update existing selftune hook entries in-place with new attributes from the snippet.
+ *
+ * For each matcher group that contains selftune hooks, replaces ALL selftune
+ * hook entries with the full set of snippet entries while:
+ *   - Resolving snippet commands using the package root from existing entries
+ *   - Preserving non-selftune hooks in the same matcher group
+ *   - Handling N→M changes (e.g. 2 hooks expanding to 4 with Write/Edit splits)
+ *
+ * Returns true if any entries were actually modified.
+ */
+export function updateExistingSelftuneHooks(
+  existingHooks: Record<string, unknown[]>,
+  key: string,
+  snippetEntries: unknown[],
+): boolean {
+  const existingArray = existingHooks[key];
+  if (!Array.isArray(existingArray)) return false;
+
+  // Collect all snippet hooks (flattened from matcher groups)
+  const allSnippetHooks: Array<Record<string, unknown>> = [];
+  for (const group of snippetEntries) {
+    if (typeof group !== "object" || group === null) continue;
+    const g = group as Record<string, unknown>;
+    const hooks = g.hooks as Array<Record<string, unknown>> | undefined;
+    if (!Array.isArray(hooks)) continue;
+    allSnippetHooks.push(...hooks);
+  }
+
+  if (allSnippetHooks.length === 0) return false;
+
+  let modified = false;
+
+  for (let i = 0; i < existingArray.length; i++) {
+    const group = existingArray[i];
+    if (typeof group !== "object" || group === null) continue;
+    const g = group as Record<string, unknown>;
+    const hooks = g.hooks as Array<Record<string, unknown>> | undefined;
+
+    // Handle flat entries (direct { command: "..." } without nested hooks array).
+    // These are a legacy format from older selftune versions or manual installs.
+    if (!Array.isArray(hooks)) {
+      if (!isHookSelftune(g)) continue;
+      const pkgRoot = derivePackageRootFromCommand(typeof g.command === "string" ? g.command : "");
+
+      // Replace the flat entry with the full snippet group structure.
+      // If we can derive a package root, resolve /PATH/TO/ in the snippet.
+      // If not (e.g. "npx selftune hook ..."), use snippet entries as-is
+      // (they were already resolved by the caller if a cliPath was provided).
+      const resolvedEntries = snippetEntries.map((se) => {
+        if (!pkgRoot) return se;
+        const raw = JSON.stringify(se).replace(/\/PATH\/TO\//g, `${pkgRoot}/`);
+        return JSON.parse(raw);
+      });
+      existingArray.splice(i, 1, ...resolvedEntries);
+      modified = true;
+      continue;
+    }
+
+    // Derive package root from the first selftune hook in this group
+    let packageRoot: string | null = null;
+    for (const hook of hooks) {
+      if (isHookSelftune(hook)) {
+        packageRoot = derivePackageRootFromCommand(
+          typeof hook.command === "string" ? hook.command : "",
+        );
+        if (packageRoot) break;
+      }
+    }
+
+    // Check if this group has any selftune hooks at all
+    const hasSelftuneHooks = hooks.some(isHookSelftune);
+    if (!hasSelftuneHooks) continue;
+
+    // Build resolved snippet hooks using the derived package root.
+    // If no package root was derivable (e.g. "npx selftune hook ..."),
+    // use snippet hooks as-is (already resolved by caller if cliPath was provided).
+    const resolvedSnippetHooks = allSnippetHooks.map((snippetHook) => {
+      const cmd = typeof snippetHook.command === "string" ? snippetHook.command : "";
+      const resolvedCmd = packageRoot ? cmd.replace(/\/PATH\/TO\//g, `${packageRoot}/`) : cmd;
+      return { ...snippetHook, command: resolvedCmd };
+    });
+
+    // Check if anything actually changed (compare sorted JSON for order independence)
+    const oldSelftune = hooks.filter(isHookSelftune);
+    const oldSorted = JSON.stringify(sortKeys(oldSelftune));
+    const newSorted = JSON.stringify(sortKeys(resolvedSnippetHooks));
+    if (oldSorted !== newSorted) {
+      modified = true;
+    }
+
+    // Rebuild hooks preserving original ordering of non-selftune entries:
+    // replace the first selftune hook with all resolved snippet hooks,
+    // remove remaining old selftune hooks, keep non-selftune hooks in place
+    const updatedHooks: Array<Record<string, unknown>> = [];
+    let selftuneInserted = false;
+    for (const hook of hooks) {
+      if (isHookSelftune(hook)) {
+        if (!selftuneInserted) {
+          // Insert all resolved snippet hooks at the position of the first selftune hook
+          updatedHooks.push(...resolvedSnippetHooks);
+          selftuneInserted = true;
+        }
+        // Skip remaining old selftune hooks (replaced by snippet set above)
+      } else {
+        updatedHooks.push(hook);
+      }
+    }
+    g.hooks = updatedHooks;
+  }
+
+  return modified;
+}
+
+/** Check if a hook entry is a selftune-managed hook. Delegates to shared isSelftuneCommand. */
+function isHookSelftune(hook: Record<string, unknown>): boolean {
+  return typeof hook.command === "string" && isSelftuneCommand(hook.command);
+}
+
+/** Sort object keys recursively for order-independent JSON comparison. */
+function sortKeys(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(sortKeys);
+  if (obj !== null && typeof obj === "object") {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj as Record<string, unknown>).sort()) {
+      sorted[key] = sortKeys((obj as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return obj;
+}
+
+/**
+ * Derive the selftune package root from an existing hook command.
+ * Supports both old format ("bun run .../cli/selftune/hooks/X.ts")
+ * and new format ("node .../bin/run-hook.cjs .../cli/selftune/hooks/X.ts").
+ *
+ * Handles paths with spaces (e.g. "/Users/Alice Smith/...") and
+ * optional surrounding quotes in the command string.
+ */
+export function derivePackageRootFromCommand(command: string): string | null {
+  // Normalize: strip quotes, collapse backslashes (for Windows-style paths)
+  const normalized = command.replace(/["']/g, "").replace(/\\/g, "/");
+  // Split on the known directory marker and take the prefix.
+  // The command may contain the package root multiple times (e.g.
+  // "node /root/bin/run-hook.cjs /root/cli/selftune/hooks/script.ts")
+  // so we split on the LAST occurrence of the marker.
+  for (const marker of ["/cli/selftune/hooks/", "/bin/run-hook.cjs"]) {
+    const idx = normalized.lastIndexOf(marker);
+    if (idx === -1) continue;
+    // Everything before the marker is "<prefix> <package-root>" or just "<package-root>"
+    const beforeMarker = normalized.slice(0, idx);
+    // Find the start of the path: scan backwards from end for the path start.
+    // Paths start with / (Unix) or a drive letter like C:/ (Windows).
+    // The command prefix (e.g. "node " or "bun run ") precedes the path.
+    const pathMatch = beforeMarker.match(/.*\s(\/.*|[A-Za-z]:\/.*)/);
+    if (pathMatch) return pathMatch[1];
+    // No space prefix — the entire string is the path (e.g. no "node " prefix)
+    if (beforeMarker.startsWith("/") || /^[A-Za-z]:\//.test(beforeMarker)) {
+      return beforeMarker;
+    }
+  }
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -615,16 +786,16 @@ export async function runInit(opts: InitOptions): Promise<SelftuneConfig> {
       );
     }
 
-    const addedHookKeys = installClaudeCodeHooks({
+    const changedHookKeys = installClaudeCodeHooks({
       settingsPath,
       cliPath,
     });
-    if (addedHookKeys.length > 0) {
+    if (changedHookKeys.length > 0) {
       config.hooks_installed = true;
       // Re-write config with updated hooks_installed flag
       writeSelftuneConfig(configPath, config);
       console.error(
-        `[INFO] Installed ${addedHookKeys.length} selftune hook(s) into ${settingsPath}: ${addedHookKeys.join(", ")}`,
+        `[INFO] Installed/updated ${changedHookKeys.length} selftune hook(s) in ${settingsPath}: ${changedHookKeys.join(", ")}`,
       );
     } else if (!config.hooks_installed) {
       // Re-check in case hooks were already present