portable-agent-layer 0.74.0 → 0.75.1

package/README.md

@@ -97,6 +97,7 @@ pal cli status        # check your setup
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
 | `pal cli subagent doctor <name>` | Evaluate a subagent definition against the authoring best practices (name/file match, per-platform blocks, model/tools/permission shape, shipped-name collision) |
 | `pal cli subagent list` | List the user-authored subagents in `~/.pal/agents/` |
+| `pal cli version` | Print the installed PAL version. `-v` and `--version` do the same |
 
 ### Target flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.74.0",
+  "version": "0.75.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -23,6 +23,7 @@
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
  *   subagent doctor <name>           Evaluate a subagent against the authoring best practices
  *   debug [on|off]                    Enable / disable verbose hook debug logging
+ *   version | -v                      Print the installed PAL version
  */
 
 import { spawnSync } from "node:child_process";
@@ -280,6 +281,11 @@ async function runCli(command: string | undefined, args: string[]) {
     case "debug":
       cliDebug(args);
       break;
+    case "version":
+    case "-v":
+    case "--version":
+      showVersion();
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -351,6 +357,7 @@ function showHelp() {
     pal cli subagent list                   List the user-authored subagents in ~/.pal/agents/
     pal cli subagent author-model           Print the flagship model that authors subagents for the active agent
     pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
+    pal cli version | -v                    Print the installed PAL version
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -1617,21 +1624,29 @@ function cliDebug(args: string[]) {
   }
 }
 
-async function status() {
-  const home = palHome();
-  const pkg = palPkg();
-
-  let pkgJson: { version: string };
+function packageVersion(): string {
   try {
-    pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8")) as {
+    const pkgJson = JSON.parse(
+      readFileSync(resolve(palPkg(), "package.json"), "utf-8")
+    ) as {
       version: string;
     };
+    return pkgJson.version;
   } catch (e) {
     throw new Error(`Failed to read package.json: ${e}`);
   }
+}
+
+function showVersion() {
+  console.log(packageVersion());
+}
+
+async function status() {
+  const home = palHome();
+  const pkg = palPkg();
 
   console.log("");
-  log.info(`Version:  ${pkgJson.version}`);
+  log.info(`Version:  ${packageVersion()}`);
   log.info(`Package:  ${pkg}`);
   log.info(`Home:     ${home}`);
   console.log("");

package/src/hooks/lib/agent.ts

@@ -9,9 +9,13 @@
  * Detection reads PAL_AGENT first (set in-process by
  * `src/targets/opencode/plugin.ts`), then the host's own environment, and only
  * then the `--agent=` flag the install templates in `assets/templates/*` put
- * on the hook command line. See declaredAgent for why that order.
+ * on the hook command line. See declaredAgent for why that order. When nothing
+ * declares an agent at all, getActiveAgent falls back to the agent CLIs found
+ * on PATH rather than assuming claude.
  */
 
+import { findBinaryOnPath } from "./which";
+
 export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
 
 const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
@@ -109,9 +113,36 @@ export function declaredAgent(): AgentType | undefined {
   return agentFromRuntimeEnv() ?? flag;
 }
 
-/** Which agent's conventions to follow. Assumes "claude" when undeclared. */
+/**
+ * The CLI each agent spawns for inference, in the order inference.ts routes
+ * them. vscode is absent because it has no CLI of its own — it runs Claude's.
+ */
+const AGENT_BINARIES: ReadonlyArray<readonly [AgentType, string]> = [
+  ["claude", "claude"],
+  ["codex", "codex"],
+  ["opencode", "opencode"],
+  ["copilot", "copilot"],
+  ["cursor", "cursor-agent"],
+];
+
+/**
+ * Which agent this machine actually has, for the case where nothing declared
+ * one — a plain terminal running `pal cli`, a cron child, a detached spawn.
+ * Assuming claude there names an agent that may not be installed, which routes
+ * inference to a binary that isn't on PATH and reports a host that isn't there.
+ */
+function agentFromInstalledBinary(): AgentType | undefined {
+  return AGENT_BINARIES.find(([, binary]) => findBinaryOnPath(binary) !== null)?.[0];
+}
+
+/**
+ * Which agent's conventions to follow.
+ *
+ * A declaration always wins; claude remains the last resort so a machine with
+ * no agent CLI at all behaves as it always has.
+ */
 export function getActiveAgent(): AgentType {
-  return declaredAgent() ?? "claude";
+  return declaredAgent() ?? agentFromInstalledBinary() ?? "claude";
 }
 
 export const isClaude = () => getActiveAgent() === "claude";

package/src/hooks/lib/detached-inference.ts

@@ -18,15 +18,26 @@
  */
 
 import { spawn } from "node:child_process";
+import { getActiveAgent } from "./agent";
 import { logDebug, logError } from "./log";
 
+/**
+ * A hook run by Cursor, Copilot or Codex knows its agent only from the
+ * `--agent=` flag its own config put on the command line, and argv does not
+ * cross a spawn. Re-declaring it here is what stops the child from taking the
+ * "claude" default and spawning the wrong CLI for its inference.
+ */
+function withAgentDeclaration(args: string[]): string[] {
+  return [...args, `--agent=${getActiveAgent()}`];
+}
+
 export function spawnDetachedInference(
   scriptPath: string,
   args: string[],
   scope: string
 ): void {
   try {
-    const child = spawn("bun", [scriptPath, ...args], {
+    const child = spawn("bun", [scriptPath, ...withAgentDeclaration(args)], {
       detached: true,
       stdio: "ignore",
       env: { ...process.env, CLAUDECODE: undefined },

package/src/hooks/lib/readme-sync.ts

@@ -24,6 +24,14 @@ export const WATCHED_PATHS = [
   "assets/agents",
 ];
 
+/**
+ * A flag spelling of a command the README documents under its canonical name,
+ * or the `cli` prefix the dispatcher consumes before a command is ever named.
+ */
+function isAliasOrInternalRoute(cmd: string): boolean {
+  return ["--help", "-h", "help", "-v", "--version", "cli"].includes(cmd);
+}
+
 /** Extract CLI command names from the switch statement in index.ts */
 function extractCliCommands(): string[] {
   const pkg = palPkg();
@@ -36,8 +44,7 @@ function extractCliCommands(): string[] {
 
   for (const match of matches) {
     const cmd = match[1];
-    // Skip help aliases and internal routing
-    if (["--help", "-h", "help", "cli"].includes(cmd)) continue;
+    if (isAliasOrInternalRoute(cmd)) continue;
     commands.push(cmd);
   }
 

package/src/hooks/lib/which.ts

@@ -9,9 +9,26 @@
  *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
+import { accessSync, constants, statSync } from "node:fs";
 import { delimiter, resolve as resolvePath } from "node:path";
 
+/**
+ * A directory carries the execute bit as "traversable", so X_OK alone accepts
+ * a folder that happens to share a CLI's name. statSync follows symlinks, so a
+ * linked binary still resolves. Windows has no executable bit — being a file
+ * under a PATHEXT extension is all it can offer.
+ */
+function isExecutableFile(candidate: string): boolean {
+  try {
+    if (!statSync(candidate).isFile()) return false;
+    if (process.platform === "win32") return true;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Resolve a binary on PATH to its full absolute path, or null if absent. */
 export function findBinaryOnPath(name: string): string | null {
   const PATH = process.env.PATH;
@@ -24,17 +41,7 @@ export function findBinaryOnPath(name: string): string | null {
     if (!dir) continue;
     for (const ext of exts) {
       const candidate = resolvePath(dir, name + ext);
-      try {
-        if (process.platform === "win32") {
-          // Windows has no executable bit — existence in PATHEXT is enough.
-          if (existsSync(candidate)) return candidate;
-        } else {
-          accessSync(candidate, constants.X_OK);
-          return candidate;
-        }
-      } catch {
-        /* not here — try next */
-      }
+      if (isExecutableFile(candidate)) return candidate;
     }
   }
   return null;