agentplane 0.3.21 → 0.3.22

package/dist/commands/branch/work-start.hook-shim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-start.hook-shim.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.hook-shim.ts"],"names":[],"mappings":"AAkCA,wBAAsB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF"}
+{"version":3,"file":"work-start.hook-shim.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.hook-shim.ts"],"names":[],"mappings":"AAgDA,wBAAsB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF"}

package/dist/commands/branch/work-start.hook-shim.js

@@ -1,8 +1,16 @@
 import { chmod, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileExists } from "../../cli/fs-utils.js";
+import { resolveAgentplaneBinPath } from "../../shared/package-paths.js";
 const HOOK_SHIM_MARKER = "agentplane-hook-shim";
-function repoLocalHookShimText() {
+function shellSingleQuote(value) {
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+function resolveInstalledHookRunnerPath() {
+    const activeBin = String(process.env.AGENTPLANE_RUNTIME_ACTIVE_BIN ?? "").trim();
+    return activeBin || resolveAgentplaneBinPath();
+}
+function repoLocalHookShimText(installedRunnerPath) {
     return [
         "#!/usr/bin/env sh",
         `# ${HOOK_SHIM_MARKER} (do not edit)`,
@@ -13,6 +21,10 @@ function repoLocalHookShimText() {
         'if command -v node >/dev/null 2>&1 && [ -f "$LOCAL_BIN" ]; then',
         '  exec node "$LOCAL_BIN" "$@"',
         "fi",
+        `INSTALL_BIN=${shellSingleQuote(installedRunnerPath)}`,
+        'if command -v node >/dev/null 2>&1 && [ -f "$INSTALL_BIN" ]; then',
+        '  exec node "$INSTALL_BIN" "$@"',
+        "fi",
         'ENV_BIN="${AGENTPLANE_HOOK_RUNNER:-}"',
         'if [ -n "$ENV_BIN" ] && command -v node >/dev/null 2>&1 && [ -f "$ENV_BIN" ]; then',
         '  exec node "$ENV_BIN" "$@"',
@@ -20,10 +32,10 @@ function repoLocalHookShimText() {
         "if command -v agentplane >/dev/null 2>&1; then",
         '  exec agentplane "$@"',
         "fi",
-        "if command -v npx >/dev/null 2>&1; then",
+        'if [ "${AGENTPLANE_HOOK_ALLOW_NPX:-}" = "1" ] && command -v npx >/dev/null 2>&1; then',
         '  exec npx --yes agentplane "$@"',
         "fi",
-        'echo "agentplane shim: runner not found (need env runner, repo-local source, agentplane in PATH, or node+npx)." >&2',
+        'echo "agentplane shim: runner not found (need installed runner, env runner, repo-local source, agentplane in PATH, or AGENTPLANE_HOOK_ALLOW_NPX=1)." >&2',
         "  exit 127",
         "",
     ].join("\n");
@@ -33,6 +45,6 @@ export async function materializeHookShimForWorktree(worktreePath) {
     if (await fileExists(shimPath))
         return;
     await mkdir(path.dirname(shimPath), { recursive: true });
-    await writeFile(shimPath, repoLocalHookShimText(), "utf8");
+    await writeFile(shimPath, repoLocalHookShimText(resolveInstalledHookRunnerPath()), "utf8");
     await chmod(shimPath, 0o755);
 }

package/dist/commands/doctor/hook-readiness.d.ts

@@ -0,0 +1,2 @@
+export declare function checkManagedHookShimReadiness(repoRoot: string): Promise<string[]>;
+//# sourceMappingURL=hook-readiness.d.ts.map

package/dist/commands/doctor/hook-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-readiness.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/hook-readiness.ts"],"names":[],"mappings":"AA4EA,wBAAsB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyIvF"}

package/dist/commands/doctor/hook-readiness.js

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { renderDiagnosticFinding } from "../shared/diagnostics.js";
+import { fileIsManaged, HOOK_MARKER, HOOK_NAMES, resolveGitHooksDir, SHIM_MARKER, } from "../hooks/shared.js";
+async function pathExists(absPath) {
+    try {
+        await fs.access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readTextIfExists(absPath) {
+    try {
+        return await fs.readFile(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function unquoteShellSingleQuoted(value) {
+    return value.replaceAll(String.raw `'\''`, "'");
+}
+function extractInstallBinFromShim(shimText) {
+    const match = /\nINSTALL_BIN='((?:'\\''|[^'])*)'/.exec(shimText);
+    if (!match)
+        return null;
+    return unquoteShellSingleQuoted(match[1] ?? "").trim() || null;
+}
+async function resolveManagedHookNames(repoRoot) {
+    let hooksDir;
+    try {
+        hooksDir = await resolveGitHooksDir(repoRoot);
+    }
+    catch {
+        return { hooksDir: null, managedHooks: [], unmanagedHooks: [] };
+    }
+    const managedHooks = [];
+    const unmanagedHooks = [];
+    for (const hook of HOOK_NAMES) {
+        const hookPath = path.join(hooksDir, hook);
+        if (!(await pathExists(hookPath)))
+            continue;
+        if (await fileIsManaged(hookPath, HOOK_MARKER))
+            managedHooks.push(hook);
+        else
+            unmanagedHooks.push(hook);
+    }
+    return { hooksDir, managedHooks, unmanagedHooks };
+}
+function renderUnmanagedHooksFinding(unmanagedHooks) {
+    return renderDiagnosticFinding({
+        severity: "INFO",
+        state: "unmanaged git hooks are present and will not be overwritten by AgentPlane",
+        likelyCause: "the repository has custom hook files outside the AgentPlane managed hook set",
+        nextAction: {
+            command: "agentplane hooks install",
+            reason: "refresh managed hooks only after manually reconciling custom hook files that should remain custom",
+        },
+        details: [`Unmanaged hooks: ${unmanagedHooks.join(", ")}`],
+    });
+}
+export async function checkManagedHookShimReadiness(repoRoot) {
+    const findings = [];
+    const { managedHooks, unmanagedHooks } = await resolveManagedHookNames(repoRoot);
+    const shimRelPath = ".agentplane/bin/agentplane";
+    const shimPath = path.join(repoRoot, shimRelPath);
+    const shimText = await readTextIfExists(shimPath);
+    const managedShim = shimText?.includes(SHIM_MARKER) === true;
+    if (managedHooks.length === 0 && unmanagedHooks.length === 0 && !shimText)
+        return findings;
+    if (managedHooks.length > 0 && !shimText) {
+        findings.push(renderDiagnosticFinding({
+            severity: "WARN",
+            state: "managed git hooks are installed but the AgentPlane hook shim is missing",
+            likelyCause: "the repository hook files still call .agentplane/bin/agentplane, but that shim was deleted or never committed",
+            nextAction: {
+                command: "agentplane hooks install",
+                reason: "recreate the managed hook shim and refresh hook files",
+            },
+            details: [`Managed hooks: ${managedHooks.join(", ")}`],
+        }));
+        return findings;
+    }
+    if (shimText && !managedShim) {
+        findings.push(renderDiagnosticFinding({
+            severity: "WARN",
+            state: "AgentPlane hook shim path exists but is not managed by AgentPlane",
+            likelyCause: "a custom .agentplane/bin/agentplane file is shadowing the managed hook runner shim",
+            nextAction: {
+                command: "inspect .agentplane/bin/agentplane, remove the custom file if unintended, then run agentplane hooks install",
+                reason: "restore the managed shim without overwriting custom executable content silently",
+            },
+            details: [`Shim path: ${shimRelPath}`],
+        }));
+        return findings;
+    }
+    if (!shimText) {
+        if (unmanagedHooks.length > 0) {
+            findings.push(renderUnmanagedHooksFinding(unmanagedHooks));
+        }
+        return findings;
+    }
+    const installedBin = extractInstallBinFromShim(shimText);
+    if (!installedBin) {
+        findings.push(renderDiagnosticFinding({
+            severity: "WARN",
+            state: "managed AgentPlane hook shim uses a stale format without an installed runner fallback",
+            likelyCause: "the shim was generated by an older AgentPlane release before installed-binary fallback was embedded",
+            nextAction: {
+                command: "agentplane hooks install",
+                reason: "rewrite the managed shim with the current installed-runtime fallback contract",
+            },
+            details: [`Shim path: ${shimRelPath}`],
+        }));
+    }
+    else if (!(await pathExists(installedBin))) {
+        findings.push(renderDiagnosticFinding({
+            severity: "WARN",
+            state: "managed AgentPlane hook shim points to a missing installed runner",
+            likelyCause: "AgentPlane was reinstalled, removed, or moved after hooks were installed in this repository",
+            nextAction: {
+                command: "agentplane hooks install",
+                reason: "refresh the embedded installed runner path after reinstalling or updating AgentPlane",
+            },
+            details: [`Embedded runner: ${installedBin}`, `Shim path: ${shimRelPath}`],
+        }));
+    }
+    const hasEnvFallback = shimText.includes("AGENTPLANE_HOOK_RUNNER");
+    const hasNpxFallback = shimText.includes("AGENTPLANE_HOOK_ALLOW_NPX");
+    if (!hasEnvFallback || !hasNpxFallback) {
+        findings.push(renderDiagnosticFinding({
+            severity: "WARN",
+            state: "managed AgentPlane hook shim is missing current fallback branches",
+            likelyCause: "the repository still has an older managed shim that cannot use env-runner or explicit npx fallback recovery",
+            nextAction: {
+                command: "agentplane hooks install",
+                reason: "rewrite the shim with the current fallback chain",
+            },
+            details: [
+                `Shim path: ${shimRelPath}`,
+                `AGENTPLANE_HOOK_RUNNER fallback: ${hasEnvFallback ? "present" : "missing"}`,
+                `AGENTPLANE_HOOK_ALLOW_NPX fallback: ${hasNpxFallback ? "present" : "missing"}`,
+            ],
+        }));
+    }
+    if (managedHooks.includes("pre-push")) {
+        const repoPrePushScript = path.join(repoRoot, "scripts", "run-pre-push-hook.mjs");
+        const packageJsonText = await readTextIfExists(path.join(repoRoot, "package.json"));
+        if (!(await pathExists(repoPrePushScript)) && packageJsonText) {
+            findings.push(renderDiagnosticFinding({
+                severity: "INFO",
+                state: "managed pre-push hook will use installed clean-project fallback checks",
+                likelyCause: "this project does not ship a repository-local scripts/run-pre-push-hook.mjs",
+                nextAction: {
+                    command: "add project-local package scripts such as format:check or test, or keep the installed fallback",
+                    reason: "make pre-push behavior explicit when the project needs stricter repository-specific checks",
+                },
+                details: [
+                    "Missing repository script: scripts/run-pre-push-hook.mjs",
+                    "Installed fallback skips package scripts that are not declared by the clean project.",
+                ],
+            }));
+        }
+    }
+    if (unmanagedHooks.length > 0) {
+        findings.push(renderUnmanagedHooksFinding(unmanagedHooks));
+    }
+    return findings;
+}

package/dist/commands/doctor/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/workspace.ts"],"names":[],"mappings":"AAYA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,KAAK,eAAe,GAAG;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAqFF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAyDnF;AAED,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB;AAoMD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC,CA2DnB"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/workspace.ts"],"names":[],"mappings":"AAYA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIpF,KAAK,eAAe,GAAG;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAqFF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAyDnF;AAED,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB;AAoMD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC,CA4DnB"}

package/dist/commands/doctor/workspace.js

@@ -6,6 +6,7 @@ import { resolvePolicyGatewayForRepo } from "../../shared/policy-gateway.js";
 import { GitContext } from "@agentplaneorg/core/git";
 import { listTaskProjection } from "../shared/task-backend.js";
 import { resolveAgentplaneAssetPath } from "../../shared/package-paths.js";
+import { checkManagedHookShimReadiness } from "./hook-readiness.js";
 async function pathExists(absPath) {
     try {
         await fs.access(absPath);
@@ -365,6 +366,6 @@ export async function checkWorkspace(repoRoot, opts) {
     if (!hasJson) {
         problems.push("No agent profiles found in .agentplane/agents (*.json expected).");
     }
-    problems.push(...checkBackendReadiness(opts?.ctx), ...(await checkTaskReadmeMigrationState(repoRoot, opts?.ctx)), ...(await checkDoneTaskReadmeArchiveDrift(repoRoot, opts?.ctx)), ...(await checkTaskProjectionDrift(repoRoot, opts?.ctx)));
+    problems.push(...checkBackendReadiness(opts?.ctx), ...(await checkManagedHookShimReadiness(repoRoot)), ...(await checkTaskReadmeMigrationState(repoRoot, opts?.ctx)), ...(await checkDoneTaskReadmeArchiveDrift(repoRoot, opts?.ctx)), ...(await checkTaskProjectionDrift(repoRoot, opts?.ctx)));
     return problems;
 }

package/dist/commands/guard/impl/commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commit.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAiKtC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CA2HlB"}
+{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commit.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAwLtC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAwIlB"}

package/dist/commands/guard/impl/commit.js

@@ -137,6 +137,22 @@ function formatCommitRef(commit) {
         return "";
     return `${commit.hash?.slice(0, 12) ?? ""} ${commit.subject ?? ""}`.trim();
 }
+async function stageActiveTaskArtifactsFromAllowTasks(opts) {
+    if (!opts.allowTasks)
+        return [];
+    const changedPaths = await opts.ctx.git.statusChangedPaths();
+    const taskArtifactPaths = changedPaths.filter((relPath) => isTaskLocalAdvancePath({
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        tasksPath: opts.ctx.config.paths.tasks_path,
+        relPath,
+    }));
+    if (taskArtifactPaths.length === 0)
+        return [];
+    const unique = [...new Set(taskArtifactPaths)].toSorted((a, b) => a.localeCompare(b));
+    await opts.ctx.git.stage(unique);
+    return unique;
+}
 export async function cmdCommit(opts) {
     try {
         const ctx = opts.ctx ??
@@ -181,6 +197,16 @@ export async function cmdCommit(opts) {
                 process.stdout.write(`${infoMessage(`commit auto-staged ${autoStaged.length} path(s) from allowlist`)}\n`);
             }
         }
+        else {
+            autoStaged = await stageActiveTaskArtifactsFromAllowTasks({
+                ctx,
+                taskId: opts.taskId,
+                allowTasks: opts.allowTasks,
+            });
+            if (autoStaged.length > 0 && !opts.quiet) {
+                process.stdout.write(`${infoMessage(`commit auto-staged ${autoStaged.length} active task artifact path(s) from --allow-tasks`)}\n`);
+            }
+        }
         await guardCommitCheck({
             ctx,
             cwd: opts.cwd,

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

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/install.ts"],"names":[],"mappings":"AAkFA,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"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/install.ts"],"names":[],"mappings":"AAgGA,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"}

package/dist/commands/hooks/install.js

@@ -5,6 +5,7 @@ import { 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 { resolveAgentplaneBinPath } from "../../shared/package-paths.js";
 import { fileIsManaged, HOOK_MARKER, HOOK_NAMES, resolveGitHooksDir, SHIM_MARKER, } from "./shared.js";
 function hookScriptText(hook) {
     return [
@@ -24,7 +25,14 @@ function hookScriptText(hook) {
         "",
     ].join("\n");
 }
-function shimScriptText() {
+function shellSingleQuote(value) {
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+function resolveInstalledHookRunnerPath() {
+    const activeBin = String(process.env.AGENTPLANE_RUNTIME_ACTIVE_BIN ?? "").trim();
+    return activeBin || resolveAgentplaneBinPath();
+}
+function shimScriptText(installedRunnerPath) {
     return [
         "#!/usr/bin/env sh",
         `# ${SHIM_MARKER} (do not edit)`,
@@ -35,6 +43,10 @@ function shimScriptText() {
         'if command -v node >/dev/null 2>&1 && [ -f "$LOCAL_BIN" ]; then',
         '  exec node "$LOCAL_BIN" "$@"',
         "fi",
+        `INSTALL_BIN=${shellSingleQuote(installedRunnerPath)}`,
+        'if command -v node >/dev/null 2>&1 && [ -f "$INSTALL_BIN" ]; then',
+        '  exec node "$INSTALL_BIN" "$@"',
+        "fi",
         'ENV_BIN="${AGENTPLANE_HOOK_RUNNER:-}"',
         'if [ -n "$ENV_BIN" ] && command -v node >/dev/null 2>&1 && [ -f "$ENV_BIN" ]; then',
         '  exec node "$ENV_BIN" "$@"',
@@ -42,10 +54,10 @@ function shimScriptText() {
         "if command -v agentplane >/dev/null 2>&1; then",
         '  exec agentplane "$@"',
         "fi",
-        "if command -v npx >/dev/null 2>&1; then",
+        'if [ "${AGENTPLANE_HOOK_ALLOW_NPX:-}" = "1" ] && command -v npx >/dev/null 2>&1; then',
         '  exec npx --yes agentplane "$@"',
         "fi",
-        'echo "agentplane shim: runner not found (need env runner, repo-local source, agentplane in PATH, or node+npx)." >&2',
+        'echo "agentplane shim: runner not found (need installed runner, env runner, repo-local source, agentplane in PATH, or AGENTPLANE_HOOK_ALLOW_NPX=1)." >&2',
         "  exit 127",
         "",
     ].join("\n");
@@ -64,7 +76,7 @@ async function ensureShim(agentplaneDir, gitRoot) {
             });
         }
     }
-    await writeFile(shimPath, shimScriptText(), "utf8");
+    await writeFile(shimPath, shimScriptText(resolveInstalledHookRunnerPath()), "utf8");
     await chmod(shimPath, 0o755);
 }
 export async function cmdHooksInstall(opts) {

package/dist/commands/hooks/run.pre-push.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.pre-push.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/run.pre-push.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AA4CD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC3E"}
+{"version":3,"file":"run.pre-push.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/run.pre-push.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAyBhD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AA+TD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB3E"}

package/dist/commands/hooks/run.pre-push.js

@@ -1,12 +1,20 @@
 import { resolveProject } from "@agentplaneorg/core/project";
 import { runProcessSync } from "@agentplaneorg/core/process";
+import fs from "node:fs";
 import path from "node:path";
 import { fileExists } from "../../cli/fs-utils.js";
-import { CliError } from "../../shared/errors.js";
 import { resolveAgentplaneRepoScriptPath } from "../../shared/package-paths.js";
 function resolveBundledPrePushHookScriptPath() {
     return resolveAgentplaneRepoScriptPath("run-pre-push-hook.mjs");
 }
+class HookFailure extends Error {
+    details;
+    constructor(message, details = []) {
+        super(message);
+        this.details = details;
+        this.name = "HookFailure";
+    }
+}
 export async function resolvePrePushHookScriptPath(gitRoot, opts = {}) {
     const repoScriptPath = path.join(gitRoot, "scripts", "run-pre-push-hook.mjs");
     if (await fileExists(repoScriptPath))
@@ -16,6 +24,228 @@ export async function resolvePrePushHookScriptPath(gitRoot, opts = {}) {
         return bundledScriptPath;
     return null;
 }
+function parsePrePushStdin(rawStdin) {
+    return rawStdin
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [localRef = "", localSha = "", remoteRef = "", remoteSha = ""] = line.split(/\s+/);
+        return { localRef, localSha, remoteRef, remoteSha };
+    });
+}
+function isAllZeroSha(value) {
+    return /^[0]+$/.test(value);
+}
+function isBranchRef(ref) {
+    return ref.startsWith("refs/heads/");
+}
+function runHookCommand(gitRoot, command, args) {
+    const result = runProcessSync({
+        command,
+        args,
+        cwd: gitRoot,
+        env: process.env,
+        stdout: "inherit",
+        stderr: "inherit",
+        reject: false,
+    });
+    return result.exitCode ?? (result.signal ? 1 : 0);
+}
+function runHookCommandWithEnv(gitRoot, command, args, env) {
+    const result = runProcessSync({
+        command,
+        args,
+        cwd: gitRoot,
+        env,
+        stdout: "inherit",
+        stderr: "inherit",
+        reject: false,
+    });
+    return result.exitCode ?? (result.signal ? 1 : 0);
+}
+function readGitText(gitRoot, args) {
+    const result = runProcessSync({
+        command: "git",
+        args,
+        cwd: gitRoot,
+        encoding: "utf8",
+        reject: false,
+    });
+    if (result.exitCode !== 0)
+        return "";
+    return String(result.stdout ?? "").trim();
+}
+function readPackageScripts(gitRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(gitRoot, "package.json"), "utf8"));
+        if (!parsed.scripts || typeof parsed.scripts !== "object" || Array.isArray(parsed.scripts)) {
+            return {};
+        }
+        const scripts = {};
+        for (const [name, value] of Object.entries(parsed.scripts)) {
+            if (typeof value === "string")
+                scripts[name] = value;
+        }
+        return scripts;
+    }
+    catch {
+        return {};
+    }
+}
+function hasProjectScript(scripts, name) {
+    return Object.hasOwn(scripts, name);
+}
+function runOptionalProjectScript(gitRoot, scripts, name, opts = {}) {
+    if (!hasProjectScript(scripts, name)) {
+        process.stdout.write(`Skipping ${name}: package.json script is not defined.\n`);
+        return { exitCode: 0, skipped: true };
+    }
+    if (opts.heading)
+        process.stdout.write(opts.heading);
+    const exitCode = opts.env
+        ? runHookCommandWithEnv(gitRoot, "bun", ["run", name], opts.env)
+        : runHookCommand(gitRoot, "bun", ["run", name]);
+    return { exitCode, skipped: false };
+}
+function trackedChangesShort(gitRoot) {
+    return readGitText(gitRoot, ["status", "--short", "--untracked-files=no"]);
+}
+function fail(message, details = []) {
+    throw new HookFailure(message, details);
+}
+function failIfTrackedChanges(gitRoot, message) {
+    const changes = trackedChangesShort(gitRoot);
+    if (!changes)
+        return;
+    fail(message, [changes]);
+}
+function gitRefExists(gitRoot, ref) {
+    return readGitText(gitRoot, ["rev-parse", "--verify", "--quiet", ref]).length > 0;
+}
+function hasReleaseTagPush(updates) {
+    return updates.some((update) => update.remoteRef.startsWith("refs/tags/"));
+}
+function isDeleteOnlyPush(updates) {
+    return (updates.length > 0 &&
+        updates.every((update) => isBranchRef(update.remoteRef) && isAllZeroSha(update.localSha) && Boolean(update.remoteSha)));
+}
+function resolveDefaultBaseRef(gitRoot) {
+    const remoteHead = readGitText(gitRoot, [
+        "symbolic-ref",
+        "--quiet",
+        "--short",
+        "refs/remotes/origin/HEAD",
+    ]);
+    if (remoteHead)
+        return remoteHead;
+    if (gitRefExists(gitRoot, "origin/main"))
+        return "origin/main";
+    if (gitRefExists(gitRoot, "main"))
+        return "main";
+    return null;
+}
+function selectBranchDiffRange(updates, opts = {}) {
+    const branchUpdates = updates.filter((update) => isBranchRef(update.localRef) && isBranchRef(update.remoteRef));
+    if (branchUpdates.length !== 1)
+        return null;
+    const [update] = branchUpdates;
+    if (!update?.localSha || !update.remoteSha)
+        return null;
+    if (isAllZeroSha(update.localSha))
+        return null;
+    if (isAllZeroSha(update.remoteSha)) {
+        const fallbackRef = typeof opts.newBranchFallbackRef === "string" ? opts.newBranchFallbackRef.trim() : "";
+        return fallbackRef ? { from: fallbackRef, to: update.localSha } : null;
+    }
+    return { from: update.remoteSha, to: update.localSha };
+}
+function readChangedFilesForRange(gitRoot, range) {
+    if (!range)
+        return [];
+    const output = readGitText(gitRoot, ["diff", "--name-only", `${range.from}..${range.to}`]);
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function fileExistsSync(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isTruthyHookEnv(name) {
+    return (String(process.env[name] ?? "")
+        .trim()
+        .toLowerCase() === "1");
+}
+function runInternalPrePushHook(gitRoot, stdin) {
+    try {
+        const updates = parsePrePushStdin(stdin);
+        const envRelease = isTruthyHookEnv("AGENTPLANE_HOOKS_RELEASE");
+        const envFull = isTruthyHookEnv("AGENTPLANE_HOOKS_FULL");
+        const isReleasePush = envRelease || envFull || hasReleaseTagPush(updates);
+        if (!isReleasePush && isDeleteOnlyPush(updates)) {
+            process.stdout.write("Skipping pre-push checks for delete-only remote branch cleanup.\n");
+            return 0;
+        }
+        const mode = isReleasePush ? "release" : "standard";
+        process.stdout.write(`Running pre-push checks in ${mode} mode.\n`);
+        const ciScript = envFull ? "ci:local:full" : "ci:local:fast";
+        const scripts = readPackageScripts(gitRoot);
+        const changedFiles = readChangedFilesForRange(gitRoot, selectBranchDiffRange(updates, {
+            newBranchFallbackRef: resolveDefaultBaseRef(gitRoot),
+        }));
+        const ciEnv = changedFiles.length > 0
+            ? { ...process.env, AGENTPLANE_FAST_CHANGED_FILES: changedFiles.join("\n") }
+            : process.env;
+        const formatResult = runOptionalProjectScript(gitRoot, scripts, "format:check", {
+            heading: "\n== Format (check) ==\n",
+        });
+        if (formatResult.exitCode !== 0) {
+            failIfTrackedChanges(gitRoot, "pre-push blocked: format:check changed tracked files unexpectedly. Revert or commit those changes and push again.");
+            fail("pre-push blocked: formatting check failed. Run `bun run format`, review the diff, commit it, and push again.");
+        }
+        if (!formatResult.skipped) {
+            failIfTrackedChanges(gitRoot, "pre-push blocked: format:check changed tracked files unexpectedly. Revert or commit those changes and push again.");
+        }
+        const ciResult = runOptionalProjectScript(gitRoot, scripts, ciScript, { env: ciEnv });
+        if (!ciResult.skipped) {
+            failIfTrackedChanges(gitRoot, `pre-push blocked: ${ciScript} changed tracked files. Commit or revert those changes and push again.`);
+        }
+        if (ciResult.exitCode !== 0) {
+            fail(`pre-push blocked: ${ciScript} failed. Fix the reported checks and push again.`);
+        }
+        if (isReleasePush) {
+            const releaseNotesScript = path.join(gitRoot, "scripts", "check-release-notes.mjs");
+            if (fileExistsSync(releaseNotesScript)) {
+                const notesExitCode = runHookCommand(gitRoot, "node", ["scripts/check-release-notes.mjs"]);
+                if (notesExitCode !== 0)
+                    return notesExitCode;
+            }
+            else {
+                process.stdout.write("Skipping release notes check: scripts/check-release-notes.mjs is not defined.\n");
+            }
+            return runOptionalProjectScript(gitRoot, scripts, "release:prepublish").exitCode;
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof HookFailure) {
+            process.stderr.write(`\n${error.message}\n`);
+            for (const detail of error.details) {
+                if (!detail)
+                    continue;
+                process.stderr.write(`${detail}\n`);
+            }
+            return 1;
+        }
+        throw error;
+    }
+}
 async function readHookStdinUtf8(timeoutMs = 25) {
     if (process.stdin.isTTY)
         return "";
@@ -59,19 +289,10 @@ export async function runPrePushHook(opts) {
         cwd: opts.cwd,
         rootOverride: opts.rootOverride ?? null,
     });
+    const stdin = await readHookStdinUtf8();
     const scriptPath = await resolvePrePushHookScriptPath(resolved.gitRoot);
     if (!scriptPath) {
-        throw new CliError({
-            exitCode: 2,
-            code: "E_USAGE",
-            message: [
-                "Missing pre-push hook script: scripts/run-pre-push-hook.mjs",
-                "The pre-push hook needs a repository-local script or an installed CLI bundle that ships the fallback.",
-                "Fix:",
-                "  1) Restore scripts/run-pre-push-hook.mjs in this repository, or",
-                "  2) Run `agentplane hooks uninstall` if this repository should not use the agentplane pre-push gate.",
-            ].join("\n"),
-        });
+        return runInternalPrePushHook(resolved.gitRoot, stdin);
     }
     const result = runProcessSync({
         command: "node",
@@ -79,7 +300,7 @@ export async function runPrePushHook(opts) {
         cwd: resolved.gitRoot,
         env: process.env,
         encoding: "utf8",
-        input: await readHookStdinUtf8(),
+        input: stdin,
         stdin: "pipe",
         stdout: "inherit",
         stderr: "inherit",

package/dist/commands/task/derive.command.js

@@ -55,7 +55,7 @@ export const taskDeriveSpec = {
     ],
     examples: [
         {
-            cmd: 'agentplane task derive 202602070101-ABCD --title "Implement X" --description "Do the thing" --owner CODER --tag code --verify "bun test"',
+            cmd: 'agentplane task derive 202602070101-ABCD --title "Implement X" --description "Do the thing" --owner CODER --tag code --verify "bun run test:project -- cli-core"',
             why: "Create an implementation task derived from a spike with seeded verify steps.",
         },
     ],