@ngockhoale/ukit 2.2.11 → 2.2.12

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.12 - 2026-09-04
+
+`ukit install` and `ukit update` now clean up broken Claude Code hook registrations automatically.
+
+A hook whose stdout contains a `hookSpecificOutput` object without the required `hookEventName`
+field fails Claude Code's schema validation on **every** tool call, surfacing as a repeating
+`PreToolUse:<Tool> hook error — Hook JSON output validation failed`. Such a hook has no effect
+either way, since its output is discarded — it produces nothing but noise.
+
+New `src/core/repairBrokenHooks.js` detects that shape generically (not keyed to any one vendor)
+across user settings, project settings, and `settings.local.json`, expanding
+`$CLAUDE_PROJECT_DIR`/`$HOME`/`~` in hook commands and also catching hooks inlined into
+`settings.json` instead of a script file. Offending registrations are removed after a
+`.ukit-backup` restore point is written next to each settings file. Detection matches only real
+key assignments, so prose mentions of the field in a hook's own comments or docstrings never
+trigger a removal.
+
+Wired into the install pipeline; since `ukit update` re-runs `ukit install`, both commands are
+covered with no new flags or commands to learn — teammates still only need `ukit install`.
+
+Scope is deliberate: UKit removes the *registration* only. An unregistered hook script never
+executes, so that is sufficient, and UKit does not delete the script file or uninstall the tool
+that wrote it. When the owning tool can be identified from the hook source, the install report
+names it and notes that it may re-register on activation, leaving permanent removal as a human
+decision.
+
+Known real-world instance: VSCode extension `tjcg.auto-accept-claude-code` v0.5.0 hardcodes two
+such hook templates and rewrites its hook file on activation.
+
 ## 2.2.11 - 2026-08-29
 
 Same-day follow-up to 2.2.10. The two premises that release shipped as unverified were checked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/install.js

@@ -1,5 +1,6 @@
 import { buildPathConfig } from '../../core/paths.js';
 import { runInstallPipeline } from '../../core/runInstallPipeline.js';
+import { formatRepairReport } from '../../core/repairBrokenHooks.js';
 import { buildCodeIndex } from '../../index/buildIndex.js';
 import { installIndexRefreshHooks } from '../../index/gitHooks.js';
 import fs from 'node:fs/promises';
@@ -238,6 +239,10 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     .join(', ');
   console.log(`[UKit] Providers: ${providerStatus}, all=${result.providerContext.allSupported}`);
 
