@akira-tl/forgerelay 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-08-09
+
+### Changed
+
+- Local console logging now defaults to a compact Loguru-style `pretty` format focused on Agent operations: short timestamps, workspace/session context, tool or Hook action, target, and `ok`/`error` or shell exit status. HTTP request logging is off by default in human mode, while explicit `json` mode keeps the previous request-on and shell-command-off machine defaults.
+
+### Fixed
+
+- File and search tools can access and modify files in the operating system temporary directory without making that directory an implicit workspace root; Codex `apply_patch` supports absolute OS-temp paths while workspace patch paths remain relative.
+
+### Security
+
+- 文件工具在 workspace 与 OS temp 边界内都会校验 canonical path，阻止通过 symlink 跳转到任意文件系统位置；shell cwd 与 workspace-open allowed roots 不随 temp 文件访问而扩大。
+
+## [0.2.0] - 2026-08-09
+
+### Added
+
+- A checked-in `127.0.0.1:7677` local debug environment with reproducible OAuth/MCP acceptance scripts, isolated runtime state, and Hooks v1 lifecycle recording.
+- 用户或 Agent 可写的生命周期 Hook，覆盖 workspace、MCP tool、明确文件变更、managed-worktree close 与本地 subagent 生命周期。
+- 首选的一 Hook 一文件配置：全局 `hooks/<hook-name>.json` 与项目 `.forgerelay/hooks/<hook-name>.json` 自动组合，文件名直接作为 Hook 名并按文件名稳定排序；旧 inline/聚合格式继续兼容。
+- 独立 Hook 的 `event + matcher + command`、bounded timeout 与 `report` 配置；可报告结果进入 Agent 可见返回，阻断失败始终可见。
+- 只读的 `forgerelay hooks list` / `hooks check` CLI，用于查看实际加载规则和在不执行 Hook 的情况下校验全局/项目配置。
+- `BeforeTool` 与 `BeforeWorktreeClose` 阻断语义，以及不会伪装回滚已完成操作的 observational after-events。
+- 通过 `FORGERELAY_HOOK_*` 和 workspace 环境变量提供生命周期上下文，同时避免暴露 native-file credentials 或 subagent prompts。
+- 异步 subagent Hook report 的 session 持久化与 `agents show` 展示。
+
+### Fixed
+
+- MCP `initialize` now reports the package version from `package.json` instead of a stale hardcoded `0.1.0` server version.
+- Hook commands on Windows preserve quoted arguments when executed through `cmd.exe`, fixing release-gate and other Hook commands that reference absolute paths.
+
+### Security
+
+- 项目 Hook 作为 allowed-root 内项目执行约定自动生效，不需要批准；Hook 文件只能声明生命周期规则，不能扩大 allowed roots、修改认证配置或覆盖全局规则。
+- 无效项目 Hook 配置会作为 Agent 可见 diagnostic 返回，同时保持工具可用；独立目录中的坏文件会被跳过，其他有效 Hook 继续加载，避免 Agent 因写坏单个规则而无法修复。
+
 ## [0.1.1] - 2026-08-09
 
 ### Changed

package/README.md

@@ -90,7 +90,9 @@ Once a workspace is open, the host can:
   parallel work;
 - close a managed worktree by committing its remaining changes and
   fast-forwarding the target branch when that can be done safely;
-- show aggregate changes through optional ChatGPT Apps-compatible UI cards.
+- show aggregate changes through optional ChatGPT Apps-compatible UI cards;
+- run user-configured lifecycle hooks around tool calls, file changes, managed
+  worktree close, and local subagent execution.
 
 Normal work happens in your existing checkout. ForgeRelay does not silently move
 every task into a worktree.
@@ -117,6 +119,39 @@ If the histories have diverged, the close is refused and the worktree is left in
 place. ForgeRelay does not put the source checkout into a merge-conflict state.
 You can rebase and verify inside the worktree, then retry the close.
 
