@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/bin/installers/copilot.mjs

@@ -30,22 +30,15 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { writeFile, mkdir, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
+import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
 
-function isDirectory(p) {
-  try {
-    return statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 function byName(a, b) {
   return a.localeCompare(b);
 }
@@ -71,19 +64,21 @@ function frontmatterYaml(name, fm) {
 }
 
 /** Compose agents from agents/<name>/; every composable dir must ship a copilot harness. */
-function buildAgents(root) {
+async function buildAgents(root) {
   const files = [];
-  const entries = readdirSync(join(root, "agents"), { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+  const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
+    byName(a.name, b.name),
+  );
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files and README
     const dir = join(root, "agents", entry.name);
-    if (!existsSync(join(dir, "agent.md"))) continue; // not a composable agent dir
-    if (!isDirectory(join(dir, "copilot")) || !existsSync(join(dir, "copilot", "frontmatter.json"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, "copilot"))) || !(await isFile(join(dir, "copilot", "frontmatter.json")))) {
       throw new Error(`agent "${entry.name}": composable directory without copilot/frontmatter.json — define the copilot harness or exclude the agent`);
     }
 
-    const fm = composeAgent(root, entry.name, "copilot");
+    const fm = await composeAgent(root, entry.name, "copilot");
     files.push({
       name: entry.name,
       file: `${entry.name}.agent.md`,
@@ -105,9 +100,9 @@ function buildAgents(root) {
  * @param {boolean} [options.dryRun] Plan and report without writing anything.
  * @returns {{ output: string, agents: string[], dryRun: boolean }}
  */
-export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
+export async function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
   const out = output ?? join(root, "agents");
-  const files = buildAgents(root);
+  const files = await buildAgents(root);
   const summary = {
     output: out,
     agents: files.map((f) => f.name),
@@ -120,9 +115,9 @@ export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } =
     return summary;
   }
 
-  mkdirSync(out, { recursive: true });
+  await mkdir(out, { recursive: true });
   for (const { file, content } of files) {
-    writeFileSync(join(out, file), content);
+    await writeFile(join(out, file), content);
   }
   console.log(`Generated ${files.length} Copilot agent file(s): ${summary.agents.join(", ")}`);
   return summary;

package/bin/installers/pi.mjs

@@ -4,12 +4,15 @@
 //
 //   <output>/agents/<slug>.agent.md   composed agents (default ~/.pi/agent/agents)
 //   <output>/skills/<group>/<name>/   token-substituted skill copies (default ~/.pi/agent/skills)
+//   <output>/settings.json            merged pi settings — CLI owns `packages` (default ~/.pi/agent/settings.json)
+//   <output>/keybindings.json         generated pi keybindings (default ~/.pi/agent/keybindings.json)
 //
 // Composition per the token-map.json contract:
 //   1. {{SECTION:name}} is resolved from the agent's pi/<name>.md section file
 //      (shared composer, scripts/lib/compose-agent.mjs).
-//   2. {{TOOL:key}} is substituted with the pi column; a null mapping drops the
-//      token from prose with a warning (pi has no ask_user/skill tool).
+//   2. {{TOOL:key}} is substituted with the pi column (pi maps ask_user →
+//      ask_questions and skill → read); any (future) null pi mapping drops the
+//      token from prose with a warning.
 //   3. {{PATH:key}} named keys resolve through the paths table; bare relative
 //      paths resolve against the plugin root (default: token-map.json's pi value,
 //      overridable with --plugin-root for checkout/symlinked installs).
@@ -18,17 +21,26 @@
 // Skill markdown files get the same TOOL/PATH substitution so pi never serves
 // literal token syntax; other skill files are copied verbatim.
 //
-// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which pi
-// loads before package skills, so the substituted copies shadow the raw package
-// skills of the same name (pi dedupes by name, user wins).
+// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which is
+// the sole pi skill source: the checkout's raw package skills are not loaded
+// locally because pi/settings.json registers agent-cortex with an object-form
+// packages filter { source, "skills": [] } (extensions stay enabled). The
+// filter exists so pi never sees the raw, un-substituted package skills and
+// reports a name collision per skill (pi warns on collisions, user dir wins).
+// Consumers who install the npm package without that filter still rely on pi's
+// shadowing order (user dir loads before package skills). Re-run this installer
+// after any skill edit so the substituted copy in the user dir stays in sync.
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { readFile, writeFile, mkdir, copyFile, readdir, lstat, rename, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, dirname, basename, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
+import { loadRequiredPackages, provisionPiPackages } from "../../lib/pi-packages.mjs";
+import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const PI = "pi";
 
@@ -37,26 +49,20 @@ const PI = "pi";
 // extended before this installer can trust it.
 const CONTRACT_VERSION = 1;
 
-const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const DEFAULT_OUTPUT = join(homedir(), ".pi", "agent");
 
-const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
+const SETTINGS_TEMPLATE = "pi/settings.json";
+const KEYBINDINGS_TEMPLATE = "pi/keybindings.json";
 
-function isDirectory(p) {
-  try {
-    return statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
+// pi parses settings.json / keybindings.json with a bare JSON.parse (see pi's
+// SettingsManager / KeybindingsManager), so JSONC comments are not an option —
+// a `//` line would make the file unreadable. The GENERATED marker therefore
+// lives in a top-level "//" key, the conventional JSON comment stand-in, which
+// pi ignores on load and preserves on write.
+const GENERATED_KEY = "//";
 
-function isFile(p) {
-  try {
-    return statSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
+const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
 
 /**
  * Install the agent-cortex pi harness into the pi runtime.
@@ -69,12 +75,22 @@ function isFile(p) {
  * @param {boolean} [options.dryRun]     Compute and report without writing anything
  * @param {string} [options.pluginRoot]  Override plugin_root used for {{PATH:...}}
  *                                       resolution (default: token-map pi value)
+ * @param {boolean} [options.provisionPackages]  Install the third-party pi packages
+ *                                       declared in the package manifest (package.json
+ *                                       pi.packages) into the pi user scope — e.g.
+ *                                       pi-questions (ask_questions) and pi-web-access
+ *                                       (fetch_content). Off by default; `agent-cortex
+ *                                       install pi` turns it on for a real install.
+ * @param {(source: string) => Promise<{ok: boolean, error: string | null}>} [options.runInstall]
+ *                                       Installer for one package source (default: pi install)
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`
  * @returns {{ agents: {name:string, filePath:string}[], skills: {skills:number, md:number, files:number, dir:string},
+ *             packages: {planned:string[], installed:string[], failed:{source:string, error:string}[]} | null,
+ *             settings: ManagedFileResult|null, keybindings: ManagedFileResult|null,
  *             warnings: string[], dryRun: boolean, agentsDir: string, skillsDir: string }}
  */
-export function installPi(options = {}) {
-  const root = options.root ?? REPO_ROOT;
+export async function installPi(options = {}) {
+  const root = options.root ?? PACKAGE_ROOT;
   const output = options.output ?? DEFAULT_OUTPUT;
   const dryRun = options.dryRun ?? false;
   const warnings = [];
@@ -83,7 +99,7 @@ export function installPi(options = {}) {
     (options.warn ?? DEFAULT_WARN)(msg);
   };
 
-  const tokenMap = loadTokenMap(root);
+  const tokenMap = await loadTokenMap(root);
   if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
     throw new Error(
       `token-map.json version ${tokenMap.version} is newer than the contract version ${CONTRACT_VERSION} this installer implements — upgrade agent-cortex`,
@@ -94,26 +110,42 @@ export function installPi(options = {}) {
   const agentsDir = join(output, "agents");
   const skillsDir = join(output, "skills");
 
-  const agents = installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
-  const skills = installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+  const agents = await installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
+  const skills = await installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+  const config = await installConfig({ root, output, dryRun, warn });
+
+  // Third-party packages give the composed agents their pi tools (ask_questions
+  // from pi-questions, fetch_content from pi-web-access). They are declared in
+  // the package manifest and only provisioned on a real install.
+  const packages = options.provisionPackages
+    ? await provisionPiPackages({
+        required: await loadRequiredPackages(root),
+        piRoot: output,
+        dryRun,
+        runInstall: options.runInstall,
+        warn,
+      })
+    : null;
 
-  return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
+  return { agents, skills, packages, ...config, warnings, dryRun, agentsDir, skillsDir };
 }
 
 // ─── Agents ──────────────────────────────────────────────────────────────────
 
-function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
   const written = [];
   const agentsSrc = join(root, "agents");
-  for (const entry of readdirSync(agentsSrc, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+  for (const entry of (await readdir(agentsSrc, { withFileTypes: true })).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
     if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files
     const dir = join(agentsSrc, entry.name);
-    if (!isFile(join(dir, "agent.md"))) continue; // not a composable agent dir
-    if (!isDirectory(join(dir, PI)) || !isFile(join(dir, PI, "frontmatter.json"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, PI))) || !(await isFile(join(dir, PI, "frontmatter.json")))) {
       throw new Error(`agent "${entry.name}": composable directory without pi/frontmatter.json — define the pi harness or exclude the agent`);
     }
 
-    const fm = composeAgent(root, entry.name, PI, {
+    const fm = await composeAgent(root, entry.name, PI, {
       dropNullTools: true,
       pluginRoot,
       resolveRelativePaths: true,
@@ -123,8 +155,8 @@ function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn })
     const content = renderPiAgent(entry.name, fm, tools);
     const filePath = join(agentsDir, `${entry.name}.agent.md`);
     if (!dryRun) {
-      mkdirSync(agentsDir, { recursive: true });
-      writeFileSync(filePath, content);
+      await mkdir(agentsDir, { recursive: true });
+      await writeFile(filePath, content);
     }
     written.push({ name: entry.name, filePath });
   }
@@ -147,24 +179,24 @@ function renderPiAgent(name, fm, tools) {
 
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
-function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
   const skillsSrc = join(root, "skills");
-  if (!isDirectory(skillsSrc)) return { skills: 0, md: 0, files: 0, dir: skillsDir };
+  if (!(await isDirectory(skillsSrc))) return { skills: 0, md: 0, files: 0, dir: skillsDir };
 
   const transform = (content) =>
     substituteTokens(content, PI, tokenMap, { dropNullTools: true, pluginRoot, resolveRelativePaths: true, warn });
 
-  if (!dryRun) mkdirSync(skillsDir, { recursive: true });
+  if (!dryRun) await mkdir(skillsDir, { recursive: true });
   let skills = 0;
   let md = 0;
   let files = 0;
-  for (const group of readdirSync(skillsSrc).sort()) {
+  for (const group of (await readdir(skillsSrc)).sort()) {
     const groupDir = join(skillsSrc, group);
-    if (!isDirectory(groupDir)) continue;
-    for (const name of readdirSync(groupDir).sort()) {
-      if (!isFile(join(groupDir, name, "SKILL.md"))) continue;
+    if (!(await isDirectory(groupDir))) continue;
+    for (const name of (await readdir(groupDir)).sort()) {
+      if (!(await isFile(join(groupDir, name, "SKILL.md")))) continue;
       skills += 1;
-      const stats = copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
+      const stats = await copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
       md += stats.md;
       files += stats.files;
     }
@@ -173,25 +205,235 @@ function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn })
 }
 
 /** Recursively copy a tree; transform .md file contents, copy everything else verbatim. */
-function copyTree(src, dest, transform, dryRun) {
+async function copyTree(src, dest, transform, dryRun) {
   let md = 0;
   let files = 0;
-  const entries = readdirSync(src, { withFileTypes: true });
+  const entries = await readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const from = join(src, entry.name);
     const to = join(dest, entry.name);
     if (entry.isDirectory()) {
-      const stats = copyTree(from, to, transform, dryRun);
+      const stats = await copyTree(from, to, transform, dryRun);
       md += stats.md;
       files += stats.files;
     } else if (entry.isFile()) {
       files += 1;
       if (entry.name.endsWith(".md")) md += 1;
       if (dryRun) continue;
-      mkdirSync(dest, { recursive: true });
-      if (entry.name.endsWith(".md")) writeFileSync(to, transform(readFileSync(from, "utf-8")));
-      else copyFileSync(from, to);
+      await mkdir(dest, { recursive: true });
+      if (entry.name.endsWith(".md")) await writeFile(to, transform(await readFile(from, "utf-8")));
+      else await copyFile(from, to);
     }
   }
   return { md, files };
-}
+}
+// ─── Pi config files ─────────────────────────────────────────────────────────
+
+/**
+ * Materialise the pi config files into the agent dir.
+ *
+ * `settings.json` is merged: the committed template supplies defaults for keys
+ * the live file lacks, while every value already present in the live file wins,
+ * so personal config (and anything pi itself wrote) survives re-install. The
+ * one key the CLI owns outright is `packages`: it is rewritten from the
+ * template with the repo path entry resolved against the target settings file.
+ *
+ * `keybindings.json` follows a checksum rule: a missing file or a legacy
+ * symlink is materialised from the template, an unmodified install is refreshed
+ * when the template changes, and a file edited after install is left untouched.
+ */
+async function installConfig({ root, output, dryRun, warn }) {
+  return {
+    settings: await installSettings({ root, output, dryRun, warn }),
+    keybindings: await installKeybindings({ root, output, dryRun, warn }),
+  };
+}
+
+async function installSettings({ root, output, dryRun, warn }) {
+  const template = await readTemplateJson(join(root, SETTINGS_TEMPLATE), warn);
+  if (template === null) return null;
+
+  const target = join(output, "settings.json");
+  const merged = mergeSettings(template, await readJsonObject(target, warn));
+  merged.packages = resolvePackages(template.packages, root, dirname(target));
+  delete merged[GENERATED_KEY];
+
+  const content = `${JSON.stringify(
+    { [GENERATED_KEY]: generatedMarker(SETTINGS_TEMPLATE), ...merged },
+    null,
+    2,
+  )}\n`;
+  return writeManagedJson({ target, content, dryRun });
+}
+
+async function installKeybindings({ root, output, dryRun, warn }) {
+  const template = await readTemplateJson(join(root, KEYBINDINGS_TEMPLATE), warn);
+  if (template === null) return null;
+
+  const target = join(output, "keybindings.json");
+  const content = `${JSON.stringify(
+    { [GENERATED_KEY]: generatedMarker(KEYBINDINGS_TEMPLATE, checksum(template)), ...template },
+    null,
+    2,
+  )}\n`;
+
+  const current = await readFileMaybe(target);
+  if (current !== null && !(await isSymlink(target)) && current !== content) {
+    const parsed = tryParseJsonObject(current);
+    // An install we wrote carries the checksum it recorded; a body that no
+    // longer matches was edited by hand and must not be clobbered. A body
+    // byte-identical to the template is a legacy copy and safe to refresh.
+    const recorded = parsed === null ? null : readRecordedChecksum(parsed[GENERATED_KEY]);
+    const unmodified = parsed !== null && (checksum(parsed) === checksum(template) || recorded === checksum(parsed));
+    if (!unmodified) {
+      warn(`${target} was modified after install — leaving it untouched (delete it to re-adopt the template)`);
+      return { path: target, action: "skipped", removedSymlink: false };
+    }
+  }
+  return writeManagedJson({ target, content, dryRun });
+}
+
+/** Human-readable marker written as the `//` key of every generated config file. */
+function generatedMarker(from, templateChecksum) {
+  const base = `GENERATED from ${from} by \`agent-cortex install pi\` — DO NOT EDIT; re-run the installer to update.`;
+  return templateChecksum ? `${base} template-checksum:${templateChecksum}` : base;
+}
+
+/** SHA-256 of a config body with the generated marker stripped, so it is stable across writes. */
+function checksum(obj) {
+  const { [GENERATED_KEY]: _marker, ...body } = obj;
+  return createHash("sha256").update(JSON.stringify(body, null, 2)).digest("hex");
+}
+
+function readRecordedChecksum(marker) {
+  if (typeof marker !== "string") return null;
+  const match = /template-checksum:([0-9a-f]{64})/.exec(marker);
+  return match ? match[1] : null;
+}
+
+/**
+ * Merge the committed template over the live file. Template keys fill in
+ * defaults, live values win (deeply), and keys the template does not know about
+ * are preserved — re-installing never discards personal or pi-written config.
+ */
+function mergeSettings(template, existing) {
+  const merged = {};
+  for (const key of Object.keys(template)) {
+    const templateValue = template[key];
+    const existingValue = existing[key];
+    if (isPlainObject(templateValue) && isPlainObject(existingValue)) {
+      merged[key] = mergeSettings(templateValue, existingValue);
+    } else {
+      merged[key] = key in existing ? existingValue : templateValue;
+    }
+  }
+  for (const key of Object.keys(existing)) {
+    if (!(key in merged)) merged[key] = existing[key];
+  }
+  return merged;
+}
+
+/**
+ * Build the CLI-managed packages list: the template entries with the repo path
+ * package resolved relative to the target settings file. pi resolves user-scope
+ * local package paths against its agent dir, so this keeps the checkout (or npm
+ * install) registered wherever the settings file lands.
+ */
+function resolvePackages(packages, root, settingsDir) {
+  if (!Array.isArray(packages)) return packages;
+  const repoSource = relative(settingsDir, root) || ".";
+  let resolved = false;
+  const out = packages.map((entry) => {
+    const source = typeof entry === "string" ? entry : entry?.source;
+    if (resolved || typeof source !== "string" || source.startsWith("npm:")) return entry;
+    resolved = true;
+    return typeof entry === "string" ? repoSource : { ...entry, source: repoSource };
+  });
+  if (!resolved) out.unshift({ source: repoSource, skills: [] });
+  return out;
+}
+
+/**
+ * Write a managed config file. A legacy symlink is replaced with a real file by
+ * writing a sibling temp file and renaming it over the target — rename replaces
+ * the link itself, so the repo template is never written through. Returns the
+ * action taken so the CLI can report the plan (dry-run included).
+ */
+async function writeManagedJson({ target, content, dryRun }) {
+  const symlink = await isSymlink(target);
+  const current = await readFileMaybe(target);
+
+  if (dryRun) {
+    return {
+      path: target,
+      action: symlink ? "would-remove-symlink" : current === content ? "unchanged" : "would-write",
+      removedSymlink: symlink,
+    };
+  }
+  if (!symlink && current === content) {
+    return { path: target, action: "unchanged", removedSymlink: false };
+  }
+
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+  try {
+    await writeFile(tmp, content);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+  return { path: target, action: symlink ? "removed-symlink" : "written", removedSymlink: symlink };
+}
+
+async function readTemplateJson(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) {
+    warn(`no ${filePath} template in the package — skipping`);
+    return null;
+  }
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) throw new Error(`${filePath} is not a JSON object`);
+  return parsed;
+}
+
+async function readJsonObject(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) return {};
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) {
+    warn(`${filePath} is not a JSON object — ignoring its contents`);
+    return {};
+  }
+  return parsed;
+}
+
+function tryParseJsonObject(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readFileMaybe(filePath) {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function isSymlink(filePath) {
+  try {
+    return (await lstat(filePath)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}

package/claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "enabledPlugins": {},
+  "extraKnownMarketplaces": {}
+}

package/{claude → claude-extras}/scripts/statusline-command.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 # Claude Code statusLine: shows model name and context-window usage as a small
 # colored progress bar, with used% (color-coded) and used/total token counts
-# in compact form, e.g.:
-#   Sonnet 5 ~/src [████░░░░░░] 17% 13k / 1M
+# in compact form, followed by the approximate session cost, e.g.:
+#   Sonnet 5 ~/src [████░░░░░░] 17% 13k / 1M $0.42
 
 input=$(cat)
 
@@ -10,11 +10,33 @@ model=$(echo "$input" | jq -r '.model.display_name')
 used=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
 used_tokens=$(echo "$input" | jq -r '.context_window.total_input_tokens // empty')
 total_tokens=$(echo "$input" | jq -r '.context_window.context_window_size // empty')
+cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // empty')
 effort=$(echo "$input" | jq -r '.effort.level // empty')
 agent_name=$(echo "$input" | jq -r '.agent.name // empty')
 cwd=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // empty')
 cwd_display="${cwd/#$HOME/~}"
 
+# Prefer the configured autocompaction threshold (from Claude Code settings)
+# as the denominator for context usage, falling back to the model's max
+# context window when no autocompaction limit is configured/available.
+settings_file="$HOME/.claude/settings.json"
+if [ -f "$settings_file" ]; then
+  autocompact_enabled=$(jq -r '.autoCompactEnabled // false' "$settings_file" 2>/dev/null)
+  autocompact_window=$(jq -r '.autoCompactWindow // empty' "$settings_file" 2>/dev/null)
+  if [ "$autocompact_enabled" = "true" ] && [ -n "$autocompact_window" ] && [ "$autocompact_window" != "null" ]; then
+    if [ "$autocompact_window" -gt 0 ] 2>/dev/null; then
+      total_tokens="$autocompact_window"
+    fi
+  fi
+fi
+
+# Recompute the used percentage against whichever denominator was selected
+# above (autocompaction limit or model max), rather than trusting the
+# pre-calculated used_percentage which is always relative to the model max.
+if [ -n "$used_tokens" ] && [ -n "$total_tokens" ] && [ "$total_tokens" -gt 0 ] 2>/dev/null; then
+  used=$(awk -v u="$used_tokens" -v t="$total_tokens" 'BEGIN { printf "%.2f", (u / t) * 100 }')
+fi
+
 # Collapse long paths to their first two and last two components, e.g.
 #   ~/src/jaybeeuu/thing/agent-cortex -> ~/src/.../thing/agent-cortex
 # Only applied when there are more than 4 total path components (so short
@@ -91,6 +113,12 @@ format_tokens() {
   }'
 }
 
+# Approximate session cost, appended after the context-usage segment, e.g. " $0.42"
+cost_str=""
+if [ -n "$cost_usd" ] && [ "$cost_usd" != "null" ]; then
+  cost_str=" ${GREEN}\$$(awk -v c="$cost_usd" 'BEGIN { printf "%.2f", c }')${RESET}"
+fi
+
 if [ -n "$used" ]; then
   used_int=$(printf '%.0f' "$used")
   [ "$used_int" -lt 0 ] && used_int=0
@@ -118,7 +146,7 @@ if [ -n "$used" ]; then
     tokens_str=" $(format_tokens "$used_tokens") / $(format_tokens "$total_tokens")"
   fi
 
-  printf "${CYAN}%s${RESET}%b%b%b ${WHITE}[${bar_color}%s${WHITE}%s${RESET}${WHITE}]${RESET} ${bar_color}%s%%${RESET}%s" "$model" "$effort_str" "$agent_str" "$cwd_str" "$bar" "$bar_empty" "$used_int" "$tokens_str"
+  printf "${CYAN}%s${RESET}%b%b%b ${WHITE}[${bar_color}%s${WHITE}%s${RESET}${WHITE}]${RESET} ${bar_color}%s%%${RESET}%s%b" "$model" "$effort_str" "$agent_str" "$cwd_str" "$bar" "$bar_empty" "$used_int" "$tokens_str" "$cost_str"
 else
-  printf "${CYAN}%s${RESET}%b%b%b ${WHITE}[context: n/a]${RESET}" "$model" "$effort_str" "$agent_str" "$cwd_str"
+  printf "${CYAN}%s${RESET}%b%b%b ${WHITE}[context: n/a]${RESET}%b" "$model" "$effort_str" "$agent_str" "$cwd_str" "$cost_str"
 fi

package/docs/claude-hooks.md

@@ -2,8 +2,8 @@
 
 The pi extensions in `extensions/` were audited for Claude Code equivalents.
 Implemented ports live in `hooks/claude/hooks.json` (copied verbatim into the
-generated plugin as `claude/hooks.json`); support scripts live in
-`hooks/claude/scripts/` and are bundled into `claude/hooks/scripts/` by
+materialised plugin as its `hooks.json`); support scripts live in
+`hooks/claude/scripts/` and are bundled into the plugin's `hooks/scripts/` by
 `bin/installers/claude.mjs` (referenced from hooks.json via `$CLAUDE_PLUGIN_ROOT`).
 
 Claude Code's hook model differs from PI's: hooks are shell commands fed a JSON
@@ -16,6 +16,7 @@ UI surface. Each decision below is grounded in the Claude Code hooks reference.
 |---|---|---|
 | `session-start.ts` | `SessionStart` hook commands | **Port** (extended) |
 | `auto-name.ts` | — | **Reject** — built-in |
+| `agent-guardrails/` | — | **Reject** — pi-only (no system-prompt hook) |
 | `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
 | `skill-stats/` | — | **Reject** — no equivalent |
 | `subagent/` | — | **Reject** — native |
@@ -76,6 +77,17 @@ events), and `elicitation_*` (dialog trivia). Skipped from the pi original: the
 response summary (Claude's notification message is already the summary) and the tmux
 session:window.pane title (unavailable to hooks; the plugin title suffices).
 
+## `agent-guardrails/` → Reject (pi-only)
+
+pi appends behavioural circuit-breakers (retry limits, check-in triggers,
+atomic-change discipline) to the system prompt once per user prompt via
+`before_agent_start` — which fires before the agent loop, so the block applies to
+every turn of that run. Claude Code has no hook that can modify the system prompt;
+its nearest surface, `SessionStart` `additionalContext`, injects conversation
+context rather than system instructions. The rules are harness-agnostic prose, so
+a future port could append them to the existing ported SessionStart hook — out of
+scope for this pi-first slice.
+
 ## `skill-stats/` → Reject (no equivalent)
 
 pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md
@@ -100,7 +112,7 @@ for little signal. Rejected; Claude Code ships its own usage analytics
 ## `subagent/` → Reject (native)
 
 pi's `subagent` tool spawns isolated `pi --mode json` processes. Claude Code has
-native subagents — the plugin already ships `claude/agents/*.md` (including
+native subagents — the plugin already ships `~/.agent-cortex/claude/agents/*.md` (including
 `ralph`, `plan`, `strategy`, `ralph-plan`) executed via the built-in Agent/Task
 tools with per-session context isolation — so a hook-based workaround would be
 strictly worse.