agentplane 0.3.21 → 0.3.23

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

@@ -1,3 +1,7 @@
+export declare function collectHooksInstallConflicts(opts: {
+    gitRoot: string;
+    agentplaneDir: string;
+}): Promise<string[]>;
 export declare function cmdHooksInstall(opts: {
     cwd: string;
     rootOverride?: string;

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":"AA+CA,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBpB;AAmDD,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,33 @@ 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();
+}
+export async function collectHooksInstallConflicts(opts) {
+    const hooksDir = await resolveGitHooksDir(opts.gitRoot);
+    const conflicts = [];
+    const shimPath = path.join(opts.agentplaneDir, "bin", "agentplane");
+    if (await fileExists(shimPath)) {
+        const managed = await fileIsManaged(shimPath, SHIM_MARKER);
+        if (!managed)
+            conflicts.push(shimPath);
+    }
+    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)
+            conflicts.push(hookPath);
+    }
+    return conflicts;
+}
+function shimScriptText(installedRunnerPath) {
     return [
         "#!/usr/bin/env sh",
         `# ${SHIM_MARKER} (do not edit)`,
@@ -35,6 +62,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 +73,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 +95,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":"AAWA,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;AAiUD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB3E"}