+  for (const line of formatRepairReport(result.hookRepair ?? { removals: [], files: [] })) {
+    console.log(`[UKit] ${line}`);
+  }
+
   const docsLabels = [
     'docs/PROJECT.md',
     'docs/MEMORY.md',

package/src/core/repairBrokenHooks.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+// Claude Code rejects any hook whose stdout carries a `hookSpecificOutput` object
+// without `hookEventName` inside it, and surfaces it as a per-tool-call
+// "Hook JSON output validation failed" error. A hook in that state never has any
+// effect - its output is discarded - so removing its registration only removes noise.
+//
+// Detection is deliberately generic rather than keyed to one known-bad extension:
+// any tool that ships this shape produces the same failure.
+
+// Only real key assignments count. Prose mentions of the field inside docstrings
+// and comments are common in hook SDKs and must not trigger a removal.
+const HOOK_OUTPUT_KEY = /["']hookSpecificOutput["']\s*\]?\s*[:=]/g;
+
+// How far past the key to look for the sibling field. Generous enough for a
+// formatted object literal, short enough not to reach an unrelated later block.
+const SIBLING_SCAN_WINDOW = 400;
+
+// Paths in a hook command string, e.g. "$CLAUDE_PROJECT_DIR/.claude/hooks/x.sh".
+const SCRIPT_PATH = /["']?((?:\/|~|\$\{?[A-Z_]+\}?\/)[^"'\s]+\.(?:sh|ps1|py|js|mjs|cjs|bash|zsh))["']?/g;
+
+// e.g. "# Auto-Accept Extension: PreToolUse hook" -> "Auto-Accept Extension"
+const OWNER_HINT = /^[#/\s]*([A-Z][\w-]*(?:\s+[\w-]+)*\s+Extension)\b/m;
+
+/**
+ * True when `source` assigns hookSpecificOutput without a nearby hookEventName.
+ */
+export function hasBrokenHookShape(source) {
+  if (typeof source !== 'string') {
+    return false;
+  }
+
+  HOOK_OUTPUT_KEY.lastIndex = 0;
+  let match = HOOK_OUTPUT_KEY.exec(source);
+  while (match) {
+    const window = source.slice(match.index, match.index + SIBLING_SCAN_WINDOW);
+    if (!window.includes('hookEventName')) {
+      HOOK_OUTPUT_KEY.lastIndex = 0;
+      return true;
+    }
+    match = HOOK_OUTPUT_KEY.exec(source);
+  }
+
+  return false;
+}
+
+function expandPath(rawPath, { projectRoot, homeDir }) {
+  return rawPath
+    .replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, projectRoot)
+    .replace(/\$\{?HOME-?\}?/g, homeDir)
+    .replace(/^~/, homeDir);
+}
+
+function extractScriptPaths(command, { projectRoot, homeDir }) {
+  const paths = [];
+  SCRIPT_PATH.lastIndex = 0;
+  let match = SCRIPT_PATH.exec(command);
+  while (match) {
+    paths.push(expandPath(match[1], { projectRoot, homeDir }));
+    match = SCRIPT_PATH.exec(command);
+  }
+  return paths;
+}
+
+async function readFileIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inspect one registered hook command. Returns null when it is fine, or
+ * { source, ownerHint } describing where the broken shape was found.
+ */
+async function inspectHookCommand(command, { projectRoot, homeDir }) {
+  if (typeof command !== 'string' || !command) {
+    return null;
+  }
+
+  for (const scriptPath of extractScriptPaths(command, { projectRoot, homeDir })) {
+    const contents = await readFileIfExists(scriptPath);
+    if (contents !== null && hasBrokenHookShape(contents)) {
+      return { source: scriptPath, ownerHint: OWNER_HINT.exec(contents)?.[1] ?? null };
+    }
+  }
+
+  // Some tools inline the whole hook body into settings.json instead of a script.
+  if (hasBrokenHookShape(command)) {
+    return { source: '<inline command>', ownerHint: null };
+  }
+
+  return null;
+}
+
+/**
+ * Drop broken hook entries from one parsed settings object.
+ * Mutates `settings` and returns the removals found.
+ */
+async function stripBrokenHooks(settings, { projectRoot, homeDir }) {
+  const removals = [];
+  const events = settings?.hooks;
+  if (!events || typeof events !== 'object' || Array.isArray(events)) {
+    return removals;
+  }
+
+  for (const [event, groups] of Object.entries(events)) {
+    if (!Array.isArray(groups)) {
+      continue;
+    }
+
+    const keptGroups = [];
+    for (const group of groups) {
+      if (!group || typeof group !== 'object') {
+        keptGroups.push(group);
+        continue;
+      }
+
+      const hooks = Array.isArray(group.hooks) ? group.hooks : null;
+      if (!hooks) {
+        keptGroups.push(group);
+        continue;
+      }
+
+      const keptHooks = [];
+      for (const hook of hooks) {
+        const finding = await inspectHookCommand(hook?.command, { projectRoot, homeDir });
+        if (finding) {
+          removals.push({ event, matcher: group.matcher ?? '', ...finding });
+        } else {
+          keptHooks.push(hook);
+        }
+      }
+
+      // A group that was already empty stays as-is; only drop groups we emptied.
+      if (keptHooks.length === 0 && hooks.length > 0) {
+        continue;
+      }
+
+      group.hooks = keptHooks;
+      keptGroups.push(group);
+    }
+
+    if (keptGroups.length > 0) {
+      events[event] = keptGroups;
+    } else {
+      delete events[event];
+    }
+  }
+
+  return removals;
+}
+
+function backupPathFor(settingsPath) {
+  return `${settingsPath}.ukit-backup`;
+}
+
+/**
+ * Remove Claude Code hook registrations that would fail schema validation on every
+ * tool call, from the user-level and project-level settings files.
+ *
+ * Registration removal alone is enough: an unregistered script is never executed.
+ * The script file itself is left on disk untouched - it belongs to whichever tool
+ * wrote it, and deleting another tool's files is not UKit's call.
+ *
+ * @returns {Promise<{removals: Array, files: string[]}>}
+ */
+export async function repairBrokenHooks({ projectRoot, homeDir = os.homedir() } = {}) {
+  const candidates = [
+    path.join(homeDir, '.claude', 'settings.json'),
+    path.join(projectRoot, '.claude', 'settings.json'),
+    path.join(projectRoot, '.claude', 'settings.local.json'),
+  ];
+
+  const removals = [];
+  const files = [];
+
+  for (const settingsPath of candidates) {
+    const raw = await readFileIfExists(settingsPath);
+    if (raw === null) {
+      continue;
+    }
+
+    let settings;
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      // Malformed settings are not ours to rewrite.
+      continue;
+    }
+
+    const found = await stripBrokenHooks(settings, { projectRoot, homeDir });
+    if (found.length === 0) {
+      continue;
+    }
+
+    // Keep a restore point before touching a file the user did not ask us to edit.
+    await fs.writeFile(backupPathFor(settingsPath), raw, 'utf8');
+    await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+
+    files.push(settingsPath);
+    removals.push(...found.map((entry) => ({ ...entry, settingsPath })));
+  }
+
+  return { removals, files };
+}
+
+/**
+ * Human-readable lines for the install/update report. Empty array when nothing was repaired.
+ */
+export function formatRepairReport({ removals, files }) {
+  if (!removals || removals.length === 0) {
+    return [];
+  }
+
+  const lines = [
+    `Removed ${removals.length} broken Claude Code hook registration(s).`,
+    'They emitted hookSpecificOutput without hookEventName, so every tool call failed',
+    'schema validation and the hook never actually ran.',
+  ];
+
+  for (const removal of removals) {
+    const owner = removal.ownerHint ? ` (${removal.ownerHint})` : '';
+    lines.push(`  - ${removal.event}: ${removal.source}${owner}`);
+  }
+
+  const owners = [...new Set(removals.map((entry) => entry.ownerHint).filter(Boolean))];
+  if (owners.length > 0) {
+    lines.push(
+      `Warning: ${owners.join(', ')} rewrites its hook on activation, so this can come back.`,
+      'Uninstall that extension to stop it for good - UKit will not remove it for you.',
+    );
+  }
+
+  lines.push(`Backup: ${files.map((file) => `${file}.ukit-backup`).join(', ')}`);
+  return lines;
+}

package/src/core/runInstallPipeline.js

@@ -12,6 +12,7 @@ import { summarizeDiff, toDiffRows } from './report.js';
 import { writeInstallMetadata } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
 import { ensureGitignore } from './ensureGitignore.js';
+import { repairBrokenHooks } from './repairBrokenHooks.js';
 import { cleanupEmptyParents, readJsonIfExists, removeFileOrLinkOnly, resolveProjectRelativePath } from './fileOps.js';
 
 const AUTO_PRUNE_OBSOLETE_PREFIXES = [
@@ -316,6 +317,13 @@ export async function runInstallPipeline({
     }
 
     await ensureGitignore(pathConfig.projectRoot);
+
+    // A hook that emits hookSpecificOutput without hookEventName fails Claude Code's
+    // schema check on every tool call, so it only ever produces noise. Teammates are
+    // not expected to know that - `ukit install` (and `ukit update`, which re-runs
+    // install) clears it for them. Backups are written next to each settings file.
+    const hookRepair = await repairBrokenHooks({ projectRoot: pathConfig.projectRoot });
+
     await pruneObsoleteManagedPaths({
       installMetaData,
       projectRoot: pathConfig.projectRoot,
@@ -350,6 +358,7 @@ export async function runInstallPipeline({
       summary,
       rows: toDiffRows(diffResults),
       writes,
+      hookRepair,
     };
   }
 
@@ -361,5 +370,6 @@ export async function runInstallPipeline({
     summary: plannedSummary,
     rows: toDiffRows(diffResults),
     writes: [],
+    hookRepair: { removals: [], files: [] },
   };
 }