claude-dev-env 2.34.0 → 2.36.0

package/scripts/select_pstack_models.mjs

@@ -0,0 +1,304 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const inheritanceAliases = new Set(['inherit-parent', 'auto']);
+const hostNamePattern = /^[a-z0-9][a-z0-9_-]*$/;
+const defaultSingleDelegationPanel = Object.freeze({
+    agentCount: 1,
+    requiresDistinctModels: false,
+});
+
+export const allPstackRoleRequirements = Object.freeze({
+    'feature, refactoring': 'reliable code execution',
+    'bug-fix': 'careful diagnosis and code execution',
+    'perf-issue': 'systems reasoning and performance analysis',
+    'hillclimb': 'strong iterative judgment',
+    'judgment and prose': 'strong judgment and clear prose',
+    'hardest tasks': 'highest available reasoning capability',
+    'how explorer': 'fast codebase exploration',
+    'how explainer': 'clear technical synthesis',
+    'how critics': 'independent technical criticism',
+    'why investigators': 'fast evidence gathering',
+    'why synthesizer': 'strong evidence synthesis',
+    'reflect tooling': 'reliable tool and workflow analysis',
+    'reflect judgment, divergent, synthesizer': 'strong judgment and divergent analysis',
+    'arena runners': 'independent solution development',
+    'arena cross-judge pool': 'independent comparative judgment',
+    'swarm workers': 'fast bounded task execution',
+    'architect runners': 'independent architecture design',
+    'interrogate reviewers': 'independent adversarial review',
+});
+
+export const defaultPanelByPstackRole = Object.freeze({
+    'how critics': Object.freeze({ agentCount: 3, requiresDistinctModels: false }),
+    'arena runners': Object.freeze({ agentCount: 3, requiresDistinctModels: true }),
+    'swarm workers': defaultSingleDelegationPanel,
+    'architect runners': Object.freeze({ agentCount: 2, requiresDistinctModels: true }),
+    'interrogate reviewers': Object.freeze({ agentCount: 3, requiresDistinctModels: true }),
+});
+
+export function selectPstackDelegation(input) {
+    validateSelectionInput(input);
+    const panel = resolvePanel(input);
+    validateDelegationIndex(input.delegationIndex, panel.agentCount);
+    const modelsByRole = readHostPreferences(input);
+    const allCandidates = collectCandidates(input, modelsByRole[input.role] ?? []);
+    const allSelectedCandidates = selectPanelCandidates(allCandidates, panel);
+    return buildSelection(input, panel, allSelectedCandidates);
+}
+
+function validateSelectionInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('selection input must be an object');
+    }
+    validateHost(input.host, input.inventoryHost);
+    validateDelegationIndex(input.delegationIndex);
+    requireStringArray(input.availableModelIds, 'available model ids');
+    requireStringArray(input.confirmedSuitableModelIds, 'confirmed suitable model ids');
+    validateRealModelIds(input.availableModelIds, 'available model ids');
+    validateParentFallback(input.parentFallback);
+    validateConfirmedModels(input);
+    if (typeof input.role !== 'string' || !Object.hasOwn(allPstackRoleRequirements, input.role)) {
+        throw new Error('role must name a portable pstack role');
+    }
+}
+
+function validateHost(host, inventoryHost) {
+    if (typeof host !== 'string' || !hostNamePattern.test(host)) {
+        throw new Error('host must be a lowercase host identifier');
+    }
+    if (inventoryHost !== host) {
+        throw new Error('inventory host must match selected host');
+    }
+}
+
+function validateDelegationIndex(delegationIndex, agentCount) {
+    if (!Number.isInteger(delegationIndex) || delegationIndex < 0) {
+        throw new Error('delegation index must be a non-negative integer');
+    }
+    if (agentCount !== undefined && delegationIndex >= agentCount) {
+        throw new Error('delegation index must identify an agent in the panel');
+    }
+}
+
+function requireStringArray(allEntries, label) {
+    if (!Array.isArray(allEntries) || allEntries.some(
+        eachEntry => typeof eachEntry !== 'string' || eachEntry === '',
+    )) {
+        throw new Error(label + ' must be an array of non-empty strings');
+    }
+}
+
+function validateRealModelIds(allModelIds, label) {
+    if (allModelIds.some(eachModelId => inheritanceAliases.has(eachModelId))) {
+        throw new Error(label + ' cannot contain inheritance aliases');
+    }
+}
+
+function validateParentFallback(parentFallback) {
+    const hasBooleanFlags = parentFallback
+        && typeof parentFallback === 'object'
+        && typeof parentFallback.isAllowed === 'boolean'
+        && typeof parentFallback.hasMaterialCapabilityLoss === 'boolean';
+    if (!hasBooleanFlags) {
+        throw new Error('parent fallback flags must be booleans');
+    }
+}
+
+function validateConfirmedModels(input) {
+    validateRealModelIds(input.confirmedSuitableModelIds, 'confirmed suitable model ids');
+    const allAvailableModelIds = new Set(input.availableModelIds);
+    if (input.confirmedSuitableModelIds.some(
+        eachModelId => !allAvailableModelIds.has(eachModelId),
+    )) {
+        throw new Error('confirmed suitable models must be available');
+    }
+}
+
+function resolvePanel(input) {
+    const panel = input.panel
+        ?? defaultPanelByPstackRole[input.role]
+        ?? defaultSingleDelegationPanel;
+    const hasValidShape = panel
+        && typeof panel === 'object'
+        && Number.isInteger(panel.agentCount)
+        && panel.agentCount > 0
+        && typeof panel.requiresDistinctModels === 'boolean';
+    if (!hasValidShape) {
+        throw new Error('panel requires a positive agent count and a diversity boolean');
+    }
+    return {
+        agentCount: panel.agentCount,
+        requiresDistinctModels: panel.requiresDistinctModels,
+    };
+}
+
+function readHostPreferences(input) {
+    const preferencesDirectory = input.preferencesDirectory
+        ?? resolve(dirname(fileURLToPath(import.meta.url)), '..', 'rules');
+    const preferencesPath = join(
+        preferencesDirectory,
+        'pstack-model-preferences.' + input.host + '.json',
+    );
+    if (!existsSync(preferencesPath)) {
+        return {};
+    }
+    const preferences = JSON.parse(readFileSync(preferencesPath, 'utf8'));
+    if (preferences.host !== input.host) {
+        throw new Error('preference host must match selected host');
+    }
+    return preferences.modelsByRole ?? {};
+}
+
+function collectCandidates(input, allPreferredModelIds) {
+    requireStringArray(allPreferredModelIds, 'role preferences');
+    const allAvailableModelIds = new Set(input.availableModelIds);
+    const allPreferredCandidates = allPreferredModelIds
+        .map(eachModelId => preferenceCandidate(eachModelId, allAvailableModelIds, input))
+        .filter(Boolean);
+    const allAlternativeCandidates = input.confirmedSuitableModelIds.map(
+        eachModelId => modelCandidate(eachModelId, 'confirmed-host-alternative'),
+    );
+    const allCandidates = deduplicateCandidates([
+        ...allPreferredCandidates,
+        ...allAlternativeCandidates,
+    ]);
+    const allCandidatesWithFallback = allCandidates.length === 0
+        && input.parentFallback.isAllowed
+        ? [parentCandidate()]
+        : allCandidates;
+    return orderCrossJudgeCandidates(input, allCandidatesWithFallback);
+}
+
+function preferenceCandidate(modelId, allAvailableModelIds, input) {
+    if (inheritanceAliases.has(modelId)) {
+        return input.parentFallback.isAllowed ? parentCandidate() : null;
+    }
+    return allAvailableModelIds.has(modelId)
+        ? modelCandidate(modelId, 'host-preference')
+        : null;
+}
+
+function modelCandidate(modelId, source) {
+    return { kind: 'model', modelId, source };
+}
+
+function parentCandidate() {
+    return { kind: 'parent', modelId: null, source: 'parent-inheritance' };
+}
+
+function deduplicateCandidates(allCandidates) {
+    const seenCandidateKeys = new Set();
+    return allCandidates.filter(eachCandidate => {
+        const candidateKey = eachCandidate.kind + ':' + (eachCandidate.modelId ?? '');
+        if (seenCandidateKeys.has(candidateKey)) {
+            return false;
+        }
+        seenCandidateKeys.add(candidateKey);
+        return true;
+    });
+}
+
+function orderCrossJudgeCandidates(input, allCandidates) {
+    if (input.role !== 'arena cross-judge pool' || !input.parentModelId) {
+        return allCandidates;
+    }
+    const allOtherCandidates = allCandidates.filter(
+        eachCandidate => eachCandidate.kind === 'model'
+            && eachCandidate.modelId !== input.parentModelId,
+    );
+    const allParentCandidates = allCandidates.filter(
+        eachCandidate => eachCandidate.kind === 'parent'
+            || eachCandidate.modelId === input.parentModelId,
+    );
+    return [...allOtherCandidates, ...allParentCandidates];
+}
+
+function selectPanelCandidates(allCandidates, panel) {
+    if (panel.requiresDistinctModels) {
+        return allCandidates
+            .filter(eachCandidate => eachCandidate.kind === 'model')
+            .slice(0, panel.agentCount);
+    }
+    if (allCandidates.length === 0) {
+        return [];
+    }
+    return Array.from(
+        { length: panel.agentCount },
+        (_, index) => allCandidates[index % allCandidates.length],
+    );
+}
+
+function buildSelection(input, requestedPanel, allSelectedCandidates) {
+    const panel = reportPanel(requestedPanel, allSelectedCandidates);
+    const failure = selectionFailure(input, panel, allSelectedCandidates);
+    const selectedCandidate = allSelectedCandidates[input.delegationIndex];
+    return {
+        selectedHost: input.host,
+        role: input.role,
+        requiredCapability: allPstackRoleRequirements[input.role],
+        availabilityValidated: true,
+        canDelegate: failure === null,
+        requiresUserChoice: failure !== null,
+        failure,
+        selectionSource: selectedCandidate?.source ?? null,
+        panel,
+        nativeSpawnArguments: nativeSpawnArguments(selectedCandidate, failure),
+        omitNativeModelArgument: selectedCandidate?.kind === 'parent',
+    };
+}
+
+function reportPanel(requestedPanel, allSelectedCandidates) {
+    const allSelectedModelIds = allSelectedCandidates.map(
+        eachCandidate => eachCandidate.modelId,
+    );
+    const distinctRealModelCount = new Set(allSelectedModelIds.filter(Boolean)).size;
+    return {
+        agentCount: requestedPanel.agentCount,
+        requiresDistinctModels: requestedPanel.requiresDistinctModels,
+        selectedModelIds: allSelectedModelIds,
+        selectionSources: allSelectedCandidates.map(eachCandidate => eachCandidate.source),
+        isCrossModelDiverse: requestedPanel.agentCount > 1
+            && distinctRealModelCount === requestedPanel.agentCount,
+    };
+}
+
+function selectionFailure(input, panel, allSelectedCandidates) {
+    if (panel.requiresDistinctModels && !panel.isCrossModelDiverse) {
+        return 'distinct-models-unavailable';
+    }
+    if (allSelectedCandidates.length < panel.agentCount) {
+        return 'no-supported-model';
+    }
+    if (allSelectedCandidates.some(eachCandidate => eachCandidate.kind === 'parent')
+        && input.parentFallback.hasMaterialCapabilityLoss) {
+        return 'parent-capability-loss';
+    }
+    return null;
+}
+
+function nativeSpawnArguments(selectedCandidate, failure) {
+    if (failure || !selectedCandidate || selectedCandidate.kind === 'parent') {
+        return {};
+    }
+    return { model: selectedCandidate.modelId };
+}
+
+async function readSelectionInput() {
+    let inputText = '';
+    for await (const eachChunk of process.stdin) {
+        inputText += eachChunk;
+    }
+    return JSON.parse(inputText);
+}
+
+function isEntryPoint() {
+    return process.argv[1]
+        && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+}
+
+if (isEntryPoint()) {
+    const selectionInput = await readSelectionInput();
+    console.log(JSON.stringify(selectPstackDelegation(selectionInput)));
+}

