@jaybeeuu/agent-cortex 1.20.0 → 1.38.1

package/claude/hooks/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/claude/hooks.json

@@ -12,12 +12,27 @@
             "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/docs/claude-hooks.md

@@ -0,0 +1,115 @@
+# Claude Code hooks — extension port audit
+
+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
+`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
+payload on stdin, with events like `SessionStart`, `SessionEnd`, `Stop`,
+`SubagentStop`, and `Notification` — there is no `before_agent_start` /
+`agent_end` / `tool_call` extension API, no runtime tool registration, and no
+UI surface. Each decision below is grounded in the Claude Code hooks reference.
+
+| pi extension | Claude port | Decision |
+|---|---|---|
+| `session-start.ts` | `SessionStart` hook commands | **Port** (extended) |
+| `auto-name.ts` | — | **Reject** — built-in |
+| `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
+| `skill-stats/` | — | **Reject** — no equivalent |
+| `subagent/` | — | **Reject** — native |
+| `agent-modes/` | — | **Reject** — no equivalent |
+
+## `session-start.ts` → SessionStart (port)
+
+pi injects skill-availability hints + project context files (AGENTS.md,
+`docs/user-preferences.md`) into every session. Claude Code already loads
+`AGENTS.md` natively and the existing SessionStart hook nudge ("Load AGENTS.md
+and active beads context…") plus the style-skill policy (PR #57) cover the
+context side. This bead closes the remaining gap: a skill-policy command listing
+the meta-skills (`using-agent-skills` for routing, `bd-tool` for beads context,
+`git-workflow` for branch/PR discipline). SessionStart command-hook stdout is
+added to Claude's context, so plain `echo` commands are the right shape —
+keep them fast and dependency-free. Skipped from the pi original: the dynamic
+file read of AGENTS.md/user-preferences.md, since Claude Code loads AGENTS.md
+itself and user-preferences.md is a pi-harness document.
+
+## `auto-name.ts` → Reject (built-in)
+
+pi names sessions via a tiny side-model call on the first prompt. Claude Code
+already auto-generates descriptive session titles (visible in `claude --resume`;
+a background model request in interactive and headless/SDK sessions) and supports
+explicit naming via `--name` / `/rename`. A hook-based title generator would
+duplicate platform behaviour with an extra LLM call — rejected. (SessionStart
+hooks can also set `sessionTitle` in JSON output for the rare case where a
+custom title is genuinely needed.)
+
+## `notify/` → Notification hook (port)
+
+pi notifies on `agent_end` for multi-turn/long tasks with a desktop notification
++ bell. Claude Code's native `Notification` event fires at the equivalent
+completion points and already carries `message`, `title`, and `notification_type`
+in the payload — and hooks emit desktop notifications by returning a
+`terminalSequence` JSON field (hooks have no controlling terminal; Claude Code
+emits the sequence itself, including inside tmux/screen).
+
+Implemented as a `Notification` hook with matcher
+`agent_completed|agent_needs_input|permission_prompt` invoking `scripts/notify.mjs`,
+which reads the payload from stdin and prints the OSC sequence for the detected
+terminal (Kitty OSC 99, iTerm2/Windows Terminal OSC 9, default urxvt/Ghostty/Warp
+OSC 777 — same detection as the pi `notify` extension). The Notification matcher
+is an **exact-string list** over the `notification_type` field; there are no
+`success`/`error` types (an earlier draft used that matcher, which silently never
+fired). The documented types are `permission_prompt`, `idle_prompt`, `auth_success`,
+`elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`,
+`elicitation_response`, `agent_needs_input`, `agent_completed`,
+`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`
+(the `agent_*` types require Claude Code v2.1.198+, the `quota_auto_resume_*`
+types v2.1.234+). The selection maps to pi's "task completed / failed / needs
+approval" semantics: `agent_completed` covers completion and failure ("finishes
+or fails"), `agent_needs_input` covers a background session waiting on input, and
+`permission_prompt` covers an awaited approval. Explicitly excluded as noise:
+`idle_prompt` (fires ~60s after every turn you don't answer within a minute — a
+desktop ping on every pause), `auth_success` and `quota_auto_resume_*` (not task
+events), and `elicitation_*` (dialog trivia). Skipped from the pi original: the LLM
+response summary (Claude's notification message is already the summary) and the tmux
+session:window.pane title (unavailable to hooks; the plugin title suffices).
+
+## `skill-stats/` → Reject (no equivalent)
+
+pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md
+reads, and turns, exposing a `/skill-stats` query. Claude Code exposes none of
+the required observability to hooks:
+
+- **No "loaded" event** — nothing fires when a skill enters context, and hooks
+  never see system-prompt contents, so the primary "loaded" metric has no source.
+- **Partial invocation/read observability only** — `PreToolUse` on the `Skill`
+  tool and `UserPromptExpansion` on slash commands would approximate
+  invocations, and `PostToolUse` on `Read` would approximate skill reads, but
+  the signals are fuzzy (Read covers any file; direct `/skill` typing bypasses
+  `PreToolUse`).
+- **No query surface** — Claude Code plugin commands are markdown files, not
+  scripts, so there is no equivalent of the pi `/skill-stats` command, and
+  persistent state would live outside the plugin model.
+
+A half-observable port would diverge from the pi semantics and add moving parts
+for little signal. Rejected; Claude Code ships its own usage analytics
+(`/usage`, sessions list, statsig) if insights are needed.
+
+## `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
+`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.
+
+## `agent-modes/` → Reject (no equivalent)
+
+pi switches system prompts + tool restrictions at runtime with a TUI mode
+selector. Claude Code exposes no hook or settings surface for dynamic
+tool-restriction/prompt-switching of the main agent; the closest equivalents are
+native (permission modes like plan mode configured via settings, and subagents
+— already covered above). The `--agent <name>` start flag is covered by
+`claude --agent` in newer versions. Rejected.

package/docs/ideas/unified-ci-pipeline.md

@@ -0,0 +1,28 @@
+# Idea: Unified CI Pipeline with Parallel Checks
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Why it might be useful
+The current CI setup has two problems:
+1. **Slow feedback** — checks run serially, making the pipeline slower than it needs to be.
+2. **Broken releases** — the release job (version branch creation) is a separate pipeline, so it can fire even when checks fail. A broken commit can reach the version branch.
+
+Combining them gives faster feedback (parallel checks) and a safety gate (release step only runs if all checks pass).
+
+## How we might do it
+- Merge the check pipeline and release pipeline into a single pipeline.
+- Fan out all checks to run in parallel.
+- Make the version branch creation a downstream job/step that depends on all checks passing.
+
+## When to think about it
+When CI pipeline speed or release safety becomes a recurring friction — e.g. after the changesets/release workflow is fully set up and seeing real traffic.
+
+## Priority
+P2 — infrastructure quality-of-life. Not blocking current work, but a clear improvement once the release flow stabilises.
+
+## Notes
+- Setup job with artifact infrastructure added (2026-08): install + build now happen once in a `setup` job, artifacts are shared with downstream jobs via upload/download-artifact. This is the first step toward the unified pipeline vision.
+- Depends on the changesets release workflow being in place (P1 beads `agnt-ctx-d1ht`, `agnt-ctx-5bcu`).
+- Should be straightforward once the pipeline shape is settled.
+- **Release pipeline fires on every push to main** — this wastes CI minutes. It should only run when there are changesets to process (e.g. when the version packages PR is merged, or when new changesets land on main). Add a path filter or a pre-check that skips the job when no `.changeset/*.md` files changed.

package/docs/skills/skill-anatomy.md

@@ -29,6 +29,14 @@ Optional fields:
 - Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
 - Avoid ALL-CAPS emphasis.
 
+## Tool references
+
+Reference agent tools by `{{TOOL:name}}` token (canonical copilot name), never a
+hardcoded harness-specific name such as `bash`, `task`, or `read_agent` — installers
+substitute the per-harness name from `token-map.json` at install time. Add any new tool
+to the map's `tools` section in the same change; unknown tokens are hard errors. See
+`token-map.README.md` for the full authoring rules.
+
 ## Required sections
 
 Every skill must include:
@@ -81,6 +89,7 @@ Provide completion gates that are testable and stage-scoped.
 
 A skill passes anatomy review when:
 - [ ] Front matter uses required fields and valid description format.
+- [ ] Tool references use `{{TOOL:name}}` tokens, not hardcoded tool names.
 - [ ] Required sections exist and follow canonical ordering.
 - [ ] Optional sections (if present) include what/when/example guidance.
 - [ ] Verification checklist contains concrete, machine-checkable items.

package/extensions/agent-modes/README.md

@@ -0,0 +1,54 @@
+# Agent Modes Extension
+
+Makes the agent-cortex agents (ralph, ralph-plan, plan, strategy) available as
+switchable PI modes. Each mode injects the agent's full system prompt into the
+running context, restricts tools to the agent's declared tool set, and shows a
+status indicator with the active agent name.
+
+## Usage
+
+| Command | Description |
+| --- | --- |
+| `/agent` | Show the agent mode selector |
+| `/agent <name>` | Switch to an agent mode directly (e.g. `/agent ralph`) |
+| `/agent default` | Return to default mode (full tool access) |
+| `Ctrl+Shift+A` | Cycle through agent modes |
+| `--agent <name>` | Start PI in a specific agent mode |
+
+## How agents are discovered
+
+Agents are read from the **composable source format** in the package's
+`agents/` directory:
+
+```
+agents/<name>/
+├── agent.md             # Shared body (harness-agnostic)
+└── pi/
+    ├── frontmatter.json # PI metadata: name, description, tools
+    └── <section>.md     # Optional sections referenced by {{SECTION:name}}
+```
+
+The PI system prompt is composed from `agent.md` per the token-map.json
+contract:
+
+1. `{{SECTION:name}}` tokens are replaced with the agent's `pi/<name>.md`.
+2. `{{TOOL:key}}` / `{{PATH:key}}` tokens are substituted against the pi column
+   of `token-map.json`, with the plugin root resolved from the actual extension
+   location. Tools without a PI equivalent (`ask_user`, `skill`) are omitted
+   from the tool set.
+
+Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
+composable directory — they are generated output (scripts/build-copilot-agents.mjs)
+but may exist for non-migrated agents. A composable directory always wins over its
+flat counterpart for the same agent id.
+
+## Development
+
+Discovery and prompt composition live in `discover.ts` (unit-tested against
+fixture directories in `discover.test.ts`); `index.ts` only wires discovery
+into the extension API.
+
+```bash
+pnpm test        # run discover.test.ts
+pnpm typecheck   # tsc --noEmit
+```

package/extensions/agent-modes/discover.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import {
+  type AgentDef,
+  type TokenMap,
+  discoverAgents,
+  loadTokenMap,
+} from "./discover.ts";
+
+// Real token-map.json at the package root — the canonical tool/path map the
+// extension ships with. Used to verify translation against the source of truth.
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const REAL_TOKEN_MAP = loadTokenMap(join(REPO_ROOT, "agents"));
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+interface Fixture {
+  dir: string;
+  agentsDir: string;
+  cleanup: () => void;
+}
+
+function makeFixture(): Fixture {
+  const dir = mkdtempSync(join(tmpdir(), "agent-modes-"));
+  return {
+    dir,
+    agentsDir: join(dir, "agents"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx: Fixture, relPath: string, content: string): void {
+  const p = join(fx.dir, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+function writeComposableAgent(
+  fx: Fixture,
+  name: string,
+  opts: {
+    body?: string;
+    frontmatter?: Record<string, unknown>;
+    sections?: Record<string, string>;
+  } = {},
+): void {
+  const base = `agents/${name}`;
+  writeFixture(fx, `${base}/agent.md`, opts.body ?? `# ${name}\nBody of ${name}.`);
+  writeFixture(
+    fx,
+    `${base}/pi/frontmatter.json`,
+    JSON.stringify(
+      opts.frontmatter ?? {
+        name: `agent-cortex:${name}`,
+        description: `Description of ${name}`,
+        tools: ["bash", "view", "task"],
+      },
+    ),
+  );
+  for (const [section, body] of Object.entries(opts.sections ?? {})) {
+    writeFixture(fx, `${base}/pi/${section}.md`, body);
+  }
+}
+
+function writeFlatAgent(fx: Fixture, name: string, body: string): void {
+  writeFixture(fx, `agents/${name}.agent.md`, body);
+}
+
+const fixtures: Fixture[] = [];
+function track(fx: Fixture): Fixture {
+  fixtures.push(fx);
+  return fx;
+}
+
+after(() => {
+  for (const fx of fixtures) fx.cleanup();
+});
+
+const FLAT_FRONTMATTER = (name: string, tools: string) =>
+  `---\ndescription: "Flat description of ${name}"\nname: "agent-cortex:${name}"\ntools: ${tools}\n---\n\nFlat body of ${name}.`;
+
+// ─── Tokens ───────────────────────────────────────────────────────────────────
+
+const TOKEN_PROSE =
+  "Run with {{TOOL:bash}}.\n" +
+  "Ask the user with {{TOOL:ask_user}}.\n" +
+  "Read the plan skill at {{PATH:skills/workflow/plan/SKILL.md}}.\n" +
+  "Agents live in {{PATH:agents_dir}}.";
+
+// ─── Composable discovery ────────────────────────────────────────────────────
+
+describe("discoverAgents (composable source format)", () => {
+  it("discovers agents from <name>/agent.md + <name>/pi/frontmatter.json", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", {
+      body: "# ralph\nUse {{TOOL:task}} to spawn subagents.\n\n{{SECTION:polling}}",
+      frontmatter: {
+        name: "agent-cortex:ralph",
+        description: "Runs beads end-to-end",
+        tools: ["bash", "view", "rg", "glob", "task", "read_agent"],
+      },
+      sections: {
+        polling: "## PI polling\nPoll with task + read_agent.",
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const ralph = agents[0];
+    assert.equal(ralph.id, "ralph");
+    assert.equal(ralph.name, "agent-cortex:ralph");
+    assert.equal(ralph.description, "Runs beads end-to-end");
+    // Canonical tool names translated to PI names via token-map (glob→find, rg→grep, view→read).
+    assert.deepEqual(ralph.tools, ["bash", "find", "grep", "read", "read_agent", "task"]);
+    // SECTION token resolved from pi/<section>.md; TOOL token substituted.
+    assert.match(ralph.prompt, /Use task to spawn subagents\./);
+    assert.match(ralph.prompt, /Poll with task \+ read_agent\./);
+    assert.doesNotMatch(ralph.prompt, /\{\{/);
+  });
+
+  it("substitutes TOOL / PATH tokens against token-map.json using the real plugin root", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      body: TOKEN_PROSE,
+      frontmatter: { name: "agent-cortex:plan", description: "Planner", tools: [] },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    const plan = agents[0];
+
+    // {{TOOL:bash}} → bash.
+    assert.match(plan.prompt, /Run with bash\./);
+    // {{TOOL:ask_user}} → null for pi — token dropped (dangling prose is the author's
+    // responsibility per token-map.README), not left as literal token syntax.
+    assert.doesNotMatch(plan.prompt, /\{\{TOOL:ask_user\}\}/);
+    // Relative {{PATH:...}} resolves against the actual package root (dir of agents/).
+    assert.match(plan.prompt, new RegExp(`Read the plan skill at ${escapeRegExp(fx.dir)}/skills/workflow/plan/SKILL\\.md\\.`));
+    // Named {{PATH:agents_dir}} resolves to <root>/agents.
+    assert.match(plan.prompt, new RegExp(`Agents live in ${escapeRegExp(fx.agentsDir)}\\.`));
+    assert.doesNotMatch(plan.prompt, /\{\{/);
+  });
+
+  it("drops null-mapped tools (ask_user, skill) from the PI tool set", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      frontmatter: {
+        name: "agent-cortex:plan",
+        description: "Planner",
+        tools: ["bash", "ask_user", "skill", "web_fetch"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    // ask_user → null (omitted), skill → null (omitted), web_fetch → fetch_content.
+    assert.deepEqual(agents[0].tools, ["bash", "fetch_content"]);
+  });
+
+  it("uses the built-in fallback map when token-map.json is unavailable", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "legacy", {
+      frontmatter: {
+        name: "agent-cortex:legacy",
+        description: "No token map",
+        tools: ["view", "glob", "ask_user"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir);
+    assert.equal(agents.length, 1);
+    // Copilot→PI fallback: view→read, glob→find+ls; unmapped ask_user passes through.
+    assert.deepEqual(agents[0].tools, ["ask_user", "find", "ls", "read"]);
+  });
+
+  it("returns an empty list for a missing agents directory", () => {
+    const fx = track(makeFixture());
+    assert.deepEqual(discoverAgents(join(fx.dir, "does-not-exist"), REAL_TOKEN_MAP), []);
+  });
+
+  it("returns an empty list when no agents are present", () => {
+    const fx = track(makeFixture());
+    mkdirSync(fx.agentsDir, { recursive: true });
+    assert.deepEqual(discoverAgents(fx.agentsDir, REAL_TOKEN_MAP), []);
+  });
+});
+
+// ─── Flat fallback ────────────────────────────────────────────────────────────
+
+describe("discoverAgents (flat fallback)", () => {
+  it("prefers a composable directory over its flat file for the same agent", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", { body: "Composable body." });
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '["bash", "view"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    assert.equal(agents[0].id, "ralph");
+    assert.match(agents[0].prompt, /Composable body\./);
+    assert.doesNotMatch(agents[0].prompt, /Flat body/);
+  });
+
+  it("falls back to flat *.agent.md for agents without a composable directory", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "strategy", FLAT_FRONTMATTER("strategy", '["bash", "view", "web_fetch"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const strategy = agents[0];
+    assert.equal(strategy.id, "strategy");
+    assert.equal(strategy.name, "agent-cortex:strategy");
+    assert.equal(strategy.description, "Flat description of strategy");
+    // view→read, web_fetch→fetch_content via token-map.
+    assert.deepEqual(strategy.tools, ["bash", "fetch_content", "read"]);
+    assert.match(strategy.prompt, /Flat body of strategy\./);
+  });
+});
+
+// ─── loadTokenMap ────────────────────────────────────────────────────────────
+
+describe("loadTokenMap", () => {
+  it("reads the real token-map.json at the package root", () => {
+    assert.ok(REAL_TOKEN_MAP);
+    assert.equal(typeof REAL_TOKEN_MAP?.tools?.bash?.pi, "string");
+    // ask_user has no PI equivalent per the contract — must stay null.
+    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, null);
+    assert.ok(REAL_TOKEN_MAP?.paths?.agents_dir);
+  });
+});
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}