@haystackeditor/cli 0.15.30 → 0.16.0

package/dist/commands/cloud-verifier-identity-census.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, extname, join, posix, resolve } from 'node:path';
-import { globSync } from 'glob';
+import fg from 'fast-glob';
 import { findGitRoot } from '../utils/hooks.js';
 import { scanPascalSelectorIdentities } from './cloud-verifier-pascal-selector-census.js';
 import { scanPythonManifestSelectorIdentities } from './cloud-verifier-python-manifest-selector-census.js';
@@ -208,7 +208,10 @@ function trackedFiles(root) {
             .sort();
     }
     catch {
-        return globSync('**/*', { cwd: root, dot: true, nodir: true })
+        // Same entries as glob's { dot: true, nodir: true }: every non-directory,
+        // with symlinks listed as themselves and never followed.
+        return fg.sync('**/*', { cwd: root, dot: true, onlyFiles: false, followSymbolicLinks: false, markDirectories: true })
+            .filter((path) => !path.endsWith('/'))
             .map(normalizePath)
             .filter((path) => !path.startsWith('.git/') &&
             !path.startsWith('.haystack/') &&

package/dist/commands/combination-search-hook.js

@@ -0,0 +1,139 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+const maximumBytes = 8 * 1024 * 1024;
+const configPath = '.haystack/combination-search.json';
+function hasHexSuffix(value, prefix, length) {
+    return typeof value === 'string' && value.length === prefix.length + length && value.startsWith(prefix)
+        && [...value.slice(prefix.length)].every(character => '0123456789abcdef'.includes(character));
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid combination-search configuration.');
+    return value;
+}
+function keys(value, expected) {
+    if (Object.keys(value).length !== expected.length || expected.some(key => !Object.hasOwn(value, key)))
+        throw new Error('Invalid combination-search fields.');
+}
+function integer(value, minimum, maximum) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new Error('Invalid combination-search limit.');
+    return value;
+}
+function settings(value) {
+    const row = record(value);
+    keys(row, ['budgetMs', 'maxUniversesInFlight', 'picksPerBatch', 'seed', 'rankingPoolSize']);
+    const picks = record(row.picksPerBatch);
+    keys(picks, ['ranked', 'baseline']);
+    const ranked = integer(picks.ranked, 0, 500), baseline = integer(picks.baseline, 0, 500);
+    if (ranked + baseline < 1 || ranked + baseline > 500)
+        throw new Error('Invalid combination-search picks.');
+    return { budgetMs: integer(row.budgetMs, 10000, 1800000), maxUniversesInFlight: integer(row.maxUniversesInFlight, 1, 500),
+        picksPerBatch: { ranked, baseline }, seed: integer(row.seed, 0, 0xffffffff), rankingPoolSize: integer(row.rankingPoolSize, 1, 100000) };
+}
+function boundedJson(value) {
+    const visit = (item, depth) => {
+        if (depth > 64)
+            throw new Error('Combination-search input is too deeply nested.');
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return;
+        if (Array.isArray(item)) {
+            for (const entry of item)
+                visit(entry, depth + 1);
+            return;
+        }
+        for (const [key, entry] of Object.entries(record(item))) {
+            if (['__proto__', 'constructor', 'prototype'].includes(key))
+                throw new Error('Invalid combination-search JSON key.');
+            visit(entry, depth + 1);
+        }
+    };
+    visit(value, 0);
+    if (Buffer.byteLength(JSON.stringify(value)) > maximumBytes)
+        throw new Error('Combination-search input exceeds 8 MiB.');
+    return value;
+}
+function configuration(value) {
+    const row = record(value);
+    keys(row, ['schemaVersion', 'combinations', 'prIntent', 'search', 'ideas']);
+    const ideas = record(row.ideas);
+    keys(ideas, ['count']);
+    if (row.schemaVersion !== 1 || typeof row.prIntent !== 'string' || !row.prIntent || row.prIntent.length > 65536)
+        throw new Error('Invalid combination-search intent.');
+    return { schemaVersion: 1, combinations: boundedJson(row.combinations), prIntent: row.prIntent,
+        search: settings(row.search), ideas: { count: integer(ideas.count, 1, 100) } };
+}
+/** Git reads only the captured immutable commit. Local changes made while the
+ * detached sender runs cannot alter the search's source or combination space. */
+export function captureCombinationSearchHook(gitRoot, repository, baseCommit, headCommit, deadline) {
+    const git = (args) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error('Combination-search capture timed out.');
+        return execFileSync('git', ['--literal-pathspecs', ...args], { cwd: gitRoot, encoding: 'utf8',
+            timeout: remaining, maxBuffer: maximumBytes, stdio: ['ignore', 'pipe', 'pipe'] });
+    };
+    const present = git(['ls-tree', '-z', '--name-only', headCommit, '--', configPath]);
+    if (!present)
+        return undefined;
+    if (present !== `${configPath}\0`)
+        throw new Error('Unexpected combination-search configuration identity.');
+    const config = configuration(JSON.parse(git(['show', `${headCommit}:${configPath}`])));
+    const stats = git(['diff', '--no-renames', '--numstat', '-z', baseCommit, headCommit, '--']);
+    const files = stats.split('\0').filter(Boolean).map(stat => {
+        const first = stat.indexOf('\t'), second = stat.indexOf('\t', first + 1);
+        if (first < 0 || second < 0)
+            throw new Error('Invalid captured diff metadata.');
+        const file = stat.slice(second + 1);
+        const count = (raw) => raw === '-' ? 0 : integer(Number(raw), 0, Number.MAX_SAFE_INTEGER);
+        return { file, additions: count(stat.slice(0, first)), deletions: count(stat.slice(first + 1, second)),
+            patch: git(['diff', '--no-renames', '--binary', '--no-ext-diff', '--no-textconv', baseCommit, headCommit, '--', file]) };
+    });
+    const inputs = { repository, baseCommit, headCommit, combinationsRef: { inline: config.combinations },
+        change: { diffRef: { inline: { sha: headCommit, parent: baseCommit, message: config.prIntent, files } },
+            prIntentRef: { inline: config.prIntent } }, search: config.search, ideas: config.ideas };
+    boundedJson(inputs);
+    return { ...inputs, idempotencyKey: `search:${createHash('sha256').update(JSON.stringify(inputs)).digest('hex')}` };
+}
+export function validateCapturedSearch(value, identity) {
+    boundedJson(value);
+    const row = record(value);
+    keys(row, ['repository', 'baseCommit', 'headCommit', 'idempotencyKey', 'combinationsRef', 'change', 'search', 'ideas']);
+    if (row.repository !== `${identity.owner}/${identity.repository}` || row.baseCommit !== identity.baseCommit || row.headCommit !== identity.workCommit
+        || !hasHexSuffix(row.idempotencyKey, 'search:', 64))
+        throw new Error('Captured search source identity differs.');
+    settings(row.search);
+    const combinations = record(row.combinationsRef);
+    keys(combinations, ['inline']);
+    const change = record(row.change);
+    keys(change, ['diffRef', 'prIntentRef']);
+    const diffRef = record(change.diffRef);
+    keys(diffRef, ['inline']);
+    const diff = record(diffRef.inline);
+    if (diff.sha !== identity.workCommit || diff.parent !== identity.baseCommit)
+        throw new Error('Captured search diff identity differs.');
+    const prIntent = record(change.prIntentRef);
+    keys(prIntent, ['inline']);
+    if (typeof prIntent.inline !== 'string' || !prIntent.inline)
+        throw new Error('Captured search intent is missing.');
+    const ideas = record(row.ideas);
+    keys(ideas, ['count']);
+    integer(ideas.count, 1, 100);
+    const { idempotencyKey, ...inputs } = row;
+    if (idempotencyKey !== `search:${createHash('sha256').update(JSON.stringify(inputs)).digest('hex')}`)
+        throw new Error('Captured search digest differs.');
+}
+export function readCombinationSearchHookStatus(value) {
+    const row = record(value);
+    if ((row.status === 'queued' || row.status === 'existing') && hasHexSuffix(row.runId, 'cv_', 48)) {
+        keys(row, ['status', 'runId']);
+        return { status: row.status, runId: row.runId };
+    }
+    if (row.status === 'unavailable' && ['not-configured', 'runner-unavailable', 'enqueue-failed'].includes(String(row.reason))) {
+        keys(row, ['status', 'reason']);
+        return { status: row.status, reason: row.reason };
+    }
+    throw new Error('Invalid combination-search acknowledgment.');
+}

