@akira-tl/forgerelay 0.1.0 → 0.2.0

package/dist/user-config.js

@@ -1,8 +1,9 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { expandHomePath } from "./roots.js";
+import { mergeHookConfigs, parseHookFile, } from "./hooks.js";
 export function forgerelayConfigDir(env = process.env) {
     const explicit = env.FORGERELAY_CONFIG_DIR ?? env.DEVSPACE_CONFIG_DIR;
     if (explicit)
@@ -19,6 +20,12 @@ export function forgerelayConfigPath(env = process.env) {
 export function forgerelayAuthPath(env = process.env) {
     return join(forgerelayConfigDir(env), "auth.json");
 }
+export function forgerelayHooksPath(env = process.env) {
+    return join(forgerelayConfigDir(env), "hooks.json");
+}
+export function forgerelayHooksDir(env = process.env) {
+    return join(forgerelayConfigDir(env), "hooks");
+}
 export function forgerelaySkillsDir(env = process.env) {
     return join(forgerelayConfigDir(env), "skills");
 }
@@ -29,16 +36,22 @@ export function loadForgeRelayFiles(env = process.env) {
     const dir = forgerelayConfigDir(env);
     const configPath = join(dir, "config.json");
     const authPath = join(dir, "auth.json");
+    const hooksPath = join(dir, "hooks.json");
     const configExists = existsSync(configPath);
     const authExists = existsSync(authPath);
+    const hooksExists = existsSync(hooksPath);
     return {
         dir,
         configPath,
         authPath,
+        hooksPath,
         configExists,
         authExists,
+        hooksExists,
         config: configExists ? readJsonFile(configPath) : {},
         auth: authExists ? readJsonFile(authPath) : {},
+        hooks: hooksExists ? readJsonFile(hooksPath) : {},
+        hookFiles: readHookFiles(join(dir, "hooks")),
         usingLegacyDir: dir === resolve(join(homedir(), ".devspace")),
     };
 }
@@ -83,6 +96,25 @@ export const loadDevspaceFiles = loadForgeRelayFiles;
 export const writeDevspaceConfig = writeForgeRelayConfig;
 export const writeDevspaceAuth = writeForgeRelayAuth;
 export const ensureDevspaceDefaultSkills = ensureForgeRelayDefaultSkills;
+function readHookFiles(directory) {
+    if (!existsSync(directory))
+        return {};
+    let hooks = {};
+    const entries = readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+        const filePath = join(directory, entry.name);
+        try {
+            hooks = mergeHookConfigs(hooks, parseHookFile(readJsonFile(filePath), entry.name.slice(0, -5)));
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Unable to load hook file ${filePath}: ${reason}`);
+        }
+    }
+    return hooks;
+}
 function readJsonFile(filePath) {
     try {
         return JSON.parse(readFileSync(filePath, "utf8"));

package/dist/workspaces.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { HookRunner } from "./hooks.js";
 import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
 import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
@@ -11,9 +11,11 @@ export class WorkspaceRegistry {
     store;
     workspaces = new Map();
     pendingOpens = new Map();
+    hooks;
     constructor(config, store) {
         this.config = config;
         this.store = store;
+        this.hooks = new HookRunner(config.hooks, config.logging);
     }
     async openWorkspace(input, openOptions = {}) {
         const workspaceInput = typeof input === "string" ? { path: input } : input;
@@ -71,14 +73,41 @@ export class WorkspaceRegistry {
             detached: false,
             managed: true,
         };
+        const hookReports = await this.hooks.run("BeforeWorktreeClose", {
+            workspaceId: workspace.id,
+            workspaceRoot: workspace.root,
+            workspaceMode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            payload: {
+                commitMessage,
+                branch: managedWorktree.branch,
+                targetBranch: managedWorktree.targetBranch,
+            },
+        });
         const result = await closeManagedWorktree({
             worktree: managedWorktree,
             commitMessage,
             config: this.config,
         });
+        hookReports.push(...await this.hooks.run("AfterWorktreeClose", {
+            workspaceId: workspace.id,
+            workspaceRoot: workspace.root,
+            workspaceMode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            cwd: result.sourceRoot,
+            payload: {
+                commitMessage,
+                branch: result.branch,
+                targetBranch: result.targetBranch,
+                commitSha: result.commitSha,
+                mergedSha: result.mergedSha,
+                committed: result.committed,
+                cleanupWarning: result.cleanupWarning,
+            },
+        }));
         this.store?.setSessionStatus(workspace.id, "closed");
         this.workspaces.delete(workspace.id);
-        return result;
+        return { ...result, hookReports };
     }
     async openReusableCheckout(path, conversationScopeId) {
         const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
@@ -235,6 +264,7 @@ export class WorkspaceRegistry {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            hookReports: [],
             workspaceReused: true,
             includeBootstrapContext: true,
         };
@@ -353,12 +383,25 @@ export class WorkspaceRegistry {
             managed: workspace.worktree?.managed,
         });
         this.workspaces.set(workspace.id, workspace);
+        const hookReports = await this.hooks.run("WorkspaceOpen", {
+            workspaceId: workspace.id,
+            workspaceRoot: workspace.root,
+            workspaceMode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            payload: {
+                mode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+                branch: workspace.worktree?.branch,
+                targetBranch: workspace.worktree?.targetBranch,
+            },
+        });
         const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
         const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
         return {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            hookReports,
             workspaceReused: false,
             includeBootstrapContext: true,
         };
@@ -381,21 +424,34 @@ export class WorkspaceRegistry {
         return assertAllowedPath(root, this.config.allowedRoots);
     }
     async loadInitialAgentsFiles(root) {
-        const agentDir = resolve(this.config.agentDir);
         const resolvedRoot = (await tryRealpath(root)) ?? root;
-        const resolvedAgentDir = (await tryRealpath(agentDir)) ?? agentDir;
+        const systemInstructionsPath = resolve(this.config.systemInstructionsPath);
         const loadedFiles = [];
-        for (const file of loadProjectContextFiles({ cwd: root, agentDir })) {
-            const path = resolve(file.path);
-            if (!isInitialAgentsFilePath(path, root, agentDir))
-                continue;
-            const content = await readResolvedContextFile(path, file.content, resolvedRoot, resolvedAgentDir);
+        const loadedRealPaths = new Set();
+        const systemInstructions = await readSystemInstructions(systemInstructionsPath);
+        const systemInstructionsRealPath = await tryRealpath(systemInstructionsPath);
+        if (systemInstructions !== undefined) {
+            loadedFiles.push({
+                path: systemInstructionsPath,
+                content: systemInstructions,
+            });
+            if (systemInstructionsRealPath)
+                loadedRealPaths.add(systemInstructionsRealPath);
+        }
+        for (const fileName of CONTEXT_FILE_NAMES) {
+            const path = join(root, fileName);
+            const content = await readResolvedProjectContextFile(path, resolvedRoot);
             if (content === undefined)
                 continue;
+            const realPath = await tryRealpath(path);
+            if (realPath && loadedRealPaths.has(realPath))
+                continue;
             loadedFiles.push({
                 path,
                 content,
             });
+            if (realPath)
+                loadedRealPaths.add(realPath);
         }
         return loadedFiles;
     }
@@ -408,7 +464,10 @@ export class WorkspaceRegistry {
                 loadedRealPaths.add(realPath);
         }
         const discovered = [];
+        const agentDir = resolve(this.config.agentDir);
         await walkWorkspace(root, async (path, entry) => {
+            if (isPathInsideRoot(path, agentDir))
+                return;
             if (!entry.isFile())
                 return;
             if (!CONTEXT_FILE_NAMES.has(entry.name))
@@ -480,20 +539,32 @@ export function formatAgentsPath(path, workspaceRoot) {
     }
     return relationship.split(sep).join("/");
 }
-function isInitialAgentsFilePath(path, root, agentDir) {
-    if (isPathInsideRoot(path, agentDir))
-        return true;
+function isProjectRootInstructionPath(path, root) {
     return isPathInsideRoot(path, root) && dirname(path) === root;
 }
-async function readResolvedContextFile(path, fallbackContent, root, agentDir) {
+async function readSystemInstructions(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function readResolvedProjectContextFile(path, root) {
     try {
         const resolvedPath = await realpath(path);
-        if (!isInitialAgentsFilePath(resolvedPath, root, agentDir))
+        if (!isProjectRootInstructionPath(resolvedPath, root))
             return undefined;
         return await readFile(resolvedPath, "utf8");
     }
-    catch {
-        return fallbackContent;
+    catch (error) {
+        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
     }
 }
 async function tryRealpath(path) {

package/docs/chatgpt-coding-workflow.md

@@ -87,10 +87,14 @@ placed into a merge-conflict state.
 Legacy `devspace/*` managed branches remain closable when they are already stored
 in workspace metadata; only new managed branches use `forgerelay/*`.
 
-## Project instructions
+## Instructions
 
-When a workspace opens, ForgeRelay loads root-level instruction files when they
-exist:
+When a workspace opens, ForgeRelay first loads exactly one global system-instructions
+file. The default is `~/.agents/AGENTS.md`; configure a different single path with
+`FORGERELAY_SYSTEM_INSTRUCTIONS_PATH`. Symbolic links are followed so this entry can
+point at a canonical source elsewhere on disk.
+
+ForgeRelay then loads root-level project instruction files when they exist:
 
 ```text
 AGENTS.md
@@ -99,8 +103,10 @@ CLAUDE.md
 CLAUDE.MD
 ```
 
-Nested instruction files are returned as available paths rather than all being
-injected eagerly. Read the relevant nested file before working under that path.
+Nested project instruction files are returned as available paths rather than all
+being injected eagerly. Read the relevant nested file before working under that path.
+`FORGERELAY_AGENT_DIR` is not an instruction source; it remains only a compatibility
+skill-discovery path.
 
 ## Agent Skills
 

package/docs/configuration.md

@@ -136,6 +136,143 @@ programs when the optional `node-pty` dependency is available.
 | `changes` | Attach UI to `open_workspace` and aggregate `show_changes`. |
 | `off` | Disable widget UI. |
 
+## Lifecycle hooks
+
+Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；命中后 ForgeRelay 直接执行，不再增加批准步骤。
+
+首选格式是 **一个 Hook 一个 JSON 文件**。全局 Hook 放在当前 ForgeRelay 配置目录的 `hooks/` 下，新安装通常是：
+
+```text
+~/.forgerelay/hooks/<hook-name>.json
+```
+
+项目 Hook 放在工作区根目录：
+
+```text
+<workspace>/.forgerelay/hooks/<hook-name>.json
+```
+
+文件名去掉 `.json` 后就是 Hook 名，也是日志和 Agent-visible report 中显示的名称。例如 `release-tag-local-ci.json` 会显示为 `release-tag-local-ci`。目录内按文件名字典序执行；需要显式排序时可以使用 `10-release-verify.json`、`20-package-inspection.json` 这样的前缀。ForgeRelay 只读取普通 `*.json` 文件，所以临时停用某条 Hook 时可以把扩展名改掉。
+
+全局 Hook 在 server 启动时读取，修改后需要重启 ForgeRelay；项目目录在每次事件时重新读取，所以 Agent 修改项目 Hook 后不需要重启。全局规则先执行，项目规则随后执行，两边都只做追加，不互相覆盖。
+
+每个独立 Hook 文件只描述一条规则：
+
+```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
+}
+```
+
+这个例子可以保存为 `.forgerelay/hooks/release-tag-local-ci.json`。Agent 通过 ForgeRelay `bash` 请求推送稳定版本 tag 时，Hook 先跑本地发布检查；成功后才执行原始 `git push`，失败则直接阻断并把 `release-tag-local-ci` 的失败报告返回给 Agent。
+
+独立 Hook 文件支持这些顶层字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `event` | 必填，九个 Hook event 之一。 |
+| `matcher` | 可选，只在匹配当前生命周期上下文时执行。 |
+| `command` | 必填，本地 shell 命令。 |
+| `timeoutSeconds` | 默认 `30`，范围 `1` 到 `300`。 |
+| `report` | 默认 `true`。为 `false` 时成功结果不主动出现在 Agent 可见报告中；blocking 失败始终可见。 |
+
+独立文件不写 `name`：文件名就是唯一的 Hook 名。一个逻辑 Hook 如果需要多个独立步骤，拆成多个文件；这样可以单独启停、重命名、排序和审查每一步。
+
+为兼容已有配置，ForgeRelay 仍接受旧的 `config.json -> hooks`、全局 `hooks.json` 和项目 `.forgerelay/hooks.json` 聚合格式。执行顺序是旧配置在前、`hooks/*.json` 独立文件在后。新配置应优先使用独立文件。
+
+若某个项目 Hook 文件 JSON 或 schema 无效，ForgeRelay 会返回 `Project hooks config` diagnostic，同时继续加载其他有效项目 Hook，并保持 workspace/tool 可用，让 Agent 可以直接修复出错文件。
+
+### 检查 Hook 配置
+
+CLI 可以只读检查规则，不会启动 MCP server，也不会执行 Hook：
+
+```bash
+forgerelay hooks list
+forgerelay hooks check
+forgerelay hooks list --project /path/to/project
+forgerelay hooks check --project /path/to/project
+```
+
+不传 `--project` 时使用当前目录。`list` 展示实际加载的全局与项目规则，包括 event、matcher、timeout、`report` 和 command；`check` 只做解析与 schema 校验，成功时输出全局/项目 Hook 数量，发现坏的全局或项目文件时返回非零状态。
+
+`matcher` 当前支持：
+
+| 字段 | 匹配方式 |
+| --- | --- |
+| `tool` | 精确匹配 MCP tool 名称。 |
+| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配。 |
+| `pathRegex` | 对 payload 中的 `path` 或 `paths` 做正则匹配。 |
+| `provider` | 精确匹配 subagent provider。 |
+| `workspaceMode` | `checkout` 或 `worktree`。 |
+
+Matcher 匹配 ForgeRelay 收到的那次 tool request，不会窥探该命令内部后续启动的子进程。例如 `bash` 参数本身是 `git push origin v0.2.0` 时可以命中；若参数只是 `./release.sh`，而脚本内部再执行 `git push`，ForgeRelay 不会把内部子进程重新解释成新的 Hook 事件。
+
+旧聚合格式里的 `matcher -> handlers` 与 handler `name` 继续按原语义工作，只作为兼容入口保留。
+
+### 事件
+
+| Event | 语义 |
+| --- | --- |
+| `WorkspaceOpen` | 新 workspace session 创建后触发；复用已有 workspace 不重复触发。 |
+| `BeforeTool` | workspace-scoped MCP tool 执行前触发；失败或超时会阻断原操作。`open_workspace` 因执行前还没有 workspace，不走该事件。 |
+| `AfterTool` | tool 成功后触发。 |
+| `AfterToolFailure` | tool 失败或被 `BeforeTool` 拒绝后触发。 |
+| `AfterFileChange` | `write`、`edit`、`apply_patch`、native artifact 等明确文件变更成功后触发；不会推断 shell 的文件副作用。 |
+| `BeforeWorktreeClose` | worktree commit、fast-forward、cleanup 前触发；失败会保留 worktree 并阻断 close。 |
+| `AfterWorktreeClose` | managed worktree 成功关闭后触发；此时从 source checkout 运行。 |
+| `SubagentStart` | 本地 subagent worker 进入执行时触发。 |
+| `SubagentStop` | subagent 完成或进入 error 状态时触发。 |
+
+`BeforeTool` 与 `BeforeWorktreeClose` 是 blocking 事件。其他事件是 observational：失败会被记录并报告，但不会回滚已经完成的文件、Git、进程或网络副作用。Blocking 同样不是事务；Hook 命令自己已经产生的副作用不会因 exit code 非零而撤销。
+
+### Agent 可见报告
+
+`report:true` 的执行结果会进入模型可见 tool result，例如：
+
+```text
+Hook results:
+✓ release-tag-local-ci (BeforeTool, project) passed in 38124ms
+```
+
+阻断失败会明确显示 `failed`。ForgeRelay 的 server instructions 要求 Agent 在出现 Hook results 时，向用户说明有意义的 Hook 是否通过或阻断了操作。异步 subagent 的 `SubagentStart` / `SubagentStop` 报告会随 session 持久化，并由 `forgerelay agents show` 展示。
+
+### Hook 环境
+
+Hook 命令继承 ForgeRelay 进程环境，并额外获得：
+
+| Variable | 含义 |
+| --- | --- |
+| `FORGERELAY_HOOK_EVENT` | 当前事件名。 |
+| `FORGERELAY_HOOK_PAYLOAD` | 事件相关 metadata 的 JSON。 |
+| `FORGERELAY_WORKSPACE_ROOT` | 当前 workspace root。 |
+| `FORGERELAY_WORKSPACE_ID` | 已知时提供 workspace ID；直接 CLI subagent 可能没有。 |
+| `FORGERELAY_WORKSPACE_MODE` | 已知时为 `checkout` 或 `worktree`。 |
+| `FORGERELAY_SOURCE_ROOT` | managed worktree 场景中的 source checkout。 |
+| `FORGERELAY_TOOL_NAME` | tool 生命周期事件中的 MCP tool 名称。 |
+
+Payload 用于策略和自动化，不包含文件正文、native-file credentials 或 subagent prompt。Shell Hook 会看到请求本身的 command metadata，因此 Hook 自己的日志仍应按可能含敏感参数处理。
+
+Hook 命令与 ForgeRelay 使用同一个本地用户权限。项目 `.forgerelay/hooks/*.json` 是可执行项目约定；允许某个 root 后，应把该 root 中的项目 Hook 视为本地开发环境的一部分。详见 [Security Model](security.md)。
+
+## System instructions
+
+ForgeRelay loads exactly one global system-instructions file. The default is
+`~/.agents/AGENTS.md`. Set `FORGERELAY_SYSTEM_INSTRUCTIONS_PATH` or the
+`systemInstructionsPath` config key to point at a different single file.
+Arrays or empty values are not accepted. Symbolic links are followed, so the
+runtime entry may point at a canonical source elsewhere on disk.
+
+Project-root `AGENTS.md` / `CLAUDE.md` files remain project context and are
+loaded separately. `FORGERELAY_AGENT_DIR` does not select a global instruction
+file; it remains a compatibility path for Agent Skills.
+
 ## Skills and subagents
 
 | Variable | Purpose |

package/docs/debugging.md

@@ -0,0 +1,126 @@
+# Local Debugging
+
+ForgeRelay development uses a dedicated loopback server on port `7677`. The
+normal product default remains `7676`; `7677` is reserved for this repository's
+local debug and acceptance workflow so development does not collide with a
+normally installed ForgeRelay instance.
+
+## Start the debug server
+
+```bash
+npm run dev
+```
+
+`npm run debug:serve` is an explicit alias for the same command.
+
+The debug launcher uses [`scripts/debug/config.json`](../scripts/debug/config.json)
+and prints the generated Owner password when it starts. It binds only to:
+
+```text
+http://127.0.0.1:7677
+```
+
+Useful endpoints are:
+
+```text
+http://127.0.0.1:7677/healthz
+http://127.0.0.1:7677/.well-known/oauth-protected-resource/mcp
+http://127.0.0.1:7677/.well-known/oauth-authorization-server
+http://127.0.0.1:7677/mcp
+```
+
+The debug server watches `src/` and restarts after source changes. One generated
+Owner password is kept for the lifetime of the launcher so restarts do not force
+a new debug credential.
+
+To provide a stable local-only Owner password instead of the generated one:
+
+```bash
+FORGERELAY_DEBUG_OWNER_TOKEN="local-debug-password-at-least-16-chars" npm run dev
+```
+
+Do not use that variable for a publicly reachable ForgeRelay deployment.
+
+## Run the end-to-end acceptance
+
+```bash
+npm run debug:accept
+```
+
+The acceptance runner starts its own ForgeRelay process on `127.0.0.1:7677`,
+sends real HTTP requests with `curl`, and shuts the server down when it finishes.
+It refuses to start when port `7677` is already occupied so it cannot
+accidentally validate an older debug process.
+
+The acceptance checks:
+
+1. `/healthz`;
+2. OAuth protected-resource and authorization-server discovery;
+3. unauthenticated `/mcp` rejection;
+4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
+5. MCP `initialize`, including package/server version consistency;
+6. `tools/list` for the full debug tool surface;
+7. a real checkout workspace with `write`, `read`, `bash`, and a deliberate failed `edit`;
+8. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
+9. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
+10. deterministic local subagent error path，不联系任何模型 provider；
+11. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。
+
+`curl` must be available on `PATH` for this acceptance command. Node and Git are
+already normal ForgeRelay development prerequisites.
+
+## Debug configuration
+
+The checked-in debug configuration is:
+
+```text
+scripts/debug/config.json
+```
+
+It deliberately contains no Owner password. Runtime secrets are generated by
+the launcher and passed through the environment.
+
+The config enables all Hooks v1 events with the local recorder at:
+
+```text
+scripts/debug/hook-recorder.mjs
+```
+
+The recorder keeps only useful lifecycle metadata such as event, workspace,
+tool, paths, branch, status, and subagent identity. It does not copy arbitrary
+hook payloads, shell commands, prompts, OAuth credentials, or native-file
+credentials into the debug log.
+
+## Generated state
+
+All debug-only runtime state is written below:
+
+```text
+.forgerelay-debug/
+```
+
+That directory is gitignored. Typical contents include:
+
+```text
+.forgerelay-debug/state/
+.forgerelay-debug/worktrees/
+.forgerelay-debug/hooks.jsonl
+.forgerelay-debug/acceptance/
+```
+
+Acceptance runner 每次都会重建自己的 `acceptance/` 子目录。除了临时 checkout/worktree，它还会建立一个本地 bare Git remote，用来验证 release tag Hook 的真实 `git push` 顺序；不会访问或修改 ForgeRelay 的远程仓库，也不会编辑 tracked project files。
+
+## Scripts
+
+The debug workflow is intentionally explicit rather than hidden in ad-hoc shell
+commands:
+
+- `scripts/debug/config.json` — loopback `7677` configuration and hook setup;
+- `scripts/debug/runtime.mjs` — shared paths, generated credentials, and deterministic debug environment;
+- `scripts/debug/serve.mjs` — watched local debug server launcher;
+- `scripts/debug/accept.mjs` — real HTTP/OAuth/MCP acceptance runner;
+- `scripts/debug/hook-recorder.mjs` — sanitized JSONL lifecycle recorder.
+
+When a bug only appears through the real HTTP transport, add the reproduction to
+`debug:accept` (or a focused test derived from it) rather than relying on a
+one-off local command that cannot be repeated later.

package/docs/roadmap.md

@@ -60,32 +60,27 @@ The initial independent release establishes:
 
 ## 0.2 — Hooks v1
 
-Hooks are the next priority because they provide a general policy extension point
-without hardcoding project-specific commands into Git/workspace logic.
+Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生命周期规则层，而不是复制完整的 Agent 权限或插件系统。
 
-Initial events:
+当前契约包括：
 
-- `WorkspaceOpen`
-- `BeforeTool`
-- `AfterTool`
-- `AfterToolFailure`
-- `AfterFileChange`
-- `BeforeWorktreeClose`
-- `AfterWorktreeClose`
-- `SubagentStart`
-- `SubagentStop`
+- 全局 `hooks/<hook-name>.json` 与项目 `.forgerelay/hooks/<hook-name>.json` 自动组合；
+- 一个独立文件就是一个 Hook，文件名就是 Hook 名，目录内按文件名稳定排序；
+- `event + matcher + command` 规则，以及 timeout 与 `report`；
+- 旧 inline/聚合 Hook 配置继续兼容；
+- `BeforeTool` / `BeforeWorktreeClose` 阻断语义；
+- observational after-events；
+- Agent 可见 Hook report；
+- `forgerelay hooks list` / `hooks check` 只读检查入口；
+- `WorkspaceOpen`、tool、文件变更、worktree 与 subagent 生命周期；
+- 项目 Hook 配置损坏时可见且可修复的 diagnostic；
+- 7677 真实网络验收中的 release-tag-push 本地验证场景。
 
-Initial handler type:
+事件仍保持九个：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
 
-- local command
+典型用法是在 `BeforeTool` 中匹配稳定版本 tag 的 `git push`，先执行项目定义的本地 CI；成功后继续 push，失败时让 Agent 获得报告并修复。`BeforeWorktreeClose` 则适合在 managed branch 集成前执行测试、类型检查或其他项目验证。
 
-The first implementation should define a deep hook engine contract and keep MCP
-tool handlers thin. HTTP/prompt/agent-style handlers can be evaluated later if
-there is a concrete need.
-
-`BeforeWorktreeClose` should become the natural place for user-configured test,
-typecheck, formatting, or security verification before a managed branch is
-integrated.
+0.2 不引入审批 UI、HTTP/prompt/agent handler、Git 字符串解析器或插件注册表。只有出现真实需求时再扩展 handler 类型。
 
 ## 0.3 — LSP code intelligence v1
 

package/docs/security.md

@@ -99,6 +99,20 @@ The security model is therefore based on:
 
 Do not describe ForgeRelay as a sandboxed coding environment.
 
+## Lifecycle hooks
+
+Hook command 是本地代码执行，使用与 ForgeRelay 相同的操作系统用户权限并继承进程环境。
+
+Hooks v1 有两个自动作用域：当前 ForgeRelay 配置目录中的 `hooks/<hook-name>.json` 全局规则，以及 workspace 根目录的 `.forgerelay/hooks/<hook-name>.json` 项目规则。项目规则不需要额外批准；打开允许根目录中的项目时，ForgeRelay 会把这些 Hook 当作该开发环境的执行约定直接使用，`WorkspaceOpen` 也可以立即触发命令。因此 allowed roots 不只是文件访问边界，也界定了你愿意让 ForgeRelay 操作的本地项目环境。
+
+每个独立 Hook 文件只声明一个 event、可选 matcher 和一个 command，以及 timeout/report。文件名只决定 Hook 名和排序，不能扩大 allowed roots、修改 OAuth 配置或删除全局规则。全局与项目规则采用组合关系。若某个项目 Hook 文件损坏，ForgeRelay 返回可见 diagnostic、跳过该无效文件并继续加载其他有效 Hook，同时保持工具可用，便于 Agent 修复。旧聚合格式仍兼容。
+
+`BeforeTool` 和 `BeforeWorktreeClose` 是阻断点：命中的 handler 失败或超时后，待执行操作不会继续。其余事件用于观察已发生的生命周期结果，失败不会回滚已经完成的工作。`report:false` 可以隐藏成功的高频报告，但不能隐藏阻断失败。
+
+Hook payload 刻意不携带文件正文、native-file credentials 或 subagent prompt。Shell tool 的 command metadata 仍可能包含敏感参数，因此 Hook 脚本自己的日志也应按敏感输入处理。
+
+详见 [Configuration Reference](configuration.md#lifecycle-hooks)。
+
 ## Git and managed worktrees
 
 Managed worktrees are branch-backed and visible in the source repository.