portable-agent-layer 0.71.0 → 0.72.0

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/tools/agent/algorithm-reflect.ts

@@ -15,87 +15,36 @@
 
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
-import { encodeAnchor } from "../../hooks/lib/anchor";
 import { paths } from "../../hooks/lib/paths";
+import { buildReflection, intOr, reflectionLine } from "../lib/algorithm-reflect";
 import { emit } from "../lib/emit";
 
-// ── Types ──
+const HELP = `
+AlgorithmReflect — Log algorithm performance after LEARN phase
 
-interface AlgorithmReflection extends RecordAttribution {
-  timestamp: string;
-  cwd: string;
-  task: string;
-  criteria_count: number;
-  criteria_passed: number;
-  criteria_failed: number;
-  sentiment: number;
-  q1: string;
-  q2: string;
-  q3: string;
-  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
-  scope: "general" | "task-specific";
-}
+Usage:
+  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
+    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+
+Arguments:
+  --task        Brief task description
+  --criteria    Total criteria count
+  --passed      Criteria passed
+  --failed      Criteria failed
+  --sentiment   Implied satisfaction 1-10
+  --q1          Q1 — Self: what I'd do differently
+  --q2          Q2 — Algorithm: structural improvement
+  --q3          Q3 — AI: reasoning blind spot
+  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
 
-// ── Core ──
+Output: algorithm-reflections.jsonl in memory/learning/reflections/
+`;
 
 function reflectionsPath(): string {
-  paths.reflections(); // ensures the directory exists
+  paths.reflections();
   return paths.reflectionsFile();
 }
 
-/**
- * Assemble a reflection record from CLI-style input, stamping the current
- * cwd (anchored) and this machine's id. Exported so the stamping logic is
- * directly testable without going through argv parsing.
- */
-export function buildReflection(input: {
-  task: string;
-  q1: string;
-  q2: string;
-  q3: string;
-  criteria_count?: number;
-  criteria_passed?: number;
-  criteria_failed?: number;
-  sentiment?: number;
-  scope?: string;
-}): AlgorithmReflection {
-  return {
-    timestamp: new Date().toISOString(),
-    cwd: encodeAnchor(process.cwd()),
-    ...currentAttribution(),
-    task: input.task,
-    criteria_count: input.criteria_count ?? 0,
-    criteria_passed: input.criteria_passed ?? 0,
-    criteria_failed: input.criteria_failed ?? 0,
-    sentiment: Math.max(1, Math.min(10, input.sentiment ?? 5)),
-    q1: input.q1,
-    q2: input.q2,
-    q3: input.q3,
-    // Default to general (the ~94% case); only "task-specific" suppresses it
-    // from algorithm-update clustering.
-    scope: input.scope === "task-specific" ? "task-specific" : "general",
-  };
-}
-
-function appendReflection(reflection: AlgorithmReflection): {
-  success: boolean;
-  message: string;
-  path: string;
-} {
-  const p = reflectionsPath();
-  const line = `${JSON.stringify(reflection)}\n`;
-  appendFileSync(p, line, "utf-8");
-
-  return {
-    success: true,
-    message: `Reflection logged: ${reflection.criteria_passed}/${reflection.criteria_count} passed, sentiment ${reflection.sentiment}/10`,
-    path: p,
-  };
-}
-
-// ── CLI ──
-
 function run() {
   const { values } = parseArgs({
     args: Bun.argv.slice(2),
@@ -114,26 +63,7 @@ function run() {
   });
 
   if (values.help) {
-    console.log(`
-AlgorithmReflect — Log algorithm performance after LEARN phase
-
-Usage:
-  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
-    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
-
-Arguments:
-  --task        Brief task description
-  --criteria    Total criteria count
-  --passed      Criteria passed
-  --failed      Criteria failed
-  --sentiment   Implied satisfaction 1-10
-  --q1          Q1 — Self: what I'd do differently
-  --q2          Q2 — Algorithm: structural improvement
-  --q3          Q3 — AI: reasoning blind spot
-  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
-
-Output: algorithm-reflections.jsonl in memory/learning/reflections/
-`);
+    console.log(HELP);
     process.exit(0);
   }
 
@@ -147,15 +77,16 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
     q1: values.q1,
     q2: values.q2,
     q3: values.q3,
-    criteria_count: parseInt(values.criteria || "0", 10),
-    criteria_passed: parseInt(values.passed || "0", 10),
-    criteria_failed: parseInt(values.failed || "0", 10),
-    sentiment: parseInt(values.sentiment || "5", 10),
+    criteria_count: intOr(values.criteria, 0),
+    criteria_passed: intOr(values.passed, 0),
+    criteria_failed: intOr(values.failed, 0),
+    sentiment: intOr(values.sentiment, 5),
     scope: values.scope,
   });
 