package/dist/commands/design-verify.js

@@ -16,8 +16,9 @@
 import chalk from 'chalk';
 import { loadToken } from '../utils/auth.js';
 import { parsePrRef } from '../utils/pr-ref.js';
-import { getDesignVerifierUniverseAction, startDesignVerifierUniverseAction, triggerDesignVerifier, waitForDesignVerifier, waitForDesignVerifierUniverseAction, } from '../utils/design-verifier-api.js';
+import { getDesignVerifierHistory, getDesignVerifierUniverseAction, startDesignVerifierUniverseAction, triggerDesignVerifier, waitForDesignVerifier, waitForDesignVerifierUniverseAction, } from '../utils/design-verifier-api.js';
 import { buildDesignVerifierAgentReport, designVerifierStageLabel, formatDesignVerifierAgentReport, } from '../utils/design-verifier-result.js';
+import { formatDesignVerifierHistory } from '../utils/design-verifier-history.js';
 function emit(json, payload, human) {
     if (json) {
         console.log(JSON.stringify(payload));
@@ -189,6 +190,31 @@ export async function designVerifyCommand(identifier, options) {
         process.exitCode = 1;
         return;
     }
+    if (options.history || options.limit !== undefined) {
+        try {
+            if (!options.history)
+                throw new Error('--limit requires --history');
+            if (options.run || options.case || options.universe || options.replay || options.execJson ||
+                options.cwd || options.commandTimeout || options.action || options.wait === false) {
+                throw new Error('--history cannot be combined with run or universe operations');
+            }
+            const limit = Number(options.limit ?? '20');
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+                throw new Error('--limit must be between 1 and 100');
+            }
+            const loaded = await getDesignVerifierHistory(pr.owner, pr.repo, token, limit);
+            if (loaded.status !== 'ok')
+                throw new Error(loaded.message);
+            emit(options.json, { ...loaded.history }, () => console.log(formatDesignVerifierHistory(loaded.history)));
+        }
+        catch (error) {
+            emit(options.json, { ok: false, error: error.message }, () => {
+                console.error(chalk.red(error.message));
+            });
+            process.exitCode = 2;
+        }
+        return;
+    }
     const pollIntervalSeconds = Number(options.pollInterval || '3');
     const timeoutSeconds = Number(options.timeout || '7200');
     if (!(Number.isFinite(pollIntervalSeconds) && pollIntervalSeconds >= 1 && pollIntervalSeconds <= 60)) {

package/dist/commands/dismiss.js

@@ -16,12 +16,13 @@ import chalk from 'chalk';
 import { emitActionPayload, failAction } from '../utils/action-output.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError } from '../utils/haystack-api.js';
+import { githubRestBaseFor } from '../utils/github-api.js';
 import { parsePrRef } from '../utils/pr-ref.js';
 // ============================================================================
 // GitHub API helpers
 // ============================================================================
 async function getPRHeadSha(owner, repo, prNumber, token) {
-    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}`, {
+    const response = await fetch(`${githubRestBaseFor(token)}/repos/${owner}/${repo}/pulls/${prNumber}`, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/vnd.github.v3+json',

package/dist/commands/hooks.js

@@ -6,10 +6,65 @@
  *   - Git hooks for Haystack quality checks and workflow guidance
  */
 import chalk from 'chalk';
-import { existsSync, accessSync, constants } from 'fs';
+import { existsSync, accessSync, constants, lstatSync, readFileSync, readdirSync } from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
-import { findGitRoot, copyHookFiles, installHookDeps, copyLlmRulesTemplate, } from '../utils/hooks.js';
+import { execFileSync, execSync } from 'child_process';
+import { findGitRoot, copyHookFiles, installHookDeps, copyLlmRulesTemplate, listHookInstallFiles, } from '../utils/hooks.js';
+function gitOutput(gitRoot, args) {
+    return execFileSync('git', args, { cwd: gitRoot, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function configuredHooksPath(gitRoot) {
+    try {
+        return gitOutput(gitRoot, ['config', '--get', 'core.hooksPath']);
+    }
+    catch (error) {
+        // `git config --get` exits 1 when the key is unset.
+        if (error.status === 1)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Everything `haystack hooks install` would change that Haystack did not
+ * itself put there: hook files in hooks/ whose content differs from what this
+ * CLI installs, and a core.hooksPath change (including one that silences
+ * hooks already active in .git/hooks). Empty means installing is safe.
+ */
+export async function describeHookOverwrites(gitRoot) {
+    const changes = [];
+    const hooksDir = path.join(gitRoot, 'hooks');
+    if (existsSync(hooksDir)) {
+        for (const file of await listHookInstallFiles()) {
+            const dest = path.join(hooksDir, file.rel);
+            let stat;
+            try {
+                stat = lstatSync(dest);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            if (!stat.isFile() || !readFileSync(dest).equals(readFileSync(file.src))) {
+                changes.push(`overwrite hooks/${file.rel}`);
+            }
+        }
+    }
+    const hooksPath = configuredHooksPath(gitRoot);
+    if (hooksPath === undefined) {
+        const gitHooksDir = path.resolve(gitRoot, gitOutput(gitRoot, ['rev-parse', '--git-path', 'hooks']));
+        const active = existsSync(gitHooksDir)
+            ? readdirSync(gitHooksDir).filter(name => !name.endsWith('.sample')).sort()
+            : [];
+        if (active.length > 0) {
+            changes.push(`set core.hooksPath to "hooks", so git stops running ${active.map(name => `.git/hooks/${name}`).join(', ')}`);
+        }
+    }
+    else if (hooksPath !== 'hooks') {
+        changes.push(`change core.hooksPath from "${hooksPath}" to "hooks"`);
+    }
+    return changes;
+}
 export async function hooksInstall(options) {
     console.log(chalk.cyan('\nHaystack Hooks Setup\n'));
     // Step 1: Validate git repo
@@ -19,12 +74,16 @@ export async function hooksInstall(options) {
         process.exit(1);
     }
     const hooksDir = path.join(gitRoot, 'hooks');
-    // Step 2: Check for existing installation
-    if (existsSync(hooksDir) && !options.force) {
-        console.error(chalk.yellow('hooks/ directory already exists. Use --force to overwrite.\n'));
+    // Step 2: Refuse to replace anything Haystack did not install unless forced.
+    const overwrites = await describeHookOverwrites(gitRoot);
+    if (overwrites.length > 0 && !options.force) {
+        console.error(chalk.yellow('Installing Haystack hooks would:'));
+        for (const change of overwrites)
+            console.error(chalk.yellow(`  - ${change}`));
+        console.error(chalk.yellow('Use --force to proceed.\n'));
         process.exit(1);
     }
-    if (existsSync(hooksDir) && options.force) {
+    if (overwrites.length > 0) {
         console.log(chalk.yellow('Overwriting existing hooks...'));
     }
     // Step 3: Copy hook files

package/dist/commands/install-session-hooks.js

@@ -6,21 +6,23 @@
  * "Needs input", with the Haystack rating and auto-fixer status.
  *
  * Supported CLIs:
- *   - Claude Code: Native SessionStart and Stop hooks in .claude/settings.json
+ *   - Claude Code: Native SessionStart and Stop hooks in .claude/settings.local.json
+ *                  (per developer; `shared` writes the committed .claude/settings.json)
  *   - Codex CLI:   AGENTS.md instructions (no native hook support)
  *   - Gemini CLI:  GEMINI.md instructions (no native hook support)
  */
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import chalk from 'chalk';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { findGitRoot } from '../utils/git.js';
+import { assertNoSymlinkOnPath } from '../utils/safe-write.js';
 // ============================================================================
 // CLI detection (reused from triage runner pattern)
 // ============================================================================
 function isCLIInstalled(name) {
     try {
-        execSync(process.platform === 'win32' ? `where ${name}` : `which ${name}`, {
+        execFileSync(process.platform === 'win32' ? 'where' : 'which', [name], {
             stdio: 'ignore',
         });
         return true;
@@ -44,19 +46,96 @@ function detectInstalledCLIs() {
 // ============================================================================
 const HAYSTACK_HOOK_COMMAND = 'haystack triage --hook';
 const HAYSTACK_PRECOMPUTE_HOOK_COMMAND = 'haystack verify precompute --hook';
-function installClaudeHook(gitRoot) {
+// The per-developer file is the default: a hook that uploads working-tree
+// snapshots must be opted into by each developer, not inherited from a commit.
+const CLAUDE_LOCAL_SETTINGS = 'settings.local.json';
+const CLAUDE_SHARED_SETTINGS = 'settings.json';
+function claudeSettingsPath(gitRoot, fileName) {
+    return join(gitRoot, '.claude', fileName);
+}
+function readClaudeSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return undefined;
+    return JSON.parse(readFileSync(settingsPath, 'utf-8'));
+}
+function claudeEntries(settings, event) {
+    const hooks = settings?.hooks;
+    const entries = hooks?.[event];
+    return Array.isArray(entries) ? entries : [];
+}
+const isTriageCommand = (h) => Boolean(h.command?.includes('haystack triage') || h.command?.includes('haystack check-pending'));
+const isPrecomputeCommand = (h) => Boolean(h.command?.includes(HAYSTACK_PRECOMPUTE_HOOK_COMMAND));
+function isGitIgnored(gitRoot, path) {
+    try {
+        execFileSync('git', ['check-ignore', '-q', '--', path], { cwd: gitRoot, stdio: 'ignore' });
+        return true;
+    }
+    catch (error) {
+        // Exit status 1 means "not ignored"; anything else is a real failure.
+        if (error.status === 1)
+            return false;
+        throw error;
+    }
+}
+/**
+ * Drops Haystack's own SessionStart and Stop commands from
+ * `.claude/settings.local.json` after a shared install. Every entry that is
+ * not Haystack's is preserved byte-for-byte in meaning; the file is removed
+ * only when nothing but Haystack's hooks was in it.
+ */
+function removeHaystackHooksFromLocalSettings(gitRoot) {
+    const localPath = claudeSettingsPath(gitRoot, CLAUDE_LOCAL_SETTINGS);
+    const relativePath = `.claude/${CLAUDE_LOCAL_SETTINGS}`;
+    assertNoSymlinkOnPath(gitRoot, localPath);
+    const local = readClaudeSettings(localPath);
+    if (!local || !local.hooks || typeof local.hooks !== 'object')
+        return;
+    const hooks = local.hooks;
+    const isHaystackCommand = (h) => isTriageCommand(h) || isPrecomputeCommand(h);
+    let removed = 0;
+    for (const event of ['SessionStart', 'Stop']) {
+        const entries = hooks[event];
+        if (!Array.isArray(entries))
+            continue;
+        const kept = entries
+            .map(entry => {
+            const own = entry.hooks?.filter(h => isHaystackCommand(h)).length ?? 0;
+            removed += own;
+            return own === 0 ? entry : { ...entry, hooks: (entry.hooks ?? []).filter(h => !isHaystackCommand(h)) };
+        })
+            .filter(entry => (entry.hooks ?? []).length > 0);
+        if (kept.length > 0)
+            hooks[event] = kept;
+        else
+            delete hooks[event];
+    }
+    if (removed === 0)
+        return;
+    if (Object.keys(hooks).length === 0)
+        delete local.hooks;
+    if (Object.keys(local).length === 0) {
+        unlinkSync(localPath);
+        console.log(chalk.dim(`  Removed ${relativePath}: it held only the Haystack hooks that now live in the shared file.`));
+        return;
+    }
+    writeFileSync(localPath, JSON.stringify(local, null, 2));
+    console.log(chalk.dim(`  Removed ${removed} Haystack hook command(s) from ${relativePath}; the shared file now carries them.`));
+}
+function installClaudeHook(gitRoot, options) {
+    const fileName = options.shared ? CLAUDE_SHARED_SETTINGS : CLAUDE_LOCAL_SETTINGS;
+    const relativePath = `.claude/${fileName}`;
     const settingsDir = join(gitRoot, '.claude');
-    const settingsPath = join(settingsDir, 'settings.json');
+    const settingsPath = claudeSettingsPath(gitRoot, fileName);
     try {
-        // Ensure .claude directory exists
-        if (!existsSync(settingsDir)) {
-            mkdirSync(settingsDir, { recursive: true });
-        }
+        assertNoSymlinkOnPath(gitRoot, settingsPath);
         // Read or create settings
-        let settings = {};
-        if (existsSync(settingsPath)) {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        }
+        const settings = readClaudeSettings(settingsPath) ?? {};
+        // Claude Code merges both files, so for a local install a hook the shared
+        // file already carries is installed; adding it here would only duplicate
+        // it. A shared install always writes, because teammates only see that file.
+        const otherSettings = options.shared
+            ? undefined
+            : readClaudeSettings(claudeSettingsPath(gitRoot, CLAUDE_SHARED_SETTINGS));
         // Ensure hooks object exists
         const hooks = (settings.hooks || {});
         settings.hooks = hooks;
@@ -64,8 +143,9 @@ function installClaudeHook(gitRoot) {
         const sessionStart = (hooks.SessionStart || []);
         hooks.SessionStart = sessionStart;
         // Check if haystack hook already installed (current or legacy)
-        const isHaystackHook = (h) => h.command?.includes('haystack triage') || h.command?.includes('haystack check-pending');
-        const existingIndex = sessionStart.findIndex(entry => entry.hooks?.some(h => isHaystackHook(h)));
+        const existingIndex = sessionStart.findIndex(entry => entry.hooks?.some(h => isTriageCommand(h)));
+        const sessionInOther = claudeEntries(otherSettings, 'SessionStart')
+            .some(entry => entry.hooks?.some(h => isTriageCommand(h)));
         let changed = false;
         let migrated = false;
         if (existingIndex !== -1) {
@@ -82,7 +162,7 @@ function installClaudeHook(gitRoot) {
                 }
             }
         }
-        else {
+        else if (!sessionInOther) {
             // Add the session-start hook (fresh install).
             sessionStart.push({
                 matcher: '',
@@ -99,7 +179,8 @@ function installClaudeHook(gitRoot) {
         // entry and add the exact command only when no matching command exists.
         const stop = (hooks.Stop || []);
         hooks.Stop = stop;
-        const hasPrecomputeHook = stop.some(entry => entry.hooks?.some(h => h.command?.includes(HAYSTACK_PRECOMPUTE_HOOK_COMMAND)));
+        const hasPrecomputeHook = [...stop, ...claudeEntries(otherSettings, 'Stop')]
+            .some(entry => entry.hooks?.some(h => isPrecomputeCommand(h)));
         if (!hasPrecomputeHook) {
             stop.push({
                 matcher: '',
@@ -113,7 +194,19 @@ function installClaudeHook(gitRoot) {
             changed = true;
         }
         if (changed) {
+            if (!existsSync(settingsDir))
+                mkdirSync(settingsDir, { recursive: true });
             writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+            console.log(chalk.dim(`  Wrote ${relativePath}${options.shared ? ' (shared with everyone who clones this repository)' : ' (this checkout only)'}.`));
+        }
+        // Claude Code unions hooks from both files, so once the shared file
+        // carries Haystack's hooks, copies left in the local file would run twice.
+        if (options.shared)
+            removeHaystackHooksFromLocalSettings(gitRoot);
+        if (changed) {
+            if (!options.shared && !isGitIgnored(gitRoot, relativePath)) {
+                console.log(chalk.yellow(`  ${relativePath} is not git-ignored; add it to .gitignore or .git/info/exclude so it stays personal.`));
+            }
             if (migrated) {
                 console.log(chalk.green('  Claude Code hook migrated from check-pending to triage.'));
             }
@@ -124,35 +217,27 @@ function installClaudeHook(gitRoot) {
         return true;
     }
     catch (err) {
-        console.error(chalk.red(`  Failed to update .claude/settings.json: ${err}`));
+        console.error(chalk.red(`  Failed to update ${relativePath}: ${err instanceof Error ? err.message : err}`));
         return false;
     }
 }
+function claudeHookPresent(gitRoot, event, matches) {
+    return [CLAUDE_LOCAL_SETTINGS, CLAUDE_SHARED_SETTINGS].some(fileName => {
+        try {
+            return claudeEntries(readClaudeSettings(claudeSettingsPath(gitRoot, fileName)), event)
+                .some(entry => entry.hooks?.some(h => matches(h)));
+        }
+        catch (error) {
+            console.error(chalk.yellow(`  Could not read .claude/${fileName}: ${error instanceof Error ? error.message : error}`));
+            return false;
+        }
+    });
+}
 function checkClaudePrecomputeHook(gitRoot) {
-    const settingsPath = join(gitRoot, '.claude', 'settings.json');
-    if (!existsSync(settingsPath))
-        return false;
-    try {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const stop = settings?.hooks?.Stop || [];
-        return stop.some((entry) => entry.hooks?.some(h => h.command?.includes(HAYSTACK_PRECOMPUTE_HOOK_COMMAND)));
-    }
-    catch {
-        return false;
-    }
+    return claudeHookPresent(gitRoot, 'Stop', isPrecomputeCommand);
 }
 function checkClaudeHook(gitRoot) {
-    const settingsPath = join(gitRoot, '.claude', 'settings.json');
-    if (!existsSync(settingsPath))
-        return false;
-    try {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const sessionStart = settings?.hooks?.SessionStart || [];
-        return sessionStart.some((entry) => entry.hooks?.some((h) => h.command?.includes('haystack triage') || h.command?.includes('haystack check-pending')));
-    }
-    catch {
-        return false;
-    }
+    return claudeHookPresent(gitRoot, 'SessionStart', isTriageCommand);
 }
 // ============================================================================
 // Codex CLI: AGENTS.md instructions
@@ -181,12 +266,13 @@ function installCodexHook(gitRoot) {
                 return true;
             }
         }
+        assertNoSymlinkOnPath(gitRoot, agentsPath);
         content += CODEX_HOOK_BLOCK;
         writeFileSync(agentsPath, content);
         return true;
     }
     catch (err) {
-        console.error(chalk.red(`  Failed to update AGENTS.md: ${err}`));
+        console.error(chalk.red(`  Failed to update AGENTS.md: ${err instanceof Error ? err.message : err}`));
         return false;
     }
 }
@@ -229,12 +315,13 @@ function installGeminiHook(gitRoot) {
                 return true;
             }
         }
+        assertNoSymlinkOnPath(gitRoot, geminiPath);
         content += GEMINI_HOOK_BLOCK;
         writeFileSync(geminiPath, content);
         return true;
     }
     catch (err) {
-        console.error(chalk.red(`  Failed to update GEMINI.md: ${err}`));
+        console.error(chalk.red(`  Failed to update GEMINI.md: ${err instanceof Error ? err.message : err}`));
         return false;
     }
 }
@@ -318,7 +405,7 @@ export async function installSessionHooks(options) {
         const config = CLI_HOOKS[target];
         const hookType = config.hasNativeHook ? 'native hook' : 'markdown instructions';
         console.log(`  Installing ${config.displayName} (${hookType})...`);
-        const success = config.install(gitRoot);
+        const success = config.install(gitRoot, { shared: options.shared === true });
         if (success) {
             console.log(chalk.green(`  ✓ ${config.displayName} configured`));
         }