portable-agent-layer 0.61.4 → 0.62.0

package/assets/schema/pal-settings.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
+  "title": "PAL settings",
+  "description": "Configuration for the Portable Agent Layer. Lives at ~/.pal/memory/pal-settings.json. All sections are optional; PAL falls back to defaults for anything absent.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference — enables editor autocomplete, validation, and hover docs."
+    },
+    "identity": {
+      "type": "object",
+      "description": "Who the assistant is and who it serves.",
+      "additionalProperties": false,
+      "properties": {
+        "ai": {
+          "type": "object",
+          "description": "The assistant's persona.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "Short name (e.g. the name you call the assistant)." },
+            "fullName": { "type": "string", "description": "Full/formal name." },
+            "displayName": { "type": "string", "description": "Uppercase label used in headers." },
+            "catchphrase": { "type": "string", "description": "Greeting line. '{name}' is substituted with the ai.name value." }
+          }
+        },
+        "principal": {
+          "type": "object",
+          "description": "The human the assistant works for.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "The principal's name." },
+            "timezone": { "type": "string", "description": "IANA timezone (e.g. Europe/Budapest)." }
+          }
+        }
+      }
+    },
+    "loadAtStartup": {
+      "type": "object",
+      "description": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "array",
+          "description": "Absolute or PAL-relative file paths to inject at session start.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "dynamicContext": {
+      "type": "object",
+      "description": "Dynamic context sections injected at session start. Set any key to false to disable it; absent keys default to enabled.",
+      "additionalProperties": { "type": "boolean" },
+      "properties": {
+        "wisdom": { "type": "boolean", "description": "Crystallized wisdom principles." },
+        "opinions": { "type": "boolean", "description": "Tracked user opinions." },
+        "relationship": { "type": "boolean", "description": "Recent relationship notes." },
+        "learningDigest": { "type": "boolean", "description": "Lessons-from-failures digest." },
+        "failurePatterns": { "type": "boolean", "description": "Recurring failure patterns." },
+        "projectHistory": { "type": "boolean", "description": "Per-project session history." },
+        "projects": { "type": "boolean", "description": "Active projects list." },
+        "sessionIntelligence": { "type": "boolean", "description": "Rating trends and session signals." },
+        "handoff": { "type": "boolean", "description": "Handoff note from the previous session." },
+        "selfModel": { "type": "boolean", "description": "The assistant's self-model synthesis." },
+        "contextualSteering": { "type": "boolean", "description": "Prompt-time steering self-checks (see the steering section)." },
+        "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
+      }
+    },
+    "attribution": {
+      "type": "object",
+      "description": "Git co-author attribution opt-in.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Add the PAL co-author trailer to commits." },
+        "decided": { "type": "boolean", "description": "Gates the one-time attribution prompt." }
+      }
+    },
+    "steering": {
+      "type": "object",
+      "description": "Contextual steering: PAL injects a short self-check into your prompt when it matches a task type. Toggle the whole feature via dynamicContext.contextualSteering.",
+      "additionalProperties": false,
+      "properties": {
+        "disable": {
+          "type": "array",
+          "description": "Shipped steering rules to suppress, by tag.",
+          "items": {
+            "type": "string",
+            "enum": ["debugging", "destructive", "refactor", "planning", "testing", "committing", "secrets"]
+          },
+          "uniqueItems": true
+        },
+        "rules": {
+          "type": "array",
+          "description": "Personal steering rules appended to the shipped set. A malformed entry (missing field or bad regex) is skipped, never fatal.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tag", "pattern", "snippet"],
+            "properties": {
+              "tag": { "type": "string", "description": "Short identifier for this rule (also used to dedupe matches)." },
+              "pattern": { "type": "string", "description": "JavaScript regex source, matched case-insensitively against the prompt." },
+              "snippet": { "type": "string", "description": "The self-check text injected when the pattern matches." }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/assets/templates/hooks.copilot.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "agentStop": [

package/assets/templates/hooks.cursor.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "beforeShellExecution": [

package/assets/templates/pal-settings.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
   "identity": {
     "ai": {
       "name": "",
@@ -12,11 +13,9 @@
     }
   },
   "loadAtStartup": {
-    "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
     "files": []
   },
   "dynamicContext": {
-    "_docs": "Dynamic context sections injected at session start. Set to false to disable.",
     "wisdom": true,
     "opinions": true,
     "relationship": true,
@@ -26,6 +25,12 @@
     "projects": true,
     "sessionIntelligence": true,
     "handoff": true,
-    "selfModel": true
+    "selfModel": true,
+    "contextualSteering": true,
+    "steeringTestReport": false
+  },
+  "steering": {
+    "disable": [],
+    "rules": []
   }
 }

package/assets/templates/settings.claude.json

@@ -108,6 +108,15 @@
             "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

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

package/src/cli/index.ts

@@ -622,6 +622,13 @@ function nodeInstallHint(): string {
   return "install Node ≥ 22.6 (see https://nodejs.org or your package manager)";
 }
 
+function rtkInstallHint(): string {
+  if (process.platform === "win32")
+    return "download rtk.exe from https://github.com/rtk-ai/rtk/releases and add it to PATH";
+  if (process.platform === "darwin") return "`brew install rtk`";
+  return "`curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh`";
+}
+
 function checkHookHealth(home: string): HookHealth {
   const stateDir = resolve(home, "memory", "state");
   // Read current + all rotated logs (`.1`..`.5`) + legacy `.prev` so a recent
@@ -671,6 +678,7 @@ interface DoctorResult {
   cursor: ToolCheck;
   copilot: ToolCheck;
   codex: ToolCheck;
+  rtk: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -684,6 +692,7 @@ function doctor(silent = false): DoctorResult {
       cursor: { name: "cursor", available: true },
       copilot: { name: "copilot", available: true },
       codex: { name: "codex", available: true },
+      rtk: { name: "rtk", available: true },
       hasAgent: true,
     };
   }
@@ -694,6 +703,7 @@ function doctor(silent = false): DoctorResult {
   const cursor = checkTool("cursor");
   const copilot = checkTool("copilot", ["version"]);
   const codex = checkTool("codex");
+  const rtk = checkTool("rtk");
   const hasAgent =
     claude.available ||
     opencode.available ||
@@ -751,6 +761,11 @@ function doctor(silent = false): DoctorResult {
       : fail(
           "Playwright Chromium — not found (run 'pal cli install' or 'bunx playwright install chromium')"
         );
+    rtk.available
+      ? ok(rtk.version || "rtk")
+      : info(
+          `rtk — not installed (optional; enables Bash output compression — ${rtkInstallHint()})`
+        );
 
     console.log("");
     log.info("PAL state");
@@ -1023,7 +1038,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, cursor, copilot, codex, hasAgent };
+  return { bun, claude, opencode, cursor, copilot, codex, rtk, hasAgent };
 }
 
 // ── Commands ──

package/src/hooks/RtkWrap.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook: PreToolUse — transparently wraps Bash commands in `rtk` to compress
+ * tool output before it reaches the model's context.
+ *
+ * PAL owns the wiring + presence-gating; rtk owns the rewrite. We do NOT
+ * reimplement rtk's selectivity or per-agent JSON shape — we forward the hook's
+ * stdin to `rtk hook <agent>` and pass its stdout straight back. rtk emits the
+ * correct rewrite object for each agent (Claude/Cursor/Copilot all differ), or
+ * nothing when a command isn't worth rewriting.
+ *
+ * Fail-open by construction: if rtk isn't installed, the agent can't rewrite,
+ * or anything throws, we emit nothing and exit 0 — the original command runs
+ * unchanged. rtk absent must never block or alter a Bash call.
+ *
+ * Codex (allow/deny only) and opencode (plugin path) have no `rtk hook`
+ * subcommand and are handled elsewhere — this hook no-ops for them.
+ */
+
+import { getActiveAgent } from "./lib/agent";
+import { findBinaryOnPath } from "./lib/which";
+
+const RTK_HOOK_SUBCOMMAND: Partial<Record<ReturnType<typeof getActiveAgent>, string>> = {
+  claude: "claude",
+  cursor: "cursor",
+  copilot: "copilot",
+};
+
+async function run(): Promise<void> {
+  const subcommand = RTK_HOOK_SUBCOMMAND[getActiveAgent()];
+  if (!subcommand) return; // codex/opencode — no rtk hook processor
+
+  const rtk = findBinaryOnPath("rtk");
+  if (!rtk) return; // fail-open: rtk not installed → command runs unchanged
+
+  const stdin = await Bun.stdin.text();
+  const proc = Bun.spawn([rtk, "hook", subcommand], {
+    stdin: Buffer.from(stdin),
+    stdout: "pipe",
+    stderr: "ignore", // drop rtk's "no hook installed" stderr nag
+  });
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+  if (proc.exitCode === 0 && out) {
+    process.stdout.write(out);
+  }
+}
+
+try {
+  await run();
+} catch {
+  // Fail open — emit nothing, allow the original command.
+}

package/src/hooks/UserPromptOrchestrator.ts

@@ -7,7 +7,7 @@
  *  - session-name: generate 4-word session headline on first prompt
  */
 
-import { injectRetrieval } from "./handlers/inject-retrieval";
+import { injectPromptContext } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
 import { logDebug, logError, logPromptSnapshot } from "./lib/log";
@@ -30,8 +30,8 @@ logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)
 if (!input?.prompt) process.exit(0);
 
 const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
-const retrieval = await injectRetrieval(input.prompt);
-logPromptSnapshot(input.prompt, retrieval);
+const injected = await injectPromptContext(input.prompt);
+logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([
   captureRating(input.prompt, sessionId),

package/src/hooks/handlers/inject-retrieval.ts

@@ -12,6 +12,7 @@ import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
+import { getSteeringReminder } from "../lib/steering";
 
 const TIMEOUT_MS = 250;
 
@@ -51,12 +52,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
   return result.reminder;
 }
 
-/** Write retrieval reminder to stdout in the correct format for the current agent.
+/** Write a reminder to stdout in the correct format for the current agent.
  *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON.
- *  Returns the reminder string that was injected, or null if nothing was injected. */
-export async function injectRetrieval(prompt: string): Promise<string | null> {
-  const reminder = await getRetrievalReminder(prompt);
-  if (!reminder) return null;
+ *  MUST be called at most once per hook run — Cursor/Codex expect a single JSON
+ *  object on stdout, so all prompt-time context is merged before this call. */
+function writeForAgent(reminder: string): void {
   if (isCursor()) {
     process.stdout.write(JSON.stringify({ additional_context: reminder }));
   } else if (isCodex()) {
@@ -71,5 +71,17 @@ export async function injectRetrieval(prompt: string): Promise<string | null> {
   } else {
     process.stdout.write(`${reminder}\n`);
   }
-  return reminder;
+}
+
+/** Gather all prompt-time context — prior-lesson retrieval + contextual steering —
+ *  merge into a single payload, and do the one per-agent write. Returns the combined
+ *  reminder that was injected, or null if there was nothing to inject. */
+export async function injectPromptContext(prompt: string): Promise<string | null> {
+  const retrieval = await getRetrievalReminder(prompt);
+  const steering = getSteeringReminder(prompt);
+  const parts = [steering, retrieval].filter((p): p is string => Boolean(p));
+  if (parts.length === 0) return null;
+  const combined = parts.join("\n\n");
+  writeForAgent(combined);
+  return combined;
 }

package/src/hooks/lib/inference.ts

@@ -20,8 +20,7 @@
  * yet wired and currently fall through to the API path.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
-import { basename, delimiter, resolve as resolvePath } from "node:path";
+import { basename } from "node:path";
 import {
   getActiveAgent,
   isClaude,
@@ -33,6 +32,7 @@ import {
 import { logDebug } from "./log";
 import { HAIKU_MODEL } from "./models";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
+import { findBinaryOnPath } from "./which";
 
 export function hasApiKey(): boolean {
   return !!process.env.PAL_ANTHROPIC_API_KEY;
@@ -213,45 +213,6 @@ let opencodeBinaryCache: string | null | undefined;
 let copilotBinaryCache: string | null | undefined;
 let cursorBinaryCache: string | null | undefined;
 
-/**
- * Resolve a binary on PATH to its full absolute path.
- *
- * Manual PATH walk (instead of Bun.which / `which` subprocess) because:
- * 1. Ubuntu 24.04 dropped the `which` binary entirely.
- * 2. Windows has no `which` at all.
- * 3. Bun.which snapshots PATH at startup and ignores mid-test mutations.
- * 4. Bun.spawn on Windows is inconsistent at resolving PATHEXT for bare
- *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
- *
- * Returns the resolved absolute path or null.
- */
-function findBinaryOnPath(name: string): string | null {
-  const PATH = process.env.PATH;
-  if (!PATH) return null;
-  const exts =
-    process.platform === "win32"
-      ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
-      : [""];
-  for (const dir of PATH.split(delimiter)) {
-    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 */
-      }
-    }
-  }
-  return null;
-}
-
 function getClaudeBinary(): string | null {
   if (claudeBinaryCache !== undefined) return claudeBinaryCache;
   claudeBinaryCache = findBinaryOnPath("claude");

package/src/hooks/lib/settings.ts

@@ -25,6 +25,11 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
+  steering?: {
+    disable?: string[];
+    rules?: Array<{ tag: string; pattern: string; snippet: string }>;
+  };
   [key: string]: unknown;
 }
 

package/src/hooks/lib/steering.ts

@@ -0,0 +1,162 @@
+/**
+ * Contextual Steering — deterministic prompt-type classifier that injects
+ * task-specific steering into the model's context at prompt time.
+ *
+ * Pure + fail-open: classifyPrompt is a regex table (no LLM, sub-millisecond).
+ * getSteeringReminder wraps matched snippets in a single <system-reminder>,
+ * byte-capped. It rides the same UserPromptSubmit path as inject-retrieval; the
+ * per-agent output adapter is shared (see inject-retrieval's writeForAgent).
+ *
+ * This is the prompt-time counterpart to STEERING_RULES.md: the always-on file
+ * keeps terse directives, while the verbose guidance lives here and is injected
+ * only when the prompt matches that task type.
+ */
+
+import { isEnabled, raw } from "./settings";
+
+/** The tags shipped as built-in defaults. Users may add their own tags via
+ *  pal-settings.json `steering.rules`, so the effective tag set is open-ended. */
+type SteeringTag =
+  | "debugging"
+  | "destructive"
+  | "refactor"
+  | "planning"
+  | "testing"
+  | "committing"
+  | "secrets";
+
+interface SteeringRule {
+  tag: string;
+  pattern: RegExp;
+  snippet: string;
+}
+
+// Ordered rule table. Multiple rules may match one prompt; classifyPrompt
+// returns every match in declaration order. Patterns are anchored on word
+// boundaries to avoid substring false-positives (e.g. "warm" ≠ "rm").
+const STEERING_RULES: Array<SteeringRule & { tag: SteeringTag }> = [
+  {
+    tag: "debugging",
+    pattern:
+      /\b(bugs?|broken|failing|fails?|errors?|crash\w*|regress\w*|debug\w*|not working|doesn'?t work|stack ?trace)\b/i,
+    snippet:
+      "Debugging something? If so, change one thing at a time and reproduce the failure before fixing — keep the correction surgical rather than a rewrite.",
+  },
+  {
+    tag: "destructive",
+    pattern:
+      /\b(delete|remove|drop|rm\s+-rf|force[- ]push|reset\s+--hard|wipe|truncate|prune)\b/i,
+    snippet:
+      "About to delete, force-push, or drop something irreversible? If so, list what's affected and confirm before acting — and if what you find contradicts how it was described, surface that first.",
+  },
+  {
+    tag: "refactor",
+    pattern:
+      /\b(refactor\w*|clean\s?up|simplif\w*|reorganiz\w*|restructur\w*|dead code|tech debt)\b/i,
+    snippet:
+      "Refactoring or cleaning up? If so, prefer first-principles simplification over adding new layers, and keep the change scoped to what was asked — flag dead code rather than silently rewriting neighboring files.",
+  },
+  {
+    tag: "planning",
+    pattern: /\b(plans?|planning|designs?|designing|architect\w*|roadmap)\b/i,
+    snippet:
+      "Planning or designing something? If you were asked to plan, present the approach and stop — wait for an explicit go-ahead before writing any code.",
+  },
+  {
+    tag: "testing",
+    pattern: /\b(tests?|testing|coverage|assertions?|vacuous)\b/i,
+    snippet:
+      "Adding or changing a test? Prove it isn't vacuous — make it fail first for the right reason, then restore it, so a green run actually means something.",
+  },
+  {
+    tag: "committing",
+    pattern: /\b(commits?|committing|pull requests?|cherry-pick|rebase|PR)\b|git push/i,
+    snippet:
+      "About to commit, push, or open a PR? Only do it if it was asked, and keep the commit scoped to exactly what was requested.",
+  },
+  {
+    tag: "secrets",
+    pattern: /\b(secrets?|api[\s-]?keys?|tokens?|passwords?|credentials?)\b|\.env\b/i,
+    snippet:
+      "Handling secrets, API keys, or credentials? Never hardcode them in source or commit them — keep them in env or private config, and never echo them into logs or output.",
+  },
+];
+
+const MAX_STEERING_BYTES = 1000;
+
+/** Merge shipped defaults with the user's pal-settings.json extension:
+ *  `steering.disable` removes built-ins by tag; `steering.rules` appends personal
+ *  rules. Malformed user entries (missing field or bad regex) are skipped, never
+ *  thrown — a broken personal rule must not disable steering for everyone. */
+function effectiveRules(): SteeringRule[] {
+  const cfg = raw().steering ?? {};
+  const disabled = new Set(cfg.disable ?? []);
+  const rules: SteeringRule[] = STEERING_RULES.filter((r) => !disabled.has(r.tag));
+  for (const u of cfg.rules ?? []) {
+    if (!u?.tag || !u?.pattern || !u?.snippet) continue;
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(u.pattern, "i");
+    } catch {
+      continue; // fail-open: skip malformed regex
+    }
+    rules.push({ tag: u.tag, pattern, snippet: u.snippet });
+  }
+  return rules;
+}
+
+/** Match a prompt against the effective rule set, one hit per tag, in order. */
+function matchRules(text: string): SteeringRule[] {
+  if (!text?.trim()) return [];
+  const matched: SteeringRule[] = [];
+  const seen = new Set<string>();
+  for (const rule of effectiveRules()) {
+    if (!seen.has(rule.tag) && rule.pattern.test(text)) {
+      seen.add(rule.tag);
+      matched.push(rule);
+    }
+  }
+  return matched;
+}
+
+/** Deterministically classify a prompt into steering tags. Pure, fail-open. */
+export function classifyPrompt(text: string): string[] {
+  return matchRules(text).map((r) => r.tag);
+}
+
+/** Build the steering <system-reminder> for a prompt, or null if nothing matches. */
+export function getSteeringReminder(prompt: string): string | null {
+  if (!isEnabled("contextualSteering")) return null;
+
+  let matched: SteeringRule[];
+  try {
+    matched = matchRules(prompt);
+  } catch {
+    return null; // fail-open: never block a prompt on a classifier error
+  }
+  if (matched.length === 0) return null;
+
+  const lines: string[] = [];
+  let budget = MAX_STEERING_BYTES;
+  for (const rule of matched) {
+    const line = `- ${rule.snippet}`;
+    const cost = Buffer.byteLength(line);
+    if (cost > budget) break; // byte-cap: drop the overflow tail, keep top matches
+    lines.push(line);
+    budget -= cost;
+  }
+  if (lines.length === 0) return null;
+
+  const inner = [
+    "Heuristic self-checks auto-matched on your prompt — they may be off; ignore any that don't apply:",
+    ...lines,
+  ];
+  // Dual-live test period: co-locate the report instruction with the trigger so
+  // it fires reliably across sessions/compaction. Flip steeringTestReport off to end it.
+  if (isEnabled("steeringTestReport")) {
+    inner.push(
+      "— Test period: assistant, briefly note to the user that a steering self-check fired, and which one(s)."
+    );
+  }
+  return ["<system-reminder>", ...inner, "</system-reminder>"].join("\n");
+}

package/src/hooks/lib/which.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-platform binary resolution — a manual PATH walk.
+ *
+ * Deliberately avoids Bun.which / a `which` subprocess because:
+ * 1. Ubuntu 24.04 dropped the `which` binary entirely.
+ * 2. Windows has no `which` at all.
+ * 3. Bun.which snapshots PATH at startup and ignores mid-test mutations.
+ * 4. Bun.spawn on Windows is inconsistent at resolving PATHEXT for bare
+ *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
+ */
+
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, resolve as resolvePath } from "node:path";
+
+/** 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;
+  if (!PATH) return null;
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
+      : [""];
+  for (const dir of PATH.split(delimiter)) {
+    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 */
+      }
+    }
+  }
+  return null;
+}

package/src/targets/opencode/plugin.ts

@@ -5,6 +5,7 @@
  * This plugin just wires opencode's hook API to those shared functions.
  */
 
+import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import type { Plugin, PluginInput } from "@opencode-ai/plugin";
 
@@ -30,6 +31,27 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
     await lib<typeof import("../../hooks/lib/context")>("context.ts");
   const { checkBashCommand, checkFilePath } =
     await lib<typeof import("../../hooks/lib/security")>("security.ts");
+  const { findBinaryOnPath } =
+    await lib<typeof import("../../hooks/lib/which")>("which.ts");
+
+  // rtk output compression — PAL gates on presence, rtk owns the rewrite.
+  // `rtk hook check <cmd>` prints the rewritten command (exit 0) or nothing
+  // (exit 1) when a command isn't worth wrapping. Fail-open: absent rtk or any
+  // error leaves the command untouched.
+  const rtkBin = findBinaryOnPath("rtk");
+  const rtkRewrite = (cmd: string): string | null => {
+    if (!rtkBin || !cmd) return null;
+    try {
+      const r = spawnSync(rtkBin, ["hook", "check", cmd], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const out = r.status === 0 ? (r.stdout ?? "").trim() : "";
+      return out && out !== cmd ? out : null;
+    } catch {
+      return null;
+    }
+  };
   const { logDebug, logError, logPromptSnapshot } =
     await lib<typeof import("../../hooks/lib/log")>("log.ts");
 
@@ -44,6 +66,8 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   const { getRetrievalReminder } = await lib<
     typeof import("../../hooks/handlers/inject-retrieval")
   >("../handlers/inject-retrieval.ts");
+  const { getSteeringReminder } =
+    await lib<typeof import("../../hooks/lib/steering")>("steering.ts");
 
   function partsToText(parts: Array<Record<string, unknown>>): string {
     return parts
@@ -140,20 +164,22 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       if (!text.trim()) return;
 
       const retrieval = await getRetrievalReminder(text);
-      logPromptSnapshot(text, retrieval);
+      const steering = getSteeringReminder(text);
+      const injectedText = [steering, retrieval].filter(Boolean).join("\n\n");
+      logPromptSnapshot(text, injectedText || null);
 
       await Promise.allSettled([
         captureRating(text, input.sessionID),
         captureSessionName(text, input.sessionID),
       ]);
 
-      if (retrieval) {
+      if (injectedText) {
         const injected = {
-          id: `pal-retrieval-${Date.now()}`,
+          id: `pal-promptctx-${Date.now()}`,
           sessionID: input.sessionID,
           messageID: input.messageID ?? `pal-msg-${Date.now()}`,
           type: "text" as const,
-          text: retrieval,
+          text: injectedText,
           synthetic: true,
         };
         output.parts = [injected, ...(output.parts ?? [])];
@@ -176,6 +202,11 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
         if (reason) {
           throw new Error(`PAL Security: Blocked — ${reason}`);
         }
+        const rewritten = rtkRewrite(cmd);
+        if (rewritten) {
+          if (typeof output.args === "string") output.args = rewritten;
+          else (output.args as Record<string, unknown>).command = rewritten;
+        }
       }
 
       if (toolName === "write" || toolName === "edit" || toolName === "patch") {

package/src/tools/agent/algorithm-reflect.ts

@@ -15,6 +15,7 @@
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -121,7 +122,7 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
   };
 
   const result = appendReflection(reflection);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/handoff-note.ts

@@ -14,6 +14,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 interface HandoffEntry {
   timestamp: string;
@@ -102,7 +103,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
       values.text || "",
       true
     );
-    console.log(JSON.stringify(result, null, 2));
+    emit.ok(result.message);
     process.exit(0);
   }
 
@@ -112,7 +113,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
   }
 
   const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/project.ts

@@ -123,10 +123,24 @@ function cmdCreate(args: string[]): void {
 
 // ── resume ────────────────────────────────────────────────────────
 
+// resume returns a lean orientation view: all narrative sections, but the
+// Criteria/Changelog blobs collapse to open-ISC titles + counts. Full ISC text
+// is fetched on demand via show-isc / list-isc, so resume stays cheap on
+// projects carrying a large backlog.
 function cmdResume(args: string[]): void {
   const name = args[0];
   if (!name) fail("Usage: resume <name>");
-  ok({ project: requireProject(name) });
+  const { criteria, changelog, ...project } = requireProject(name);
+  const iscs = parseIscs(criteria ?? "");
+  const openIscs = iscs.filter((i) => !i.checked);
+  const done = iscs.filter((i) => i.checked).length + parseIscs(changelog ?? "").length;
+  ok({
+    project: {
+      ...project,
+      open_iscs: openIscs.map((i) => ({ id: i.id, title: iscTitle(i.text) })),
+      isc_summary: { open: openIscs.length, done },
+    },
+  });
 }
 
 // ── status transitions ────────────────────────────────────────────
@@ -351,6 +365,14 @@ function parseIscs(criteria: string): Isc[] {
   return out;
 }
 
+// Collapse a full ISC line to a glanceable title for resume: cut at the first
+// clause boundary, then hard-cap length. Full text stays reachable via show-isc.
+function iscTitle(text: string): string {
+  const boundary = text.search(/; | — | \(|\. /);
+  const clause = (boundary > 0 ? text.slice(0, boundary) : text).trim();
+  return clause.length > 80 ? `${clause.slice(0, 79).trimEnd()}…` : clause;
+}
+
 // Scans Criteria AND Changelog so an archived id can never be handed out again.
 function nextIscId(p: ProjectProgress): number {
   const ids = [...parseIscs(p.criteria ?? ""), ...parseIscs(p.changelog ?? "")].map(
@@ -493,6 +515,20 @@ function cmdListIsc(args: string[]): void {
   });
 }
 
+// show-isc prints one ISC's full text on demand — the "detail" counterpart to
+// resume's titles. Scans Criteria (open + not-yet-archived) and Changelog.
+function cmdShowIsc(args: string[]): void {
+  const name = args[0];
+  const id = Number(args[1]);
+  if (!name || !Number.isInteger(id) || id < 1) fail("Usage: show-isc <name> <id>");
+  const p = requireProject(name);
+  const isc = [...parseIscs(p.criteria ?? ""), ...parseIscs(p.changelog ?? "")].find(
+    (i) => i.id === id
+  );
+  if (!isc) fail(`ISC-${id} not found in project "${name}".`);
+  ok({ name, id: isc.id, status: isc.checked ? "closed" : "open", text: isc.text });
+}
+
 // Backfill: sweep any done ISCs still sitting in Criteria (legacy projects, or
 // completions from before archive-on-complete) into the Changelog in one pass.
 function cmdPruneIsc(args: string[]): void {
@@ -576,7 +612,7 @@ function help(): void {
 Commands:
   list                                          show all registered projects
   create [name] [--path PATH] [--objectives X]  register a project
-  resume <name>                                 print full project ISA
+  resume <name>                                 print lean project view (open-ISC titles; full text via show-isc)
   complete <name>                               mark complete
   archive <name>                                mark archived
   pause <name> | unpause <name>                 toggle paused/active
@@ -593,6 +629,7 @@ Commands:
   complete-isc <name> <id>                      mark ISC-N as done
   reopen-isc <name> <id>                        reopen ISC-N (mark not done)
   list-isc <name> [--all | --closed]           list open ISCs (default); --all or --closed for done
+  show-isc <name> <id>                          print one ISC's full text
   prune-isc <name>                              archive done ISCs from Criteria into the Changelog
   isa-init <name>                               mark project as ISA-initialized
   scaffold-task-isa <title>                     create a one-shot task ISA in memory/work/
@@ -685,6 +722,9 @@ function run(): void {
     case "list-isc":
       cmdListIsc(rest);
       return;
+    case "show-isc":
+      cmdShowIsc(rest);
+      return;
     case "prune-isc":
       cmdPruneIsc(rest);
       return;

package/src/tools/agent/relationship-note.ts

@@ -6,8 +6,8 @@
  * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
- *   bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+ *   bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
+ *   bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
  *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
  *
  * Note types:
@@ -18,6 +18,7 @@
 
 import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
+import { emit } from "../lib/emit";
 
 function run() {
   const { values } = parseArgs({
@@ -36,8 +37,8 @@ function run() {
 RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
-  bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+  bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
+  bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
 
 Flags:
@@ -83,13 +84,7 @@ Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 
   appendNotes(notes);
 
-  console.log(
-    JSON.stringify(
-      { success: true, message: "Relationship note written", count: notes.length },
-      null,
-      2
-    )
-  );
+  emit.ok(`Relationship note written (${notes.length})`);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/thread.ts

@@ -15,6 +15,7 @@ import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -137,13 +138,7 @@ Usage:
       process.exit(1);
     }
     const thread = addThread(values.title, values.context ?? "");
-    console.log(
-      JSON.stringify(
-        { success: true, id: thread.id, message: `Thread added: ${thread.title}` },
-        null,
-        2
-      )
-    );
+    emit.data(`Added with id ${thread.id}`);
   }
 
   if (cmd === "resolve") {
@@ -151,12 +146,14 @@ Usage:
       console.error("--id required");
       process.exit(1);
     }
-    console.log(JSON.stringify(resolveThread(values.id), null, 2));
+    const resolved = resolveThread(values.id);
+    if (resolved.success) emit.ok(resolved.message ?? "Thread resolved");
+    else emit.data(JSON.stringify(resolved, null, 2));
   }
 
   if (cmd === "list") {
     const threads = listThreads(values.all ?? false);
-    console.log(JSON.stringify({ count: threads.length, threads }, null, 2));
+    emit.data(JSON.stringify({ count: threads.length, threads }, null, 2));
   }
 }
 

package/src/tools/agent/wisdom-frame.ts

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -233,7 +234,7 @@ Examples:
 
   const cliType = (values.type || "evolution") as ObservationType;
   const result = updateFrame(values.domain, values.observation, cliType);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/lib/emit.ts

@@ -0,0 +1,31 @@
+/**
+ * Output convention for agent-invoked CLI tools: quiet on success, full on
+ * failure. The agent captures tool output over a pipe (non-TTY), where success
+ * confirmations are pure noise that costs context tokens; a human at a TTY wants
+ * them. Gate on the TTY signal, with PAL_VERBOSE / PAL_QUIET as explicit overrides.
+ *
+ *   data()  requested payload — ALWAYS emitted (list output, reports, results)
+ *   ok()    success confirmation / progress — only at a TTY or under PAL_VERBOSE
+ *
+ * Errors stay on console.error (stderr) + a non-zero exit — always surfaced,
+ * independent of this gate.
+ */
+
+function isVerbose(): boolean {
+  if (process.env.PAL_QUIET === "1") return false;
+  if (process.env.PAL_VERBOSE === "1") return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+function line(stream: { write: (s: string) => void }, text: string): void {
+  stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+export const emit = {
+  data(text: string): void {
+    line(process.stdout, text);
+  },
+  ok(text: string): void {
+    if (isVerbose()) line(process.stdout, text);
+  },
+};

package/src/tools/relationship-reflect.ts

@@ -26,6 +26,7 @@ import {
 } from "../hooks/lib/opinions";
 import { palHome } from "../hooks/lib/paths";
 import { similarity } from "../hooks/lib/text-similarity";
+import { emit } from "./lib/emit";
 
 // ── Types ──
 
@@ -413,11 +414,11 @@ Output:
   const notes = loadNotes(daysBack);
   const ratings = loadRatings(daysBack);
 
-  console.log(`Loaded ${notes.length} notes from last ${daysBack} days`);
-  console.log(`Loaded ${ratings.length} ratings`);
+  emit.ok(`Loaded ${notes.length} notes from last ${daysBack} days`);
+  emit.ok(`Loaded ${ratings.length} ratings`);
 
   if (notes.length === 0 && ratings.length === 0) {
-    console.log("No data to analyze");
+    emit.ok("No data to analyze");
     process.exit(0);
   }
 
@@ -425,42 +426,42 @@ Output:
 
   const avgRating =
     ratings.length > 0 ? ratings.reduce((s, r) => s + r.rating, 0) / ratings.length : 0;
-  console.log(`\nAverage Rating: ${avgRating.toFixed(1)}/10`);
+  emit.ok(`\nAverage Rating: ${avgRating.toFixed(1)}/10`);
 
   const summaries = groupNoteOccurrences(notes);
-  console.log(`Observations: ${summaries.length} unique`);
+  emit.ok(`Observations: ${summaries.length} unique`);
 
   if (opinionChanges.length > 0) {
-    console.log("\nOpinion changes:");
+    emit.ok("\nOpinion changes:");
     for (const change of opinionChanges) {
       if (change.action === "created") {
-        console.log(
+        emit.ok(
           `  + NEW (${Math.round(change.newConfidence * 100)}%) ${change.statement.slice(0, 80)}`
         );
       } else {
-        console.log(
+        emit.ok(
           `  ~ ${Math.round(change.oldConfidence ?? 0 * 100)}% → ${Math.round(change.newConfidence * 100)}% ${change.statement.slice(0, 80)}`
         );
       }
     }
   } else {
-    console.log("\nNo opinion changes");
+    emit.ok("\nNo opinion changes");
   }
 
   if (dryRun) {
-    console.log("\n[DRY RUN] Would write reflection report + update opinions");
+    emit.data("[DRY RUN] Would write reflection report + update opinions");
   } else {
     const report = formatReport(period, notes, ratings, opinionChanges);
     const filepath = writeReport(report, period);
     setLastReflectDate(new Date().toISOString().slice(0, 10));
-    console.log(`\nCreated reflection report: ${filepath}`);
+    emit.ok(`\nCreated reflection report: ${filepath}`);
 
     const opinions = readOpinions();
     const high = opinions.filter((o) => o.confidence >= 0.85);
     if (high.length > 0) {
-      console.log("\nHigh-confidence opinions (injected into context):");
+      emit.ok("\nHigh-confidence opinions (injected into context):");
       for (const o of high) {
-        console.log(`  [${Math.round(o.confidence * 100)}%] ${o.statement.slice(0, 80)}`);
+        emit.ok(`  [${Math.round(o.confidence * 100)}%] ${o.statement.slice(0, 80)}`);
       }
     }
   }

package/src/tools/token-cost.ts

@@ -8,12 +8,14 @@
  * Invoked via `pal cli usage [--today|--week|--month|--all] [--project <name>]`.
  */
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { MODEL_PRICING } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
+import { findBinaryOnPath } from "../hooks/lib/which";
 
 // ── Types ──
 
@@ -370,6 +372,51 @@ function readPalInference(): {
   return { buckets, byModel, byCaller };
 }
 
+// ── rtk compression savings ──
+
+interface RtkSummary {
+  total_commands: number;
+  total_saved: number;
+  avg_savings_pct: number;
+}
+
+/**
+ * Query rtk's own savings ledger. `installed: false` means rtk isn't on PATH;
+ * `summary: null` with `installed: true` means rtk is present but has no data
+ * (or errored) — the two cases print differently in the usage report.
+ */
+function readRtkGain(): { installed: boolean; summary: RtkSummary | null } {
+  const rtk = findBinaryOnPath("rtk");
+  if (!rtk) return { installed: false, summary: null };
+  try {
+    const r = spawnSync(rtk, ["gain", "--format", "json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (r.status !== 0 || !r.stdout) return { installed: true, summary: null };
+    const parsed = JSON.parse(r.stdout) as { summary?: RtkSummary };
+    return { installed: true, summary: parsed.summary ?? null };
+  } catch {
+    return { installed: true, summary: null };
+  }
+}
+
+function printRtkGain(): void {
+  const { installed, summary } = readRtkGain();
+  console.log("\n  rtk Compression\n");
+  if (!installed) {
+    console.log("  rtk not installed");
+    return;
+  }
+  if (!summary || summary.total_commands === 0) {
+    console.log("  rtk installed — no savings recorded yet");
+    return;
+  }
+  console.log(
+    `  Tokens saved   ${fmt(summary.total_saved).padStart(8)} tok  ${summary.avg_savings_pct.toFixed(1)}% avg  across ${fmt(summary.total_commands)} commands`
+  );
+}
+
 // ── CLI ──
 
 export function usage() {
@@ -426,6 +473,8 @@ export function usage() {
     printRow("Total", tb.total);
   }
 
+  printRtkGain();
+
   const grand = emptyBucket();
   for (const b of [cc.buckets.total, pal.buckets.total]) {
     grand.input += b.input;