mainflow 0.20.0 → 0.22.0

package/dist/grant-commands.js

@@ -0,0 +1,245 @@
+import { H as GRANT_FORMS } from "./dist-DCYzrl7J.js";
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/grant-commands.ts
+/**
+* Text that may hold a grantable command; a call that matches neither is not one this hook decides. It is matched
+* in lowercase with quotes and backslashes removed, because the shell drops those (pn\pm, 'pnpm') and a
+* case-insensitive file system runs NPM as npm.
+*/
+const MENTIONS = {
+	publish: /\b(?:npm|pnpm)\b[\s\S]*\bpublish\b/,
+	release: /\bgh\b[\s\S]*\brelease\b[\s\S]*\b(?:create|new)\b/
+};
+const mentionText = (command) => command.toLowerCase().replace(/[\\'"]/g, "");
+/** How much of a command a reason quotes. */
+const QUOTED = 200;
+const quote = (text) => text.length > QUOTED ? `${text.slice(0, QUOTED)}…` : text;
+var Refused = class extends Error {};
+/** A bare word: no shell syntax at all. */
+const BARE = /^[A-Za-z0-9._/@:=+-]+$/;
+/** A title or notes value in quotes, where the shell expands nothing. */
+const QUOTED_VALUE = /^'[^']*'$|^"[^"\\$`]*"$/;
+/** A git tag a release may create: no path separators, no `..`. */
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const OWNER_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Split a call into words separated by spaces; only printable ASCII, and quotes only around a whole word. */
+function words(command) {
+	const text = command.trim();
+	if (!/^[\x20-\x7e]*$/.test(text)) throw new Refused("指令含換行、tab 或其他不可見字元");
+	const result = [];
+	let i = 0;
+	while (i < text.length) {
+		if (text[i] === " ") {
+			i++;
+			continue;
+		}
+		const quoteChar = text[i] === "'" || text[i] === "\"" ? text[i] : null;
+		const space = text.indexOf(" ", i);
+		const end = quoteChar ? text.indexOf(quoteChar, i + 1) + 1 : space < 0 ? text.length : space;
+		if (quoteChar && (end === 0 || end < text.length && text[end] !== " ")) throw new Refused("引號要包住一整個值");
+		const word = text.slice(i, end);
+		if (!(quoteChar ? QUOTED_VALUE : BARE).test(word)) throw new Refused(`「${quote(word)}」含 shell 語法`);
+		result.push(word);
+		i = end;
+	}
+	return result;
+}
+/** Take the flags after the command words: `values` take the next word, `flags` stand alone; each at most once. */
+function flagsOf(rest, values, flags) {
+	const found = /* @__PURE__ */ new Map();
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (found.has(word)) throw new Refused(`${word} 重複`);
+		if (values.has(word)) {
+			const value = rest[++i];
+			if (value === void 0) throw new Refused(`${word} 沒有值`);
+			found.set(word, value);
+		} else if (flags.has(word)) found.set(word, "");
+		else throw new Refused(`「${quote(word)}」不在固定寫法裡`);
+	}
+	return found;
+}
+/** Values other than --title and --notes are bare words, so they cannot hide a quote. */
+function bareValue(flag, value) {
+	if (value !== void 0 && !BARE.test(value)) throw new Refused(`${flag} 的值不能加引號`);
+	return value;
+}
+function publishForm(list, text) {
+	const [tool, sub, ...rest] = list;
+	if (tool !== "npm" && tool !== "pnpm" || sub !== "publish") throw new Refused("不是單獨一條 npm publish 或 pnpm publish");
+	const flags = flagsOf(rest, /* @__PURE__ */ new Set(["--access", "--tag"]), /* @__PURE__ */ new Set([
+		"--ignore-scripts",
+		"--dry-run",
+		"--provenance",
+		...tool === "pnpm" ? ["--no-git-checks"] : []
+	]));
+	if (!flags.has("--ignore-scripts")) throw new Refused("沒有帶 --ignore-scripts，lifecycle 腳本會執行");
+	const access = bareValue("--access", flags.get("--access"));
+	if (access !== void 0 && access !== "public" && access !== "restricted") throw new Refused("--access 只能是 public 或 restricted");
+	const tag = bareValue("--tag", flags.get("--tag"));
+	if (tag !== void 0 && !TAG.test(tag)) throw new Refused("--tag 不是 dist-tag 名稱");
+	return {
+		action: "publish",
+		tool,
+		text
+	};
+}
+function releaseForm(list, text) {
+	const [tool, sub, verb, tag, ...rest] = list;
+	if (tool !== "gh" || sub !== "release" || verb !== "create") throw new Refused("不是單獨一條 gh release create");
+	if (!tag || !TAG.test(tag) || tag.includes("..")) throw new Refused("tag 只能用英數字、點、底線與連字號，不能含 / 或 ..");
+	const repo = bareValue("-R", flagsOf(rest, /* @__PURE__ */ new Set([
+		"-R",
+		"--title",
+		"--notes"
+	]), /* @__PURE__ */ new Set([
+		"--generate-notes",
+		"--draft",
+		"--prerelease",
+		"--verify-tag"
+	])).get("-R"));
+	if (!repo || !OWNER_REPO.test(repo)) throw new Refused("-R <owner/repo> 必填");
+	return {
+		action: "release",
+		tag,
+		repo,
+		text
+	};
+}
+/** Whether a Bash call is one this hook decides and, if so, whether it is in a fixed form. */
+function scanCommand(command) {
+	const text = mentionText(command);
+	const publish = MENTIONS.publish.test(text);
+	const release = MENTIONS.release.test(text);
+	if (!publish && !release) return { kind: "none" };
+	const forms = [...publish ? [GRANT_FORMS.publish] : [], ...release ? [GRANT_FORMS.release] : []].join("，或");
+	try {
+		const list = words(command);
+		return {
+			kind: "fixed",
+			call: release && (!publish || list[0] === "gh") ? releaseForm(list, command.trim()) : publishForm(list, command.trim())
+		};
+	} catch (error) {
+		if (error instanceof Refused) return {
+			kind: "refused",
+			reason: `授權放行只接受${forms}（這次：${error.message}）`
+		};
+		throw error;
+	}
+}
+const refuse = (form, why) => ({
+	ok: false,
+	reason: `授權放行只接受${GRANT_FORMS[form]}（這次：${why}）`
+});
+const real = (path) => {
+	try {
+		return realpathSync(path);
+	} catch {
+		return null;
+	}
+};
+const within = (path, root) => {
+	const rel = relative(root, path);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+};
+/**
+* The payload's cwd after realpath, when it exists and lies in the hub or in a repository config.yaml lists; a
+* listed repository counts as part of the hub even when it sits outside the hub directory, as ../mainflow does.
+*/
+function scopedCwd(cwd, root, repos) {
+	const scope = (why) => ({
+		ok: false,
+		reason: `授權只在 hub 與 config.yaml 登記的倉庫內生效（這次：${why}）`
+	});
+	if (typeof cwd !== "string" || !isAbsolute(cwd)) return scope("payload 的 cwd 不是絕對路徑");
+	const dir = real(cwd);
+	if (!dir) return scope(`目錄 ${quote(cwd)} 不存在`);
+	return [root, ...Object.values(repos).map((path) => resolve(root, path))].flatMap((r) => real(r) ?? []).some((r) => within(dir, r)) ? {
+		ok: true,
+		dir
+	} : scope(`${quote(dir)} 不在 hub 或登記的倉庫內`);
+}
+/** A version as npm publishes it: no v prefix, no spaces, no leading zeros. */
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** Largest package.json read; a bigger one is not a manifest this hook trusts. */
+const MAX_MANIFEST = 1048576;
+/**
+* Read a file only when it is a regular file of at most MAX_MANIFEST bytes, following symlinks. It is opened
+* without blocking and checked on the open descriptor, so a FIFO or a device such as /dev/zero is refused rather
+* than waited on, and the file checked is the file read.
+*/
+function readManifest(file) {
+	let fd;
+	try {
+		fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+	} catch {
+		return null;
+	}
+	try {
+		const stat = fstatSync(fd);
+		return stat.isFile() && stat.size <= MAX_MANIFEST ? readFileSync(fd, "utf8") : null;
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+/** name and version from package.json in `dir`; a private package, or one that publishes another directory, is refused. */
+function resolvePublish(dir) {
+	const text = readManifest(join(dir, "package.json"));
+	if (text === null) return refuse("publish", `${quote(dir)} 的 package.json 不是 1 MB 以內的一般檔案`);
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return refuse("publish", `${quote(dir)} 的 package.json 不是 JSON`);
+	}
+	if (typeof data !== "object" || data === null) return refuse("publish", "package.json 不是物件");
+	if (typeof data.name !== "string" || typeof data.version !== "string") return refuse("publish", "package.json 沒有 name 或 version");
+	if (!SEMVER.test(data.version)) return refuse("publish", `version ${quote(JSON.stringify(data.version))} 不是標準的 semver`);
+	if (data.version.split("+")[0].split(/[.-]/).filter((part) => /^\d+$/.test(part)).some((part) => !Number.isSafeInteger(Number(part)))) return refuse("publish", `version ${quote(data.version)} 有超過 Number.MAX_SAFE_INTEGER 的數字`);
+	if (data.private) return refuse("publish", `${data.name} 是 private 套件`);
+	if (data.publishConfig?.directory !== void 0) return refuse("publish", "package.json 的 publishConfig.directory 會改發布別的目錄");
+	return {
+		ok: true,
+		request: {
+			action: "publish",
+			name: data.name,
+			version: data.version
+		}
+	};
+}
+/** The origin remote of a checkout as github.com/owner/repo in lowercase, or null when it is not on github.com. */
+function githubOrigin(dir) {
+	const result = spawnSync("git", [
+		"-C",
+		dir,
+		"remote",
+		"get-url",
+		"origin"
+	], { encoding: "utf8" });
+	const url = result.status === 0 ? result.stdout.trim().replace(/\.git$/, "") : "";
+	const match = /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/.exec(url);
+	return match ? `github.com/${match[1]}`.toLowerCase() : null;
+}
+function resolveRelease(call, ctx) {
+	const slug = `github.com/${call.repo}`.toLowerCase();
+	const repos = Object.entries(ctx.repos).filter(([, path]) => githubOrigin(resolve(ctx.root, path)) === slug).map(([name]) => name);
+	if (repos.length === 0) return refuse("release", `${quote(call.repo)} 不是 config.yaml 裡任何倉庫的 origin`);
+	return {
+		ok: true,
+		request: {
+			action: "release",
+			repos,
+			tag: call.tag
+		}
+	};
+}
+/** What a fixed-form call would publish or release; refused when the package or repository does not qualify. */
+function resolveFixed(call, ctx) {
+	return call.action === "publish" ? resolvePublish(ctx.cwd) : resolveRelease(call, ctx);
+}
+//#endregion
+export { TAG, githubOrigin, quote, resolveFixed, scanCommand, scopedCwd };

package/dist/hooks.d.ts

@@ -15,7 +15,7 @@ export interface ClaudeCodePayload {
   stop_hook_active?: boolean;
   /** MessageDisplay: the lines of an assistant message about to be shown */
   delta?: string;
-  /** PostToolUse: the tool that ran and its input */
+  /** PreToolUse and PostToolUse: the tool about to run or that ran, and its input */
   tool_name?: string;
   tool_input?: {
     file_path?: string;
@@ -32,15 +32,36 @@ export interface HookContext {
   cli: string;
   /** Start the hub's interface without waiting; given by the CLI entry point, left out by callers that must not spawn */
   startUi?: (root: string) => void;
+  /** Report something on stderr without changing what the hook prints; runHook sets it */
+  warn?: (message: string) => void;
+  /** $CLAUDE_PROJECT_DIR: where the session was opened; events in PROJECT_HUB_EVENTS find the hub from it first */
+  projectDir?: string;
 }
+/**
+ * Read a hook's stdin: one JSON object, as Claude Code sends it. Anything else is null, including arrays,
+ * scalars, empty input, and an object with a key written twice, since which value the host acted on is unknown.
+ */
+export declare function parsePayload(text: string): ClaudeCodePayload | null;
 export declare const claudeCodeSessionId: (raw: string) => string;
 type Handler = (root: string, ctx: HookContext) => string | null;
 /** How a hub's interface is linked from a reply: through its /open route, which shows the address in the app. */
 export declare const openLink: (hub: string) => (path: string) => string;
+/** Why an event could not run its handler: outside a hub, the handler threw, or stdin was not JSON. */
+export type HookFailure = {
+  kind: 'outside-hub';
+} | {
+  kind: 'error';
+  message: string;
+} | {
+  kind: 'unreadable-input';
+};
 export declare const HOOK_PLATFORMS: Record<string, Record<string, Handler>>;
+/** What an event prints when it cannot run its handler; null for the events that stay silent. */
+export declare function hookFallback(platform: string, event: string, ctx: HookContext, failure: HookFailure): string | null;
 /**
  * Run a hook handler. A hook must never break the host session, so outside a hub it stays silent and any
- * failure is reported on stderr while the caller still exits 0.
+ * failure is reported on stderr while the caller still exits 0. Events listed in the fallbacks print their
+ * fallback instead of staying silent.
  */
 export declare function runHook(platform: string, event: string, ctx: HookContext): {
   stdout: string | null;

package/dist/hooks.js

@@ -1,4 +1,6 @@
-import { G as mayDecorate, H as decorateReply, I as setSessionInfo, L as setSessionStatus, O as sessionBriefing, P as readSession, R as settleSession, U as endsWithMarker, W as headerLine, dt as DATA_DIR, ft as currentBranch, i as hostName, j as ensureSession, k as turnReminder, mt as worktreesOf, nt as loadHub, pt as findHubRoot, tt as HubError } from "./host-BsLqiI0_.js";
+import { G as endsWithMarker, H as grantScope, I as setSessionInfo, J as appendOps, K as headerLine, L as setSessionStatus, O as sessionBriefing, P as readSession, R as settleSession, U as matchGrants, W as decorateReply, _t as worktreesOf, gt as findHubRoot, ht as currentBranch, i as hostName, it as loadHub, j as ensureSession, k as turnReminder, mt as DATA_DIR, pt as readYaml, q as mayDecorate, rt as HubError } from "./host-0_zkFbzM.js";
+import { D as configSchema, W as describeRequest } from "./dist-DCYzrl7J.js";
+import { resolveFixed, scanCommand, scopedCwd } from "./grant-commands.js";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 //#region src/hooks.ts
@@ -20,6 +22,46 @@ const brief = (text) => {
 	const flat = (text ?? "").replace(/\s+/g, " ").trim();
 	return flat.length > SUMMARY_LIMIT ? `${flat.slice(0, 279)}…` : flat;
 };
+/**
+* Read a hook's stdin: one JSON object, as Claude Code sends it. Anything else is null, including arrays,
+* scalars, empty input, and an object with a key written twice, since which value the host acted on is unknown.
+*/
+function parsePayload(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || hasDuplicateKeys(text)) return null;
+	return parsed;
+}
+/** Whether any object in valid JSON text names a key twice; JSON.parse keeps only the last one. */
+function hasDuplicateKeys(text) {
+	const stack = [];
+	for (let i = 0; i < text.length; i++) {
+		const c = text[i];
+		const top = stack.at(-1);
+		if (c === "{") stack.push({
+			keys: /* @__PURE__ */ new Set(),
+			expectKey: true
+		});
+		else if (c === "[") stack.push(null);
+		else if (c === "}" || c === "]") stack.pop();
+		else if (c === "," && top) top.expectKey = true;
+		else if (c === "\"") {
+			const start = i;
+			for (i++; text[i] !== "\""; i++) if (text[i] === "\\") i++;
+			if (top?.expectKey) {
+				const key = JSON.parse(text.slice(start, i + 1));
+				if (top.keys.has(key)) return true;
+				top.keys.add(key);
+				top.expectKey = false;
+			}
+		}
+	}
+	return false;
+}
 const shortId = (raw) => raw.replace(/[^a-z0-9]/gi, "").toLowerCase().slice(0, 8);
 const claudeCodeSessionId = (raw) => `claude-code-${shortId(raw)}`;
 /**
@@ -158,9 +200,92 @@ const CLAUDE_CODE_EVENTS = {
 		setSessionStatus(root, id, "ended");
 		return null;
 	},
+	"pre-tool-use": decideByGrants,
 	"post-tool-use": checkAfterWrite,
 	"message-display": displayReply
 };
+/**
+* Events that must not stay silent when they cannot decide, because silence would let through what they
+* guard; each says what to print instead. Every other event stays silent on failure.
+*/
+const CLAUDE_CODE_FALLBACKS = { "pre-tool-use": askWhenGrantable };
+/** The PreToolUse answer; `ask` hands the call to the usual permission prompt, with the reason shown. */
+const permission = (decision, reason) => JSON.stringify({ hookSpecificOutput: {
+	hookEventName: "PreToolUse",
+	permissionDecision: decision,
+	permissionDecisionReason: `[mainflow] ${reason}`
+} });
+const askBecause = (reason) => permission("ask", `${reason}，所以照常詢問`);
+/**
+* Scan a Bash call; null when it mentions no grantable command, so the hook stays silent. A Bash call whose
+* command is not a string cannot be judged, so it is refused.
+*/
+function grantableCall(payload) {
+	if (typeof payload.tool_name !== "string" || payload.tool_name.toLowerCase() !== "bash") return null;
+	const command = payload.tool_input?.command;
+	if (typeof command !== "string") return {
+		kind: "refused",
+		reason: "tool_input.command 不是字串"
+	};
+	const scan = scanCommand(command);
+	return scan.kind === "none" ? null : scan;
+}
+/** Outside a hub, or when deciding failed: ask for a grantable call, stay silent for any other. */
+function askWhenGrantable({ payload }, failure) {
+	const reason = failure.kind === "outside-hub" ? "不在 mainflow hub 裡，沒有主脈絡授權可用" : failure.kind === "error" ? `判斷授權時出錯：${failure.message}` : "hook 讀不到 PreToolUse 的輸入";
+	if (failure.kind === "unreadable-input") return askBecause(reason);
+	try {
+		return grantableCall(payload) ? askBecause(reason) : null;
+	} catch {
+		return askBecause(reason);
+	}
+}
+/** The ops log's fields cannot hold its separator, so notes that contain one are written with a broken bar. */
+const opsText = (text) => text.replace(/\s\|\s/g, " ¦ ").replace(/\s+/g, " ").slice(0, 200);
+/** Log the allowed operation with the grant that covered it; a failure only warns, the call stays allowed. */
+function logGranted(root, scope, call, request, grant, warn) {
+	try {
+		appendOps(root, {
+			target: request.action === "publish" ? `npm ${request.name}` : `github release ${request.repos.join("/")}`,
+			operation: opsText(call.text),
+			result: `授權放行 ${grant.ref}（${describeRequest(request)}）`,
+			ref: scope.served[grant.mainline]
+		});
+	} catch (error) {
+		warn?.(`mainflow hook claude-code pre-tool-use: allowed by ${grant.ref} but could not write the ops log: ${error.message}`);
+	}
+}
+/**
+* PreToolUse: allow a publish or release that a grant covers, ask for every other one. `allow` lets the whole
+* call run, so only the two fixed forms in grant-commands.ts can be allowed. A grant counts only when the
+* session's one action in progress serves its mainline and the mainline is open; the package comes from
+* package.json in the payload's cwd and the repository from config.yaml. Calls that mention no grantable command
+* print nothing, so other hooks and the usual permission rules decide them. Any failure asks: the caller turns a
+* throw into the fallback above.
+*/
+function decideByGrants(root, { payload, warn }) {
+	const scan = grantableCall(payload);
+	if (!scan) return null;
+	if (scan.kind === "refused") return askBecause(scan.reason);
+	const sessionId = payload.session_id;
+	if (typeof sessionId !== "string" || !sessionId) return askBecause("payload 沒有字串的 session_id");
+	const scoped = grantScope(root, readSession(root, claudeCodeSessionId(sessionId)));
+	if (!scoped.ok) return askBecause(scoped.reason);
+	const config = readYaml(join(root, DATA_DIR, "config.yaml"), configSchema).data;
+	const place = scopedCwd(payload.cwd, root, config.repos);
+	if (!place.ok) return askBecause(place.reason);
+	const resolved = resolveFixed(scan.call, {
+		cwd: place.dir,
+		root,
+		repos: config.repos
+	});
+	if (!resolved.ok) return askBecause(resolved.reason);
+	const match = matchGrants(scoped.scope, [resolved.request]);
+	if (!match.ok) return askBecause(match.reason);
+	const { grant } = match.matches[0];
+	logGranted(root, scoped.scope, scan.call, resolved.request, grant, warn);
+	return permission("allow", `主脈絡授權 ${grant.ref} 涵蓋 ${describeRequest(resolved.request)}`);
+}
 /** How many problems outside the written file the reminder lists before it only gives the count. */
 const OTHER_PROBLEMS_SHOWN = 5;
 const problemLine = (p) => `- ${p.file}${p.field ? ` › ${p.field}` : ""}：${p.message}`;
@@ -222,9 +347,29 @@ function checkAfterWrite(root, { payload, cli }) {
 	} });
 }
 const HOOK_PLATFORMS = { "claude-code": CLAUDE_CODE_EVENTS };
