portable-agent-layer 0.71.0 → 0.73.0

package/src/hooks/lib/compact-recall.ts

@@ -0,0 +1,89 @@
+/**
+ * The last exchange before a compaction, and what is safe to do with it after.
+ *
+ * A summary can collapse the turn that was in flight when the window filled, so
+ * the originals are re-injected verbatim on the next session. Everything here
+ * used to sit inside the spawned hook: the budget split, the order the candidate
+ * files are tried in, and whether the file just read may be deleted.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+/** Hook output is capped at 10,000 chars; the rest is headroom for the framing. */
+const MAX_OUTPUT = 9_000;
+
+/** The user's half. The assistant's reply is the longer of the two in most turns. */
+const USER_SHARE = 0.4;
+
+/** Held back for the reminder's headings and framing text. */
+const FRAMING_RESERVE = 300;
+
+export interface SavedExchange {
+  sessionId: string;
+  timestamp: string;
+  trigger: string | null;
+  customInstructions: string | null;
+  userMessage: string;
+  assistantMessage: string;
+}
+
+export interface RecallBudget {
+  user: number;
+  assistant: number;
+}
+
+export function recallBudget(max: number = MAX_OUTPUT): RecallBudget {
+  const user = Math.floor(max * USER_SHARE);
+  return { user, assistant: max - user - FRAMING_RESERVE };
+}
+
+/** Says how much was dropped, so a truncated message cannot read as a complete one. */
+export function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}\n[... truncated ${s.length - max} chars]`;
+}
+
+function exchangeDir(): string {
+  return resolve(paths.state(), "last-exchange");
+}
+
+/**
+ * The session's own file first, then the fallback. latest.json is overwritten by
+ * every compaction, so it is right only when nothing more specific exists.
+ */
+export function findSavedExchange(sessionId?: string): string | null {
+  const candidates = [
+    sessionId ? resolve(exchangeDir(), `${sessionId}.json`) : null,
+    resolve(exchangeDir(), "latest.json"),
+  ].filter((path): path is string => path !== null);
+  return candidates.find((path) => existsSync(path)) ?? null;
+}
+
+/**
+ * Consume-on-read, but only for the session's own file: latest.json is the
+ * safety fallback and deleting it would leave the next compaction with nothing.
+ */
+export function isConsumable(file: string, sessionId?: string): boolean {
+  if (!sessionId) return false;
+  return file === resolve(exchangeDir(), `${sessionId}.json`);
+}
+
+export function buildRecall(saved: SavedExchange, budget = recallBudget()): string {
+  return [
+    "<system-reminder>",
+    "## Last exchange before compaction",
+    "_Restored verbatim from PAL state. The compaction summary may have collapsed this; the originals are below._",
+    "",
+    "**User:**",
+    truncate(saved.userMessage || "(no user message captured)", budget.user),
+    "",
+    "**Assistant:**",
+    truncate(
+      saved.assistantMessage || "(no assistant message captured)",
+      budget.assistant
+    ),
+    "</system-reminder>",
+  ].join("\n");
+}

package/src/hooks/lib/failure-principle.ts

@@ -0,0 +1,98 @@
+/**
+ * What a low-rated session is asked about, and what is kept from the answer.
+ *
+ * The handler around this is spawned detached — claude --print's cold start
+ * outruns the Stop hook's budget — so none of it was reachable from a test. The
+ * decisions are here instead: how much of the transcript the question carries,
+ * what the question is, and which of the two sources wins for each field.
+ */
+
+import { extractContent, parseMessages } from "./transcript";
+
+/** Enough of the ending to see what went wrong, without paying for the whole session. */
+const MAX_MESSAGES = 10;
+
+/** Per message, so one long tool dump cannot crowd out the other nine. */
+const MAX_CHARS_PER_MESSAGE = 300;
+
+export interface PendingFailure {
+  rating: number;
+  context: string;
+  detailedContext?: string;
+  principle?: string;
+  responsePreview?: string;
+  userPreview?: string;
+  cwd?: string;
+}
+
+export interface InferredPrinciple {
+  principle?: string;
+  detailedContext?: string;
+}
+
+export function recentExchange(transcript: string): string {
+  return parseMessages(transcript)
+    .slice(-MAX_MESSAGES)
+    .map(
+      (message) =>
+        `${message.role.toUpperCase()}: ${extractContent(message).slice(0, MAX_CHARS_PER_MESSAGE)}`
+    )
+    .join("\n\n");
+}
+
+/** The parent may already have a principle, in which case there is nothing to ask. */
+export function needsInference(pending: PendingFailure): boolean {
+  return !pending.principle;
+}
+
+export function principleRequest(pending: PendingFailure, recent: string) {
+  return {
+    system: `Analyze this failed AI interaction (rated ${pending.rating}/10). Return JSON: {"principle": "<verb-first actionable rule, 10-20 words — write a full sentence, not a fragment>", "detailed_context": "<root cause and what to do differently, 50-150 words>"}.`,
+    user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
+    maxTokens: 400,
+    timeout: 90_000,
+    jsonSchema: {
+      type: "object" as const,
+      properties: {
+        principle: { type: "string" as const },
+        detailed_context: { type: "string" as const },
+      },
+      required: ["principle", "detailed_context"],
+      additionalProperties: false,
+    },
+    caller: "failure-principle",
+  };
+}
+
+function parseInferred(output: string | null): InferredPrinciple {
+  if (!output) return {};
+  try {
+    const parsed = JSON.parse(output) as {
+      principle?: string;
+      detailed_context?: string;
+    };
+    return {
+      principle: parsed.principle || undefined,
+      detailedContext: parsed.detailed_context || undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The two fields resolve differently on purpose. A principle the parent already
+ * had means inference never ran, so there is nothing to lose to; a detailed
+ * context it already had was written from the full session and outranks one
+ * inferred from ten messages.
+ */
+export function mergeInferredPrinciple(
+  pending: PendingFailure,
+  output: string | null
+): InferredPrinciple {
+  const inferred = parseInferred(output);
+  return {
+    principle: pending.principle || inferred.principle,
+    detailedContext: pending.detailedContext ?? inferred.detailedContext,
+  };
+}

package/src/hooks/lib/goal-links.ts

@@ -0,0 +1,83 @@
+/**
+ * Which projects serve which stated goal, and how far along that makes it.
+ *
+ * The linkage needs judgement — "Catalyst is the starter that pays for the rest"
+ * serves "land two retained clients" only if you know what both mean — so a model
+ * draws it. The progress does not: it is criteria closed over criteria written,
+ * counted here, because a model returning "64%" says something unfalsifiable
+ * about a goal it cannot measure.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+interface GoalLink {
+  goalId: string;
+  projects: string[];
+}
+
+export interface GoalLinks {
+  generatedAt: string;
+  /** Hash of the goals and projects the linkage was drawn from. */
+  inputs: string;
+  links: GoalLink[];
+}
+
+export interface GoalProgress {
+  projects: string[];
+  closed: number;
+  written: number;
+}
+
+function goalLinksPath(): string {
+  return resolve(paths.state(), "goal-links.json");
+}
+
+export function readGoalLinks(): GoalLinks | null {
+  const path = goalLinksPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as GoalLinks;
+    return Array.isArray(parsed.links) && parsed.generatedAt ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeGoalLinks(links: GoalLinks): Promise<void> {
+  await writeFile(goalLinksPath(), `${JSON.stringify(links, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * A stable fingerprint of what the linkage was drawn from, so a stop where
+ * neither the goals nor the projects moved costs nothing.
+ */
+export function linkInputs(goalIds: string[], projectSlugs: string[]): string {
+  return Bun.hash(
+    JSON.stringify([[...goalIds].sort(), [...projectSlugs].sort()])
+  ).toString(36);
+}
+
+/**
+ * Counted, not estimated. A goal nothing serves has no progress rather than
+ * zero — "no project serves this yet" is the answer worth showing.
+ */
+export function progressFor(
+  goalId: string,
+  links: GoalLinks | null,
+  criteriaBySlug: Map<string, { closed: number; written: number }>
+): GoalProgress | null {
+  const projects = links?.links.find((l) => l.goalId === goalId)?.projects ?? [];
+  const known = projects.filter((slug) => criteriaBySlug.has(slug));
+  if (known.length === 0) return null;
+  let closed = 0;
+  let written = 0;
+  for (const slug of known) {
+    const counts = criteriaBySlug.get(slug) as { closed: number; written: number };
+    closed += counts.closed;
+    written += counts.written;
+  }
+  return { projects: known, closed, written };
+}

package/src/hooks/lib/ledger-hook.ts

@@ -13,6 +13,7 @@ import {
   claimPending,
   type LedgerEntry,
   type LedgerOutcome,
+  type PendingSnapshot,
   reapStalePending,
   recordAction,
   savePending,
@@ -245,6 +246,40 @@ export function commitApplied(call: LedgeredCall): LedgerEntry | null {
   return entry;
 }
 
+/**
+ * The snapshot is the trustworthy source, but its absence is recoverable here in
+ * a way it never is after a successful edit: nothing landed, so whatever is on
+ * disk now is still the before-state.
+ */
+export function unappliedBefore(
+  pending: PendingSnapshot | null,
+  target: string
+): string | null {
+  if (pending) return pending.before;
+  return contentsOf(target);
+}
+
+/**
+ * Record a call that did not land. Unlike the applied half this writes with or
+ * without a parked snapshot, because a missing snapshot here is recoverable and
+ * dropping the entry would lose the only record that the attempt happened.
+ */
+export function commitUnapplied(
+  call: LedgeredCall,
+  verdict: UnappliedVerdict
+): LedgerEntry {
+  return recordAction({
+    tool: call.tool,
+    target: call.target,
+    outcome: verdict.outcome,
+    before: unappliedBefore(claimPending(call.toolUseId), call.target),
+    // Nothing landed. That is what this event means, and it is the difference
+    // between this entry and an applied one.
+    after: null,
+    reason: verdict.reason,
+  });
+}
+
 export function toolUseIdOf(payload: Record<string, unknown>): string | null {
   for (const key of ["tool_use_id", "toolUseId", "tool_call_id"]) {
     const value = payload[key];

package/src/hooks/lib/ledger.ts

@@ -46,8 +46,14 @@ import { isSensitivePath } from "./sensitive-path";
  * lose the only signal in the record that says where the boundary was drawn,
  * and "what did I try that was refused" is a question worth being able to ask
  * separately from "what did I try that broke".
+ *
+ * `blocked` is a rule refusing, on the same reasoning: a person can be asked to
+ * reconsider and a rule cannot, so "PAL would not let me" and "you would not
+ * let me" are different facts about where the boundary sits. It is also the
+ * only outcome PAL itself decides, which is what makes the declare-enforce-record
+ * triad demonstrable rather than merely wired.
  */
-export type LedgerOutcome = "applied" | "failed" | "denied";
+export type LedgerOutcome = "applied" | "failed" | "denied" | "blocked";
 
 /**
  * One side of a change, identified rather than reproduced. The hash ties the
@@ -107,6 +113,12 @@ export interface LedgerEntry extends RecordAttribution {
   delta?: LedgerDelta;
   /** Why the action did not land. Absent on an applied one. */
   reason?: string;
+  /**
+   * The shell command a rule refused. Only a blocked shell action carries one:
+   * it has no file to name, so without this the entry could say a command was
+   * refused but not which.
+   */
+  command?: string;
 }
 
 export interface RecordActionInput {
@@ -121,6 +133,7 @@ export interface RecordActionInput {
   /** Resulting content; null when nothing landed. */
   after: string | null;
   reason?: string;
+  command?: string;
 }
 
 /**
@@ -254,6 +267,7 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
     after: stateOf(input.after),
     ...(delta ? { delta } : {}),
     ...(input.reason ? { reason: input.reason } : {}),
+    ...(input.command ? { command: input.command } : {}),
   };
 
   const file = ledgerPath();
@@ -262,6 +276,39 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
   return entry;
 }
 
+/** A refused command is quoted back, not stored whole. */
+const MAX_COMMAND_CHARS = 500;
+
+export interface RecordBlockedInput {
+  tool: string;
+  /** Absolute path of the file, or of the directory a refused command ran in. */
+  target: string;
+  /** The refused command, when the tool was a shell rather than an editor. */
+  command?: string;
+  /** What the rule told the agent — the same words, so both records agree. */
+  reason: string;
+}
+
+/**
+ * A rule refused this before it ran. Written by whoever enforces the rule, at
+ * the moment it fires, because a refusal produces no other event: nothing runs,
+ * so no post-tool hook reports it and nothing downstream can infer it happened.
+ *
+ * There is no before or after. The file is untouched, and a delta claiming
+ * otherwise would be the ledger describing a change that never occurred.
+ */
+export function recordBlocked(input: RecordBlockedInput): LedgerEntry {
+  return recordAction({
+    tool: input.tool,
+    target: input.target,
+    outcome: "blocked",
+    before: null,
+    after: null,
+    reason: input.reason,
+    ...(input.command ? { command: input.command.slice(0, MAX_COMMAND_CHARS) } : {}),
+  });
+}
+
 /**
  * The before-state, held between the two halves of one tool call.
  *

package/src/hooks/lib/models.ts

@@ -5,7 +5,7 @@
 import type { AgentType } from "./agent";
 
 export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
-export const SONNET_MODEL = "claude-sonnet-4-6";
+export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
 /**

package/src/hooks/lib/projects.ts

@@ -45,6 +45,9 @@ export interface ProjectProgress {
   serves?: ServesKind;
   serves_note?: string;
   serves_by?: ServesAuthority;
+  /** The user's own placement on the grid, which overrules both guesses. */
+  placed?: string;
+  placed_by?: ServesAuthority;
   // ISA body sections
   problem?: string;
   goal?: string;
@@ -284,6 +287,8 @@ export function writeProject(p: ProjectProgress): void {
   if (p.serves) meta.serves = p.serves;
   if (p.serves_note) meta.serves_note = p.serves_note;
   if (p.serves_by) meta.serves_by = p.serves_by;
+  if (p.placed) meta.placed = p.placed;
+  if (p.placed_by) meta.placed_by = p.placed_by;
   writeFileSync(ensureAndGetIsaFile(p.name), stringify(meta, buildBody(p)), "utf-8");
 }
 

package/src/hooks/lib/security-gate.ts

@@ -0,0 +1,159 @@
+/**
+ * The gate's decision, separated from the process that carries it out.
+ *
+ * SecurityValidator is spawned, so nothing can import it and nothing measures
+ * it — every rule about which tool names run a shell, which argument spells the
+ * path, and what the agent is told was unreachable from a test. The decision
+ * lives here instead; the entrypoint is left with stdin, stdout and the ledger.
+ */
+
+import { normalizeToolUse } from "./agent";
+import { logDebug } from "./log";
+import { checkBashCommand, checkFilePath } from "./security";
+
+/** beforeShellExecution (Cursor only) — flat, no tool-name wrapper. */
+interface ShellExecInput {
+  command: string;
+  sandbox?: boolean;
+}
+
+export type SecurityInput = Record<string, unknown> | ShellExecInput;
+
+export interface GateRefusal {
+  tool: string;
+  /** The file, or the directory a refused command would have run in. */
+  target: string;
+  /** Set only when a shell was refused: it has no file to name. */
+  command?: string;
+  /** Why, for the ledger. */
+  reason: string;
+  /** Why, in the words the agent is given — the two differ only by framing. */
+  message: string;
+  hookEventName?: string;
+}
+
+// A name this list misses is a command this hook waves through, so both sets mirror
+// the tool names VS Code's own Copilot build ships in its shell and edit tool sets.
+const SHELL_TOOLS = [
+  "bash",
+  "shell",
+  "powershell",
+  "local_shell",
+  "runinterminal",
+  "run_in_terminal",
+  "terminal",
+  "execute_command",
+];
+
+const FILE_WRITE_TOOLS = [
+  "write",
+  "edit",
+  "multiedit",
+  "write_file",
+  "apply_patch",
+  "applypatch",
+  "create",
+  "create_file",
+  "createfile",
+  "str_replace",
+  "str_replace_editor",
+  "insert",
+  "insert_edit_into_file",
+  "replace_string_in_file",
+  "multi_replace_string_in_file",
+  "replacestring",
+  "edit_notebook_file",
+  "notebookedit",
+];
+
+function isShellExec(input: SecurityInput): input is ShellExecInput {
+  return !("tool_name" in input) && !("toolName" in input) && "command" in input;
+}
+
+/** First of `keys` present as a non-empty string — agents disagree on argument spelling. */
+function firstStringArg(
+  args: Record<string, unknown>,
+  keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** Tool names that run a shell command, across every agent's naming. */
+function runsShellCommand(toolName: string): boolean {
+  return SHELL_TOOLS.includes(toolName.toLowerCase());
+}
+
+/** Tool names that write to a file, across every agent's naming. */
+function writesFile(toolName: string): boolean {
+  return FILE_WRITE_TOOLS.includes(toolName.toLowerCase());
+}
+
+/**
+ * What the gate would do with this call, or null to let it through.
+ *
+ * `cwd` is passed rather than read so a test can pin the target of a refused
+ * command, which has no file of its own to name.
+ */
+export function decideRefusal(input: SecurityInput, cwd: string): GateRefusal | null {
+  if (isShellExec(input)) {
+    const reason = checkBashCommand(input.command);
+    if (!reason) return null;
+    return {
+      tool: "shell",
+      target: cwd,
+      command: input.command,
+      reason,
+      message: `Blocked: ${reason}`,
+    };
+  }
+
+  const toolUse = normalizeToolUse(input);
+  if (!toolUse) return null;
+
+  // Each agent names its shell/write tools differently; log the real name so an
+  // unrecognized one shows up here instead of silently skipping the check.
+  logDebug(
+    "SecurityValidator",
+    `toolName=${toolUse.toolName} args=${Object.keys(toolUse.toolInput).join(",")}`
+  );
+
+  const command = firstStringArg(toolUse.toolInput, ["command", "commandLine", "script"]);
+  if (runsShellCommand(toolUse.toolName) && command) {
+    const reason = checkBashCommand(command);
+    // "No output" from a downstream tool is indistinguishable between "denied,
+    // never ran" and "ran, produced nothing" — logging the verdict here, next
+    // to the literal command, is what actually tells the two apart.
+    const verdict = reason ? `BLOCK(${reason})` : "ALLOW";
+    logDebug("SecurityValidator", `bashVerdict=${verdict} command=${command}`);
+    if (reason) {
+      return {
+        tool: toolUse.toolName,
+        target: cwd,
+        command,
+        reason,
+        message: `Blocked: ${reason}`,
+        hookEventName: toolUse.hookEventName,
+      };
+    }
+  }
+
+  const filePath = firstStringArg(toolUse.toolInput, ["file_path", "filePath", "path"]);
+  if (writesFile(toolUse.toolName) && filePath) {
+    const reason = checkFilePath(filePath);
+    if (reason) {
+      return {
+        tool: toolUse.toolName,
+        target: filePath,
+        reason,
+        message: reason,
+        hookEventName: toolUse.hookEventName,
+      };
+    }
+  }
+
+  return null;
+}

package/src/hooks/lib/session-context.ts

@@ -0,0 +1,74 @@
+/**
+ * What each agent is handed at session start, and in which envelope.
+ *
+ * The four runtimes disagree on all of it: whether AGENTS.md is already loaded,
+ * which JSON key carries injected context, and whether it is read from stdout at
+ * all. This has been wrong in production before — Copilot silently received no
+ * context for weeks — and none of it was reachable from a test.
+ */
+
+export interface ContextEnvelope {
+  /** Whether the agent parses stdout as JSON or reads it as raw text. */
+  kind: "json" | "text";
+  payload: string;
+  /** Copilot only: the same context, also written where its extension reads. */
+  file?: string;
+}
+
+/**
+ * A subagent gets none of this. Its parent already carries the context, and
+ * paying for it again on every spawn is the whole cost of a cheap subagent.
+ */
+export function isSubagentSession(env: NodeJS.ProcessEnv): boolean {
+  if (env.CLAUDE_AGENT_TYPE !== undefined) return true;
+  return env.CLAUDE_PROJECT_DIR?.includes("/.claude/Agents/") ?? false;
+}
+
+/**
+ * Copilot and Cursor read AGENTS.md natively from nothing, so it is prepended
+ * here; Codex reaches it through a symlink and Claude Code loads it itself.
+ */
+export function needsAgentsMd(agent: string): boolean {
+  return agent === "copilot" || agent === "cursor";
+}
+
+/**
+ * Copilot also writes the same text to a file, because its CLI reads stdout
+ * while the VS Code extension reads only ~/.copilot/instructions/.
+ */
+export function contextEnvelope(
+  agent: string,
+  reminder: string,
+  agentsMd: string
+): ContextEnvelope | null {
+  const merged = needsAgentsMd(agent)
+    ? [agentsMd, reminder].filter(Boolean).join("\n\n")
+    : reminder;
+  if (!merged) return null;
+
+  if (agent === "copilot") {
+    return {
+      kind: "json",
+      payload: JSON.stringify({ additionalContext: merged }),
+      file: merged,
+    };
+  }
+  if (agent === "cursor") {
+    return { kind: "json", payload: JSON.stringify({ additional_context: merged }) };
+  }
+  if (agent === "codex") {
+    return {
+      kind: "json",
+      payload: JSON.stringify({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: merged },
+      }),
+    };
+  }
+  // Claude Code, and opencode which uses the plugin path rather than this hook.
+  return { kind: "text", payload: merged };
+}
+
+/** The file Copilot's VS Code extension reads, with the applyTo header it needs. */
+export function copilotInstructions(context: string): string {
+  return `---\napplyTo: "**"\n---\n\n${context}`;
+}

package/src/hooks/lib/settings.ts

@@ -30,6 +30,8 @@ export interface PalSettingsData {
    * paths whose contents are never stored; it cannot shrink it.
    */
   ledger?: { redactPaths?: string[] };
+  /** Control-room ranking knobs and attention sources — see src/tools/control-room/prefs.ts. */
+  controlRoom?: Record<string, unknown>;
   /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
   steering?: {
     disable?: string[];