opencode-command-hooks 0.3.0 → 0.5.1

package/README.md

@@ -75,11 +75,12 @@ hooks:
 
 ### Hook Configuration Options
 
-| Option   | Type                   | Description                       |
-| -------- | ---------------------- | --------------------------------- |
-| `run`    | `string` \| `string[]` | Command(s) to execute             |
-| `inject` | `string`               | Message injected into the session |
-| `toast`  | `object`               | Toast notification configuration  |
+| Option           | Type                   | Description                                                              |
+| ---------------- | ---------------------- | ------------------------------------------------------------------------ |
+| `run`            | `string` \| `string[]` | Command(s) to execute                                                    |
+| `inject`         | `string`               | Message injected into the session                                        |
+| `toast`          | `object`               | Toast notification configuration                                         |
+| `overrideGlobal` | `boolean`              | When `true`, suppresses global hooks matching the same event/phase+tool. Must be a JSON boolean (`true`/`false`), not a string. |
 
 ### Toast Configuration
 
@@ -173,13 +174,21 @@ Add to your `opencode.json`:
 
 ## Configuration
 
-### JSON Config
+### Config Locations
+
+The plugin loads hooks from two locations:
 
-Create `.opencode/command-hooks.jsonc` in your project (the plugin searches upward from the current working directory):
+1. **User global**: `~/.config/opencode/command-hooks.jsonc` — hooks that apply to all projects
+2. **Project**: `.opencode/command-hooks.jsonc` — project-specific hooks (searches upward from cwd)
+
+Both are merged by default. See [Configuration Precedence](#configuration-precedence) for details.
+
+### JSON Config
 
 ```jsonc
 {
   "truncationLimit": 30000,
+  "ignoreGlobalConfig": false,
   "tool": [
     // Tool hooks
   ],
@@ -191,11 +200,12 @@ Create `.opencode/command-hooks.jsonc` in your project (the plugin searches upwa
 
 #### JSON Config Options
 
-| Option            | Type            | Description                                                                                                                        |
-| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `truncationLimit` | `number`        | Maximum characters to capture from command output. Defaults to 30,000 (matching OpenCode's bash tool). Must be a positive integer. |
-| `tool`            | `ToolHook[]`    | Array of tool execution hooks                                                                                                      |
-| `session`         | `SessionHook[]` | Array of session lifecycle hooks                                                                                                   |
+| Option              | Type            | Description                                                                                                                        |
+| ------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `truncationLimit`   | `number`        | Maximum characters to capture from command output. Defaults to 30,000 (matching OpenCode's bash tool). Must be a positive integer. Project config overrides global when both are set. |
+| `ignoreGlobalConfig`| `boolean`       | When `true`, skip loading `~/.config/opencode/command-hooks.jsonc`. Defaults to `false`. Must be a JSON boolean (`true`/`false`), not a string. |
+| `tool`              | `ToolHook[]`    | Array of tool execution hooks                                                                                                      |
+| `session`           | `SessionHook[]` | Array of session lifecycle hooks                                                                                                   |
 
 ### Markdown Frontmatter
 
@@ -216,11 +226,53 @@ hooks:
 
 ### Configuration Precedence
 
-1. Hooks are loaded from `.opencode/command-hooks.jsonc`
-2. Markdown hooks are converted to normal hooks with auto-generated IDs
-3. If a markdown hook and a global hook share the same `id`, the markdown hook wins
-4. Duplicate IDs within the same source are errors
-5. Global config is cached to avoid repeated file reads
+Hooks are loaded from two locations and merged:
+
+1. **User global config**: `~/.config/opencode/command-hooks.jsonc`
+2. **Project config**: `.opencode/command-hooks.jsonc` (searches upward from cwd)
+
+**Merge behavior:**
+
+| Scenario | Result |
+|----------|--------|
+| Different hook IDs | Both run (concatenation) |
+| Same hook ID | Project replaces global |
+| `overrideGlobal: true` on hook | Suppresses all global hooks for same event/phase+tool |
+| `ignoreGlobalConfig: true` in project | Skips global config entirely |
+| Both set `truncationLimit` | Project value wins |
+
+**Example: Override all global hooks for an event**
+
+```jsonc
+{
+  "session": [
+    {
+      "id": "my-session-idle",
+      "when": { "event": "session.idle" },
+      "run": "echo only this runs",
+      "overrideGlobal": true
+    }
+  ]
+}
+```
+
+**Example: Ignore global config entirely**
+
+```jsonc
+{
+  "ignoreGlobalConfig": true,
+  "tool": [
+    // Only these hooks will run
+  ]
+}
+```
+
+Additional precedence rules:
+- Markdown hooks are converted to normal hooks with auto-generated IDs
+- If a markdown hook and a config hook share the same `id`, the markdown hook wins
+- Duplicate IDs within the same source are errors
+- Tool override matching uses canonical keys, so `"bash"` and `["bash"]` are treated as equivalent
+- Config files are schema-validated; invalid value types (for example `"false"` for a boolean field) make that source invalid
 
 ---
 

package/dist/config/agent.d.ts

@@ -1,8 +1,11 @@
 /**
  * Agent configuration resolution and loading for command hooks
  *
- * Handles finding and parsing agent markdown files (.opencode/agent/*.md or
- * ~/.config/opencode/agent/*.md) to extract command_hooks from YAML frontmatter.
+ * Handles finding and parsing agent markdown files (.opencode/agents/*.md or
+ * ~/.config/opencode/agents/*.md) to extract command_hooks from YAML frontmatter.
+ *
+ * Backward compatibility: legacy singular directories (.opencode/agent and
+ * ~/.config/opencode/agent) are also supported as fallbacks.
  * These hooks are applied when the specific subagent is invoked via the task tool.
  */
 import type { CommandHooksConfig } from "../types/hooks.js";
@@ -10,8 +13,10 @@ import type { CommandHooksConfig } from "../types/hooks.js";
  * Resolve agent markdown file path by agent name
  *
  * Searches for agent markdown files in the following order:
- * 1. Project-level: .opencode/agent/{name}.md
- * 2. User-level: ~/.config/opencode/agent/{name}.md
+ * 1. Project-level: .opencode/agents/{name}.md
+ * 2. Project-level legacy fallback: .opencode/agent/{name}.md
+ * 3. User-level: ~/.config/opencode/agents/{name}.md
+ * 4. User-level legacy fallback: ~/.config/opencode/agent/{name}.md
  *
  * Returns the first existing path found, or null if no file exists.
  *
@@ -21,8 +26,10 @@ import type { CommandHooksConfig } from "../types/hooks.js";
  * @example
  * ```typescript
  * const path = await resolveAgentPath("engineer");
- * // Returns: "/Users/example/project/.opencode/agent/engineer.md" (if exists)
- * // Or: "/Users/example/.config/opencode/agent/engineer.md" (if project path doesn't exist)
+ * // Returns: "/Users/example/project/.opencode/agents/engineer.md" (if exists)
+ * // Or: "/Users/example/project/.opencode/agent/engineer.md" (legacy fallback)
+ * // Or: "/Users/example/.config/opencode/agents/engineer.md" (if project paths don't exist)
+ * // Or: "/Users/example/.config/opencode/agent/engineer.md" (legacy fallback)
  * // Or: null (if neither exists)
  * ```
  */

package/dist/config/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/config/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqChF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqBpF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/config/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqBpF"}

package/dist/config/agent.js

@@ -1,8 +1,11 @@
 /**
  * Agent configuration resolution and loading for command hooks
  *
- * Handles finding and parsing agent markdown files (.opencode/agent/*.md or
- * ~/.config/opencode/agent/*.md) to extract command_hooks from YAML frontmatter.
+ * Handles finding and parsing agent markdown files (.opencode/agents/*.md or
+ * ~/.config/opencode/agents/*.md) to extract command_hooks from YAML frontmatter.
+ *
+ * Backward compatibility: legacy singular directories (.opencode/agent and
+ * ~/.config/opencode/agent) are also supported as fallbacks.
  * These hooks are applied when the specific subagent is invoked via the task tool.
  */
 import { join } from "path";
@@ -13,8 +16,10 @@ import { logger } from "../logging.js";
  * Resolve agent markdown file path by agent name
  *
  * Searches for agent markdown files in the following order:
- * 1. Project-level: .opencode/agent/{name}.md
- * 2. User-level: ~/.config/opencode/agent/{name}.md
+ * 1. Project-level: .opencode/agents/{name}.md
+ * 2. Project-level legacy fallback: .opencode/agent/{name}.md
+ * 3. User-level: ~/.config/opencode/agents/{name}.md
+ * 4. User-level legacy fallback: ~/.config/opencode/agent/{name}.md
  *
  * Returns the first existing path found, or null if no file exists.
  *
@@ -24,8 +29,10 @@ import { logger } from "../logging.js";
  * @example
  * ```typescript
  * const path = await resolveAgentPath("engineer");
- * // Returns: "/Users/example/project/.opencode/agent/engineer.md" (if exists)
- * // Or: "/Users/example/.config/opencode/agent/engineer.md" (if project path doesn't exist)
+ * // Returns: "/Users/example/project/.opencode/agents/engineer.md" (if exists)
+ * // Or: "/Users/example/project/.opencode/agent/engineer.md" (legacy fallback)
+ * // Or: "/Users/example/.config/opencode/agents/engineer.md" (if project paths don't exist)
+ * // Or: "/Users/example/.config/opencode/agent/engineer.md" (legacy fallback)
  * // Or: null (if neither exists)
  * ```
  */
@@ -36,32 +43,25 @@ export async function resolveAgentPath(agentName) {
         return null;
     }
     const agentFileName = `${agentName}.md`;
-    // Check project-level agent file
-    const projectAgentPath = join(process.cwd(), ".opencode", "agent", agentFileName);
-    try {
-        const projectFile = Bun.file(projectAgentPath);
-        if (await projectFile.exists()) {
-            logger.debug(`Found project agent file: ${projectAgentPath}`);
-            return projectAgentPath;
+    const candidatePaths = [
+        join(process.cwd(), ".opencode", "agents", agentFileName),
+        join(process.cwd(), ".opencode", "agent", agentFileName),
+        join(homedir(), ".config", "opencode", "agents", agentFileName),
+        join(homedir(), ".config", "opencode", "agent", agentFileName),
+    ];
+    for (const candidatePath of candidatePaths) {
+        try {
+            const file = Bun.file(candidatePath);
+            if (await file.exists()) {
+                logger.debug(`Found agent file: ${candidatePath}`);
+                return candidatePath;
+            }
         }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        logger.debug(`Error checking project agent file ${projectAgentPath}: ${message}`);
-    }
-    // Check user-level agent file
-    const userAgentPath = join(homedir(), ".config", "opencode", "agent", agentFileName);
-    try {
-        const userFile = Bun.file(userAgentPath);
-        if (await userFile.exists()) {
-            logger.debug(`Found user agent file: ${userAgentPath}`);
-            return userAgentPath;
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`Error checking agent file ${candidatePath}: ${message}`);
         }
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        logger.debug(`Error checking user agent file ${userAgentPath}: ${message}`);
-    }
     logger.debug(`No agent file found for: ${agentName}`);
     return null;
 }

package/dist/config/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/config/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/config/agent.ts"],"names":[],"mappings":"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"}

package/dist/config/global.d.ts

@@ -1,24 +1,36 @@
 /**
  * Global configuration parser for loading hooks from .opencode/command-hooks.jsonc
  *
- * Searches for .opencode/command-hooks.jsonc starting from the current working
- * directory and walking up the directory tree. Parses JSONC format as CommandHooksConfig.
+ * Loads both user global config (~/.config/opencode/command-hooks.jsonc) and
+ * project config (.opencode/command-hooks.jsonc), merging them with project taking precedence.
+ *
+ * Supports:
+ * - `ignoreGlobalConfig: true` in project config to skip user global entirely
+ * - `overrideGlobal: true` on individual hooks to suppress matching global hooks
  */
 import type { CommandHooksConfig } from "../types/hooks.js";
 export type GlobalConfigResult = {
     config: CommandHooksConfig;
     error: string | null;
 };
+export declare const clearGlobalConfigCacheForTests: () => void;
 /**
- * Load and parse global command hooks configuration
+ * Load and merge command hooks configuration from both sources
+ *
+ * Loads both user global config (~/.config/opencode/command-hooks.jsonc) and
+ * project config (.opencode/command-hooks.jsonc), then merges them.
  *
- * Searches for .opencode/command-hooks.jsonc starting from the current working
- * directory and walking up. Parses the entire file as CommandHooksConfig.
+ * Merge behavior:
+ * - If project config has `ignoreGlobalConfig: true`, skip user global entirely
+ * - Otherwise, merge with project hooks taking precedence:
+ *   - Same hook `id` → project version wins
+ *   - Hook with `overrideGlobal: true` → suppresses matching global hooks
+ *   - Different `id` without override → both run (concatenation)
  *
  * Error handling:
- * - If no config file found: returns empty config (not an error)
- * - If config file is malformed: logs warning, returns empty config
- * - If file is not a valid CommandHooksConfig: logs warning, returns empty config
+ * - If no config files found: returns empty config (not an error)
+ * - If user global has parse error: warns and uses project config only
+ * - If project has parse error: returns error
  * - Never throws errors - always returns a valid config
  *
  * @returns Promise resolving to GlobalConfigResult

package/dist/config/global.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../../src/config/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK5D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAuIF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,QAAa,OAAO,CAAC,kBAAkB,CA2EnE,CAAA"}
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../../src/config/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAkB5D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AA0KF,eAAO,MAAM,8BAA8B,QAAO,IAGjD,CAAA;AAqGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,QAAa,OAAO,CAAC,kBAAkB,CAkEnE,CAAA"}

package/dist/config/global.js

@@ -1,12 +1,31 @@
 /**
  * Global configuration parser for loading hooks from .opencode/command-hooks.jsonc
  *
- * Searches for .opencode/command-hooks.jsonc starting from the current working
- * directory and walking up the directory tree. Parses JSONC format as CommandHooksConfig.
+ * Loads both user global config (~/.config/opencode/command-hooks.jsonc) and
+ * project config (.opencode/command-hooks.jsonc), merging them with project taking precedence.
+ *
+ * Supports:
+ * - `ignoreGlobalConfig: true` in project config to skip user global entirely
+ * - `overrideGlobal: true` on individual hooks to suppress matching global hooks
  */
-import { isValidCommandHooksConfig } from "../schemas.js";
+import { ConfigSchema } from "../schemas.js";
+import { mergeConfigs } from "./merge.js";
 import { join, dirname } from "path";
+import { homedir } from "os";
+import { stat } from "fs/promises";
 import { logger } from "../logging.js";
+/**
+ * Get the user's global config directory path
+ * Uses ~/.config/opencode/ following XDG convention
+ */
+const getUserConfigPath = () => {
+    const envHome = process.env.HOME || process.env.USERPROFILE;
+    const baseHome = envHome && envHome.length > 0 ? envHome : homedir();
+    return join(baseHome, ".config", "opencode", "command-hooks.jsonc");
+};
+const CONFIG_CACHE_TTL_MS = 250;
+const projectConfigPathCache = new Map();
+const configBlobCache = new Map();
 /**
  * Strip comments from JSONC content
  * Handles both line comments and block comments
@@ -90,27 +109,45 @@ const parseJson = (content) => {
         throw new Error(`Failed to parse JSON: ${message}`);
     }
 };
+const getFileMtimeMs = async (path) => {
+    try {
+        const stats = await stat(path);
+        if (!stats.isFile()) {
+            return null;
+        }
+        return stats.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+};
 /**
- * Find command hooks config file by walking up directory tree
- * Looks for .opencode/command-hooks.jsonc
+ * Find project config file by walking up directory tree
+ * Looks for .opencode/command-hooks.jsonc in project directories
  */
-const findConfigFile = async (startDir) => {
+const findProjectConfigFile = async (startDir) => {
+    const now = Date.now();
+    const cached = projectConfigPathCache.get(startDir);
+    if (cached && now - cached.cachedAt < CONFIG_CACHE_TTL_MS) {
+        if (cached.path === null) {
+            return null;
+        }
+        const cachedPathStillExists = (await getFileMtimeMs(cached.path)) !== null;
+        if (cachedPathStillExists) {
+            return cached.path;
+        }
+    }
     let currentDir = startDir;
     // Limit search depth to avoid infinite loops
     const maxDepth = 20;
     let depth = 0;
     while (depth < maxDepth) {
-        // Try .opencode/command-hooks.jsonc
         const configPath = join(currentDir, ".opencode", "command-hooks.jsonc");
-        try {
-            const file = Bun.file(configPath);
-            if (await file.exists()) {
-                logger.debug(`Found config file: ${configPath}`);
-                return configPath;
-            }
-        }
-        catch {
-            // Continue searching
+        const mtimeMs = await getFileMtimeMs(configPath);
+        if (mtimeMs !== null) {
+            logger.debug(`Found project config file: ${configPath}`);
+            projectConfigPathCache.set(startDir, { path: configPath, cachedAt: now });
+            return configPath;
         }
         // Move up one directory
         const parentDir = dirname(currentDir);
@@ -121,84 +158,165 @@ const findConfigFile = async (startDir) => {
         currentDir = parentDir;
         depth++;
     }
-    logger.debug(`No config file found after searching ${depth} directories`);
+    logger.debug(`No project config file found after searching ${depth} directories`);
+    projectConfigPathCache.set(startDir, { path: null, cachedAt: now });
     return null;
 };
+const emptyConfig = () => ({ tool: [], session: [] });
+export const clearGlobalConfigCacheForTests = () => {
+    projectConfigPathCache.clear();
+    configBlobCache.clear();
+};
 /**
- * Load and parse global command hooks configuration
+ * Load and parse config from a specific file path
  *
- * Searches for .opencode/command-hooks.jsonc starting from the current working
- * directory and walking up. Parses the entire file as CommandHooksConfig.
+ * @param configPath - Path to the config file
+ * @param source - Source identifier for logging ("project" or "user global")
+ * @returns GlobalConfigResult with parsed config or error
+ */
+const loadConfigFromPath = async (configPath, source) => {
+    const now = Date.now();
+    const mtimeMs = await getFileMtimeMs(configPath);
+    const cached = configBlobCache.get(configPath);
+    if (cached) {
+        if (mtimeMs === null && cached.mtimeMs === null && now - cached.cachedAt < CONFIG_CACHE_TTL_MS) {
+            return { config: cached.config, error: cached.error };
+        }
+        if (mtimeMs !== null && cached.mtimeMs === mtimeMs) {
+            return { config: cached.config, error: cached.error };
+        }
+    }
+    if (mtimeMs === null) {
+        const missingResult = { config: emptyConfig(), error: null };
+        configBlobCache.set(configPath, { ...missingResult, mtimeMs: null, cachedAt: now });
+        return missingResult;
+    }
+    // Read file
+    let content;
+    try {
+        content = await Bun.file(configPath).text();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.info(`Failed to read ${source} config file ${configPath}: ${message}`);
+        const readErrorResult = {
+            config: emptyConfig(),
+            error: `Failed to read ${source} config file ${configPath}: ${message}`,
+        };
+        configBlobCache.set(configPath, { ...readErrorResult, mtimeMs, cachedAt: now });
+        return readErrorResult;
+    }
+    // Parse JSONC
+    let parsed;
+    try {
+        const stripped = stripJsoncComments(content);
+        parsed = parseJson(stripped);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.info(`Failed to parse ${source} config file ${configPath}: ${message}`);
+        const parseErrorResult = {
+            config: emptyConfig(),
+            error: `Failed to parse ${source} config file ${configPath}: ${message}`,
+        };
+        configBlobCache.set(configPath, { ...parseErrorResult, mtimeMs, cachedAt: now });
+        return parseErrorResult;
+    }
+    // Validate and parse with the full schema
+    const parseResult = ConfigSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        const issueSummary = parseResult.error.issues
+            .map(issue => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+            return `${path}: ${issue.message}`;
+        })
+            .join("; ");
+        logger.info(`${source} config file failed schema validation, using empty config: ${issueSummary}`);
+        const validationErrorResult = {
+            config: emptyConfig(),
+            error: `${source} config file failed schema validation`,
+        };
+        configBlobCache.set(configPath, { ...validationErrorResult, mtimeMs, cachedAt: now });
+        return validationErrorResult;
+    }
+    // Return with defaults for missing arrays
+    const result = {
+        truncationLimit: parseResult.data.truncationLimit,
+        ignoreGlobalConfig: parseResult.data.ignoreGlobalConfig,
+        tool: parseResult.data.tool ?? [],
+        session: parseResult.data.session ?? [],
+    };
+    logger.debug(`Loaded ${source} config: truncationLimit=${result.truncationLimit}, ${result.tool?.length ?? 0} tool hooks, ${result.session?.length ?? 0} session hooks`);
+    const successResult = { config: result, error: null };
+    configBlobCache.set(configPath, { ...successResult, mtimeMs, cachedAt: now });
+    return successResult;
+};
+/**
+ * Load and merge command hooks configuration from both sources
+ *
+ * Loads both user global config (~/.config/opencode/command-hooks.jsonc) and
+ * project config (.opencode/command-hooks.jsonc), then merges them.
+ *
+ * Merge behavior:
+ * - If project config has `ignoreGlobalConfig: true`, skip user global entirely
+ * - Otherwise, merge with project hooks taking precedence:
+ *   - Same hook `id` → project version wins
+ *   - Hook with `overrideGlobal: true` → suppresses matching global hooks
+ *   - Different `id` without override → both run (concatenation)
  *
  * Error handling:
- * - If no config file found: returns empty config (not an error)
- * - If config file is malformed: logs warning, returns empty config
- * - If file is not a valid CommandHooksConfig: logs warning, returns empty config
+ * - If no config files found: returns empty config (not an error)
+ * - If user global has parse error: warns and uses project config only
+ * - If project has parse error: returns error
  * - Never throws errors - always returns a valid config
  *
  * @returns Promise resolving to GlobalConfigResult
  */
 export const loadGlobalConfig = async () => {
-    let configPath = null;
     try {
-        // Find config file
         logger.debug(`loadGlobalConfig: starting search from: ${process.cwd()}`);
-        configPath = await findConfigFile(process.cwd());
-        if (!configPath) {
-            logger.debug("No .opencode/command-hooks.jsonc file found, using empty config");
-            return { config: { tool: [], session: [] }, error: null };
-        }
-        // Read file
-        let content;
-        try {
-            const file = Bun.file(configPath);
-            content = await file.text();
+        // Step 1: Load project config first (to check ignoreGlobalConfig flag)
+        const projectConfigPath = await findProjectConfigFile(process.cwd());
+        const projectResult = projectConfigPath
+            ? await loadConfigFromPath(projectConfigPath, "project")
+            : { config: emptyConfig(), error: null };
+        // If project config had an error, return it
+        if (projectResult.error) {
+            return projectResult;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.info(`Failed to read config file ${configPath}: ${message}`);
-            return {
-                config: { tool: [], session: [] },
-                error: `Failed to read config file ${configPath}: ${message}`,
-            };
+        // Step 2: If project says ignore global, return project only
+        if (projectResult.config.ignoreGlobalConfig) {
+            logger.debug("Project config has ignoreGlobalConfig: true, skipping user global");
+            return projectResult;
         }
-        // Parse JSONC
-        let parsed;
-        try {
-            const stripped = stripJsoncComments(content);
-            parsed = parseJson(stripped);
+        // Step 3: Load user global config
+        const userGlobalPath = getUserConfigPath();
+        const userGlobalResult = await loadConfigFromPath(userGlobalPath, "user global");
+        // Step 4: If user global had parse error, log and use project only
+        if (userGlobalResult.error) {
+            logger.info(`Failed to load user global config (${userGlobalPath}): ${userGlobalResult.error}. Using project config only.`);
+            return projectResult;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.info(`Failed to parse config file ${configPath}: ${message}`);
-            return {
-                config: { tool: [], session: [] },
-                error: `Failed to parse config file ${configPath}: ${message}`,
-            };
+        // Step 5: If neither config has hooks, return empty
+        const hasUserGlobalHooks = (userGlobalResult.config.tool?.length ?? 0) > 0 ||
+            (userGlobalResult.config.session?.length ?? 0) > 0;
+        const hasProjectHooks = (projectResult.config.tool?.length ?? 0) > 0 ||
+            (projectResult.config.session?.length ?? 0) > 0;
+        if (!hasUserGlobalHooks && !hasProjectHooks) {
+            logger.debug("No hooks found in either config, using empty config");
+            return { config: emptyConfig(), error: null };
         }
-        // Validate entire file as CommandHooksConfig
-        if (!isValidCommandHooksConfig(parsed)) {
-            logger.info("Config file is not a valid CommandHooksConfig (expected { tool?: [], session?: [] }), using empty config");
-            return {
-                config: { tool: [], session: [] },
-                error: "Config file is not a valid CommandHooksConfig (expected { tool?: [], session?: [] })",
-            };
-        }
-        // Return with defaults for missing arrays
-        const result = {
-            truncationLimit: parsed.truncationLimit,
-            tool: parsed.tool ?? [],
-            session: parsed.session ?? [],
-        };
-        logger.debug(`Loaded global config: truncationLimit=${result.truncationLimit}, ${result.tool?.length ?? 0} tool hooks, ${result.session?.length ?? 0} session hooks`);
-        return { config: result, error: null };
+        // Step 6: Merge configs - user global as base, project as override
+        const { config: mergedConfig } = mergeConfigs(userGlobalResult.config, projectResult.config);
+        logger.debug(`Merged configs: ${mergedConfig.tool?.length ?? 0} tool hooks, ${mergedConfig.session?.length ?? 0} session hooks`);
+        return { config: mergedConfig, error: null };
     }
     catch (error) {
         // Catch-all for unexpected errors
         const message = error instanceof Error ? error.message : String(error);
         logger.info(`Unexpected error loading global config: ${message}`);
         return {
-            config: { tool: [], session: [] },
+            config: emptyConfig(),
             error: `Unexpected error loading global config: ${message}`,
         };
     }