devflow-kit 2.5.0 → 3.0.0

package/dist/cli/commands/ambient.js

@@ -1,63 +1,47 @@
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { syncManifestFeature } from '../../core/manifest.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
+import { HOOKS_DIR_SUFFIX, endsWithAny, ensureHook, hasHook, removeHooks, runHookCommand, runHookSuffix, } from '../../targets/claude-code/hooks.js';
 const PREAMBLE_HOOK_MARKER = 'preamble';
-const LEGACY_HOOK_MARKER = 'ambient-prompt';
-/** Stale marker from previous installs — cleaned on disable/re-enable */
-const CLASSIFICATION_HOOK_MARKER = 'session-start-classification';
 /** SessionStart orchestrator charter hook — presence-gated by ambient toggle */
 const ORCHESTRATOR_HOOK_MARKER = 'session-start-orchestrator';
+/**
+ * The command endings of each ambient hook devflow has ever registered.
+ *
+ * D-AMBIENT-EXACT-HOOK — the ambient instance of D-EXACT-HOOK-OWNER (hooks.ts): a
+ * hook is devflow's when its command ENDS in one of these, under any directory — so
+ * installs made under a custom or repo-local devflow directory are still recognised —
+ * and never because it merely contains a marker word: a user's
+ * `~/bin/preamble-logger.sh` or `echo preamble` is theirs (applies ADR-024). The
+ * legacy forms are the pre-preamble `ambient-prompt` hook (first a bare
+ * `ambient-prompt.sh`, then through `run-hook`) and the retired
+ * `session-start-classification` hook, both still swept on enable and disable.
+ */
+const AMBIENT_HOOK_SUFFIXES = {
+    preamble: [runHookSuffix(PREAMBLE_HOOK_MARKER)],
+    legacyPrompt: [runHookSuffix('ambient-prompt'), `${HOOKS_DIR_SUFFIX}ambient-prompt.sh`],
+    classification: [runHookSuffix('session-start-classification')],
+    orchestrator: [runHookSuffix(ORCHESTRATOR_HOOK_MARKER)],
+};
+const isPreamble = endsWithAny(AMBIENT_HOOK_SUFFIXES.preamble);
+const isLegacy = endsWithAny(AMBIENT_HOOK_SUFFIXES.legacyPrompt);
+const isAmbient = endsWithAny([...AMBIENT_HOOK_SUFFIXES.preamble, ...AMBIENT_HOOK_SUFFIXES.legacyPrompt]);
+const isClassification = endsWithAny(AMBIENT_HOOK_SUFFIXES.classification);
+const isOrchestrator = endsWithAny(AMBIENT_HOOK_SUFFIXES.orchestrator);
 /**
  * Path where the legacy commands rule was installed.
  * The commands rule was removed — this path now exists only to purge the
  * legacy file from prior installs. Managed by ambient.ts directly (not the
  * plugin rules system), so only ambient enable/disable/init paths clean it up.
+ * Resolved under the Claude Code directory (D-CLAUDE-CONFIG-DIR), where the
+ * legacy install wrote it.
  */
