@jaybeeuu/agent-cortex 1.20.0 → 1.38.1

package/extensions/subagent/wait.ts

@@ -0,0 +1,118 @@
+/**
+ * Blocking wait over background subagent runs.
+ *
+ * Factored out of the extension entrypoint so the wait semantics can be tested
+ * without spawning real `pi` processes: the run store is injected as a lookup
+ * function and completion is driven by each entry's `promise` (which resolves
+ * exactly when the run's result is committed).
+ */
+
+export interface BackgroundEntry<T> {
+	/** The run's result once it finishes; null while the agent is still working. */
+	result: T | null;
+	/** Resolves when the run finishes (success, failure, or abort). */
+	promise: Promise<unknown>;
+}
+
+export interface CompletedRun<T> {
+	agentId: string;
+	result: T;
+}
+
+export interface WaitResult<T> {
+	/** Requested agents whose result is now available, in requested order. */
+	completed: CompletedRun<T>[];
+	/** Requested agents still working when the wait ended. */
+	running: string[];
+	/** Requested IDs with no tracked run (never dispatched or expired). */
+	notFound: string[];
+	/** True when the wait ended because the timeout elapsed with agents still running. */
+	timedOut: boolean;
+	/** True when the wait ended because the abort signal fired. */
+	aborted: boolean;
+}
+
+export interface WaitOptions {
+	/** Block for at most this many milliseconds before returning (default 120_000). */
+	timeoutMs?: number;
+	/** Abort the wait early (e.g. user Ctrl+C). */
+	signal?: AbortSignal;
+}
+
+export const DEFAULT_WAIT_TIMEOUT_MS = 120_000;
+
+type GetEntry<T> = (agentId: string) => BackgroundEntry<T> | undefined;
+
+function scan<T>(getEntry: GetEntry<T>, agentIds: string[], timedOut: boolean, aborted: boolean): WaitResult<T> {
+	const completed: CompletedRun<T>[] = [];
+	const running: string[] = [];
+	const notFound: string[] = [];
+	for (const agentId of agentIds) {
+		const entry = getEntry(agentId);
+		if (!entry) notFound.push(agentId);
+		else if (entry.result !== null) completed.push({ agentId, result: entry.result });
+		else running.push(agentId);
+	}
+	return { completed, running, notFound, timedOut, aborted };
+}
+
+export async function waitForAgents<T>(
+	getEntry: GetEntry<T>,
+	agentIds: string[],
+	options: WaitOptions = {},
+): Promise<WaitResult<T>> {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+	const { signal } = options;
+
+	const hasResolution = (result: WaitResult<T>): boolean => result.completed.length > 0 || result.notFound.length > 0;
+
+	// Fast path: any requested agent that already resolved (completed or unknown)
+	// ends the wait — the caller dispatches replacements before waiting again.
+	const initial = scan(getEntry, agentIds, false, false);
+	if (hasResolution(initial)) return initial;
+
+	// Single shared abort racer so a fired signal always wins the next race.
+	const abortRacer: Promise<"aborted"> | undefined = signal
+		? new Promise((resolve) => {
+				if (signal.aborted) resolve("aborted");
+				else signal.addEventListener("abort", () => resolve("aborted"), { once: true });
+			})
+		: undefined;
+
+	const deadline = Date.now() + timeoutMs;
+	let timedOut = false;
+	let aborted = false;
+
+	while (!timedOut && !aborted) {
+		const runningPromises: Promise<unknown>[] = agentIds
+			.map(getEntry)
+			.filter((entry): entry is BackgroundEntry<T> => entry !== undefined && entry.result === null)
+			.map((entry) => entry.promise);
+
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) {
+			timedOut = true;
+			break;
+		}
+
+		const racers: Promise<"completed" | "timeout" | "aborted">[] = [];
+		if (runningPromises.length > 0) {
+			// A settled run promise means its result was committed before settling.
+			racers.push(Promise.race(runningPromises.map((p) => p.then(() => "completed" as const, () => "completed" as const))));
+		}
+		racers.push(new Promise((resolve) => setTimeout(() => resolve("timeout" as const), remaining)));
+		if (abortRacer) racers.push(abortRacer);
+
+		const outcome = await Promise.race(racers);
+		if (outcome === "timeout") timedOut = true;
+		else if (outcome === "aborted") aborted = true;
+
+		// "completed": at least one run promise settled — re-scan. Entries whose
+		// result is now available end the wait; everything else loops back under
+		// the same deadline.
+		const current = scan(getEntry, agentIds, timedOut, aborted);
+		if (hasResolution(current) || timedOut || aborted) return current;
+	}
+
+	return scan(getEntry, agentIds, timedOut, aborted);
+}