package/scripts/tests/test-audit-hooks.mjs

@@ -0,0 +1,379 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { auditHooks } from "../audit-hooks.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+
+function writeJson(filePath, document) {
+  writeFileSync(filePath, JSON.stringify(document), "utf8");
+}
+
+function createAuditFixture({ canonicalHooks = {}, claudeHooks = { hooks: {} }, codexHooks = { hooks: {} } } = {}) {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-"));
+  const canonicalHooksRoot = path.join(fixtureRoot, "packages", "claude-dev-env", "hooks");
+  const homeDirectory = path.join(fixtureRoot, "home");
+  mkdirSync(canonicalHooksRoot, { recursive: true });
+  mkdirSync(path.join(homeDirectory, ".claude", "hooks"), { recursive: true });
+  mkdirSync(path.join(homeDirectory, ".codex", "hooks"), { recursive: true });
+  writeJson(path.join(canonicalHooksRoot, "hooks.json"), { hooks: canonicalHooks });
+  writeJson(path.join(homeDirectory, ".claude", "settings.json"), claudeHooks);
+  writeJson(path.join(homeDirectory, ".codex", "hooks.json"), codexHooks);
+  return { fixtureRoot, homeDirectory, canonicalHooksRoot };
+}
+
+function writeHookFile(hooksRoot, relativePath) {
+  const hookPath = path.join(hooksRoot, relativePath);
+  mkdirSync(path.dirname(hookPath), { recursive: true });
+  writeFileSync(hookPath, "", "utf8");
+}
+
+function runGit(repositoryRoot, argumentsList, environment) {
+  const command = spawnSync("git", argumentsList, {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+    env: environment,
+    shell: false,
+  });
+  assert.equal(command.status, 0, command.stderr);
+  return command;
+}
+
+test("reports the canonical execution graph", () => {
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{
+        matcher: "Write",
+        hooks: [{ type: "command", command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/write_existing_file_blocker.py" }],
+      }],
+    },
+  });
+  try {
+    const report = auditHooks({ repositoryRoot: fixture.fixtureRoot });
+    assert.equal(report.summary.directCount, 1);
+    assert.equal(report.summary.dispatcherCount, 0);
+    assert.equal(report.summary.effectiveCount, 0);
+    assert.equal(report.summary.logicalAssociationCount, 1);
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("renders deterministic private JSON", () => {
+  const report = auditHooks({ repositoryRoot });
+  const first = JSON.stringify(report);
+  const second = JSON.stringify(report);
+  assert.equal(first, second);
+  assert.equal(first.includes(repositoryRoot), false);
+  assert.equal(first.includes("python3 ${CLAUDE_PLUGIN_ROOT}"), false);
+});
+
+test("reports every unclassified target", () => {
+  const temporaryRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-"));
+  const catalogPath = path.join(temporaryRoot, "lifecycle.json");
+  writeFileSync(catalogPath, '{"schema_version":1,"hooks":{}}', "utf8");
+  try {
+    const report = auditHooks({ catalogPath, repositoryRoot });
+    assert.equal(report.summary.unclassifiedCount, report.summary.uniqueTargetCount);
+    assert.equal(report.findings.some(({ code }) => code === "UNCLASSIFIED_HOOK"), true);
+  } finally {
+    rmSync(temporaryRoot, { force: true, recursive: true });
+  }
+});
+
+test("keeps each hosted matcher as narrow as its roster", () => {
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{
+        matcher: "Bash|Write",
+        hooks: [{ type: "command", command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py" }],
+      }],
+    },
+  });
+  const constantsRoot = path.join(fixture.canonicalHooksRoot, "hooks_constants");
+  writeHookFile(fixture.canonicalHooksRoot, "blocking/pre_tool_use_dispatcher.py");
+  mkdirSync(constantsRoot, { recursive: true });
+  writeFileSync(
+    path.join(constantsRoot, "pre_tool_use_dispatcher_constants.py"),
+    [
+      'BASH_TOOL_NAME = "Bash"',
+      "ALL_BASH_TOOL_NAMES = frozenset({BASH_TOOL_NAME})",
+      "ALL_HOSTED_HOOK_ENTRIES = (",
+      'HostedHookEntry(script_relative_path="blocking/shell_substitution_blocker.py", applicable_tool_names=ALL_BASH_TOOL_NAMES),',
+      ")",
+    ].join("\n"),
+    "utf8",
+  );
+  try {
+    const report = auditHooks({ repositoryRoot: fixture.fixtureRoot });
+    const shellGate = report.hostedRegistrations.find(({ target }) =>
+      target.endsWith("shell_substitution_blocker.py"),
+    );
+    assert.equal(shellGate.matcher, "Bash");
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("omits untrusted lifecycle prose from output", () => {
+  const temporaryRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-"));
+  const catalogPath = path.join(temporaryRoot, "lifecycle.json");
+  const privateText = "PRIVATE_TOKEN python3 C:/Users/example/private.py";
+  const catalog = {
+    hooks: {
+      "script:blocking/code_rules_enforcer.py": {
+        lifecycle: "move_to_linter",
+        reason: privateText,
+        replacement: privateText,
+      },
+    },
+  };
+  writeFileSync(catalogPath, JSON.stringify(catalog), "utf8");
+  try {
+    const rendered = JSON.stringify(auditHooks({ catalogPath, repositoryRoot }));
+    assert.equal(rendered.includes(privateText), false);
+  } finally {
+    rmSync(temporaryRoot, { force: true, recursive: true });
+  }
+});
+
+test("classifies installed-only targets", () => {
+  const fixture = createAuditFixture();
+  const temporaryRoot = fixture.fixtureRoot;
+  const claudeRoot = path.join(fixture.homeDirectory, ".claude");
+  const codexRoot = path.join(fixture.homeDirectory, ".codex");
+  const installedOnly = {
+    hooks: {
+      SessionStart: [{ hooks: [{ command: "node cleanup.mjs", type: "command" }], matcher: "" }],
+    },
+  };
+  writeJson(path.join(claudeRoot, "settings.json"), installedOnly);
+  writeJson(path.join(codexRoot, "hooks.json"), { hooks: {} });
+  const catalogPath = path.join(temporaryRoot, "lifecycle.json");
+  writeFileSync(catalogPath, '{"hooks":{}}', "utf8");
+  try {
+    const report = auditHooks({
+      catalogPath,
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: temporaryRoot,
+    });
+    const missingTargets = new Set(
+      report.findings.filter(({ code }) => code === "UNCLASSIFIED_HOOK").map(({ target }) => target),
+    );
+    assert.equal(missingTargets.has("external:cleanup.mjs"), true);
+  } finally {
+    rmSync(temporaryRoot, { force: true, recursive: true });
+  }
+});
+
+test("reads dispatcher children from the installed hook tree", () => {
+  const fixture = createAuditFixture();
+  const temporaryRoot = fixture.fixtureRoot;
+  const claudeRoot = path.join(fixture.homeDirectory, ".claude");
+  const installedHooks = path.join(claudeRoot, "hooks");
+  const constantsRoot = path.join(installedHooks, "hooks_constants");
+  const blockingRoot = path.join(installedHooks, "blocking");
+  mkdirSync(constantsRoot, { recursive: true });
+  mkdirSync(blockingRoot, { recursive: true });
+  const config = {
+    hooks: {
+      PreToolUse: [{
+        hooks: [{
+          command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py",
+          type: "command",
+        }],
+        matcher: "Write",
+      }],
+    },
+  };
+  const roster = [
+    'WRITE_TOOL_NAME = "Write"',
+    "ALL_WRITE_TOOL_NAMES = frozenset({WRITE_TOOL_NAME})",
+    "ALL_HOSTED_HOOK_ENTRIES = (",
+    'HostedHookEntry(script_relative_path="blocking/installed_only.py", applicable_tool_names=ALL_WRITE_TOOL_NAMES),',
+    ")",
+  ].join("\n");
+  writeJson(path.join(claudeRoot, "settings.json"), config);
+  writeFileSync(path.join(constantsRoot, "pre_tool_use_dispatcher_constants.py"), roster, "utf8");
+  writeFileSync(path.join(blockingRoot, "pre_tool_use_dispatcher.py"), "", "utf8");
+  writeJson(path.join(fixture.homeDirectory, ".codex", "hooks.json"), { hooks: {} });
+  try {
+    const report = auditHooks({
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: temporaryRoot,
+    });
+    assert.equal(
+      report.installedLogicalRegistrations.some(({ target }) => target.endsWith("installed_only.py")),
+      true,
+    );
+    assert.equal(
+      report.findings.some(({ code, target }) =>
+        code === "MISSING_HOOK_TARGET" && target === "script:blocking/installed_only.py",
+      ),
+      true,
+    );
+  } finally {
+    rmSync(temporaryRoot, { force: true, recursive: true });
+  }
+});
+
+test("reports missing installed dispatcher targets", () => {
+  const fixture = createAuditFixture({
+    claudeHooks: {
+      hooks: {
+        PreToolUse: [{
+          matcher: "Write",
+          hooks: [{
+            type: "command",
+            command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py",
+          }],
+        }],
+      },
+    },
+  });
+  const constantsPath = path.join(
+    fixture.homeDirectory,
+    ".claude",
+    "hooks",
+    "hooks_constants",
+    "pre_tool_use_dispatcher_constants.py",
+  );
+  mkdirSync(path.dirname(constantsPath), { recursive: true });
+  writeFileSync(constantsPath, "ALL_HOSTED_HOOK_ENTRIES = ()\n", "utf8");
+  try {
+    const report = auditHooks({
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: fixture.fixtureRoot,
+    });
+    assert.equal(
+      report.findings.some(({ code, scope, target }) =>
+        code === "MISSING_HOOK_TARGET" &&
+        scope === "claude" &&
+        target === "script:blocking/pre_tool_use_dispatcher.py",
+      ),
+      true,
+    );
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("checks canonical managed parity for Codex registrations", () => {
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{
+        matcher: "Write",
+        hooks: [{ type: "command", command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/write_existing_file_blocker.py" }],
+      }],
+    },
+  });
+  try {
+    const report = auditHooks({
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: fixture.fixtureRoot,
+    });
+    assert.equal(
+      report.findings.some(({ code, scope, target }) =>
+        code === "MISSING_MANAGED_REGISTRATION" &&
+        scope === "codex" &&
+        target === "script:blocking/write_existing_file_blocker.py",
+      ),
+      true,
+    );
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("compares managed registrations by event, matcher, and target", () => {
+  const command = "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/write_existing_file_blocker.py";
+  const fixture = createAuditFixture({
+    canonicalHooks: {
+      PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command }] }],
+    },
+    claudeHooks: {
+      hooks: {
+        PostToolUse: [{ matcher: "Read", hooks: [{ type: "command", command }] }],
+      },
+    },
+    codexHooks: {
+      hooks: {
+        PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command }] }],
+      },
+    },
+  });
+  writeHookFile(path.join(fixture.homeDirectory, ".claude", "hooks"), "blocking/write_existing_file_blocker.py");
+  writeHookFile(path.join(fixture.homeDirectory, ".codex", "hooks"), "blocking/write_existing_file_blocker.py");
+  try {
+    const report = auditHooks({
+      homeDirectory: fixture.homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: fixture.fixtureRoot,
+    });
+    assert.equal(
+      report.findings.some(({ code, scope, target }) =>
+        code === "MISSING_MANAGED_REGISTRATION" &&
+        scope === "claude" &&
+        target === "script:blocking/write_existing_file_blocker.py",
+      ),
+      true,
+    );
+    assert.equal(
+      report.findings.some(({ code, scope }) =>
+        code === "MISSING_MANAGED_REGISTRATION" && scope === "codex",
+      ),
+      false,
+    );
+  } finally {
+    rmSync(fixture.fixtureRoot, { force: true, recursive: true });
+  }
+});
+
+test("finds default Git hooks from a worktree", () => {
+  const sourceRoot = mkdtempSync(path.join(tmpdir(), "hook-audit-git-"));
+  const worktreeRoot = path.join(sourceRoot, "worktree");
+  const globalConfigPath = path.join(sourceRoot, "global-gitconfig");
+  writeFileSync(globalConfigPath, "", "utf8");
+  const environment = { ...process.env, GIT_CONFIG_GLOBAL: globalConfigPath, GIT_CONFIG_NOSYSTEM: "1" };
+  const previousGlobalConfig = process.env.GIT_CONFIG_GLOBAL;
+  const previousNoSystem = process.env.GIT_CONFIG_NOSYSTEM;
+  process.env.GIT_CONFIG_GLOBAL = globalConfigPath;
+  process.env.GIT_CONFIG_NOSYSTEM = "1";
+  try {
+    runGit(sourceRoot, ["init", "--quiet"], environment);
+    runGit(sourceRoot, ["config", "user.email", "hook-audit@example.invalid"], environment);
+    runGit(sourceRoot, ["config", "user.name", "Hook Audit"], environment);
+    runGit(sourceRoot, ["commit", "--quiet", "--allow-empty", "-m", "fixture"], environment);
+    runGit(sourceRoot, ["worktree", "add", "--quiet", worktreeRoot, "HEAD"], environment);
+    writeHookFile(path.join(sourceRoot, ".git", "hooks"), "pre-commit");
+    const canonicalHooksRoot = path.join(worktreeRoot, "packages", "claude-dev-env", "hooks");
+    const homeDirectory = path.join(sourceRoot, "home");
+    mkdirSync(canonicalHooksRoot, { recursive: true });
+    mkdirSync(path.join(homeDirectory, ".claude", "hooks"), { recursive: true });
+    mkdirSync(path.join(homeDirectory, ".codex", "hooks"), { recursive: true });
+    writeJson(path.join(canonicalHooksRoot, "hooks.json"), { hooks: {} });
+    writeJson(path.join(homeDirectory, ".claude", "settings.json"), { hooks: {} });
+    writeJson(path.join(homeDirectory, ".codex", "hooks.json"), { hooks: {} });
+    const report = auditHooks({
+      homeDirectory,
+      includeInstalled: true,
+      repositoryRoot: worktreeRoot,
+    });
+    assert.deepEqual(report.gitRegistrations.map(({ target }) => target), ["git:pre-commit"]);
+  } finally {
+    if (previousGlobalConfig === undefined) delete process.env.GIT_CONFIG_GLOBAL;
+    else process.env.GIT_CONFIG_GLOBAL = previousGlobalConfig;
+    if (previousNoSystem === undefined) delete process.env.GIT_CONFIG_NOSYSTEM;
+    else process.env.GIT_CONFIG_NOSYSTEM = previousNoSystem;
+    rmSync(sourceRoot, { force: true, recursive: true });
+  }
+});