portable-agent-layer 0.88.1 → 0.89.1

package/src/cli/subagent.ts

@@ -1,75 +1,68 @@
 /**
- * pal cli subagent — manage personal subagents under ~/.pal/agents/.
- *
- *   pal cli subagent link <name>     Install ~/.pal/agents/<name>.md into every
- *                                    installed agent (split per platform).
- *   pal cli subagent doctor <name>   Evaluate ~/.pal/agents/<name>.md against the
- *                                    subagent-authoring best practices.
- *   pal cli subagent list            List the user-authored subagents.
- *   pal cli subagent author-model    Print the flagship model configured to author
- *                                    subagents for the active agent (empty if none).
+ * pal cli subagent — manage personal subagents under ~/.pal/agents/, each one
+ * merged definition split per platform on install.
  */
 
-import { getActiveAgent } from "../hooks/lib/agent";
-import { flagshipAuthorModel } from "../hooks/lib/models";
 import { installPersonalSubagent, listPersonalSubagents, log } from "../targets/lib";
+import { group, leaf } from "../tools/lib/command";
 import {
   formatSubagentReport,
   lintSubagent,
   resolveSubagentFile,
 } from "../tools/subagent-doctor";
+import { printAuthorModel } from "./skill";
 
-export async function runSubagent(args: string[]): Promise<number> {
-  const [sub, name] = args;
-
-  if (sub === "author-model") {
-    const model = flagshipAuthorModel(getActiveAgent());
-    if (model) console.log(model);
-    return 0;
+function list(): number {
+  const names = listPersonalSubagents();
+  if (names.length === 0) {
+    log.info("No personal subagents in ~/.pal/agents/");
+  } else {
+    for (const n of names) console.log(n);
   }
+  return 0;
+}
 
-  if (sub === "list") {
-    const names = listPersonalSubagents();
-    if (names.length === 0) {
-      log.info("No personal subagents in ~/.pal/agents/");
+function doctor(name: string): number {
+  const report = lintSubagent(resolveSubagentFile(name));
+  console.log(formatSubagentReport(report));
+  return report.errors > 0 ? 1 : 0;
+}
+
+function link(name: string): number {
+  try {
+    const installed = installPersonalSubagent(name);
+    if (installed.length === 0) {
+      log.warn(
+        `'${name}' installed into no agents (none installed yet). ` +
+          "Run 'pal cli install' first, then re-link."
+      );
     } else {
-      for (const n of names) console.log(n);
+      log.success(`Installed '${name}' into: ${installed.join(", ")}`);
     }
     return 0;
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : String(e));
+    return 1;
   }
-
-  if (sub === "doctor") {
-    if (!name) {
-      log.error("Usage: pal cli subagent doctor <file-or-name>");
-      return 1;
-    }
-    const report = lintSubagent(resolveSubagentFile(name));
-    console.log(formatSubagentReport(report));
-    return report.errors > 0 ? 1 : 0;
-  }
-
-  if (sub === "link") {
-    if (!name) {
-      log.error("Usage: pal cli subagent link <name>");
-      return 1;
-    }
-    try {
-      const installed = installPersonalSubagent(name);
-      if (installed.length === 0) {
-        log.warn(
-          `'${name}' installed into no agents (none installed yet). ` +
-            "Run 'pal cli install' first, then re-link."
-        );
-      } else {
-        log.success(`Installed '${name}' into: ${installed.join(", ")}`);
-      }
-      return 0;
-    } catch (e) {
-      log.error(e instanceof Error ? e.message : String(e));
-      return 1;
-    }
-  }
-
-  log.error("Usage: pal cli subagent <link|doctor|list|author-model> [name]");
-  return 1;
 }
+
+export const subagentCommand = group({
+  summary: "Manage personal subagents under ~/.pal/agents/",
+  commands: {
+    link: leaf({
+      summary: "Install ~/.pal/agents/<name>.md into every installed agent",
+      args: "<name>",
+      run: ({ positionals }) => link(positionals[0]),
+    }),
+    doctor: leaf({
+      summary: "Check a subagent against the subagent-authoring best practices",
+      args: "<name>",
+      run: ({ positionals }) => doctor(positionals[0]),
+    }),
+    list: leaf({ summary: "List the user-authored subagents", run: list }),
+    "author-model": leaf({
+      summary: "Print the flagship model that authors subagents for the active agent",
+      run: printAuthorModel,
+    }),
+  },
+});

package/src/cli/tree.ts

@@ -0,0 +1,177 @@
+/**
+ * Every `pal cli` command, as one tree. The commands whose code lives in
+ * index.ts arrive as handlers, because index.ts routes on import and so can
+ * never be imported by a test that walks this tree.
+ */
+
+import { AGENT_NAMES, AGENT_REGISTRY } from "../hooks/lib/agent-registry";
+import {
+  type Group,
+  group,
+  type Leaf,
+  leaf,
+  type OptionSpec,
+  type OptionSpecs,
+} from "../tools/lib/command";
+import { usageCommand } from "../tools/token-cost";
+import { builtinTools, builtinToolVerbs } from "./builtin-tools";
+import { identityCommand } from "./identity";
+import { knowledgeCommand } from "./knowledge";
+import { ledgerCommand } from "./ledger-command";
+import { runMigrate } from "./migrate";
+import { telosCommand, timezoneCommand } from "./personal-context";
+import { ruleCommand } from "./rule";
+import { serverCommand } from "./server";
+import { skillCommand } from "./skill";
+import { subagentCommand } from "./subagent";
+
+type Handler = Leaf["run"];
+export type DebugState = "on" | "off" | "status";
+
+export interface AdminHandlers {
+  init: Handler;
+  install: Handler;
+  uninstall: Handler;
+  update: Handler;
+  export: Handler;
+  import: Handler;
+  status: Handler;
+  doctor: Handler;
+  debug(state: DebugState): void;
+  version: Handler;
+}
+
+const ENVIRONMENT = `Environment:
+  PAL_HOME          Override user state directory (default: ~/.pal or repo root)
+  PAL_PKG           Override package root
+  PAL_CLAUDE_DIR    Override Claude config dir (default: ~/.claude)
+  PAL_OPENCODE_DIR  Override opencode config dir (default: ~/.config/opencode)
+  PAL_CURSOR_DIR    Override Cursor config dir (default: ~/.cursor)
+  PAL_COPILOT_DIR   Override Copilot config dir (default: ~/.copilot)
+  PAL_CODEX_DIR     Override Codex config dir (default: ~/.codex)
+  PAL_GEMINI_DIR    Override Antigravity's Gemini dir (default: ~/.gemini)
+  PAL_AGENTS_DIR    Override agents dir (default: ~/.agents)`;
+
+function agentOptions(verb: string): OptionSpecs {
+  const perAgent = AGENT_NAMES.map((agent): [string, OptionSpec] => [
+    agent,
+    { type: "boolean", description: `${verb} ${AGENT_REGISTRY[agent].label}` },
+  ]);
+  return {
+    ...Object.fromEntries(perAgent),
+    all: { type: "boolean", description: `${verb} every supported agent` },
+  };
+}
+
+const VERBOSE: OptionSpec = {
+  type: "boolean",
+  description: "Step-by-step log, and every passing doctor check",
+};
+const DRY_RUN: OptionSpec = { type: "boolean", description: "Show what would happen" };
+
+function debugCommand(admin: AdminHandlers): Group {
+  const state = (s: DebugState, summary: string) =>
+    leaf({ summary, run: () => admin.debug(s) });
+  return group({
+    summary: "Verbose hook debug logging (persisted)",
+    fallback: "status",
+    commands: {
+      status: state("status", "Show whether it is on, and where it logs"),
+      on: state("on", "Turn it on"),
+      off: state("off", "Turn it off"),
+    },
+  });
+}
+
+function adminCommands(admin: AdminHandlers): Record<string, Leaf | Group> {
+  return {
+    init: leaf({
+      summary: "Scaffold PAL home and install (default: every installed agent)",
+      options: { ...agentOptions("Install into"), verbose: VERBOSE },
+      run: admin.init,
+    }),
+    install: leaf({
+      summary:
+        "Register hooks and skills (default: every installed agent), then run the doctor",
+      options: { ...agentOptions("Install into"), verbose: VERBOSE },
+      run: admin.install,
+    }),
+    uninstall: leaf({
+      summary: "Remove hooks and skills (default: every agent)",
+      options: agentOptions("Uninstall from"),
+      run: admin.uninstall,
+    }),
+    update: leaf({ summary: "Update PAL (git pull or bun add -g)", run: admin.update }),
+    export: leaf({
+      summary: "Export your state to a zip",
+      args: "[path]",
+      options: { "dry-run": DRY_RUN },
+      run: admin.export,
+    }),
+    import: leaf({
+      summary: "Merge your state from a zip (default: the newest export or backup)",
+      args: "[path]",
+      options: {
+        "dry-run": DRY_RUN,
+        overwrite: { type: "boolean", description: "Replace instead of merging" },
+      },
+      run: admin.import,
+    }),
+    status: leaf({ summary: "Show PAL configuration", run: admin.status }),
+    doctor: leaf({
+      summary: "Find what is wrong and how to fix it; exits 1 on any failure",
+      options: {
+        verbose: { type: "boolean", description: "Show passing checks too" },
+        json: { type: "boolean", description: "Machine-readable output" },
+        "probe-inference": {
+          type: "boolean",
+          description: "Also fire a real inference call per route (costs tokens)",
+        },
+        probe: { type: "boolean", description: "Same as --probe-inference" },
+      },
+      run: admin.doctor,
+    }),
+    migrate: leaf({
+      summary: "Run pending data migrations",
+      options: {
+        list: { type: "boolean", description: "List pending and done migrations" },
+        "dry-run": DRY_RUN,
+      },
+      run: ({ argv }) => runMigrate(argv),
+    }),
+  };
+}
+
+export function cliTree(admin: AdminHandlers): Group {
+  return group({
+    summary: "Admin commands for the Portable Agent Layer",
+    aliases: { "-v": "version", "--version": "version" },
+    details: ENVIRONMENT,
+    commands: {
+      ...adminCommands(admin),
+      usage: usageCommand,
+      actor: identityCommand("actor"),
+      machine: identityCommand("machine"),
+      telos: telosCommand,
+      timezone: timezoneCommand,
+      knowledge: knowledgeCommand,
+      ledger: ledgerCommand,
+      rule: ruleCommand,
+      server: serverCommand,
+      skill: skillCommand,
+      subagent: subagentCommand,
+      ...builtinTools,
+      debug: debugCommand(admin),
+      version: leaf({ summary: "Print the installed PAL version", run: admin.version }),
+    },
+  });
+}
+
+export function inertAdmin(): AdminHandlers {
+  return new Proxy({} as AdminHandlers, { get: () => () => undefined });
+}
+
+export function adminCommandNames(): string[] {
+  const names = Object.keys(cliTree(inertAdmin()).commands);
+  return names.filter((name) => !builtinToolVerbs.includes(name));
+}

package/src/hooks/InvocationContext.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook: PreInvocation (Antigravity) — injects the session context once per
+ * conversation and the prompt context once per turn.
+ *
+ * Silent and fail-open: anything that goes wrong prints nothing. What to inject
+ * is decided in lib/invocation-context.ts, where a test can import it.
+ */
+
+import { enterHookWorkspace } from "./lib/hook-turn";
+import { type InvocationPayload, invocationContext } from "./lib/invocation-context";
+import { logError } from "./lib/log";
+import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { readStdinJSON } from "./lib/stdin";
+
+if (isPalSpawnedInference()) process.exit(0);
+
+try {
+  const input = await readStdinJSON<InvocationPayload>();
+  if (!input) process.exit(0);
+
+  enterHookWorkspace(input);
+  const reply = await invocationContext(input);
+  if (reply) process.stdout.write(reply);
+} catch (err) {
+  logError("InvocationContext", err);
+}

package/src/hooks/LedgerCommit.ts

@@ -11,7 +11,8 @@
  */
 
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
-import { commitApplied, ledgeredCalls } from "./lib/ledger-hook";
+import { enterHookWorkspace } from "./lib/hook-turn";
+import { commitApplied, landedCalls } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -21,7 +22,8 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  for (const call of ledgeredCalls(input)) {
+  enterHookWorkspace(input);
+  for (const call of landedCalls(input)) {
     const entry = commitApplied(call);
     if (entry) {
       logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);

package/src/hooks/LedgerSnapshot.ts

@@ -11,6 +11,7 @@
  */
 
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
 import { ledgeredCalls, snapshotCall } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
@@ -21,6 +22,7 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
+  enterHookWorkspace(input);
   const calls = ledgeredCalls(input);
   if (calls.length === 0) process.exit(0);
 

package/src/hooks/SecurityValidator.ts

@@ -9,6 +9,7 @@
 
 import { blockResponse } from "./lib/agent";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
 import { recordBlocked } from "./lib/ledger";
 import { logError } from "./lib/log";
 import { decideRefusal, type SecurityInput } from "./lib/security-gate";
@@ -20,6 +21,7 @@ try {
   const input = await readStdinJSON<SecurityInput>();
   if (!input) process.exit(0);
 
+  enterHookWorkspace(input);
   const refusal = decideRefusal(input, process.cwd());
   if (!refusal) process.exit(0);
 

package/src/hooks/StopOrchestrator.ts

@@ -8,8 +8,14 @@
 import { checkReadmeSync } from "./handlers/readme-sync";
 import { watchReplyRules } from "./lib/adaptation-steering";
 import { stopBlockResponse } from "./lib/agent";
+import {
+  type AntigravityStopFields,
+  isSideStop,
+  withTranscriptReply,
+} from "./lib/antigravity-transcript";
 import { watchClaims } from "./lib/claim-log";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
 import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
@@ -20,11 +26,16 @@ import { type StopTurnPayload, stopTurn } from "./lib/stop";
 if (isPalSpawnedInference()) process.exit(0);
 if (duplicatesCursorHooks()) process.exit(0);
 
+const received = await readStdinJSON<StopTurnPayload & AntigravityStopFields>();
+if (isSideStop(received)) process.exit(0);
+const payload = withTranscriptReply(received);
+enterHookWorkspace(payload);
+
 // Check README sync before anything else — may block the session
 try {
   // A block carrying no reason stops the turn without telling the model why, so it
   // is worth less than not blocking at all — require the reason to raise one.
-  const decision = checkReadmeSync();
+  const decision = await checkReadmeSync();
   if (decision.decision === "block" && decision.reason) {
     process.stdout.write(stopBlockResponse(decision.reason));
     process.exit(0);
@@ -33,7 +44,6 @@ try {
   logError("StopOrchestrator:readme-sync", err);
 }
 
-const payload = await readStdinJSON<StopTurnPayload>();
 try {
   const sendBack = watchClaims(payload);
   if (sendBack) {

package/src/hooks/UserPromptOrchestrator.ts

@@ -8,11 +8,10 @@
  */
 
 import { injectPromptContext } from "./handlers/inject-retrieval";
-import { captureRating } from "./handlers/rating";
-import { captureSessionName } from "./handlers/session-name";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { type HookTurnPayload, hookSessionId } from "./lib/hook-turn";
-import { logDebug, logError, logPromptSnapshot } from "./lib/log";
+import { logDebug, logPromptSnapshot } from "./lib/log";
+import { capturePrompt } from "./lib/prompt-capture";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -34,15 +33,4 @@ const sessionId = hookSessionId(input);
 const injected = await injectPromptContext(input.prompt, sessionId);
 logPromptSnapshot(input.prompt, injected);
 
-const results = await Promise.allSettled([
-  captureRating(input.prompt, sessionId, sentAt),
-  captureSessionName(input.prompt, sessionId ?? ""),
-]);
-
-const handlerNames = ["rating", "session-name"];
-for (let i = 0; i < results.length; i++) {
-  const r = results[i];
-  if (r.status === "rejected") {
-    logError(`UserPromptOrchestrator:${handlerNames[i]}`, r.reason);
-  }
-}
+await capturePrompt(input.prompt, sessionId, sentAt, "UserPromptOrchestrator");

package/src/hooks/handlers/context-digests.ts

@@ -5,42 +5,34 @@
  * at the next session start, keeping hook stdout small.
  *
  * Sources are defined in src/hooks/lib/semi-static.ts — add one entry there
- * to extend coverage to all consumers (CLAUDE.md, opencode, Cursor, Copilot).
+ * to extend coverage to all consumers (CLAUDE.md, opencode, Cursor, Copilot, Antigravity).
  */
 
 import { existsSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { ensureDir, platform } from "../lib/paths";
 import {
+  antigravityFilename,
+  antigravityRule,
   copilotFilename,
   cursorFilename,
   getSemiStaticSources,
 } from "../lib/semi-static";
 
-export function writeContextDigests(): void {
-  const sources = getSemiStaticSources();
-
-  // Resolve Cursor/Copilot destination dirs once (null if agent not installed)
-  let rulesDir: string | null = null;
-  let instructionsDir: string | null = null;
-
+function subdirIfInstalled(agentHome: () => string, subdir: string): string | null {
   try {
-    const cursorDir = platform.cursorDir();
-    if (existsSync(cursorDir)) {
-      rulesDir = ensureDir(resolve(cursorDir, "rules"));
-    }
+    const home = agentHome();
+    return existsSync(home) ? ensureDir(resolve(home, subdir)) : null;
   } catch {
-    /* non-fatal */
+    return null;
   }
+}
 
-  try {
-    const copilotDir = platform.copilotDir();
-    if (existsSync(copilotDir)) {
-      instructionsDir = ensureDir(resolve(copilotDir, "instructions"));
-    }
-  } catch {
-    /* non-fatal */
-  }
+export function writeContextDigests(): void {
+  const sources = getSemiStaticSources();
+  const rulesDir = subdirIfInstalled(platform.cursorDir, "rules");
+  const instructionsDir = subdirIfInstalled(platform.copilotDir, "instructions");
+  const antigravityRulesDir = subdirIfInstalled(platform.antigravityPluginDir, "rules");
 
   for (const src of sources) {
     try {
@@ -67,6 +59,14 @@ export function writeContextDigests(): void {
           "utf-8"
         );
       }
+
+      if (antigravityRulesDir) {
+        writeFileSync(
+          resolve(antigravityRulesDir, antigravityFilename(src)),
+          antigravityRule(src.description, content),
+          "utf-8"
+        );
+      }
     } catch {
       /* non-fatal */
     }

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

@@ -39,15 +39,19 @@ interface ReadmeSyncDecision {
 }
 
 /** Returns a block decision if README is stale, or empty object to allow stop. */
-export function checkReadmeSync(): ReadmeSyncDecision {
+export async function checkReadmeSync(): Promise<ReadmeSyncDecision> {
   if (!hasDocumentableChanges()) {
     logDebug("readme-sync", "No documentable changes detected");
     return {};
   }
 
   logDebug("readme-sync", "Documentable files changed — validating README");
-  const result = validateReadmeSync();
+  const { adminCommandNames } = await import("../../cli/tree");
+  return readmeDecision(adminCommandNames());
+}
 
+function readmeDecision(cliCommands: string[]): ReadmeSyncDecision {
+  const result = validateReadmeSync(cliCommands);
   if (!result.ok) {
     logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
     const issueList = result.issues.map((i) => `- ${i}`).join("\n");

package/src/hooks/lib/agent-definition.ts

@@ -4,27 +4,17 @@
  * and a body that becomes the subagent's system prompt.
  */
 
+import { AGENT_NAMES, type AgentName } from "./agent-registry";
 import { splitFrontmatter } from "./frontmatter";
 
-export const AGENT_PLATFORMS = [
-  "claude",
-  "opencode",
-  "cursor",
-  "copilot",
-  "codex",
-] as const;
-export type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
-
 export interface AgentDefinition {
   hasFrontmatter: boolean;
   global: string[];
-  platforms: Partial<Record<AgentPlatform, string[]>>;
+  platforms: Partial<Record<AgentName, string[]>>;
   body: string;
 }
 
-const PLATFORM_BLOCK_HEADER = new RegExp(
-  String.raw`^(${AGENT_PLATFORMS.join("|")}):\s*$`
-);
+const PLATFORM_BLOCK_HEADER = new RegExp(String.raw`^(${AGENT_NAMES.join("|")}):\s*$`);
 const BLOCK_INDENT = "  ";
 
 export function parseAgentDefinition(content: string): AgentDefinition {
@@ -34,14 +24,14 @@ export function parseAgentDefinition(content: string): AgentDefinition {
   }
 
   const global: string[] = [];
-  const platforms: Partial<Record<AgentPlatform, string[]>> = {};
-  let current: AgentPlatform | null = null;
+  const platforms: Partial<Record<AgentName, string[]>> = {};
+  let current: AgentName | null = null;
 
   for (const line of split.frontmatter.split("\n")) {
     if (!line.trim()) continue;
     const header = PLATFORM_BLOCK_HEADER.exec(line);
     if (header) {
-      current = header[1] as AgentPlatform;
+      current = header[1] as AgentName;
       platforms[current] ??= [];
       continue;
     }