-  const result = appendReflection(reflection);
-  emit.receipt(result.path, {
+  const path = reflectionsPath();
+  appendFileSync(path, reflectionLine(reflection), "utf-8");
+  emit.receipt(path, {
     passed: reflection.criteria_passed,
     of: reflection.criteria_count,
     scope: reflection.scope,

package/src/tools/agent/analyze.ts

@@ -5,130 +5,17 @@
  * Reads failures and session learnings, finds recurring patterns,
  * summarizes ratings, and generates recommendations.
  *
+ * What the report says is in lib/analyze-report.ts.
+ *
  * Usage: bun run tool:analyze
  */
 
 import { parseArgs } from "node:util";
 import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
-import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
-
-// ── ANSI Colors ──
-
-const c = {
-  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
-  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
-  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
-  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
-  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
-  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
-  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
-};
-
-function printReport(result: AnalysisResult): void {
-  const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
-  const hasRatings = result.ratings !== null;
-
-  if (!hasPatterns && !hasRatings) {
-    console.log("\n  No patterns or ratings data found.\n");
-    return;
-  }
-
-  if (result.ratings) {
-    const r = result.ratings;
-    const lowOrMid = r.average <= 4 ? c.red : c.yellow;
-    const avgColor = r.average >= 7 ? c.green : lowOrMid;
-    const ratingStr = `${r.average.toFixed(1)}/10`;
-    const lowStr = `Low (≤4): ${r.low.count}`;
-    const highStr = `High (≥7): ${r.high.count}`;
-    console.log(
-      `\n  ${c.bold("Ratings:")} ${avgColor(ratingStr)} avg (${r.total} total)`
-    );
-    console.log(`  ${c.red(lowStr)} | ${c.green(highStr)}`);
-  }
-
-  if (result.candidates.length > 0) {
-    const graduationHeader = `Graduation Report — ${result.candidates.length} pattern(s) detected`;
-    console.log(`\n  ${c.bold(c.green(graduationHeader))}\n`);
-    console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
-
-    for (const candidate of result.candidates) {
-      const domain = `[${candidate.domain}]`;
-      const count = `${candidate.entries.length}x`;
-      console.log(`  ${c.cyan(domain)} ${c.bold(count)} occurrences`);
-      console.log("");
-
-      for (const entry of candidate.entries) {
-        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-        const tag =
-          sourceType === "failure"
-            ? c.red(`[${sourceType}]`)
-            : c.yellow(`[${sourceType}]`);
-        console.log(
-          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 100)}`
-        );
-      }
-
-      console.log(`\n  ${c.dim("Files:")}`);
-      for (const entry of candidate.entries) {
-        console.log(`    ${c.dim(entry.path)}`);
-      }
-
-      console.log("");
-      const framePath = `memory/wisdom/frames/${candidate.domain}.md`;
-      console.log(`  Target frame: ${c.magenta(framePath)}`);
-      console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
-    }
-  }
-
-  if (result.emerging.length > 0) {
-    console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
-    for (const group of result.emerging) {
-      const domain = `[${group.domain}]`;
-      const count = `${group.entries.length}x`;
-      console.log(`  ${c.cyan(domain)} ${c.bold(count)}`);
-      for (const entry of group.entries) {
-        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-        const tag =
-          sourceType === "failure"
-            ? c.red(`[${sourceType}]`)
-            : c.yellow(`[${sourceType}]`);
-        console.log(
-          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 80)}`
-        );
-      }
-      console.log("  Files:");
-      for (const entry of group.entries) {
-        console.log(`    ${c.dim(entry.path)}`);
-      }
-      console.log("");
-    }
-  }
-
-  if (result.recommendations.length > 0) {
-    console.log(`  ${c.bold("Recommendations:")}\n`);
-    for (const rec of result.recommendations) {
-      console.log(`    ${rec}`);
-    }
-    console.log("");
-  }
-
-  if (result.candidates.length > 0) {
-    console.log(`  To crystallize: add a line to the wisdom frame file.`);
-    console.log(`  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`);
-  }
-}
+import { analyze } from "../../hooks/lib/graduation";
+import { reportLines } from "../lib/analyze-report";
 
-export async function run(argv: string[] = Bun.argv.slice(2)) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      help: { type: "boolean", short: "h" },
-      actionable: { type: "boolean", short: "a" },
-    },
-  });
-
-  if (values.help) {
-    console.log(`
+const HELP = `
   PAL Learning Analysis — unified graduation + ratings report
 
   Reads all captured failures (rating ≤3) and session learnings,
@@ -147,12 +34,24 @@ export async function run(argv: string[] = Bun.argv.slice(2)) {
     - Your principle here [CRYSTAL: 85%]
 
   Usage: pal cli analyze [--actionable]
-`);
+`;
+
+export async function run(argv: string[] = Bun.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      help: { type: "boolean", short: "h" },
+      actionable: { type: "boolean", short: "a" },
+    },
+  });
+
+  if (values.help) {
+    console.log(HELP);
     process.exit(0);
   }
 
   const result = await analyze({ actionable: values.actionable });
-  printReport(result);
+  for (const line of reportLines(result)) console.log(line);
   writeLastAnalyzeDate(new Date().toISOString());
 }