package/hooks/claude/hooks.json

@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Load AGENTS.md and active beads context before taking action.'"
+          },
+          {
+            "type": "command",
+            "command": "echo 'Style policy: this project ships style skills — prefer them over ad-hoc choices. Invoke style-code BEFORE writing or editing code (and when refactoring); style-tests BEFORE writing or changing tests; style-documentation BEFORE writing or updating docs; style-comms BEFORE composing commit messages, PR descriptions, tickets, or other written deliverables.'"
+          },
+          {
+            "type": "command",
+            "command": "echo 'Skill policy: agent-cortex ships skills — prefer them over ad-hoc choices. using-agent-skills routes work to the right skill (check it first when unsure); bd-tool tracks beads tasks (run bd ready for available work); git-workflow enforces branch and PR discipline. Invoke skills via the Skill tool.'"
+          },
+          {
+            "type": "command",
+            "command": "echo 'Be extremely concise. Sacrifice grammar for the sake of concision.'"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "agent_completed|agent_needs_input|permission_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/notify.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/claude/scripts/notify.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Claude Code Notification hook — desktop notification on task completion/error.
+//
+// Reads the Notification hook JSON payload from stdin and prints a
+// `{ "terminalSequence": "..." }` response for Claude Code to emit. Hooks run
+// without a controlling terminal, so OSC sequences must go through Claude Code
+// itself (it handles tmux/screen re-wrapping); writing /dev/tty directly fails.
+//
+// Mapped from the pi `notify` extension (extensions/notify/): pi notifies on
+// agent_end for multi-turn or long tasks. Claude Code's Notification matcher is an
+// exact-string list over `notification_type` values (there are no `success`/
+// `error` types) — hooks.json selects `agent_completed|agent_needs_input|permission_prompt`
+// to mirror "task completed / failed / needs approval". The payload already carries
+// a message + title, so no summarization LLM call is needed here.
+//
+// Zero dependencies; runs on the Node that ships with Claude Code.
+
+let raw = "";
+for await (const chunk of process.stdin) {
+  raw += chunk;
+}
+
+let payload = {};
+try {
+  payload = raw.trim() ? JSON.parse(raw) : {};
+} catch {
+  process.exit(0); // never fail a session on an unparsable payload
+}
+
+const message = typeof payload.message === "string" ? payload.message.trim() : "";
+if (!message) process.exit(0); // nothing worth notifying (e.g. autocompact events)
+
+const title =
+  typeof payload.title === "string" && payload.title.trim() ? payload.title.trim() : "Claude Code";
+const type = typeof payload.notification_type === "string" ? payload.notification_type : "";
+
+process.stdout.write(JSON.stringify({ terminalSequence: pickSequence(title, message, type) }) + "\n");
+
+/** Pick an OSC notification escape sequence for the detected terminal. */
+function pickSequence(title, message, type) {
+  const body = message.replace(/\u001b/g, "").replace(/\n/g, " ").trim();
+  const label = type ? `${type}: ${title}` : title;
+
+  if (process.env.KITTY_WINDOW_ID) {
+    // Kitty: two-part persistent notification (title + body) — same form as the pi notify extension.
+    return `\u001b]99;i=1:d=1;${title}\u001b\\\u001b]99;i=1:p=body;${body}\u001b\\`;
+  }
+  if (process.env.TERM_PROGRAM === "iTerm.app" || process.env.ITERM_SESSION_ID) {
+    // iTerm2 / ConEmu / Windows Terminal / WezTerm: OSC 9.
+    return `\u001b]9;${label}: ${body}\u0007`;
+  }
+  // urxvt / Ghostty / Warp, and default fallback: OSC 777.
+  return `\u001b]777;notify;${label};${body}\u0007`;
+}

package/lib/cli.mjs

@@ -1,5 +1,15 @@
 const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
 
+// Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
+// the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
+// malformed options surface as `optionError` on the parsed result; the CLI
+// prints them and exits 1.
+const INSTALL_OPTIONS = {
+  "--dry-run": { key: "dryRun" },
+  "--output": { key: "output" },
+  "--plugin-root": { key: "pluginRoot" },
+};
+
 export function parseArgs(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     return { command: "help" };
@@ -8,8 +18,42 @@ export function parseArgs(argv) {
   const [command, ...rest] = argv;
 
   if (command === "install") {
-    const harness = rest[0] ?? null;
-    return { command: "install", harness };
+    let harness = null;
+    let i = 0;
+    if (rest.length > 0 && !rest[0].startsWith("--")) {
+      harness = rest[0];
+      i = 1;
+    }
+
+    const options = {};
+    for (; i < rest.length; i++) {
+      const arg = rest[i];
+      // Support both `--output=<dir>` and `--output <dir>`.
+      const inlineValue = arg.startsWith("--output=") ? arg.slice("--output=".length) : null;
+      const spec = inlineValue !== null ? INSTALL_OPTIONS["--output"] : INSTALL_OPTIONS[arg];
+      if (!spec) {
+        return { command: "install", harness, optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+      }
+      if (spec.key === "dryRun") {
+        options.dryRun = true;
+        continue;
+      }
+      if (inlineValue !== null) {
+        options[spec.key] = inlineValue;
+        continue;
+      }
+      const value = rest[i + 1];
+      if (value == null || value.startsWith("--")) {
+        return { command: "install", harness, optionError: `Missing value for "${arg}". Run "agent-cortex --help" for usage.` };
+      }
+      options[spec.key] = value;
+      i += 1;
+    }
+
+    if (Object.keys(options).length === 0) {
+      return { command: "install", harness };
+    }
+    return { command: "install", harness, ...options };
   }
 
   return { command: "unknown", name: command };
@@ -21,6 +65,21 @@ export function buildHelpText() {
 Commands:
   install <harness>   Install agent-cortex for a harness
                       Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}
+                      Options (claude):
+                        --output <dir>   Write the plugin subtree to <dir>
+                                         (default: <package root>/claude)
+                        --dry-run        Print what would be generated without writing
+                      Options (copilot):
+                        --output <dir>   Write the flat *.agent.md files to <dir>
+                                         (default: <package root>/agents — the dir
+                                         plugin.json "agents" scans)
+                        --dry-run        Print what would be generated without writing
+                      Options (pi):
+                        --dry-run             Show what would be installed without writing
+                        --output <dir>        Install into <dir>/agents and <dir>/skills
+                                              (default: ~/.pi/agent)
+                        --plugin-root <dir>   Override the plugin root used for {{PATH:...}}
+                                              tokens (default: token-map.json's pi value)
   --help, -h          Show this help text`;
 }
 
@@ -34,4 +93,4 @@ export function validateHarness(harness) {
   return { ok: true };
 }
 
-export { SUPPORTED_HARNESSES };
+export { SUPPORTED_HARNESSES };

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.20.0",
+  "version": "1.38.1",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/jaybeeuu/agent-cortex"
-  },
+  "repository": "https://github.com/jaybeeuu/agent-cortex",
   "bin": {
     "agent-cortex": "./bin/agent-cortex.mjs"
   },
@@ -17,6 +14,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.1",
     "tsx": "^4.0.0",
     "yaml": "^2.0.0"
   },
@@ -31,9 +29,14 @@
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
     "lint": "pnpm typecheck",
-    "test": "pnpm -r test",
+    "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node scripts/build-claude-agents.mjs",
+    "build:claude": "node bin/agent-cortex.mjs install claude",
+    "build:copilot": "node scripts/build-copilot-agents.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:claude && pnpm build:copilot",
+    "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
+    "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.36.0",
+  "version": "1.38.1",
   "author": {
     "name": "jaybeeuu"
   },

package/pnpm-workspace.yaml

@@ -1,4 +1,5 @@
 packages:
+  - "."
   - "skills/*/scripts"
   - "extensions/*"
 allowBuilds:

package/scripts/build-copilot-agents.mjs

@@ -0,0 +1,30 @@
+// Regenerates the committed Copilot CLI flat agent files (agents/*.agent.md)
+// from the canonical composable agent sources (agents/<name>/).
+//
+// This script is a thin wrapper over the shared install-time generator
+// (bin/installers/copilot.mjs) — `agent-cortex install copilot` runs exactly the
+// same code path, so install-time and build-time output can never diverge. CI
+// runs this and checks `git diff --exit-code -- 'agents/*.agent.md'` to
+// guarantee the committed flat files are never stale: a fresh clone (or a
+// direct path plugin install) ships the Copilot plugin read-ready.
+//
+//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
+//                             agents/<name>/copilot/frontmatter.json +
+//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
+//                             with {{TOOL:...}}/{{PATH:...}} substituted against
+//                             the copilot column of token-map.json.
+//
+// The flat files live in the same agents/ directory the Copilot plugin scans
+// (plugin.json "agents": "agents/"), next to the composable dirs they come
+// from — the generator only writes *.agent.md files and never deletes.
+//
+// Run: pnpm build:copilot   (node scripts/build-copilot-agents.mjs)
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { installCopilot } from "../bin/installers/copilot.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/lib/compose-agent.mjs

@@ -0,0 +1,241 @@
+// Shared composer: reads a composable agent directory (agents/<name>/) and emits
+// the harness-specific agent content defined by agents/README.md. The Copilot
+// generator (scripts/build-copilot-agents.mjs) and the Claude install-time generator
+// (bin/installers/claude.mjs) compose from here, so the composable dirs are
+// the single source of truth and the flat/generated files stay in lockstep.
+//
+// Composition per the agents/README.md contract:
+//   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
+//   2. {{TOOL:key}} is replaced with the harness column of token-map.json.
+//   3. {{PATH:arg}} with a named key resolves through token-map.json's paths
+//      table; anything else is a relative path and stays verbatim.
+// Substitution order is SECTION → TOOL → PATH (matches extensions/agent-modes).
+// Missing sections, unknown tool keys, or schema-invalid frontmatter are hard
+// errors: a committed generated file must never ship a literal token or a
+// silently dropped section.
+//
+// Options (the pi installer passes `dropNullTools`, `pluginRoot` and
+// `resolveRelativePaths`; the copilot generator and claude installer use the strict defaults):
+//   dropNullTools          replace null-mapped tool tokens with an empty string and
+//                          warn instead of throwing (pi's prose rule per the
+//                          token-map contract)
+//   pluginRoot             override the plugin_root used for resolved paths
+//                          (installers compute it from the actual install layout)
+//   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
+//                          instead of staying verbatim (install time; the build
+//                          scripts leave them bare for Copilot CLI resolution)
+//   warn                   callback for drop/omit warnings (default: no-op; the
+//                          pi installer collects them into its result)
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Token substitution ──────────────────────────────────────────────────────
+
+const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
+const PATH_RE = /\{\{PATH:([^}]+)\}\}/g;
+
+function noop() {}
+
+/**
+ * Substitute {{TOOL:...}} and {{PATH:...}} tokens in arbitrary content (agent
+ * bodies, skill files) against one harness column of token-map.json.
+ *
+ * - TOOL: unknown key → throw (the map must stay complete); null mapping → drop
+ *   with a warning when `dropNullTools`, otherwise throw.
+ * - PATH: named key → resolve through the paths table (plugin_root overridable);
+ *   non-keyed → join(pluginRoot, arg) when `resolveRelativePaths`, else verbatim.
+ * - SECTION tokens are *not* handled here — the agent composer resolves them from
+ *   the harness's section files before calling this.
+ *
+ * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
+ * @returns {string}
+ */
+export function substituteTokens(content, harness, tokenMap, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop, context = "" } = options;
+  const ctx = context ? `${context}: ` : "";
+
+  // 2. {{TOOL:key}} → token-map.json tools.<key>.<harness>
+  content = content.replace(TOOL_RE, (_token, key) => {
+    const entry = tokenMap.tools[key];
+    if (!entry) throw new Error(`${ctx}unknown tool token {{TOOL:${key}}} — extend token-map.json`);
+    const mapped = entry[harness];
+    if (mapped == null) {
+      if (dropNullTools) {
+        warn(`tool token {{TOOL:${key}}} has no ${harness} mapping — dropped`);
+        return "";
+      }
+      throw new Error(`${ctx}tool token {{TOOL:${key}}} has no ${harness} mapping (null) — drop the token in agent.md first`);
+    }
+    return mapped;
+  });
+
+  // 3. {{PATH:arg}} → named keys via token-map.json paths; relative paths verbatim
+  //    (or resolved against pluginRoot when the installer option is set)
+  content = content.replace(PATH_RE, (_token, arg) =>
+    resolvePath(arg, harness, tokenMap, { pluginRoot, resolveRelativePaths }),
+  );
+
+  return content;
+}
+
+/**
+ * Compose the harness-specific agent content from a composable agent directory.
+ *
+ * @param {string} root    Package root (contains agents/ and token-map.json)
+ * @param {string} name    Agent directory name (e.g. "ralph", "plan")
+ * @param {string} harness Harness id: "copilot" | "claude" | "pi"
+ * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
+ */
+export function composeAgent(root, name, harness, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
+  const agentDir = join(root, "agents", name);
+  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = loadTokenMap(root);
+
+  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
+  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+    const sectionPath = join(agentDir, harness, `${section}.md`);
+    if (!existsSync(sectionPath)) {
+      throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
+    }
+    return readFileSync(sectionPath, "utf-8").trim();
+  });
+
+  // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
+  body = substituteTokens(body, harness, tokenMap, {
+    dropNullTools,
+    pluginRoot,
+    resolveRelativePaths,
+    warn,
+    context: `agent "${name}"`,
+  });
+
+  return { ...frontmatter, body: body.trim() };
+}
+
+// ─── Frontmatter ─────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ["name", "description", "tools"];
+const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
+
+/** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
+function parseFrontmatter(path, name, harness) {
+  const raw = readFileSync(path, "utf-8");
+  let fm;
+  try {
+    fm = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`agent "${name}": invalid JSON in ${path}: ${err.message}`);
+  }
+  if (typeof fm !== "object" || fm === null) {
+    throw new Error(`agent "${name}": ${path} must be a JSON object`);
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in fm)) throw new Error(`agent "${name}": ${path} missing required field "${field}" (harness ${harness})`);
+  }
+  if (typeof fm.name !== "string" || fm.name.trim() === "") throw new Error(`agent "${name}": ${path} name must be a non-empty string`);
+  if (typeof fm.description !== "string" || fm.description.trim() === "") throw new Error(`agent "${name}": ${path} description must be a non-empty string`);
+  if (!Array.isArray(fm.tools) || fm.tools.length === 0 || !fm.tools.every((t) => typeof t === "string")) {
+    throw new Error(`agent "${name}": ${path} tools must be a non-empty array of strings`);
+  }
+  for (const key of Object.keys(fm)) {
+    if (![...REQUIRED_FIELDS, ...KNOWN_OPTIONAL_FIELDS].includes(key)) {
+      throw new Error(`agent "${name}": ${path} unknown field "${key}" — strict schema per agents/README.md`);
+    }
+  }
+  return {
+    name: fm.name,
+    description: fm.description,
+    tools: fm.tools,
+    ...(typeof fm.model === "string" ? { model: fm.model } : {}),
+    ...(typeof fm.argumentHint === "string" ? { argumentHint: fm.argumentHint } : {}),
+  };
+}
+
+// ─── Path resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a {{PATH:...}} argument for a harness's generated output.
+ * Named keys resolve through token-map.json's paths table (recursively for
+ * {base, relative} specs); non-keyed args are relative paths, kept verbatim —
+ * the installer beads own precise runtime path resolution (see token-map.README.md).
+ * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
+ * plugin_root base and bare relative paths resolve against the actual install
+ * layout instead.
+ */
+function resolvePath(arg, harness, tokenMap, opts = {}) {
+  const entry = tokenMap.paths?.[arg];
+  if (!entry) {
+    if (opts.resolveRelativePaths && opts.pluginRoot) return join(opts.pluginRoot, arg);
+    return arg;
+  }
+
+  const spec = entry[harness];
+  if (typeof spec === "string") {
+    if (arg === "plugin_root" && opts.pluginRoot) return opts.pluginRoot;
+    return spec;
+  }
+  if (spec && typeof spec === "object" && typeof spec.base === "string" && typeof spec.relative === "string") {
+    return join(resolvePath(spec.base, harness, tokenMap, opts), spec.relative);
+  }
+  throw new Error(`unresolvable {{PATH:${arg}}} for harness "${harness}" — extend token-map.json`);
+}
+
+/**
+ * Translate a frontmatter tool list into one harness's tool names.
+ *
+ * Canonical keys resolve through token-map.json's tools table; a null mapping
+ * means the harness has no equivalent and the entry is omitted (the contract's
+ * tool-list rule); a name that is not a canonical key passes through untouched
+ * (it may be a native tool, e.g. pi's fetch_content). Mirrors the runtime
+ * translation in extensions/agent-modes/discover.ts.
+ *
+ * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} options  { warn }
+ * @returns {string[]}
+ */
+export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}) {
+  const out = [];
+  for (const tool of tools) {
+    const mapping = tokenMap.tools[tool];
+    if (mapping === undefined) {
+      out.push(tool);
+      continue;
+    }
+    const mapped = mapping[harness];
+    if (mapped == null) {
+      warn(`tool "${tool}" has no ${harness} mapping — omitted from the tool list`);
+      continue;
+    }
+    out.push(mapped);
+  }
+  return out;
+}
+
+// ─── Token map ───────────────────────────────────────────────────────────────
+
+/** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
+export function loadTokenMap(root) {
+  const path = join(root, "token-map.json");
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    throw new Error(`missing ${path} — the composer requires token-map.json`);
+  }
+  const parsed = JSON.parse(raw);
+  if (!parsed.tools || !parsed.paths) {
+    throw new Error(`${path}: expected "tools" and "paths" tables`);
+  }
+  return parsed;
+}

package/scripts/sync-plugin-version.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Sync plugin.json version with package.json
+# Called by changesets after versioning to keep them in lockstep
+
+set -euo pipefail
+
+VERSION=$(node -p "require('./package.json').version")
+
+# Update plugin.json version field
+node -e "
+const fs = require('fs');
+const plugin = JSON.parse(fs.readFileSync('plugin.json', 'utf8'));
+plugin.version = '$VERSION';
+fs.writeFileSync('plugin.json', JSON.stringify(plugin, null, 2) + '\n');
+"
+
+echo "✓ Synced plugin.json to version $VERSION"

package/skills/engineering/design-an-interface/SKILL.md

@@ -23,7 +23,7 @@ Ask: "What does this module need to do? Who will use it?"
 
 ### 2. Generate Designs (Parallel Sub-Agents)
 
-Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+Spawn 3+ sub-agents simultaneously using {{TOOL:task}}. Each must produce a **radically different** approach.
 
 ```
 Prompt template for each sub-agent:

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -13,7 +13,7 @@ A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a sma
 
 ### 1. Explore the codebase
 
-Explore the codebase using your available tools (bash, rg, view, glob, find). Navigate organically and note where you experience friction:
+Explore the codebase using your available tools ({{TOOL:bash}}, {{TOOL:rg}}, {{TOOL:view}}, {{TOOL:glob}}). Navigate organically and note where you experience friction:
 
 - Where does understanding one concept require bouncing between many small files?
 - Where are modules so shallow that the interface is nearly as complex as the implementation?