agentplane 0.1.6 → 0.1.7

package/dist/commands/guard/index.js

@@ -0,0 +1,367 @@
+import { extractTaskSuffix, getStagedFiles, getUnstagedFiles, loadConfig, resolveProject, validateCommitSubject, } from "@agentplaneorg/core";
+import { mapCoreError } from "../../cli/error-map.js";
+import { invalidValueMessage, successMessage } from "../../cli/output.js";
+import { CliError } from "../../shared/errors.js";
+import { formatCommentBodyForCommit } from "../../shared/comment-format.js";
+import { execFileAsync } from "../shared/git.js";
+function pathIsUnder(candidate, prefix) {
+    if (prefix === "." || prefix === "")
+        return true;
+    if (candidate === prefix)
+        return true;
+    return candidate.startsWith(`${prefix}/`);
+}
+function normalizeAllowPrefix(prefix) {
+    return prefix.replace(/\/+$/, "");
+}
+export function suggestAllowPrefixes(paths) {
+    const out = new Set();
+    for (const filePath of paths) {
+        if (!filePath)
+            continue;
+        const idx = filePath.lastIndexOf("/");
+        if (idx <= 0)
+            out.add(filePath);
+        else
+            out.add(filePath.slice(0, idx));
+    }
+    return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+export const GUARD_COMMIT_USAGE = "Usage: agentplane guard commit <task-id> -m <message> --allow <path> [--allow <path>...] [--auto-allow] [--allow-tasks] [--require-clean] [--quiet]";
+export const GUARD_COMMIT_USAGE_EXAMPLE = 'agentplane guard commit 202602030608-F1Q8AB -m "✨ F1Q8AB update" --allow packages/agentplane';
+export const COMMIT_USAGE = "Usage: agentplane commit <task-id> -m <message>";
+export const COMMIT_USAGE_EXAMPLE = 'agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB update"';
+async function guardCommitCheck(opts) {
+    const resolved = await resolveProject({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+    });
+    const loaded = await loadConfig(resolved.agentplaneDir);
+    const policy = validateCommitSubject({
+        subject: opts.message,
+        taskId: opts.taskId,
+        genericTokens: loaded.config.commit.generic_tokens,
+    });
+    if (!policy.ok) {
+        throw new CliError({ exitCode: 5, code: "E_GIT", message: policy.errors.join("\n") });
+    }
+    const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    if (staged.length === 0) {
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: "No staged files (git index empty)",
+        });
+    }
+    if (opts.allow.length === 0) {
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: "Provide at least one --allow <path> prefix",
+        });
+    }
+    const allow = opts.allow.map((prefix) => normalizeAllowPrefix(prefix));
+    const denied = new Set();
+    if (!opts.allowTasks)
+        denied.add(".agentplane/tasks.json");
+    if (opts.requireClean) {
+        const unstaged = await getUnstagedFiles({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        if (unstaged.length > 0) {
+            throw new CliError({ exitCode: 5, code: "E_GIT", message: "Working tree is dirty" });
+        }
+    }
+    for (const filePath of staged) {
+        if (denied.has(filePath)) {
+            throw new CliError({
+                exitCode: 5,
+                code: "E_GIT",
+                message: `Staged file is forbidden by default: ${filePath} (use --allow-tasks to override)`,
+            });
+        }
+        if (!allow.some((prefix) => pathIsUnder(filePath, prefix))) {
+            throw new CliError({
+                exitCode: 5,
+                code: "E_GIT",
+                message: `Staged file is outside allowlist: ${filePath}`,
+            });
+        }
+    }
+}
+export async function gitStatusChangedPaths(opts) {
+    const resolved = await resolveProject({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+    });
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-uall"], {
+        cwd: resolved.gitRoot,
+    });
+    const files = [];
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const filePart = trimmed.slice(2).trim();
+        if (!filePart)
+            continue;
+        const name = filePart.includes("->") ? filePart.split("->").at(-1)?.trim() : filePart;
+        if (name)
+            files.push(name);
+    }
+    return files;
+}
+export async function ensureGitClean(opts) {
+    const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    if (staged.length > 0) {
+        throw new CliError({ exitCode: 5, code: "E_GIT", message: "Working tree has staged changes" });
+    }
+    const unstaged = await getUnstagedFiles({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+    });
+    if (unstaged.length > 0) {
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: "Working tree has unstaged changes",
+        });
+    }
+}
+async function stageAllowlist(opts) {
+    const resolved = await resolveProject({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+    });
+    const changed = await gitStatusChangedPaths({ cwd: opts.cwd, rootOverride: opts.rootOverride });
+    if (changed.length === 0) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "No changes to stage (working tree clean)",
+        });
+    }
+    const allow = opts.allow.map((prefix) => normalizeAllowPrefix(prefix.trim().replace(/^\.?\//, "")));
+    const denied = new Set();
+    if (!opts.allowTasks)
+        denied.add(".agentplane/tasks.json");
+    const staged = [];
+    for (const filePath of changed) {
+        if (denied.has(filePath))
+            continue;
+        if (allow.some((prefix) => pathIsUnder(filePath, prefix))) {
+            staged.push(filePath);
+        }
+    }
+    const unique = [...new Set(staged)].toSorted((a, b) => a.localeCompare(b));
+    if (unique.length === 0) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "No changes matched allowed prefixes (use --commit-auto-allow or update --commit-allow)",
+        });
+    }
+    await execFileAsync("git", ["add", "--", ...unique], { cwd: resolved.gitRoot });
+    return unique;
+}
+function deriveCommitMessageFromComment(opts) {
+    const summary = (opts.formattedComment ?? formatCommentBodyForCommit(opts.body, opts.config))
+        .trim()
+        .replaceAll(/\s+/g, " ");
+    if (!summary) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Comment body is required to build a commit message from the task comment",
+        });
+    }
+    const prefix = opts.emoji.trim();
+    if (!prefix) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Emoji prefix is required when deriving commit messages from task comments",
+        });
+    }
+    const suffix = extractTaskSuffix(opts.taskId);
+    if (!suffix) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: invalidValueMessage("task id", opts.taskId, "valid task id"),
+        });
+    }
+    return `${prefix} ${suffix} ${summary}`;
+}
+export async function commitFromComment(opts) {
+    let allowPrefixes = opts.allow.map((prefix) => prefix.trim()).filter(Boolean);
+    if (opts.autoAllow && allowPrefixes.length === 0) {
+        const changed = await gitStatusChangedPaths({ cwd: opts.cwd, rootOverride: opts.rootOverride });
+        allowPrefixes = suggestAllowPrefixes(changed);
+    }
+    if (allowPrefixes.length === 0) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Provide at least one --commit-allow prefix or enable --commit-auto-allow",
+        });
+    }
+    const staged = await stageAllowlist({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        allow: allowPrefixes,
+        allowTasks: opts.allowTasks,
+    });
+    const message = deriveCommitMessageFromComment({
+        taskId: opts.taskId,
+        body: opts.commentBody,
+        emoji: opts.emoji,
+        formattedComment: opts.formattedComment,
+        config: opts.config,
+    });
+    await guardCommitCheck({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        taskId: opts.taskId,
+        message,
+        allow: allowPrefixes,
+        allowTasks: opts.allowTasks,
+        requireClean: opts.requireClean,
+        quiet: opts.quiet,
+    });
+    const resolved = await resolveProject({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+    });
+    const env = {
+        ...process.env,
+        AGENTPLANE_TASK_ID: opts.taskId,
+        AGENTPLANE_ALLOW_TASKS: opts.allowTasks ? "1" : "0",
+        AGENTPLANE_ALLOW_BASE: opts.allowTasks ? "1" : "0",
+    };
+    await execFileAsync("git", ["commit", "-m", message], { cwd: resolved.gitRoot, env });
+    const { stdout } = await execFileAsync("git", ["log", "-1", "--pretty=%H:%s"], {
+        cwd: resolved.gitRoot,
+    });
+    const trimmed = stdout.trim();
+    const [hash, subject] = trimmed.split(":", 2);
+    if (!opts.quiet) {
+        process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim(), `staged=${staged.join(", ")}`)}\n`);
+    }
+    return { hash: hash ?? "", message: subject ?? "", staged };
+}
+export async function cmdGuardClean(opts) {
+    try {
+        const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+        if (staged.length > 0) {
+            throw new CliError({
+                exitCode: 5,
+                code: "E_GIT",
+                message: "Staged files exist",
+            });
+        }
+        if (!opts.quiet) {
+            process.stdout.write(`${successMessage("index clean", undefined, "no staged files")}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "guard clean", root: opts.rootOverride ?? null });
+    }
+}
+export async function cmdGuardSuggestAllow(opts) {
+    try {
+        const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+        if (staged.length === 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "No staged files (git index empty)",
+            });
+        }
+        const prefixes = suggestAllowPrefixes(staged);
+        if (opts.format === "args") {
+            const args = prefixes.map((p) => `--allow ${p}`).join(" ");
+            process.stdout.write(`${args}\n`);
+        }
+        else {
+            for (const prefix of prefixes)
+                process.stdout.write(`${prefix}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        throw mapCoreError(err, { command: "guard suggest-allow", root: opts.rootOverride ?? null });
+    }
+}
+export async function cmdGuardCommit(opts) {
+    try {
+        await guardCommitCheck(opts);
+        if (!opts.quiet)
+            process.stdout.write("OK\n");
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "guard commit", root: opts.rootOverride ?? null });
+    }
+}
+export async function cmdCommit(opts) {
+    try {
+        let allow = opts.allow;
+        if (opts.autoAllow && allow.length === 0) {
+            const staged = await getStagedFiles({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const prefixes = suggestAllowPrefixes(staged);
+            if (prefixes.length === 0) {
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: "No staged files (git index empty)",
+                });
+            }
+            allow = prefixes;
+        }
+        await guardCommitCheck({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            message: opts.message,
+            allow,
+            allowTasks: opts.allowTasks,
+            requireClean: opts.requireClean,
+            quiet: opts.quiet,
+        });
+        const resolved = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const env = {
+            ...process.env,
+            AGENTPLANE_TASK_ID: opts.taskId,
+            AGENTPLANE_ALLOW_TASKS: opts.allowTasks ? "1" : "0",
+            AGENTPLANE_ALLOW_BASE: opts.allowBase ? "1" : "0",
+        };
+        await execFileAsync("git", ["commit", "-m", opts.message], { cwd: resolved.gitRoot, env });
+        if (!opts.quiet) {
+            const { stdout } = await execFileAsync("git", ["log", "-1", "--pretty=%H:%s"], {
+                cwd: resolved.gitRoot,
+            });
+            const trimmed = stdout.trim();
+            const [hash, subject] = trimmed.split(":", 2);
+            process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim())}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "commit", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/hooks/index.d.ts

@@ -0,0 +1,18 @@
+export declare const HOOK_NAMES: readonly ["commit-msg", "pre-commit", "pre-push"];
+export declare function cmdHooksInstall(opts: {
+    cwd: string;
+    rootOverride?: string;
+    quiet: boolean;
+}): Promise<number>;
+export declare function cmdHooksUninstall(opts: {
+    cwd: string;
+    rootOverride?: string;
+    quiet: boolean;
+}): Promise<number>;
+export declare function cmdHooksRun(opts: {
+    cwd: string;
+    rootOverride?: string;
+    hook: (typeof HOOK_NAMES)[number];
+    args: string[];
+}): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/index.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,UAAU,mDAAoD,CAAC;AAqG5E,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmClB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2HlB"}

package/dist/commands/hooks/index.js

@@ -0,0 +1,290 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getStagedFiles, loadConfig, resolveBaseBranch, resolveProject } from "@agentplaneorg/core";
+import { loadTaskBackend } from "../../backends/task-backend.js";
+import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
+import { fileExists } from "../../cli/fs-utils.js";
+import { infoMessage, successMessage } from "../../cli/output.js";
+import { CliError } from "../../shared/errors.js";
+import { gitCurrentBranch, gitRevParse } from "../shared/git-ops.js";
+import { isPathWithin } from "../shared/path.js";
+const HOOK_MARKER = "agentplane-hook";
+const SHIM_MARKER = "agentplane-hook-shim";
+export const HOOK_NAMES = ["commit-msg", "pre-commit", "pre-push"];
+async function resolveGitHooksDir(cwd) {
+    const repoRoot = await gitRevParse(cwd, ["--show-toplevel"]);
+    const commonDirRaw = await gitRevParse(cwd, ["--git-common-dir"]);
+    const hooksRaw = await gitRevParse(cwd, ["--git-path", "hooks"]);
+    const commonDir = path.resolve(path.isAbsolute(commonDirRaw) ? commonDirRaw : path.join(repoRoot, commonDirRaw));
+    const hooksDir = path.resolve(path.isAbsolute(hooksRaw) ? hooksRaw : path.join(repoRoot, hooksRaw));
+    const resolvedRoot = path.resolve(repoRoot);
+    if (!isPathWithin(resolvedRoot, hooksDir) && !isPathWithin(commonDir, hooksDir)) {
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: [
+                "Refusing to manage git hooks outside the repository.",
+                `hooks_path=${hooksDir}`,
+                `repo_root=${resolvedRoot}`,
+                `common_dir=${commonDir}`,
+                "Fix:",
+                "  1) Use a repo-relative core.hooksPath (e.g., .git/hooks)",
+                "  2) Re-run `agentplane hooks install`",
+            ].join("\n"),
+        });
+    }
+    return hooksDir;
+}
+async function fileIsManaged(filePath, marker) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return content.includes(marker);
+    }
+    catch {
+        return false;
+    }
+}
+function hookScriptText(hook) {
+    return [
+        "#!/usr/bin/env sh",
+        `# ${HOOK_MARKER} (do not edit)`,
+        "set -e",
+        "if ! command -v agentplane >/dev/null 2>&1; then",
+        '  echo "agentplane hooks: agentplane not found in PATH" >&2',
+        "  exit 1",
+        "fi",
+        "exec agentplane hooks run " + hook + ' "$@"',
+        "",
+    ].join("\n");
+}
+function shimScriptText() {
+    return [
+        "#!/usr/bin/env sh",
+        `# ${SHIM_MARKER} (do not edit)`,
+        "set -e",
+        "if ! command -v agentplane >/dev/null 2>&1; then",
+        '  echo "agentplane shim: agentplane not found in PATH" >&2',
+        "  exit 1",
+        "fi",
+        'exec agentplane "$@"',
+        "",
+    ].join("\n");
+}
+async function ensureShim(agentplaneDir, gitRoot) {
+    const shimDir = path.join(agentplaneDir, "bin");
+    const shimPath = path.join(shimDir, "agentplane");
+    await mkdir(shimDir, { recursive: true });
+    if (await fileExists(shimPath)) {
+        const managed = await fileIsManaged(shimPath, SHIM_MARKER);
+        if (!managed) {
+            throw new CliError({
+                exitCode: 5,
+                code: "E_GIT",
+                message: `Refusing to overwrite existing shim: ${path.relative(gitRoot, shimPath)}`,
+            });
+        }
+    }
+    await writeFile(shimPath, shimScriptText(), "utf8");
+    await chmod(shimPath, 0o755);
+}
+function readCommitSubject(message) {
+    for (const line of message.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        return trimmed;
+    }
+    return "";
+}
+function subjectHasSuffix(subject, suffixes) {
+    const lowered = subject.toLowerCase();
+    return suffixes.some((suffix) => suffix && lowered.includes(suffix.toLowerCase()));
+}
+export async function cmdHooksInstall(opts) {
+    try {
+        const resolved = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const hooksDir = await resolveGitHooksDir(resolved.gitRoot);
+        await mkdir(hooksDir, { recursive: true });
+        await mkdir(resolved.agentplaneDir, { recursive: true });
+        await ensureShim(resolved.agentplaneDir, resolved.gitRoot);
+        for (const hook of HOOK_NAMES) {
+            const hookPath = path.join(hooksDir, hook);
+            if (await fileExists(hookPath)) {
+                const managed = await fileIsManaged(hookPath, HOOK_MARKER);
+                if (!managed) {
+                    throw new CliError({
+                        exitCode: 5,
+                        code: "E_GIT",
+                        message: `Refusing to overwrite existing hook: ${path.relative(resolved.gitRoot, hookPath)}`,
+                    });
+                }
+            }
+            await writeFile(hookPath, hookScriptText(hook), "utf8");
+            await chmod(hookPath, 0o755);
+        }
+        if (!opts.quiet) {
+            process.stdout.write(`${path.relative(resolved.gitRoot, hooksDir)}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "hooks install", root: opts.rootOverride ?? null });
+    }
+}
+export async function cmdHooksUninstall(opts) {
+    try {
+        const resolved = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const hooksDir = await resolveGitHooksDir(resolved.gitRoot);
+        let removed = 0;
+        for (const hook of HOOK_NAMES) {
+            const hookPath = path.join(hooksDir, hook);
+            if (!(await fileExists(hookPath)))
+                continue;
+            const managed = await fileIsManaged(hookPath, HOOK_MARKER);
+            if (!managed)
+                continue;
+            await rm(hookPath, { force: true });
+            removed++;
+        }
+        if (!opts.quiet) {
+            process.stdout.write(removed > 0
+                ? `${successMessage("removed hooks", undefined, `count=${removed}`)}\n`
+                : `${infoMessage("no agentplane hooks found")}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "hooks uninstall", root: opts.rootOverride ?? null });
+    }
+}
+export async function cmdHooksRun(opts) {
+    try {
+        if (opts.hook === "commit-msg") {
+            const messagePath = opts.args[0];
+            if (!messagePath) {
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: "Missing commit message file path",
+                });
+            }
+            const raw = await readFile(messagePath, "utf8");
+            const subject = readCommitSubject(raw);
+            if (!subject) {
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: "Commit message subject is empty",
+                });
+            }
+            const taskId = (process.env.AGENTPLANE_TASK_ID ?? "").trim();
+            if (taskId) {
+                const suffix = taskId.split("-").at(-1) ?? "";
+                if (!subject.includes(taskId) && (suffix.length === 0 || !subject.includes(suffix))) {
+                    throw new CliError({
+                        exitCode: 5,
+                        code: "E_GIT",
+                        message: "Commit subject must include task id or suffix",
+                    });
+                }
+                return 0;
+            }
+            const { backend } = await loadTaskBackend({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const tasks = await backend.listTasks();
+            const suffixes = tasks.map((task) => task.id.split("-").at(-1) ?? "").filter(Boolean);
+            if (suffixes.length === 0) {
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: "No task IDs available to validate commit subject",
+                });
+            }
+            if (!subjectHasSuffix(subject, suffixes)) {
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: "Commit subject must mention a task suffix",
+                });
+            }
+            return 0;
+        }
+        if (opts.hook === "pre-commit") {
+            const staged = await getStagedFiles({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            if (staged.length === 0)
+                return 0;
+            const allowTasks = (process.env.AGENTPLANE_ALLOW_TASKS ?? "").trim() === "1";
+            const allowBase = (process.env.AGENTPLANE_ALLOW_BASE ?? "").trim() === "1";
+            const resolved = await resolveProject({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const loaded = await loadConfig(resolved.agentplaneDir);
+            const tasksPath = loaded.config.paths.tasks_path;
+            const tasksStaged = staged.includes(tasksPath);
+            const nonTasks = staged.filter((entry) => entry !== tasksPath);
+            if (tasksStaged && !allowTasks) {
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: `${tasksPath} is protected by agentplane hooks (set AGENTPLANE_ALLOW_TASKS=1 to override)`,
+                });
+            }
+            if (loaded.config.workflow_mode === "branch_pr") {
+                const baseBranch = await resolveBaseBranch({
+                    cwd: opts.cwd,
+                    rootOverride: opts.rootOverride ?? null,
+                    cliBaseOpt: null,
+                    mode: loaded.config.workflow_mode,
+                });
+                if (!baseBranch) {
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: "Base branch could not be resolved (use `agentplane branch base set`).",
+                    });
+                }
+                const currentBranch = await gitCurrentBranch(resolved.gitRoot);
+                if (tasksStaged && currentBranch !== baseBranch) {
+                    throw new CliError({
+                        exitCode: 5,
+                        code: "E_GIT",
+                        message: `${tasksPath} commits are allowed only on ${baseBranch} in branch_pr mode`,
+                    });
+                }
+                if (nonTasks.length > 0 && currentBranch === baseBranch && !allowBase) {
+                    throw new CliError({
+                        exitCode: 5,
+                        code: "E_GIT",
+                        message: `Code commits are forbidden on ${baseBranch} in branch_pr mode`,
+                    });
+                }
+            }
+            return 0;
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, {
+            command: `hooks run ${opts.hook}`,
+            root: opts.rootOverride ?? null,
+        });
+    }
+}