portable-agent-layer 0.36.0 → 0.38.0

package/src/hooks/lib/agent.ts

@@ -1,40 +1,42 @@
 /**
  * Agent detection and output format adapters.
  *
- * Cursor and Claude Code use different JSON contracts for hook I/O.
+ * Cursor, Codex, and Claude Code use different JSON contracts for hook I/O.
  * These helpers normalize the differences so hook handlers stay clean.
  */
 
-export type AgentType = "claude" | "cursor";
+type AgentType = "claude" | "cursor" | "codex";
 
 /** Detect which agent is running via environment variables */
-export function detectAgent(): AgentType {
+function detectAgent(): AgentType {
+  // PAL_AGENT is set explicitly in hook command prefixes — most reliable signal.
+  // IDE env vars (CURSOR_VERSION, CODEX_CLI_VERSION) are NOT reliably forwarded to
+  // hook subprocesses, so PAL_AGENT is the primary detection mechanism.
+  if (process.env.PAL_AGENT === "cursor") return "cursor";
+  if (process.env.PAL_AGENT === "codex") return "codex";
+  // Fallbacks for environments that do forward IDE env vars
   if (process.env.CURSOR_VERSION) return "cursor";
+  if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
   return "claude";
 }
 
 export const isCursor = () => detectAgent() === "cursor";
+export const isCodex = () => detectAgent() === "codex";
 
 /**
  * Format a "block this action" response for the current agent.
- * Claude Code: { decision: "block", reason }
- * Cursor:      { permission: "deny", user_message }
+ * Claude Code:       { decision: "block", reason }
+ * Cursor preToolUse: { permission: "deny", user_message }
+ * Codex PreToolUse:  { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" } }
  */
-export function blockResponse(reason: string): string {
+export function blockResponse(reason: string, hookEventName?: string): string {
   if (isCursor()) {
     return JSON.stringify({ permission: "deny", user_message: reason });
   }
-  return JSON.stringify({ decision: "block", reason });
-}
-
-/**
- * Format sessionStart context injection for the current agent.
- * Claude Code: raw text to stdout
- * Cursor:      { additional_context: "..." }
- */
-export function sessionStartOutput(context: string): string {
-  if (isCursor()) {
-    return JSON.stringify({ additional_context: context });
+  if (isCodex() && hookEventName === "PreToolUse") {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" },
+    });
   }
-  return context;
+  return JSON.stringify({ decision: "block", reason });
 }

package/src/hooks/lib/context.ts

@@ -12,12 +12,10 @@ import { paths } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
 import { loadFailurePatterns, loadSynthesisRecommendations } from "./semi-static";
-import { readSessionNames } from "./session-names";
 import * as settings from "./settings";
-import { isSetupComplete, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
-import { readProjectHistory, readSessions } from "./work-tracking";
+import { readProjectHistory } from "./work-tracking";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -41,89 +39,6 @@ function loadStartupFiles(): string {
   return sections.join("\n\n---\n\n");
 }
 
-/** Count lines in a signals JSONL file */
-export function countSignals(filename: string): number {
-  const filepath = resolve(paths.signals(), filename);
-  if (!existsSync(filepath)) return 0;
-  try {
-    const content = readFileSync(filepath, "utf-8").trim();
-    return content ? content.split("\n").length : 0;
-  } catch {
-    return 0;
-  }
-}
-
-/** Load the N most recent session names (fallback for greeting) */
-export function loadRecentSessions(count: number): string[] {
-  try {
-    const sessions = readSessions();
-    if (sessions.length > 0) {
-      return sessions
-        .slice(-count)
-        .reverse()
-        .map((s) => s.name);
-    }
-    // Fallback to session-names.json for backwards compat
-    const names = readSessionNames();
-    const entries = Object.values(names);
-    return entries.slice(-count).reverse();
-  } catch {
-    return [];
-  }
-}
-
-/** Read cached counts from counts.json, falling back to live counting */
-function loadCachedCounts(): {
-  signals: number;
-  telos: number;
-  skills: number;
-  sessions: number;
-} {
-  try {
-    const countsPath = resolve(paths.state(), "counts.json");
-    if (existsSync(countsPath)) {
-      return JSON.parse(readFileSync(countsPath, "utf-8"));
-    }
-  } catch {
-    /* fall through */
-  }
-  // Fallback: count live (first session before any stop has run)
-  return {
-    signals: countSignals("ratings.jsonl"),
-    telos: 0,
-    skills: 0,
-    sessions: 0,
-  };
-}
-
-/** Build the visible greeting lines for stderr */
-export function buildGreeting(): string[] {
-  const counts = loadCachedCounts();
-  const setupState = readSetupState();
-  const setupIncomplete = setupState && !isSetupComplete(setupState);
-
-  const greeting: string[] = [];
-
-  if (setupIncomplete) {
-    const done = STEP_ORDER.length - remainingSteps(setupState).length;
-    greeting.push(
-      `🔧 PAL setup ${done}/${STEP_ORDER.length} | ${counts.signals} signals`
-    );
-  } else {
-    greeting.push(
-      `✅ PAL ready | ${counts.telos} TELOS | ${counts.skills} skills | ${counts.signals} signals | ${counts.sessions} sessions`
-    );
-  }
-
-  // Show recent session names for quick context
-  const recent = loadRecentSessions(3);
-  if (recent.length > 0) {
-    greeting.push(`📂 Recent: ${recent.join(" | ")}`);
-  }
-
-  return greeting;
-}
-
 /** Load high-confidence wisdom principles for injection into system-reminder */
 export function loadWisdomContext(): string {
   try {
@@ -159,7 +74,7 @@ export function loadLearningDigest(): string {
 }
 
 /** Load self-model for session context injection */
-export function loadSelfModel(): string {
+function loadSelfModel(): string {
   try {
     const p = resolve(paths.memory(), "self-model", "current.md");
     if (!existsSync(p)) return "";
@@ -181,7 +96,7 @@ export function loadSignalTrends(): string {
 }
 
 /** Load per-project session history for the current working directory */
-export function loadProjectHistoryContext(): string {
+function loadProjectHistoryContext(): string {
   try {
     const cwd = process.cwd();
     const entries = readProjectHistory(cwd, 3);
@@ -199,16 +114,46 @@ export function loadProjectHistoryContext(): string {
   }
 }
 
-/** Load recent relationship notes (today + yesterday) */
+/**
+ * Filter raw relationship note lines:
+ * - O entries: stripped (loaded natively via digest)
+ * - HTML comments: stripped, but cwd is extracted from session comments
+ * - Session entries: kept only if block cwd matches current project (or legacy with no cwd)
+ * - W entries and structural lines: always kept
+ */
+function filterRelationshipNotes(notes: string, cwd: string): string {
+  const lines = notes.split("\n");
+  const out: string[] = [];
+  let blockCwd: string | null = null;
+
+  for (const line of lines) {
+    if (/^## \d{2}:\d{2}/.test(line)) {
+      blockCwd = null;
+      out.push(line);
+      continue;
+    }
+    const cwdMatch = new RegExp(/<!--.*cwd:(\S+)/).exec(line);
+    if (cwdMatch) {
+      blockCwd = cwdMatch[1];
+      continue;
+    }
+    if (/^\s*<!--/.test(line)) continue;
+    if (/^\s*- O\(/.test(line)) continue;
+    if (/^\s*- Session:/.test(line)) {
+      if (blockCwd === null || blockCwd === cwd) out.push(line);
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/** Load recent relationship notes (today + yesterday), scoped to current project */
 export function loadRelationshipContext(): string {
   try {
     const notes = loadRecentNotes(2);
     if (!notes) return "";
-    // Strip O entries (opinions loaded natively via digest) and HTML comment lines
-    const filtered = notes
-      .split("\n")
-      .filter((l) => !/^\s*- O\(/.test(l) && !/^\s*<!--/.test(l))
-      .join("\n");
+    const filtered = filterRelationshipNotes(notes, process.cwd());
     return capSection(`## Recent Interaction Notes\n${filtered}`, 1500);
   } catch {
     return "";
@@ -216,7 +161,7 @@ export function loadRelationshipContext(): string {
 }
 
 /** Load session intelligence from compact synthesis state */
-export function loadSessionIntelligence(): string {
+function loadSessionIntelligence(): string {
   try {
     const p = resolve(paths.state(), "synthesis.json");
     if (!existsSync(p)) return "";
@@ -224,30 +169,13 @@ export function loadSessionIntelligence(): string {
 
     const lines: string[] = ["## Session Intelligence"];
 
-    // Open Threads — project-specific only
-    if (state.threads?.length > 0) {
-      const cwd = process.cwd();
-      const here = state.threads.filter((t: { cwd?: string }) => t.cwd === cwd);
-
-      if (here.length > 0) {
-        lines.push("");
-        lines.push(`**Open threads — this project (${here.length}):**`);
-        for (const t of here) {
-          lines.push(`- ${t.title} (opened ${t.opened})`);
-          if (t.context) lines.push(`  ${t.context}`);
-        }
-        lines.push(
-          "→ Continue this work or explicitly close it before starting something new."
-        );
-      }
-    }
-
     // Rating Trend
     if (state.ratings?.count > 0) {
       const r = state.ratings;
-      lines.push("");
+      const lowNote = r.lowCount > 0 ? ` ${r.lowCount} low ratings.` : "";
       lines.push(
-        `**Rating trend:** ${r.avg}/10 avg (last 10: ${r.recentAvg}/10, ${r.trend}).${r.lowCount > 0 ? ` ${r.lowCount} low ratings.` : ""}`
+        "",
+        `**Rating trend:** ${r.avg}/10 avg (last 10: ${r.recentAvg}/10, ${r.trend}).${lowNote}`
       );
       if (r.trend === "declining") {
         lines.push(
@@ -265,8 +193,8 @@ export function loadSessionIntelligence(): string {
     // Algorithm Performance
     if (state.algorithm?.reflectionCount > 0) {
       const a = state.algorithm;
-      lines.push("");
       lines.push(
+        "",
         `**Algorithm:** ${a.reflectionCount} reflections, ${a.passRate}% criteria pass rate, ${a.avgSentiment}/10 sentiment.`
       );
       if (a.passRate < 80) {
@@ -295,7 +223,7 @@ export function loadSessionIntelligence(): string {
 }
 
 /** Load handoff state for the current project */
-export function loadHandoff(): string {
+function loadHandoff(): string {
   try {
     const p = resolve(paths.state(), "last-handoff.json");
     if (!existsSync(p)) return "";

package/src/hooks/lib/entities.ts

@@ -12,7 +12,7 @@ import { ensureDir, paths } from "./paths";
 
 // --- Types ---
 
-export interface PersonEntity {
+interface PersonEntity {
   id: string;
   name: string;
   first_seen: string;
@@ -20,7 +20,7 @@ export interface PersonEntity {
   source_ids: string[];
 }
 
-export interface CompanyEntity {
+interface CompanyEntity {
   id: string;
   name: string;
   domain: string | null;
@@ -29,7 +29,7 @@ export interface CompanyEntity {
   source_ids: string[];
 }
 
-export interface LinkEntity {
+interface LinkEntity {
   id: string;
   url: string;
   first_seen: string;
@@ -37,7 +37,7 @@ export interface LinkEntity {
   source_ids: string[];
 }
 
-export interface SourceEntity {
+interface SourceEntity {
   id: string;
   url: string | null;
   author: string | null;
@@ -47,7 +47,7 @@ export interface SourceEntity {
   source_ids: string[];
 }
 
-export interface EntityIndex {
+interface EntityIndex {
   version: string;
   last_updated: string;
   people: Record<string, PersonEntity>;
@@ -100,8 +100,8 @@ function emptyIndex(): EntityIndex {
 
 /** Migrate older indexes that lack links/sources. */
 function ensureShape(index: EntityIndex): EntityIndex {
-  if (!index.links) index.links = {};
-  if (!index.sources) index.sources = {};
+  index.links ??= {};
+  index.sources ??= {};
   return index;
 }
 

package/src/hooks/lib/frontmatter.ts

@@ -5,7 +5,7 @@
  * Supports strings, numbers, booleans, and inline JSON arrays.
  */
 
-export interface Parsed<T = Record<string, string>> {
+interface Parsed<T = Record<string, string>> {
   meta: T;
   body: string;
 }
@@ -30,7 +30,7 @@ export function parse<T = Record<string, string>>(content: string): Parsed<T> {
 
   const meta: Record<string, unknown> = {};
   for (const line of rawMeta.split("\n")) {
-    const match = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    const match = new RegExp(/^(\w[\w-]*)\s*:\s*(.*)$/).exec(line);
     if (!match) continue;
     const [, key, rawValue] = match;
     const value = rawValue.trim();
@@ -50,7 +50,7 @@ export function parse<T = Record<string, string>>(content: string): Parsed<T> {
       (value.startsWith('"') && value.endsWith('"')) ||
       (value.startsWith("'") && value.endsWith("'"))
     ) {
-      meta[key] = value.slice(1, -1).replace(/\\"/g, '"');
+      meta[key] = value.slice(1, -1).replaceAll('\\"', '"');
       continue;
     }
 
@@ -77,7 +77,7 @@ export function stringify(meta: Record<string, unknown>, body: string): string {
     if (Array.isArray(value)) {
       lines.push(`${key}: ${JSON.stringify(value)}`);
     } else if (typeof value === "string") {
-      lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
+      lines.push(`${key}: "${value.replaceAll('"', '\\"')}"`);
     } else {
       lines.push(`${key}: ${String(value)}`);
     }

package/src/hooks/lib/graduation.ts

@@ -12,6 +12,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { hasApiKey } from "./inference";
 import {
   type FailureEntry,
   type LearningEntry,
@@ -24,14 +25,14 @@ import { extractKeywords, similarity } from "./text-similarity";
 
 // ── Types ──
 
-export interface AnalysisEntry {
+interface AnalysisEntry {
   source: string;
   path: string;
   text: string;
   date: string;
 }
 
-export interface PatternGroup {
+interface PatternGroup {
   pattern: string;
   entries: AnalysisEntry[];
   domain: string;
@@ -51,7 +52,7 @@ interface GraduationState {
   graduated: GraduatedEntry[];
 }
 
-export interface RatingsSummary {
+interface RatingsSummary {
   total: number;
   average: number;
   low: { count: number; examples: string[] };
@@ -125,7 +126,7 @@ function toAnalysisEntries(
 
 function isActionable(text: string): boolean {
   const trimmed = text.trim();
-  if (/\?[\s]*$/.test(trimmed)) return false;
+  if (/\?\s*$/.test(trimmed)) return false;
   if (extractKeywords(trimmed).size < 4) return false;
   return true;
 }
@@ -214,7 +215,7 @@ async function generateRecommendations(
   ratings: RatingsSummary | null
 ): Promise<string[]> {
   if (candidates.length === 0 && !ratings) return [];
-  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+  if (!hasApiKey()) {
     return candidates
       .slice(0, 3)
       .map(
@@ -298,7 +299,7 @@ function writeState(state: GraduationState): void {
 function synthesizePrinciple(group: PatternGroup): string {
   const sorted = [...group.entries].sort((a, b) => a.text.length - b.text.length);
   let principle = sorted[0].text;
-  const firstSentence = principle.match(/^[^.!?]+[.!?]?/);
+  const firstSentence = new RegExp(/^[^.!?]+[.!?]?/).exec(principle);
   if (firstSentence) principle = firstSentence[0];
   if (principle.length > 120) principle = `${principle.slice(0, 117)}...`;
   return principle.trim();
@@ -306,7 +307,7 @@ function synthesizePrinciple(group: PatternGroup): string {
 
 // ── Main Analysis ──
 
-export interface AnalyzeOptions {
+interface AnalyzeOptions {
   /** Generate actionable recommendations via inference. Default: false (patterns only). */
   actionable?: boolean;
 }

package/src/hooks/lib/inference.ts

@@ -4,7 +4,11 @@
 
 import { HAIKU_MODEL } from "./models";
 
-export interface InferenceOptions {
+export function hasApiKey(): boolean {
+  return !!process.env.PAL_ANTHROPIC_API_KEY;
+}
+
+interface InferenceOptions {
   system?: string;
   user: string;
   model?: string;
@@ -14,7 +18,7 @@ export interface InferenceOptions {
   jsonSchema?: Record<string, unknown>;
 }
 
-export interface InferenceResult {
+interface InferenceResult {
   success: boolean;
   output?: string;
   usage?: { inputTokens: number; outputTokens: number };

package/src/hooks/lib/learning-category.ts

@@ -3,7 +3,7 @@
  * Used by both learning.ts and work-learning.ts handlers.
  */
 
-export type LearningCategory = "system" | "algorithm";
+type LearningCategory = "system" | "algorithm";
 
 const SYSTEM_KEYWORDS =
   /\b(config|setting|install|deploy|build|lint|format|biome|typescript|tsc|hook|plugin|ci|cd|pipeline|docker|package|dependency|migration|schema|database|env|permission|security|git|commit|branch|merge)\b/i;

package/src/hooks/lib/learning-store.ts

@@ -19,6 +19,7 @@ export interface FailureEntry {
   principle: string;
   date: string;
   ts: string;
+  cwd: string;
 }
 
 export interface LearningEntry {
@@ -76,6 +77,7 @@ export function readFailures(baseDir: string, limit?: number): FailureEntry[] {
             date?: string;
             ts?: string;
             slug?: string;
+            cwd?: string;
           }>(content);
 
           if (!meta.context) continue;
@@ -88,6 +90,7 @@ export function readFailures(baseDir: string, limit?: number): FailureEntry[] {
             principle: meta.principle || "",
             date: meta.date || (meta.ts ? String(meta.ts).slice(0, 10) : ""),
             ts: meta.ts ? String(meta.ts) : "",
+            cwd: meta.cwd || "",
           });
 
           if (limit && entries.length >= limit) return entries;
@@ -128,7 +131,9 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
           if (!meta.title) continue;
 
-          const insightsMatch = body.match(/## Insights\n([\s\S]*?)(?=\n##|$)/);
+          const insightsMatch = new RegExp(/## Insights\n([\s\S]*?)(?=\n##|$)/).exec(
+            body
+          );
 
           entries.push({
             filename: file,

package/src/hooks/lib/notify.ts

@@ -20,11 +20,11 @@ function spawnSilent(cmd: string, args: string[]): Promise<void> {
 }
 
 function escapeAppleScript(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return s.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
 }
 
 function escapePowerShellSingle(s: string): string {
-  return s.replace(/'/g, "''");
+  return s.replaceAll("'", "''");
 }
 
 export async function notify(title: string, body: string): Promise<void> {

package/src/hooks/lib/opinions.ts

@@ -18,13 +18,13 @@ import { similarity } from "./text-similarity";
 export type EvidenceType = "supporting" | "counter" | "confirmation" | "contradiction";
 export type OpinionCategory = "communication" | "technical" | "workflow" | "general";
 
-export interface Evidence {
+interface Evidence {
   date: string;
   type: EvidenceType;
   source: string;
 }
 
-export interface Opinion {
+interface Opinion {
   id: string;
   statement: string;
   confidence: number;
@@ -145,7 +145,7 @@ export function createOpinion(statement: string, source: string): Opinion {
 }
 
 /** Check if an opinion already has evidence with this exact source text. */
-export function hasEvidence(opinion: Opinion, source: string): boolean {
+function hasEvidence(opinion: Opinion, source: string): boolean {
   return opinion.evidence.some((e) => e.source === source);
 }
 

package/src/hooks/lib/paths.ts

@@ -54,6 +54,7 @@ export const paths = {
   projectHistory: () => ensureDir(home("memory", "projects")),
   sessionLearning: () => ensureDir(home("memory", "learning", "session")),
   synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
+  work: () => ensureDir(home("memory", "work")),
   backups: () => ensureDir(home("backups")),
 } as const;
 
@@ -78,6 +79,7 @@ export const assets = {
   claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
+  codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
   agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;