-export const COMMANDS_RULE_PATH = path.join(os.homedir(), '.claude', 'rules', 'devflow', 'commands.md');
-/** Filter hook entries from a parsed Settings object for a given event. Returns true if any were removed. */
-function filterHookEntries(settings, eventName, shouldRemove) {
-    if (!settings.hooks?.[eventName])
-        return false;
-    const before = settings.hooks[eventName].length;
-    settings.hooks[eventName] = settings.hooks[eventName].filter((matcher) => !shouldRemove(matcher));
-    if (settings.hooks[eventName].length === before)
-        return false;
-    if (settings.hooks[eventName].length === 0) {
-        delete settings.hooks[eventName];
-    }
-    if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
-    }
-    return true;
-}
-/** Add a hook entry for an event if the marker is not already present. Returns true when an entry was added. */
-function ensureHook(settings, eventName, marker, entry) {
-    if (settings.hooks?.[eventName]?.some((m) => m.hooks.some((h) => h.command.includes(marker)))) {
-        return false;
-    }
-    settings.hooks ??= {};
-    settings.hooks[eventName] ??= [];
-    settings.hooks[eventName].push(entry);
-    return true;
-}
-function isLegacy(matcher) {
-    return matcher.hooks.some((h) => h.command.includes(LEGACY_HOOK_MARKER));
-}
-function isAmbient(matcher) {
-    return matcher.hooks.some((h) => h.command.includes(PREAMBLE_HOOK_MARKER) || h.command.includes(LEGACY_HOOK_MARKER));
-}
-function isClassification(matcher) {
-    return matcher.hooks.some((h) => h.command.includes(CLASSIFICATION_HOOK_MARKER));
-}
-function isOrchestrator(matcher) {
-    return matcher.hooks.some((h) => h.command.includes(ORCHESTRATOR_HOOK_MARKER));
-}
+export const COMMANDS_RULE_PATH = path.join(getClaudeDirectory(), 'rules', 'devflow', 'commands.md');
 /**
  * Remove the legacy commands awareness rule file left by prior installs.
  * Idempotent — no-op if the file does not exist.
@@ -75,23 +59,44 @@ export async function removeLegacyCommandsRule() {
         // filesystem. Neither should abort the caller's primary operation.
     }
 }
+/**
+ * A predicate matching devflow's own hook (`isOurs`) registered with any command
+ * other than `canonical` — i.e. under a directory other than the one `canonical` names.
+ */
+function isMisdirected(isOurs, canonical) {
+    return (hook) => isOurs(hook) && (hook.command ?? '').trim() !== canonical;
+}
 /**
  * Add the ambient hooks (preamble UserPromptSubmit + session-start-orchestrator SessionStart)
  * and remove any legacy commands rule. Removes any legacy `ambient-prompt` hook first.
  * Idempotent — each hook is checked before adding so enable repairs partial states.
  * Legacy rule purge runs unconditionally to ensure stale files are always cleaned up.
+ *
+ * D-AMBIENT-CANONICAL-DIR: enable converges on `devflowDir`. A preamble or
+ * orchestrator hook devflow registered under another directory (an earlier enable
+ * that inferred its directory from a user's Stop hook, or a retired custom
+ * directory) is removed and the hook re-registered at `devflowDir`. Only hooks
+ * matched exactly (D-AMBIENT-EXACT-HOOK) are touched, one hook at a time, so the
+ * user's hooks and their matcher-group siblings keep their places.
  */
 export async function addAmbientHook(settingsJson, devflowDir) {
     const settings = JSON.parse(settingsJson);
-    const removedLegacy = filterHookEntries(settings, 'UserPromptSubmit', isLegacy);
+    const preambleCommand = runHookCommand(devflowDir, PREAMBLE_HOOK_MARKER);
+    const orchestratorCommand = runHookCommand(devflowDir, ORCHESTRATOR_HOOK_MARKER);
+    const removedLegacy = removeHooks(settings, 'UserPromptSubmit', isLegacy);
     // Sweep stale classification hook from prior installs — symmetric with removeAmbientHook
-    const removedClassification = filterHookEntries(settings, 'SessionStart', isClassification);
-    const addedPreamble = ensureHook(settings, 'UserPromptSubmit', PREAMBLE_HOOK_MARKER, { hooks: [{ type: 'command', command: path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ' preamble', timeout: 5 }] });
-    const addedOrchestrator = ensureHook(settings, 'SessionStart', ORCHESTRATOR_HOOK_MARKER, { hooks: [{ type: 'command', command: path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ' session-start-orchestrator', timeout: 10 }] });
+    const removedClassification = removeHooks(settings, 'SessionStart', isClassification);
+    const removedMisdirected = [
+        removeHooks(settings, 'UserPromptSubmit', isMisdirected(isPreamble, preambleCommand)),
+        removeHooks(settings, 'SessionStart', isMisdirected(isOrchestrator, orchestratorCommand)),
+    ].some(Boolean);
+    const addedPreamble = ensureHook(settings, 'UserPromptSubmit', isPreamble, { hooks: [{ type: 'command', command: preambleCommand, timeout: 5 }] });
+    const addedOrchestrator = ensureHook(settings, 'SessionStart', isOrchestrator, { hooks: [{ type: 'command', command: orchestratorCommand, timeout: 10 }] });
     // Purge legacy commands rule (runs before early-return so stale files are always removed)
     await removeLegacyCommandsRule();
-    if (!removedLegacy && !removedClassification && !addedPreamble && !addedOrchestrator)
+    if (!removedLegacy && !removedClassification && !removedMisdirected && !addedPreamble && !addedOrchestrator) {
         return settingsJson;
+    }
     return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
@@ -99,22 +104,38 @@ export async function addAmbientHook(settingsJson, devflowDir) {
  * Removes preamble + legacy from UserPromptSubmit.
  * Removes session-start-orchestrator from SessionStart.
  * Also removes stale SessionStart classification hook from previous installs.
- * Purges legacy COMMANDS_RULE_PATH if present (runs before early-return).
+ * Purges legacy COMMANDS_RULE_PATH if present (runs before early-return), unless
+ * `options.purgeLegacyRule` is false — a legacy repo-local uninstall edits a repo's
+ * settings and must not touch the user's Claude directory (D-LEGACY-LOCAL-CLEANUP).
  * Idempotent — returns unchanged JSON if no ambient hooks were present.
  * Preserves other hooks. Cleans empty arrays/objects.
  */
-export async function removeAmbientHook(settingsJson) {
+export async function removeAmbientHook(settingsJson, options = {}) {
     const settings = JSON.parse(settingsJson);
-    const removedPrompt = filterHookEntries(settings, 'UserPromptSubmit', isAmbient);
-    const removedOrchestrator = filterHookEntries(settings, 'SessionStart', isOrchestrator);
+    const removedPrompt = removeHooks(settings, 'UserPromptSubmit', isAmbient);
+    const removedOrchestrator = removeHooks(settings, 'SessionStart', isOrchestrator);
     // Clean up stale classification hooks from previous installs (no longer registered)
-    const removedClassification = filterHookEntries(settings, 'SessionStart', isClassification);
+    const removedClassification = removeHooks(settings, 'SessionStart', isClassification);
     // Purge legacy commands rule (runs before early-return so stale files are always removed)
-    await removeLegacyCommandsRule();
+    if (options.purgeLegacyRule !== false)
+        await removeLegacyCommandsRule();
     if (!removedPrompt && !removedOrchestrator && !removedClassification)
         return settingsJson;
     return JSON.stringify(settings, null, 2) + '\n';
 }
+/**
+ * Converge the ambient hooks in a settings JSON string to `enabled`.
+ *
+ * The one ambient transform `devflow init` applies inside its single settings
+ * read-modify-write pass: always remove-then-add, which upgrades a legacy
+ * `ambient-prompt` hook and re-points devflow's hooks at `devflowDir`. Both halves
+ * match hooks exactly (D-AMBIENT-EXACT-HOOK), so a user's own hooks — and their
+ * siblings in a shared matcher group — come through byte-identical.
+ */
+export async function convergeAmbientHooks(settingsJson, enabled, devflowDir) {
+    const cleaned = await removeAmbientHook(settingsJson);
+    return enabled ? addAmbientHook(cleaned, devflowDir) : cleaned;
+}
 /**
  * Check if the ambient hook (legacy or current) is registered in settings JSON or parsed Settings object.
  * Preamble-authoritative: returns true iff the UserPromptSubmit preamble hook is present.
@@ -122,110 +143,104 @@ export async function removeAmbientHook(settingsJson) {
  */
 export function hasAmbientHook(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    return settings.hooks?.UserPromptSubmit?.some((matcher) => matcher.hooks.some((h) => h.command.includes(PREAMBLE_HOOK_MARKER) || h.command.includes(LEGACY_HOOK_MARKER))) ?? false;
+    return hasHook(settings, 'UserPromptSubmit', isAmbient);
 }
 /**
  * Check if the orchestrator SessionStart hook is present in settings JSON or parsed Settings object.
  */
 function hasOrchestratorHook(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    return settings.hooks?.SessionStart?.some((matcher) => matcher.hooks.some((h) => h.command.includes(ORCHESTRATOR_HOOK_MARKER))) ?? false;
+    return hasHook(settings, 'SessionStart', isOrchestrator);
 }
-export const ambientCommand = new Command('ambient')
-    .description('Enable or disable ambient mode (orchestrator charter + plan handoff)')
-    .option('--enable', 'Register ambient mode hooks')
-    .option('--disable', 'Remove ambient mode hooks')
-    .option('--status', 'Check if ambient mode is enabled')
-    .action(async (options) => {
-    const hasFlag = options.enable || options.disable || options.status;
-    if (!hasFlag) {
-        p.intro(color.bgMagenta(color.white(' Ambient Mode ')));
-        p.note(`${color.cyan('devflow ambient --enable')}   Register orchestrator hooks\n` +
-            `${color.cyan('devflow ambient --disable')}  Remove orchestrator hooks\n` +
-            `${color.cyan('devflow ambient --status')}   Check current state`, 'Usage');
-        return;
-    }
-    const claudeDir = getClaudeDirectory();
-    const settingsPath = path.join(claudeDir, 'settings.json');
-    let settingsContent;
-    try {
-        settingsContent = await fs.readFile(settingsPath, 'utf-8');
-    }
-    catch (err) {
-        if (err.code !== 'ENOENT')
-            throw err;
-        if (options.status) {
-            p.log.info('Ambient mode: disabled (no settings.json found)');
+/**
+ * Build a fresh Commander Command for the `ambient` subcommand.
+ * Exported for tests that need per-test isolation (Commander keeps parsed option
+ * values on the instance, so a reused command leaks options between runs).
+ */
+export function createAmbientCommand() {
+    return new Command('ambient')
+        .description('Enable or disable ambient mode (orchestrator charter + plan handoff)')
+        .option('--enable', 'Register ambient mode hooks')
+        .option('--disable', 'Remove ambient mode hooks')
+        .option('--status', 'Check if ambient mode is enabled')
+        .action(async (options) => {
+        const hasFlag = options.enable || options.disable || options.status;
+        if (!hasFlag) {
+            p.intro(color.bgMagenta(color.white(' Ambient Mode ')));
+            p.note(`${color.cyan('devflow ambient --enable')}   Register orchestrator hooks\n` +
+                `${color.cyan('devflow ambient --disable')}  Remove orchestrator hooks\n` +
+                `${color.cyan('devflow ambient --status')}   Check current state`, 'Usage');
             return;
         }
-        // Create minimal settings.json
-        settingsContent = '{}';
-    }
-    // Parse settings once, guarded against corrupt files.
-    // hasAmbientHook / hasOrchestratorHook accept Settings directly to avoid re-parsing.
-    let parsedSettings;
-    try {
-        parsedSettings = JSON.parse(settingsContent);
-    }
-    catch (err) {
-        p.log.error(`Could not parse settings.json: ${err.message}`);
-        return;
-    }
-    if (options.status) {
-        const enabled = hasAmbientHook(parsedSettings);
-        const hasOrchestrator = hasOrchestratorHook(parsedSettings);
-        const repairHint = enabled !== hasOrchestrator
-            ? ` ${color.dim('(partial — run devflow ambient --enable to repair)')}`
-            : '';
-        if (enabled) {
-            p.log.info(`Ambient mode: ${color.green('enabled')}${repairHint}`);
+        const claudeDir = getClaudeDirectory();
+        const settingsPath = path.join(claudeDir, 'settings.json');
+        let settingsContent;
+        try {
+            settingsContent = await fs.readFile(settingsPath, 'utf-8');
         }
-        else {
-            p.log.info(`Ambient mode: ${color.dim('disabled')}${repairHint}`);
-        }
-        return;
-    }
-    // Resolve devflow scripts directory.
-    // Primary: getDevFlowDirectory() — purpose-built, not coupled to hook path layout.
-    // Fallback: infer from Stop hook command path (legacy installs where getDevFlowDirectory
-    //   may not yet reflect the correct location).
-    let devflowDir = getDevFlowDirectory();
-    try {
-        const stopHook = parsedSettings.hooks?.Stop?.[0]?.hooks?.[0]?.command;
-        if (stopHook) {
-            const hookBinary = stopHook.split(' ')[0];
-            const inferred = path.resolve(hookBinary, '..', '..', '..');
-            // Only use inferred path when it differs from the canonical default —
-            // this handles legacy installs where the hook was installed to a non-standard location.
-            if (inferred !== devflowDir) {
-                devflowDir = inferred;
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            if (options.status) {
+                p.log.info('Ambient mode: disabled (no settings.json found)');
+                return;
             }
+            // Create minimal settings.json
+            settingsContent = '{}';
         }
-    }
-    catch (err) {
-        p.log.warn(`Could not resolve devflow directory from Stop hook: ${err.message}`);
-    }
-    if (options.enable) {
-        const updated = await addAmbientHook(settingsContent, devflowDir);
-        if (updated === settingsContent) {
-            // Both hooks already present — addAmbientHook purges any legacy rule anyway
-            p.log.info('Ambient mode already enabled');
+        // Parse settings once, guarded against corrupt files.
+        // hasAmbientHook / hasOrchestratorHook accept Settings directly to avoid re-parsing.
+        let parsedSettings;
+        try {
+            parsedSettings = JSON.parse(settingsContent);
+        }
+        catch (err) {
+            p.log.error(`Could not parse settings.json: ${err.message}`);
             return;
         }
-        await writeFileAtomicExclusive(settingsPath, updated);
-        await syncManifestFeature(getDevFlowDirectory(), 'ambient', true);
-        p.log.success('Ambient mode enabled — orchestrator hooks registered');
-        p.log.info(color.dim('Charter at session start, reminder per prompt, plan handoffs auto-run devflow:implement (git repos only)'));
-    }
-    if (options.disable) {
-        const updated = await removeAmbientHook(settingsContent);
-        if (updated === settingsContent) {
-            p.log.info('Ambient mode already disabled');
+        if (options.status) {
+            const enabled = hasAmbientHook(parsedSettings);
+            const hasOrchestrator = hasOrchestratorHook(parsedSettings);
+            const repairHint = enabled !== hasOrchestrator
+                ? ` ${color.dim('(partial — run devflow ambient --enable to repair)')}`
+                : '';
+            if (enabled) {
+                p.log.info(`Ambient mode: ${color.green('enabled')}${repairHint}`);
+            }
+            else {
+                p.log.info(`Ambient mode: ${color.dim('disabled')}${repairHint}`);
+            }
             return;
         }
-        await writeFileAtomicExclusive(settingsPath, updated);
-        await syncManifestFeature(getDevFlowDirectory(), 'ambient', false);
-        p.log.success('Ambient mode disabled — hooks removed');
-    }
-});
+        // D-AMBIENT-CANONICAL-DIR: the hooks always point at the canonical devflow
+        // directory, where init installs run-hook. Never infer it from settings.json:
+        // the first Stop hook is whichever hook the user listed first (a notification
+        // sound, say), and a path derived from it names a run-hook that does not
+        // exist, so every prompt would fail.
+        const devflowDir = getDevFlowDirectory();
+        if (options.enable) {
+            const updated = await addAmbientHook(settingsContent, devflowDir);
+            if (updated === settingsContent) {
+                // Both hooks already present — addAmbientHook purges any legacy rule anyway
+                p.log.info('Ambient mode already enabled');
+                return;
+            }
+            await writeSettingsFileAtomic(settingsPath, updated);
+            await syncManifestFeature(devflowDir, 'ambient', true);
+            p.log.success('Ambient mode enabled — orchestrator hooks registered');
+            p.log.info(color.dim('Charter at session start, reminder per prompt, plan handoffs auto-run devflow:implement (git repos only)'));
+        }
+        if (options.disable) {
+            const updated = await removeAmbientHook(settingsContent);
+            if (updated === settingsContent) {
+                p.log.info('Ambient mode already disabled');
+                return;
+            }
+            await writeSettingsFileAtomic(settingsPath, updated);
+            await syncManifestFeature(devflowDir, 'ambient', false);
+            p.log.success('Ambient mode disabled — hooks removed');
+        }
+    });
+}
+export const ambientCommand = createAmbientCommand();
 //# sourceMappingURL=ambient.js.map

package/dist/cli/commands/capture.js

@@ -1,4 +1,4 @@
-import * as path from 'path';
+import { devflowHookOwner, ensureHook, hasHook, removeHooks, runHookCommand, } from '../../targets/claude-code/hooks.js';
 // ─── Capture hook utilities ────────────────────────────────────────────────
 //
 // The capture bundle (capture-prompt, capture-turn, capture-question) is
@@ -9,19 +9,20 @@ import * as path from 'path';
 // queue-append's queue_read_gates). Follows the context.ts add/remove/has
 // pattern rather than memory.ts's toggle pattern.
 //
-// IMPORTANT — Stop-array ordering contract: capture-turn MUST be registered
-// BEFORE memory-worker in the Stop hook array (see memory.ts). Settings.json
-// hook arrays run in array order, and memory-worker's throttle/spawn decision
-// assumes the current turn has already been appended to the queue by
-// capture-turn earlier in the same Stop event (append-before-spawn). This
-// module only ever pushes capture-turn; callers (init.ts) must register the
-// capture bundle before the memory bundle to preserve this ordering.
+// Stop-event concurrency contract: Claude Code runs the hooks of one event in
+// parallel, so array position in settings.json orders nothing at run time —
+// memory-worker can spawn background-memory-update before capture-turn has
+// appended this turn's assistant row. The worker tolerates that: a queue that
+// holds only user rows is left in place and the LLM run skipped
+// (D-QUEUE-NO-ORPHAN-DELETE in background-memory-update), so the next run
+// takes the whole turn. init.ts still registers the capture bundle before the
+// memory bundle, which keeps settings.json stable across re-inits.
 const CAPTURE_PROMPT_MARKER = 'capture-prompt';
 const CAPTURE_TURN_MARKER = 'capture-turn';
 const CAPTURE_QUESTION_MARKER = 'capture-question';
 const CAPTURE_QUESTION_MATCHER = 'AskUserQuestion';
 /**
- * Map of hook event type → filename marker for the capture hooks.
+ * Map of hook event type → run-hook marker for the capture hooks.
  * Three hooks total: UserPromptSubmit, Stop, PostToolUse (matcher-scoped).
  */
 const CAPTURE_HOOK_CONFIG = {
@@ -29,6 +30,15 @@ const CAPTURE_HOOK_CONFIG = {
     Stop: CAPTURE_TURN_MARKER,
     PostToolUse: CAPTURE_QUESTION_MARKER,
 };
+/**
+ * D-EXACT-HOOK-OWNER: a capture hook is devflow's only when its command ends in
+ * `/scripts/hooks/run-hook <marker>` (hooks.ts), under any directory. The capture
+ * hooks have been registered through run-hook since they first shipped, so there
+ * is no legacy form to recognise.
+ */
+function isCaptureHook(marker) {
+    return devflowHookOwner([marker]);
+}
 /**
  * Add all 3 capture hooks (UserPromptSubmit, Stop, PostToolUse) to settings JSON.
  * Idempotent — skips hooks that already exist. Returns unchanged JSON if all 3 present.
@@ -40,31 +50,14 @@ export function addCaptureHooks(settingsJson, devflowDir) {
     if (hasCaptureHooks(settings)) {
         return settingsJson;
     }
-    if (!settings.hooks) {
-        settings.hooks = {};
-    }
     for (const [hookType, marker] of Object.entries(CAPTURE_HOOK_CONFIG)) {
-        const existing = settings.hooks[hookType] ?? [];
-        const alreadyPresent = existing.some((matcher) => matcher.hooks.some((h) => h.command.includes(marker)));
-        if (!alreadyPresent) {
-            const hookCommand = path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ` ${marker}`;
-            const newEntry = {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand,
-                        timeout: 10,
-                    },
-                ],
-            };
-            if (hookType === 'PostToolUse') {
-                newEntry.matcher = CAPTURE_QUESTION_MATCHER;
-            }
-            if (!settings.hooks[hookType]) {
-                settings.hooks[hookType] = [];
-            }
-            settings.hooks[hookType].push(newEntry);
+        const newEntry = {
+            hooks: [{ type: 'command', command: runHookCommand(devflowDir, marker), timeout: 10 }],
+        };
+        if (hookType === 'PostToolUse') {
+            newEntry.matcher = CAPTURE_QUESTION_MATCHER;
         }
+        ensureHook(settings, hookType, isCaptureHook(marker), newEntry);
     }
     return JSON.stringify(settings, null, 2) + '\n';
 }
@@ -81,25 +74,11 @@ export function removeCaptureHooks(input) {
     // happened. String input is returned byte-identical (no re-formatting).
     const settingsJson = typeof input === 'string' ? input : JSON.stringify(input, null, 2) + '\n';
     const settings = typeof input === 'string' ? JSON.parse(input) : structuredClone(input);
-    if (!settings.hooks) {
-        return settingsJson;
-    }
     let changed = false;
     for (const [hookType, marker] of Object.entries(CAPTURE_HOOK_CONFIG)) {
-        if (!settings.hooks[hookType]) {
-            continue;
-        }
-        const before = settings.hooks[hookType].length;
-        settings.hooks[hookType] = settings.hooks[hookType].filter((matcher) => !matcher.hooks.some((h) => h.command.includes(marker)));
-        if (settings.hooks[hookType].length !== before) {
-            changed = true;
-        }
-        if (settings.hooks[hookType].length === 0) {
-            delete settings.hooks[hookType];
-        }
-    }
-    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
+        // Evaluate every removal — never short-circuit (PF-015).
+        const removed = removeHooks(settings, hookType, isCaptureHook(marker));
+        changed = changed || removed;
     }
     if (!changed) {
         return settingsJson;
@@ -118,15 +97,10 @@ export function hasCaptureHooks(input) {
  */
 export function countCaptureHooks(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    if (!settings.hooks) {
-        return 0;
-    }
     let count = 0;
     for (const [hookType, marker] of Object.entries(CAPTURE_HOOK_CONFIG)) {
-        const matchers = settings.hooks[hookType] ?? [];
-        if (matchers.some((matcher) => matcher.hooks.some((h) => h.command.includes(marker)))) {
+        if (hasHook(settings, hookType, isCaptureHook(marker)))
             count++;
-        }
     }
     return count;
 }