+## Lifecycle hooks
+
+Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一个文件：全局放在 `~/.forgerelay/hooks/<hook-name>.json`，项目放在 `<repo>/.forgerelay/hooks/<hook-name>.json`。文件名就是 Hook 名，方便直接从目录看出每条规则的用途；全局与项目规则组合执行，不需要额外批准。
+
+例如项目里的 `.forgerelay/hooks/release-tag-local-ci.json` 可以要求稳定版本 tag push 前先完成本地发布检查：
+
+```json
+{
+  "event": "BeforeTool",
+  "matcher": {
+    "tool": "bash",
+    "commandRegex": "^git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+$"
+  },
+  "command": "npm run release:verify",
+  "timeoutSeconds": 300,
+  "report": true
+}
+```
+
+命中 `BeforeTool` 后，Hook 先执行；成功才继续原始 `git push`，失败则直接阻断。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+
+旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
+
+可以直接检查当前全局与项目规则，而不会执行 Hook：
+
+```bash
+forgerelay hooks list
+forgerelay hooks check
+forgerelay hooks list --project /path/to/project
+```
+
+`list` 展示实际加载的规则、matcher、timeout、report 与 command；`check` 只校验配置并在发现坏文件时返回非零状态。完整 matcher、事件与环境变量见 [Configuration Reference](docs/configuration.md#lifecycle-hooks)。
+
 ## Local coding agents
 
 ForgeRelay can delegate work to local coding runtimes through user-defined
@@ -200,11 +235,10 @@ forgerelay doctor
 The next additions are focused on making the local execution layer more useful,
 not on turning ForgeRelay into another all-in-one agent framework:
 
-1. lifecycle hooks;
-2. LSP-backed code intelligence;
-3. first-class MCP subagent delegation;
-4. stronger worktree verification and recovery;
-5. checkpoint/rewind and retention improvements.
+1. LSP-backed code intelligence;
+2. first-class MCP subagent delegation;
+3. stronger worktree verification and recovery;
+4. checkpoint/rewind and retention improvements.
 
 ForgeRelay does not plan to add its own shell sandbox, long-term memory system,
 or plugin marketplace. Conversation, planning, web access, and other host-native
@@ -239,6 +273,7 @@ Trusted Publishing setup.
 ## Documentation
 
 - [Setup Guide](docs/setup.md)
+- [Local Debugging and 7677 Acceptance](docs/debugging.md)
 - [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
 - [Configuration Reference](docs/configuration.md)
 - [Agent Profile Schema](docs/agent-profile-schema.md)
@@ -266,7 +301,17 @@ The original copyright notice remains in [LICENSE](LICENSE). See
 ```bash
 npm install --include=dev
 npm run dev
+npm run debug:accept
 npm run typecheck
 npm test
 npm run build
 ```
+
+`npm run dev` uses the checked-in local debug configuration and binds ForgeRelay
+to `127.0.0.1:7677`, keeping the normal `7676` product port free. The
+`debug:accept` command starts a temporary 7677 server and sends real
+HTTP/OAuth/MCP requests through it, including workspace tools, managed worktree
+close, and Hooks v1 lifecycle recording. Debug state stays under the gitignored
+`.forgerelay-debug/` directory.
+
+See [Local Debugging](docs/debugging.md) for the exact configuration and scripts.

package/dist/apply-patch.js

@@ -4,6 +4,7 @@ import { access, lstat, mkdir, readFile, realpath, rename, rm, stat, writeFile }
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { TextDecoder } from "node:util";
 import { createTwoFilesPatch, FILE_HEADERS_ONLY } from "diff";
+import { AccessDeniedError, resolveCanonicalAllowedPath } from "./roots.js";
 function patchError(message) {
     return new Error(`Invalid patch: ${message}`);
 }
@@ -137,10 +138,24 @@ function isInside(root, path) {
     const rel = relative(root, path);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-async function resolveConfinedPath(root, input) {
-    if (!input || input.includes("\0") || isAbsolute(input)) {
+async function resolveConfinedPath(root, input, auxiliaryRoots = []) {
+    if (!input || input.includes("\0")) {
         throw patchError(`path must be relative to the workspace: ${input}`);
     }
+    if (isAbsolute(input)) {
+        if (auxiliaryRoots.length === 0) {
+            throw patchError(`path must be relative to the workspace: ${input}`);
+        }
+        try {
+            return await resolveCanonicalAllowedPath(input, root, auxiliaryRoots);
+        }
+        catch (error) {
+            if (error instanceof AccessDeniedError) {
+                throw patchError(`path is outside allowed auxiliary roots: ${input}`);
+            }
+            throw error;
+        }
+    }
     const rootPath = await realpath(root);
     const target = resolve(rootPath, input);
     if (!isInside(rootPath, target)) {
@@ -269,7 +284,7 @@ export async function isSamePatchFile(source, destination, readIdentity = lstat)
         throw error;
     }
 }
-export async function applyPatch(root, patch) {
+export async function applyPatch(root, patch, auxiliaryRoots = []) {
     const actions = parsePatch(patch);
     const results = [];
     const patches = [];
@@ -289,14 +304,14 @@ export async function applyPatch(root, patch) {
     };
     for (const action of actions) {
         if (action.kind === "add") {
-            const absolute = await resolveConfinedPath(root, action.path);
+            const absolute = await resolveConfinedPath(root, action.path, auxiliaryRoots);
             const original = await readStagedOptional(absolute, action.path);
             staged.set(absolute, { content: action.content, mode: original?.mode });
             patches.push(unifiedFilePatch(action.path, action.path, original?.content ?? null, action.content));
             results.push({ path: action.path, operation: original ? "update" : "add" });
             continue;
         }
-        const absolute = await resolveConfinedPath(root, action.path);
+        const absolute = await resolveConfinedPath(root, action.path, auxiliaryRoots);
         const file = await readStagedRequired(absolute, action.path);
         if (action.kind === "delete") {
             staged.set(absolute, null);
@@ -306,7 +321,7 @@ export async function applyPatch(root, patch) {
         }
         const updated = applyHunks(action.path, file.content, action.hunks);
         if (action.moveTo) {
-            const destination = await resolveConfinedPath(root, action.moveTo);
+            const destination = await resolveConfinedPath(root, action.moveTo, auxiliaryRoots);
             const samePatchFile = await isSamePatchFile(absolute, destination);
             if (!samePatchFile)
                 await readStagedOptional(destination, action.moveTo);

package/dist/artifact-tools.js

@@ -5,8 +5,9 @@ import { isAbsolute, join, normalize, sep } from "node:path";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
+import { runToolWithHooks } from "./hooks.js";
 import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent } from "./logger.js";
+import { logEvent, sessionIdPrefix, workspaceLogLabel } from "./logger.js";
 const ARTIFACT_WRITE_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: false,
@@ -31,7 +32,7 @@ const openAIFileReferenceInputSchema = z.strictObject({
 export function isArtifactDownloadSupportedPlatform(platform = process.platform) {
     return ARTIFACT_DOWNLOAD_PLATFORMS.has(platform);
 }
-export function registerArtifactTools(server, { config, workspaces, incomingArtifactAdapters = [], }) {
+export function registerArtifactTools(server, { config, workspaces, hooks, incomingArtifactAdapters = [], }) {
     const incomingRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
     registerAppTool(server, "download_artifact", {
         title: "Download attached or generated file",
@@ -46,21 +47,37 @@ export function registerArtifactTools(server, { config, workspaces, incomingArti
         },
         _meta: { "openai/fileParams": ["file"] },
         annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input) => executeArtifactTool(config, input, async () => {
+    }, async (input, extra) => {
         const workspace = workspaces.getWorkspace(input.workspaceId);
-        const downloaded = await downloadIncomingArtifact({
-            registry: incomingRegistry,
-            workspaceId: workspace.id,
-            workspaceRoot: workspace.root,
-            maxFileBytes: config.artifactMaxFileBytes,
-            file: input.file,
-            path: input.path,
+        return runToolWithHooks(hooks, {
+            tool: "download_artifact",
+            invocation: {
+                workspaceId: workspace.id,
+                workspaceRoot: workspace.root,
+                workspaceMode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+            },
+            payload: { path: input.path },
+            changedPaths: (result) => [result.structuredContent.path],
+            operation: () => executeArtifactTool(config, input, {
+                workspace: workspaceLogLabel(workspace.root, workspace.id),
+                session: sessionIdPrefix(extra?.sessionId),
+            }, async () => {
+                const downloaded = await downloadIncomingArtifact({
+                    registry: incomingRegistry,
+                    workspaceId: workspace.id,
+                    workspaceRoot: workspace.root,
+                    maxFileBytes: config.artifactMaxFileBytes,
+                    file: input.file,
+                    path: input.path,
+                });
+                return {
+                    publicResult: { path: downloaded.path },
+                    logResult: downloaded,
+                };
+            }),
         });
-        return {
-            publicResult: { path: downloaded.path },
-            logResult: downloaded,
-        };
-    }));
+    });
 }
 /**
  * Stream a trusted native file directly into one already-open workspace.
@@ -151,7 +168,7 @@ export function artifactToolLogFields(input) {
         path: input.path,
     };
 }
-async function executeArtifactTool(config, input, operation) {
+async function executeArtifactTool(config, input, logContext, operation) {
     const startedAt = performance.now();
     try {
         const { publicResult, logResult } = await operation();
@@ -159,6 +176,7 @@ async function executeArtifactTool(config, input, operation) {
             logEvent(config.logging, "info", "artifact_tool_call", {
                 tool: "download_artifact",
                 ...artifactToolLogFields(input),
+                ...logContext,
                 path: logResult.path,
                 size: logResult.size,
                 sha256: logResult.sha256,
@@ -173,6 +191,7 @@ async function executeArtifactTool(config, input, operation) {
             logEvent(config.logging, "warn", "artifact_tool_call", {
                 tool: "download_artifact",
                 ...artifactToolLogFields(input),
+                ...logContext,
                 success: false,
                 errorCode: error instanceof ArtifactError ? error.code : "internal_error",
                 durationMs: Math.round(performance.now() - startedAt),

package/dist/cli.js

@@ -11,6 +11,8 @@ import * as prompts from "@clack/prompts";
 import { getShellConfig } from "@earendil-works/pi-coding-agent";
 import { satisfies } from "semver";
 import { loadConfig } from "./config.js";
+import { formatVisibleHookReports, HookRunner } from "./hooks.js";
+import { runHooksCommand } from "./hook-cli.js";
 import { runLocalAgentProvider } from "./local-agent-adapters.js";
 import { isLocalAgentProvider, loadLocalAgentProfiles, } from "./local-agent-profiles.js";
 import { assertLocalAgentProviderAvailable, formatLocalAgentProviderAvailabilitySummary, } from "./local-agent-availability.js";
@@ -39,6 +41,9 @@ async function main(argv) {
         case "config":
             runConfigCommand(args);
             return;
+        case "hooks":
+            await runHooksCommand(args);
+            return;
         case "agents":
             await runAgentsCommand(args);
             return;
@@ -53,7 +58,7 @@ async function main(argv) {
 function normalizeCommand(command) {
     if (!command || command === "serve" || command === "start")
         return "serve";
-    if (command === "init" || command === "doctor" || command === "config" || command === "agents")
+    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
         return "help";
@@ -261,6 +266,8 @@ function printHelp() {
         "  forgerelay doctor          Show config, runtime, and native dependency status",
         "  forgerelay config get      Print persisted config",
         "  forgerelay config set publicBaseUrl <url|null>",
+        "  forgerelay hooks list [--project <path>]",
+        "  forgerelay hooks check [--project <path>]",
         "  forgerelay agents ls       List subagent sessions",
         "  forgerelay agents run <profile-or-provider-or-id> [--model <model>] <prompt>",
         "  forgerelay agents show <id>",
@@ -326,6 +333,7 @@ async function runAgentsRun(args) {
             thinking: parsed.thinking ?? existing.thinking,
             latestResponse: undefined,
             error: undefined,
+            hookReports: undefined,
         });
         spawnAgentWorker(existing.id, promptFile);
         console.log(formatAgentLine({
@@ -369,6 +377,9 @@ async function runAgentsShow(args) {
         record = store.get(id) ?? record;
     }
     console.log(formatAgentLine(record));
+    const hookSummary = formatVisibleHookReports(record.hookReports ?? []);
+    if (hookSummary)
+        console.log(hookSummary);
     if (record.latestResponse) {
         console.log(record.latestResponse);
         return;
@@ -391,7 +402,21 @@ async function runAgentsWorker(args) {
     const record = store.get(id);
     if (!record)
         throw new Error(`Unknown subagent id: ${id}`);
-    store.update(record.id, { status: "running", error: undefined });
+    const hooks = new HookRunner(config.hooks, config.logging);
+    const hookInvocation = {
+        workspaceId: record.workspaceId,
+        workspaceRoot: record.workspaceRoot,
+        payload: {
+            agentId: record.id,
+            profile: record.profileName,
+            provider: record.provider,
+            model: record.model,
+            thinking: record.thinking,
+        },
+    };
+    store.update(record.id, { status: "running", error: undefined, hookReports: undefined });
+    const hookReports = await hooks.run("SubagentStart", hookInvocation);
+    store.update(record.id, { hookReports });
     try {
         const profiles = await loadLocalAgentProfiles(config, record.workspaceRoot);
         const profile = profiles.find((candidate) => candidate.name === record.profileName);
@@ -399,17 +424,35 @@ async function runAgentsWorker(args) {
         const result = profile
             ? await runLocalAgentProfile(profile, record, prompt)
             : await runRawLocalAgentProvider(record, prompt);
+        hookReports.push(...await hooks.run("SubagentStop", {
+            ...hookInvocation,
+            payload: {
+                ...hookInvocation.payload,
+                status: "idle",
+                providerSessionId: result.providerSessionId,
+            },
+        }));
         store.update(record.id, {
             providerSessionId: result.providerSessionId ?? undefined,
             status: "idle",
             latestResponse: result.finalResponse,
             error: undefined,
+            hookReports,
         });
     }
     catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        hookReports.push(...await hooks.run("SubagentStop", {
+            ...hookInvocation,
+            payload: {
+                ...hookInvocation.payload,
+                status: "error",
+            },
+        }));
         store.update(record.id, {
             status: "error",
-            error: error instanceof Error ? error.message : String(error),
+            error: message,
+            hookReports,
         });
     }
 }

package/dist/config.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "./roots.js";
+import { mergeHookConfigs, parseHookConfig } from "./hooks.js";
 import { forgerelayAgentsDir, forgerelaySkillsDir, loadForgeRelayFiles } from "./user-config.js";
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
@@ -80,10 +81,10 @@ function parseLogLevel(value) {
     throw new Error(`Invalid FORGERELAY_LOG_LEVEL: ${value}`);
 }
 function parseLogFormat(value) {
-    if (!value || value === "json")
-        return "json";
-    if (value === "pretty")
+    if (!value || value === "pretty")
         return "pretty";
+    if (value === "json")
+        return "json";
     throw new Error(`Invalid FORGERELAY_LOG_FORMAT: ${value}`);
 }
 function parsePathList(value) {
@@ -109,15 +110,17 @@ function parsePositiveInteger(value, fallback, name, max = Number.MAX_SAFE_INTEG
     return parsed;
 }
 function parseLoggingConfig(env) {
+    const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
     const toolCalls = productEnv(env, "LOG_TOOL_CALLS");
+    const shellCommands = productEnv(env, "LOG_SHELL_COMMANDS");
     return {
         level: parseLogLevel(productEnv(env, "LOG_LEVEL")),
-        format: parseLogFormat(productEnv(env, "LOG_FORMAT")),
-        requests: requests === undefined ? true : parseBoolean(requests),
+        format,
+        requests: requests === undefined ? format === "json" : parseBoolean(requests),
         assets: parseBoolean(productEnv(env, "LOG_ASSETS")),
         toolCalls: toolCalls === undefined ? true : parseBoolean(toolCalls),
-        shellCommands: parseBoolean(productEnv(env, "LOG_SHELL_COMMANDS")),
+        shellCommands: shellCommands === undefined ? format === "pretty" : parseBoolean(shellCommands),
         trustProxy: parseBoolean(productEnv(env, "TRUST_PROXY")),
     };
 }
@@ -214,6 +217,7 @@ export function loadConfig(env = process.env) {
             : parseBoolean(productEnv(env, "SUBAGENTS")),
         agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
         systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
+        hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),
         logging: parseLoggingConfig(env),
     };
 }

package/dist/db/migrations.js

@@ -24,6 +24,11 @@ const migrations = [
         name: "workspace-worktree-branches",
         up: migrateWorkspaceWorktreeBranches,
     },
+    {
+        version: 6,
+        name: "local-agent-hook-reports",
+        up: migrateLocalAgentHookReports,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -181,6 +186,9 @@ function migrateWorkspaceWorktreeBranches(sqlite) {
     addColumnIfMissing(sqlite, "workspace_sessions", "branch", "text");
     addColumnIfMissing(sqlite, "workspace_sessions", "target_branch", "text");
 }
+function migrateLocalAgentHookReports(sqlite) {
+    addColumnIfMissing(sqlite, "local_agent_sessions", "hook_reports_json", "text");
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/db/schema.js

@@ -76,6 +76,7 @@ export const localAgentSessions = sqliteTable("local_agent_sessions", {
     status: text("status").notNull(),
     latestResponse: text("latest_response"),
     error: text("error"),
+    hookReportsJson: text("hook_reports_json"),
     createdAt: text("created_at").notNull(),
     updatedAt: text("updated_at").notNull(),
 }, (table) => [

package/dist/hook-cli.js

@@ -0,0 +1,100 @@
+import { resolve } from "node:path";
+import { HOOK_EVENTS, loadProjectHookConfig, mergeHookConfigs, parseHookConfig, } from "./hooks.js";
+import { loadForgeRelayFiles } from "./user-config.js";
+export async function runHooksCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || ["help", "--help", "-h"].includes(subcommand)) {
+        printHooksHelp();
+        return;
+    }
+    const projectRoot = parseProjectRoot(rest);
+    const globalHooks = loadGlobalHooks();
+    const project = await loadProjectHookConfig(projectRoot);
+    const globalEntries = flattenHooks(globalHooks, "global");
+    const projectEntries = flattenHooks(project.hooks, "project");
+    if (subcommand === "list") {
+        for (const entry of [...globalEntries, ...projectEntries]) {
+            console.log(formatHookEntry(entry));
+        }
+        if (globalEntries.length === 0 && projectEntries.length === 0) {
+            console.log("No hooks configured.");
+        }
+        if (project.diagnostic) {
+            console.error(`Project hooks diagnostic: ${project.diagnostic}`);
+        }
+        return;
+    }
+    if (subcommand === "check") {
+        if (project.diagnostic) {
+            throw new Error(`Hook check failed: ${project.diagnostic}`);
+        }
+        console.log(`Hooks OK: ${globalEntries.length} global, ${projectEntries.length} project`);
+        return;
+    }
+    throw new Error(`Unknown hooks command: ${subcommand}`);
+}
+function loadGlobalHooks() {
+    const files = loadForgeRelayFiles();
+    return mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles);
+}
+function parseProjectRoot(args) {
+    let projectRoot = process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg !== "--project") {
+            throw new Error(`Unknown hooks option: ${arg}`);
+        }
+        const value = args[index + 1];
+        if (!value)
+            throw new Error("Usage: forgerelay hooks <list|check> [--project <path>]");
+        projectRoot = resolve(value);
+        index += 1;
+    }
+    return projectRoot;
+}
+function flattenHooks(config, scope) {
+    const entries = [];
+    for (const event of HOOK_EVENTS) {
+        let handlerIndex = 0;
+        for (const rule of config[event] ?? []) {
+            for (const handler of rule.handlers) {
+                handlerIndex += 1;
+                entries.push({
+                    scope,
+                    event,
+                    name: handler.name ?? `${event} handler ${handlerIndex}`,
+                    matcher: rule.matcher,
+                    command: handler.command,
+                    timeoutSeconds: handler.timeoutSeconds,
+                    report: handler.report,
+                });
+            }
+        }
+    }
+    return entries;
+}
+function formatHookEntry(entry) {
+    const matcher = formatMatcher(entry.matcher);
+    return `${entry.scope} ${entry.name} ${entry.event} ${matcher} timeout=${entry.timeoutSeconds}s report=${entry.report} :: ${entry.command}`;
+}
+function formatMatcher(matcher) {
+    if (!matcher)
+        return "matcher=*";
+    const parts = [
+        matcher.tool ? `tool=${matcher.tool}` : undefined,
+        matcher.commandRegex ? `commandRegex=${matcher.commandRegex}` : undefined,
+        matcher.pathRegex ? `pathRegex=${matcher.pathRegex}` : undefined,
+        matcher.provider ? `provider=${matcher.provider}` : undefined,
+        matcher.workspaceMode ? `workspaceMode=${matcher.workspaceMode}` : undefined,
+    ].filter((value) => value !== undefined);
+    return parts.length > 0 ? parts.join(" ") : "matcher=*";
+}
+function printHooksHelp() {
+    console.log([
+        "ForgeRelay hooks",
+        "",
+        "Usage:",
+        "  forgerelay hooks list [--project <path>]",
+        "  forgerelay hooks check [--project <path>]",
+    ].join("\n"));
+}