+const HOOK_FALLBACKS = { "claude-code": CLAUDE_CODE_FALLBACKS };
+/**
+* Events that find the hub from $CLAUDE_PROJECT_DIR before the payload's cwd. A publish runs in the package's own
+* repository, which config.yaml may list outside the hub directory (../mainflow), so its cwd leads to no hub.
+*/
+const PROJECT_HUB_EVENTS = /* @__PURE__ */ new Set(["pre-tool-use"]);
+function hubRootFor(event, ctx) {
+	return (PROJECT_HUB_EVENTS.has(event) && ctx.projectDir && isAbsolute(ctx.projectDir) ? findHubRoot(ctx.projectDir) : null) ?? findHubRoot(typeof ctx.payload.cwd === "string" ? ctx.payload.cwd : process.cwd());
+}
+/** What an event prints when it cannot run its handler; null for the events that stay silent. */
+function hookFallback(platform, event, ctx, failure) {
+	const fallback = HOOK_FALLBACKS[platform]?.[event];
+	if (!fallback) return null;
+	try {
+		return fallback(ctx, failure);
+	} catch {
+		return null;
+	}
+}
 /**
 * Run a hook handler. A hook must never break the host session, so outside a hub it stays silent and any
-* failure is reported on stderr while the caller still exits 0.
+* failure is reported on stderr while the caller still exits 0. Events listed in the fallbacks print their
+* fallback instead of staying silent.
 */
 function runHook(platform, event, ctx) {
 	const handler = HOOK_PLATFORMS[platform]?.[event];
@@ -232,22 +377,31 @@ function runHook(platform, event, ctx) {
 		stdout: null,
 		error: `unknown hook ${platform} ${event}; known: ${Object.entries(HOOK_PLATFORMS).flatMap(([p, e]) => Object.keys(e).map((k) => `${p} ${k}`)).join(", ")}`
 	};
-	const root = findHubRoot(ctx.payload.cwd ?? process.cwd());
-	if (!root) return {
-		stdout: null,
-		error: null
-	};
+	const warnings = [];
+	const errorText = (message) => [...warnings, ...message ? [message] : []].join("\n") || null;
 	try {
-		return {
-			stdout: handler(root, ctx),
+		const root = hubRootFor(event, ctx);
+		if (!root) return {
+			stdout: hookFallback(platform, event, ctx, { kind: "outside-hub" }),
 			error: null
 		};
+		return {
+			stdout: handler(root, {
+				...ctx,
+				warn: (message) => warnings.push(message)
+			}),
+			error: errorText()
+		};
 	} catch (error) {
+		const message = error.message;
 		return {
-			stdout: null,
-			error: `mainflow hook ${platform} ${event}: ${error.message}`
+			stdout: hookFallback(platform, event, ctx, {
+				kind: "error",
+				message
+			}),
+			error: errorText(`mainflow hook ${platform} ${event}: ${message}`)
 		};
 	}
 }
 //#endregion
-export { HOOK_PLATFORMS, claudeCodeSessionId, openLink, runHook, subagentTranscript };
+export { HOOK_PLATFORMS, claudeCodeSessionId, hookFallback, openLink, parsePayload, runHook, subagentTranscript };