@akira-tl/forgerelay 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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
+
+- GitHub CI is now release-only: ordinary branch pushes, pull-request updates, and manual dispatches do not start cloud CI; the reusable CI workflow is invoked only by the stable `vX.Y.Z` tag release workflow.
+- Release automation now triggers only for stable `vX.Y.Z` version tags, waits for cloud CI to pass, then publishes; ordinary branch pushes never enter the CI or publication workflows.
+- Global system instructions now come from exactly one configured file, defaulting to `~/.agents/AGENTS.md`; `FORGERELAY_AGENT_DIR` remains a skill-compatibility path rather than an instruction source.
+
+### Fixed
+
+- Symbolic-link system instruction entries now follow their configured target even when the canonical source lives outside the runtime instruction directory.
+- Project instruction aliases that resolve to the same file are loaded once, preventing duplicate `AGENTS.md` context on case-insensitive filesystems such as default macOS and Windows checkouts.
+
 ## [0.1.0] - 2026-08-09
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 **Give MCP coding agents a real local workspace.**
 
 [![npm](https://img.shields.io/npm/v/%40akira-tl%2Fforgerelay?style=flat-square)](https://www.npmjs.com/package/@akira-tl/forgerelay)
-[![CI](https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/ci.yml?style=flat-square&branch=main)](https://github.com/Akira-TL/forgerelay/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/release.yml?style=flat-square&label=release)](https://github.com/Akira-TL/forgerelay/actions/workflows/release.yml)
 [![License](https://img.shields.io/npm/l/%40akira-tl%2Fforgerelay?style=flat-square)](LICENSE)
 
 ForgeRelay is a self-hosted MCP server that lets ChatGPT and other MCP-capable
@@ -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
@@ -227,9 +261,11 @@ npm run release:major
 npm run release:verify
 ```
 
-Pushing a matching `vX.Y.Z` tag to `Akira-TL/forgerelay` is the publish action.
-GitHub Actions verifies the tagged commit, publishes `@akira-tl/forgerelay` to
-npm, and creates the matching GitHub Release.
+Daily branch pushes do not run cloud CI. When preparing a release, run the full
+local release verification first. Pushing a matching `vX.Y.Z` tag to
+`Akira-TL/forgerelay` is the only cloud CI and publish trigger: GitHub Actions
+runs the reusable multi-platform CI, then publishes `@akira-tl/forgerelay` and
+creates the matching GitHub Release only after CI succeeds.
 
 See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
 Trusted Publishing setup.
@@ -237,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)
@@ -264,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/artifact-tools.js

@@ -5,6 +5,7 @@ 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";
 const ARTIFACT_WRITE_ANNOTATIONS = {
@@ -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,34 @@ export function registerArtifactTools(server, { config, workspaces, incomingArti
         },
         _meta: { "openai/fileParams": ["file"] },
         annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input) => executeArtifactTool(config, input, async () => {
+    }, async (input) => {
         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, 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.

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;
@@ -164,6 +165,17 @@ function defaultWorktreeRoot() {
 function defaultAgentDir() {
     return join(homedir(), ".codex");
 }
+function defaultSystemInstructionsPath() {
+    return join(homedir(), ".agents", "AGENTS.md");
+}
+function parseSystemInstructionsPath(value) {
+    if (value === undefined)
+        return resolve(defaultSystemInstructionsPath());
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("FORGERELAY_SYSTEM_INSTRUCTIONS_PATH must be one non-empty path");
+    }
+    return resolve(expandHomePath(value.trim()));
+}
 export function loadConfig(env = process.env) {
     const files = loadForgeRelayFiles(env);
     const host = env.HOST ?? files.config.host ?? "127.0.0.1";
@@ -202,6 +214,8 @@ export function loadConfig(env = process.env) {
             ? files.config.subagents === true
             : 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"));
+}