gsd-pi 2.11.0 → 2.12.0

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -0,0 +1,449 @@
+// GSD Extension — Hook Engine (Post-Unit, Pre-Dispatch, State Persistence)
+// Manages hook queue, cycle tracking, artifact verification, pre-dispatch
+// interception, and durable hook state for user-configured extensibility.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import type {
+  PostUnitHookConfig,
+  PreDispatchHookConfig,
+  HookExecutionState,
+  HookDispatchResult,
+  PreDispatchResult,
+  PersistedHookState,
+  HookStatusEntry,
+} from "./types.js";
+import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Hook Queue State ──────────────────────────────────────────────────────
+
+/** Currently executing hook, or null if in normal dispatch flow. */
+let activeHook: HookExecutionState | null = null;
+
+/** Queue of hooks remaining for the current trigger unit. */
+let hookQueue: Array<{
+  config: PostUnitHookConfig;
+  triggerUnitType: string;
+  triggerUnitId: string;
+}> = [];
+
+/** Cycle counts per hook+trigger, keyed as "hookName/triggerUnitType/triggerUnitId". */
+const cycleCounts = new Map<string, number>();
+
+/** Set when a hook completes with retry_on artifact present — signals caller to re-run trigger. */
+let retryPending = false;
+
+/** Stores the trigger unit info for pending retries so caller knows what to re-run. */
+let retryTrigger: { unitType: string; unitId: string } | null = null;
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Called after a unit completes. Returns the next hook unit to dispatch,
+ * or null if no hooks apply (normal dispatch should proceed).
+ *
+ * Call flow:
+ * 1. A core unit (e.g. execute-task) completes → handleAgentEnd calls this
+ * 2. If hooks match, returns first hook to dispatch. Caller sends the prompt.
+ * 3. Hook unit completes → handleAgentEnd calls this again (activeHook is set)
+ * 4. Checks retry_on / next hook / done → returns next action or null
+ */
+export function checkPostUnitHooks(
+  completedUnitType: string,
+  completedUnitId: string,
+  basePath: string,
+): HookDispatchResult | null {
+  // If we just completed a hook unit, handle its result
+  if (activeHook) {
+    return handleHookCompletion(basePath);
+  }
+
+  // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
+  if (completedUnitType.startsWith("hook/")) return null;
+
+  // Check if any hooks are configured for this unit type
+  const hooks = resolvePostUnitHooks().filter(h =>
+    h.after.includes(completedUnitType),
+  );
+  if (hooks.length === 0) return null;
+
+  // Build hook queue for this trigger
+  hookQueue = hooks.map(config => ({
+    config,
+    triggerUnitType: completedUnitType,
+    triggerUnitId: completedUnitId,
+  }));
+
+  return dequeueNextHook(basePath);
+}
+
+/**
+ * Returns whether a hook is currently active (for progress display).
+ */
+export function getActiveHook(): HookExecutionState | null {
+  return activeHook;
+}
+
+/**
+ * Returns true if a retry of the trigger unit was requested by a hook.
+ * Caller should re-dispatch the original trigger unit, then hooks will
+ * fire again on its next completion.
+ */
+export function isRetryPending(): boolean {
+  return retryPending;
+}
+
+/**
+ * Returns the trigger unit info for a pending retry, or null.
+ * Clears the retry state after reading.
+ */
+export function consumeRetryTrigger(): { unitType: string; unitId: string } | null {
+  if (!retryPending || !retryTrigger) return null;
+  const trigger = { ...retryTrigger };
+  retryPending = false;
+  retryTrigger = null;
+  return trigger;
+}
+
+/**
+ * Reset all hook state. Called on auto-mode start/stop.
+ */
+export function resetHookState(): void {
+  activeHook = null;
+  hookQueue = [];
+  cycleCounts.clear();
+  retryPending = false;
+  retryTrigger = null;
+}
+
+// ─── Internal ──────────────────────────────────────────────────────────────
+
+function dequeueNextHook(basePath: string): HookDispatchResult | null {
+  while (hookQueue.length > 0) {
+    const entry = hookQueue.shift()!;
+    const { config, triggerUnitType, triggerUnitId } = entry;
+
+    // Check idempotency — if artifact already exists, skip this hook
+    if (config.artifact) {
+      const artifactPath = resolveHookArtifactPath(basePath, triggerUnitId, config.artifact);
+      if (existsSync(artifactPath)) continue;
+    }
+
+    // Check cycle limit
+    const cycleKey = `${config.name}/${triggerUnitType}/${triggerUnitId}`;
+    const currentCycle = (cycleCounts.get(cycleKey) ?? 0) + 1;
+    const maxCycles = config.max_cycles ?? 1;
+    if (currentCycle > maxCycles) continue;
+
+    cycleCounts.set(cycleKey, currentCycle);
+
+    activeHook = {
+      hookName: config.name,
+      triggerUnitType,
+      triggerUnitId,
+      cycle: currentCycle,
+      pendingRetry: false,
+    };
+
+    // Build the prompt with variable substitution
+    const [mid, sid, tid] = triggerUnitId.split("/");
+    const prompt = config.prompt
+      .replace(/\{milestoneId\}/g, mid ?? "")
+      .replace(/\{sliceId\}/g, sid ?? "")
+      .replace(/\{taskId\}/g, tid ?? "");
+
+    return {
+      hookName: config.name,
+      prompt,
+      model: config.model,
+      unitType: `hook/${config.name}`,
+      unitId: triggerUnitId,
+    };
+  }
+
+  // No more hooks — clear active state and return null for normal dispatch
+  activeHook = null;
+  return null;
+}
+
+function handleHookCompletion(basePath: string): HookDispatchResult | null {
+  const hook = activeHook!;
+  const hooks = resolvePostUnitHooks();
+  const config = hooks.find(h => h.name === hook.hookName);
+
+  // Check if retry was requested via retry_on artifact
+  if (config?.retry_on) {
+    const retryArtifactPath = resolveHookArtifactPath(basePath, hook.triggerUnitId, config.retry_on);
+    if (existsSync(retryArtifactPath)) {
+      // Check cycle limit before allowing retry
+      const cycleKey = `${config.name}/${hook.triggerUnitType}/${hook.triggerUnitId}`;
+      const currentCycle = cycleCounts.get(cycleKey) ?? 1;
+      const maxCycles = config.max_cycles ?? 1;
+
+      if (currentCycle < maxCycles) {
+        // Signal retry — caller will re-dispatch the trigger unit
+        activeHook = null;
+        hookQueue = [];
+        retryPending = true;
+        retryTrigger = { unitType: hook.triggerUnitType, unitId: hook.triggerUnitId };
+        return null;
+      }
+      // Max cycles reached — fall through to normal completion
+    }
+  }
+
+  // Hook completed normally — try next hook in queue
+  activeHook = null;
+  return dequeueNextHook(basePath);
+}
+
+/**
+ * Resolve the path where a hook artifact is expected to be written.
+ * Uses the trigger unit's directory context:
+ *   - Task-level (M001/S01/T01): .gsd/M001/slices/S01/tasks/T01-{artifact}
+ *   - Slice-level (M001/S01):    .gsd/M001/slices/S01/{artifact}
+ *   - Milestone-level (M001):    .gsd/M001/{artifact}
+ */
+export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
+  const parts = unitId.split("/");
+  if (parts.length === 3) {
+    const [mid, sid, tid] = parts;
+    return join(basePath, ".gsd", mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
+  }
+  if (parts.length === 2) {
+    const [mid, sid] = parts;
+    return join(basePath, ".gsd", mid, "slices", sid, artifactName);
+  }
+  return join(basePath, ".gsd", parts[0], artifactName);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 2: Pre-Dispatch Hooks
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run pre-dispatch hooks for a unit about to be dispatched.
+ * Returns a result indicating whether the unit should proceed (with optional
+ * prompt modifications), be skipped, or be replaced entirely.
+ *
+ * Multiple hooks can fire for the same unit type. They compose:
+ * - "modify" hooks stack (all prepend/append applied in order)
+ * - "skip" short-circuits (first matching skip wins)
+ * - "replace" short-circuits (first matching replace wins)
+ * - Skip/replace hooks take precedence over modify hooks
+ */
+export function runPreDispatchHooks(
+  unitType: string,
+  unitId: string,
+  prompt: string,
+  basePath: string,
+): PreDispatchResult {
+  // Don't intercept hook units
+  if (unitType.startsWith("hook/")) {
+    return { action: "proceed", prompt, firedHooks: [] };
+  }
+
+  const hooks = resolvePreDispatchHooks().filter(h =>
+    h.before.includes(unitType),
+  );
+  if (hooks.length === 0) {
+    return { action: "proceed", prompt, firedHooks: [] };
+  }
+
+  const [mid, sid, tid] = unitId.split("/");
+  const substitute = (text: string): string =>
+    text
+      .replace(/\{milestoneId\}/g, mid ?? "")
+      .replace(/\{sliceId\}/g, sid ?? "")
+      .replace(/\{taskId\}/g, tid ?? "");
+
+  const firedHooks: string[] = [];
+  let currentPrompt = prompt;
+
+  for (const hook of hooks) {
+    if (hook.action === "skip") {
+      // Check optional skip condition
+      if (hook.skip_if) {
+        const conditionPath = resolveHookArtifactPath(basePath, unitId, hook.skip_if);
+        if (!existsSync(conditionPath)) continue; // Condition not met, don't skip
+      }
+      firedHooks.push(hook.name);
+      return { action: "skip", firedHooks };
+    }
+
+    if (hook.action === "replace") {
+      firedHooks.push(hook.name);
+      return {
+        action: "replace",
+        prompt: substitute(hook.prompt ?? ""),
+        unitType: hook.unit_type,
+        model: hook.model,
+        firedHooks,
+      };
+    }
+
+    if (hook.action === "modify") {
+      firedHooks.push(hook.name);
+      if (hook.prepend) {
+        currentPrompt = `${substitute(hook.prepend)}\n\n${currentPrompt}`;
+      }
+      if (hook.append) {
+        currentPrompt = `${currentPrompt}\n\n${substitute(hook.append)}`;
+      }
+    }
+  }
+
+  return {
+    action: "proceed",
+    prompt: currentPrompt,
+    model: hooks.find(h => h.action === "modify" && h.model)?.model,
+    firedHooks,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: Hook State Persistence
+// ═══════════════════════════════════════════════════════════════════════════
+
+const HOOK_STATE_FILE = "hook-state.json";
+
+function hookStatePath(basePath: string): string {
+  return join(basePath, ".gsd", HOOK_STATE_FILE);
+}
+
+/**
+ * Persist current hook cycle counts to disk so they survive crashes/restarts.
+ * Called after each hook dispatch and on auto-mode pause.
+ */
+export function persistHookState(basePath: string): void {
+  const state: PersistedHookState = {
+    cycleCounts: Object.fromEntries(cycleCounts),
+    savedAt: new Date().toISOString(),
+  };
+  try {
+    const dir = join(basePath, ".gsd");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(hookStatePath(basePath), JSON.stringify(state, null, 2), "utf-8");
+  } catch {
+    // Non-fatal — state is recreatable from artifacts
+  }
+}
+
+/**
+ * Restore hook cycle counts from disk after a crash/restart.
+ * Called during auto-mode resume.
+ */
+export function restoreHookState(basePath: string): void {
+  try {
+    const filePath = hookStatePath(basePath);
+    if (!existsSync(filePath)) return;
+    const raw = readFileSync(filePath, "utf-8");
+    const state: PersistedHookState = JSON.parse(raw);
+    if (state.cycleCounts && typeof state.cycleCounts === "object") {
+      cycleCounts.clear();
+      for (const [key, value] of Object.entries(state.cycleCounts)) {
+        if (typeof value === "number") {
+          cycleCounts.set(key, value);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — fresh state is fine
+  }
+}
+
+/**
+ * Clear persisted hook state file from disk.
+ * Called on clean auto-mode stop.
+ */
+export function clearPersistedHookState(basePath: string): void {
+  try {
+    const filePath = hookStatePath(basePath);
+    if (existsSync(filePath)) {
+      writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, savedAt: new Date().toISOString() }, null, 2), "utf-8");
+    }
+  } catch {
+    // Non-fatal
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 3: Hook Status Reporting
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get status of all configured hooks for display by /gsd hooks.
+ */
+export function getHookStatus(): HookStatusEntry[] {
+  const entries: HookStatusEntry[] = [];
+
+  // Post-unit hooks
+  const postHooks = resolvePostUnitHooks();
+  for (const hook of postHooks) {
+    const activeCycles: Record<string, number> = {};
+    for (const [key, count] of cycleCounts) {
+      if (key.startsWith(`${hook.name}/`)) {
+        activeCycles[key] = count;
+      }
+    }
+    entries.push({
+      name: hook.name,
+      type: "post",
+      enabled: hook.enabled !== false,
+      targets: hook.after,
+      activeCycles,
+    });
+  }
+
+  // Pre-dispatch hooks
+  const preHooks = resolvePreDispatchHooks();
+  for (const hook of preHooks) {
+    entries.push({
+      name: hook.name,
+      type: "pre",
+      enabled: hook.enabled !== false,
+      targets: hook.before,
+      activeCycles: {},
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Format hook status for terminal display.
+ */
+export function formatHookStatus(): string {
+  const entries = getHookStatus();
+  if (entries.length === 0) {
+    return "No hooks configured. Add post_unit_hooks or pre_dispatch_hooks to .gsd/preferences.md";
+  }
+
+  const lines: string[] = ["Configured Hooks:", ""];
+
+  const postHooks = entries.filter(e => e.type === "post");
+  const preHooks = entries.filter(e => e.type === "pre");
+
+  if (postHooks.length > 0) {
+    lines.push("Post-Unit Hooks (run after unit completes):");
+    for (const hook of postHooks) {
+      const status = hook.enabled ? "enabled" : "disabled";
+      const cycles = Object.keys(hook.activeCycles).length;
+      const cycleInfo = cycles > 0 ? ` (${cycles} active cycle${cycles === 1 ? "" : "s"})` : "";
+      lines.push(`  ${hook.name} [${status}] → after: ${hook.targets.join(", ")}${cycleInfo}`);
+    }
+    lines.push("");
+  }
+
+  if (preHooks.length > 0) {
+    lines.push("Pre-Dispatch Hooks (run before unit dispatches):");
+    for (const hook of preHooks) {
+      const status = hook.enabled ? "enabled" : "disabled";
+      lines.push(`  ${hook.name} [${status}] → before: ${hook.targets.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/resources/extensions/gsd/preferences.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
 import type { GitPreferences } from "./git-service.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
@@ -93,6 +94,8 @@ export interface GSDPreferences {
   budget_ceiling?: number;
   remote_questions?: RemoteQuestionsConfig;
   git?: GitPreferences;
+  post_unit_hooks?: PostUnitHookConfig[];
+  pre_dispatch_hooks?: PreDispatchHookConfig[];
 }
 
 export interface LoadedGSDPreferences {
@@ -626,6 +629,8 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     git: (base.git || override.git)
       ? { ...(base.git ?? {}), ...(override.git ?? {}) }
       : undefined,
+    post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
+    pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
   };
 }
 
@@ -713,6 +718,138 @@ function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Post-Unit Hooks ─────────────────────────────────────────────────
+  if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
+    const validHooks: PostUnitHookConfig[] = [];
+    const seenNames = new Set<string>();
+    const knownUnitTypes = new Set([
+      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+      "run-uat", "fix-merge", "complete-milestone",
+    ]);
+    for (const hook of preferences.post_unit_hooks) {
+      if (!hook || typeof hook !== "object") {
+        errors.push("post_unit_hooks entry must be an object");
+        continue;
+      }
+      const name = typeof hook.name === "string" ? hook.name.trim() : "";
+      if (!name) {
+        errors.push("post_unit_hooks entry missing name");
+        continue;
+      }
+      if (seenNames.has(name)) {
+        errors.push(`duplicate post_unit_hooks name: ${name}`);
+        continue;
+      }
+      const after = normalizeStringList(hook.after);
+      if (after.length === 0) {
+        errors.push(`post_unit_hooks "${name}" missing after`);
+        continue;
+      }
+      for (const ut of after) {
+        if (!knownUnitTypes.has(ut)) {
+          errors.push(`post_unit_hooks "${name}" unknown unit type in after: ${ut}`);
+        }
+      }
+      const prompt = typeof hook.prompt === "string" ? hook.prompt.trim() : "";
+      if (!prompt) {
+        errors.push(`post_unit_hooks "${name}" missing prompt`);
+        continue;
+      }
+      const validHook: PostUnitHookConfig = { name, after, prompt };
+      if (hook.max_cycles !== undefined) {
+        const mc = typeof hook.max_cycles === "number" ? hook.max_cycles : Number(hook.max_cycles);
+        validHook.max_cycles = Number.isFinite(mc) ? Math.max(1, Math.min(10, Math.round(mc))) : 1;
+      }
+      if (typeof hook.model === "string" && hook.model.trim()) {
+        validHook.model = hook.model.trim();
+      }
+      if (typeof hook.artifact === "string" && hook.artifact.trim()) {
+        validHook.artifact = hook.artifact.trim();
+      }
+      if (typeof hook.retry_on === "string" && hook.retry_on.trim()) {
+        validHook.retry_on = hook.retry_on.trim();
+      }
+      if (typeof hook.agent === "string" && hook.agent.trim()) {
+        validHook.agent = hook.agent.trim();
+      }
+      if (hook.enabled !== undefined) {
+        validHook.enabled = !!hook.enabled;
+      }
+      seenNames.add(name);
+      validHooks.push(validHook);
+    }
+    if (validHooks.length > 0) {
+      validated.post_unit_hooks = validHooks;
+    }
+  }
+
+  // ─── Pre-Dispatch Hooks ─────────────────────────────────────────────────
+  if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
+    const validPreHooks: PreDispatchHookConfig[] = [];
+    const seenPreNames = new Set<string>();
+    const knownUnitTypes = new Set([
+      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+      "run-uat", "fix-merge", "complete-milestone",
+    ]);
+    const validActions = new Set(["modify", "skip", "replace"]);
+    for (const hook of preferences.pre_dispatch_hooks) {
+      if (!hook || typeof hook !== "object") {
+        errors.push("pre_dispatch_hooks entry must be an object");
+        continue;
+      }
+      const name = typeof hook.name === "string" ? hook.name.trim() : "";
+      if (!name) {
+        errors.push("pre_dispatch_hooks entry missing name");
+        continue;
+      }
+      if (seenPreNames.has(name)) {
+        errors.push(`duplicate pre_dispatch_hooks name: ${name}`);
+        continue;
+      }
+      const before = normalizeStringList(hook.before);
+      if (before.length === 0) {
+        errors.push(`pre_dispatch_hooks "${name}" missing before`);
+        continue;
+      }
+      for (const ut of before) {
+        if (!knownUnitTypes.has(ut)) {
+          errors.push(`pre_dispatch_hooks "${name}" unknown unit type in before: ${ut}`);
+        }
+      }
+      const action = typeof hook.action === "string" ? hook.action.trim() : "";
+      if (!validActions.has(action)) {
+        errors.push(`pre_dispatch_hooks "${name}" invalid action: ${action} (must be modify, skip, or replace)`);
+        continue;
+      }
+      const validHook: PreDispatchHookConfig = { name, before, action: action as PreDispatchHookConfig["action"] };
+      if (typeof hook.prepend === "string" && hook.prepend.trim()) validHook.prepend = hook.prepend.trim();
+      if (typeof hook.append === "string" && hook.append.trim()) validHook.append = hook.append.trim();
+      if (typeof hook.prompt === "string" && hook.prompt.trim()) validHook.prompt = hook.prompt.trim();
+      if (typeof hook.unit_type === "string" && hook.unit_type.trim()) validHook.unit_type = hook.unit_type.trim();
+      if (typeof hook.skip_if === "string" && hook.skip_if.trim()) validHook.skip_if = hook.skip_if.trim();
+      if (typeof hook.model === "string" && hook.model.trim()) validHook.model = hook.model.trim();
+      if (hook.enabled !== undefined) validHook.enabled = !!hook.enabled;
+
+      // Validation: action-specific required fields
+      if (action === "replace" && !validHook.prompt) {
+        errors.push(`pre_dispatch_hooks "${name}" action "replace" requires prompt`);
+        continue;
+      }
+      if (action === "modify" && !validHook.prepend && !validHook.append) {
+        errors.push(`pre_dispatch_hooks "${name}" action "modify" requires prepend or append`);
+        continue;
+      }
+
+      seenPreNames.add(name);
+      validPreHooks.push(validHook);
+    }
+    if (validPreHooks.length > 0) {
+      validated.pre_dispatch_hooks = validPreHooks;
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};
@@ -794,3 +931,58 @@ function normalizeStringList(value: unknown): string[] {
     .map((item) => item.trim())
     .filter(Boolean);
 }
+
+function mergePostUnitHooks(
+  base?: PostUnitHookConfig[],
+  override?: PostUnitHookConfig[],
+): PostUnitHookConfig[] | undefined {
+  if (!base?.length && !override?.length) return undefined;
+  const merged = [...(base ?? [])];
+  for (const hook of override ?? []) {
+    // Override hooks with same name replace base hooks
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve enabled post-unit hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePostUnitHooks(): PostUnitHookConfig[] {
+  const prefs = loadEffectiveGSDPreferences();
+  return (prefs?.preferences.post_unit_hooks ?? [])
+    .filter(h => h.enabled !== false);
+}
+
+function mergePreDispatchHooks(
+  base?: PreDispatchHookConfig[],
+  override?: PreDispatchHookConfig[],
+): PreDispatchHookConfig[] | undefined {
+  if (!base?.length && !override?.length) return undefined;
+  const merged = [...(base ?? [])];
+  for (const hook of override ?? []) {
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve enabled pre-dispatch hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
+  const prefs = loadEffectiveGSDPreferences();
+  return (prefs?.preferences.pre_dispatch_hooks ?? [])
+    .filter(h => h.enabled !== false);
+}