@jaybeeuu/agent-cortex 1.42.0 → 2.0.0

package/extensions/agent-modes/discover.ts

@@ -18,9 +18,9 @@ import type { ThemeColor } from "@earendil-works/pi-coding-agent";
  *      and symlinked installs).
  *
  * Flat `agents/*.agent.md` files are parsed as a fallback for agents that have
- * no composable directory (they are generated output for Copilot, so they may
- * exist for any agent). A composable directory always wins over its flat
- * counterpart.
+ * no composable directory (a staged pi package ships flat renders, and a
+ * hand-written agent may be a single flat file). A composable directory always
+ * wins over its flat counterpart.
  */
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -40,7 +40,7 @@ export interface AgentDef {
   prompt: string;
 }
 
-export type HarnessId = "copilot" | "claude" | "pi";
+export type HarnessId = "claude" | "pi";
 
 export interface PathSpec {
   base: string;
@@ -290,6 +290,21 @@ interface FlatParsed {
   prompt: string;
 }
 
+/**
+ * Split a scalar `tools` value into tool names.
+ *
+ * Accepts the quoted string the pi installer renders (`tools: "bash, read"`)
+ * as well as an unquoted whitespace-separated list (`tools: bash read`).
+ * Commas alone are not enough: a whitespace-separated list would collapse to
+ * one bogus name and the agent would run with no usable tool allowlist.
+ */
+function splitToolList(raw: string): string[] {
+  return raw
+    .replace(/^["']|["']$/g, "")
+    .split(/[,\s]+/)
+    .filter(Boolean);
+}
+
 function parseFlatFrontmatter(raw: string): FlatParsed {
   const lines = raw.split(/\r?\n/);
   if (lines[0] !== "---") return { prompt: raw };
@@ -327,11 +342,16 @@ function parseFlatFrontmatter(raw: string): FlatParsed {
   }
 
   // Parse tools from the tools frontmatter.
-  // Supports two formats:
-  //   tools: ["bash", "view"]        (JSON array, single line)
-  //   tools:                         (YAML list, subsequent lines)
+  // Supports three formats:
+  //   tools: ["bash", "view"]          (JSON array, single line)
+  //   tools: "bash, view"              (scalar list, comma or whitespace separated)
+  //   tools:                           (YAML list, subsequent lines)
   //     - bash
   //     - view
+  //
+  // The scalar form is what the pi installer renders for generated agents, so
+  // it must be read here rather than dropped to DEFAULT_TOOLS (which lifts the
+  // restriction instead of applying it).
   let inToolsBlock = false;
   for (const line of yamlLines) {
     const trimmed = line.trim();
@@ -354,6 +374,8 @@ function parseFlatFrontmatter(raw: string): FlatParsed {
           tools = [];
           continue;
         }
+        tools = splitToolList(val);
+        continue;
       }
     }
 
@@ -409,8 +431,8 @@ function readFlatAgent(filePath: string, tokenMap: TokenMap | null): AgentDef |
  * Discover agents from the agents directory.
  *
  * Composable directories (`<name>/agent.md` + `<name>/pi/frontmatter.json`) are
- * the primary source. Flat `*.agent.md` files (generated output for Copilot) are
- * read only when no composable directory exists for that agent id. When
+ * the primary source. Flat `*.agent.md` files (a staged package's renders, or a
+ * hand-written agent) are read only when no composable directory exists for that agent id. When
  * `tokenMap` is omitted, token-map.json is loaded from the package root;
  * missing/unreadable maps fall back to the built-in copilot→pi translation.
  */

package/extensions/session-start/README.md

@@ -0,0 +1,38 @@
+# session-start
+
+A PI extension that injects, at the start of every session, the project's context files:
+
+- `AGENTS.md`
+- `docs/user-preferences.md`
+
+Paths are relative to the session working directory (`ctx.cwd`); missing or empty files are
+skipped. Content is injected as a hidden `session-start` message on `before_agent_start`, so it
+reaches the model without cluttering the transcript UI.
+
+## No skill list here — on purpose
+
+Earlier versions of this extension appended a hand-written blurb advertising three skills with
+`/skill:<name>` syntax. Both halves were wrong:
+
+- pi has no `/skill:` resolver — nothing maps that token to a read. Skills are used by reading
+  the `SKILL.md` path that pi lists.
+- pi's own system prompt already lists **every** discovered skill with its absolute `SKILL.md`
+  path, so a local three-skill list was incomplete and drifted from `skills/` silently.
+
+The blurb is gone and `index.test.ts` pins the absence of both `/skill:` syntax and hardcoded
+skill names. Keep the authoritative list in `skills/`; do not reintroduce it here.
+
+## Installation
+
+Bundled with the `agent-cortex` PI package — install the package for auto-discovery:
+
+```bash
+pi install git:https://github.com/jaybeeuu/agent-cortex
+```
+
+## Development
+
+```bash
+pnpm --filter @agent-cortex/session-start test
+pnpm --filter @agent-cortex/session-start typecheck
+```

package/extensions/session-start/index.test.ts

@@ -0,0 +1,122 @@
+import { after, before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import sessionStartExtension from "./index.ts";
+
+// ─── Harness ─────────────────────────────────────────────────────────────────
+
+interface InjectedMessage {
+  customType: string;
+  content: string;
+  display: boolean;
+}
+
+/** A handler recorded from `pi.on`, invoked via Reflect.apply so its exact
+ *  overload signature does not leak into the fake. */
+type RecordedHandler = (...args: never[]) => unknown;
+
+interface FakePi {
+  pi: ExtensionAPI;
+  /** Simulate pi dispatching `before_agent_start` and return the injected message. */
+  start(cwd: string): Promise<InjectedMessage | undefined>;
+}
+
+function createFakePi(): FakePi {
+  const handlers = new Map<string, RecordedHandler[]>();
+
+  const pi: ExtensionAPI = {
+    on: (event: string, handler: RecordedHandler) => {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+  } as unknown as ExtensionAPI;
+
+  return {
+    pi,
+    async start(cwd) {
+      const handler = handlers.get("before_agent_start")?.[0];
+      assert.ok(handler, "session-start should register a before_agent_start handler");
+      const run = handler as unknown as (
+        event: unknown,
+        ctx: { cwd: string },
+      ) => Promise<{ message?: InjectedMessage } | undefined>;
+      const result = await run({}, { cwd });
+      return result?.message;
+    },
+  };
+}
+
+/** Run one simulated session start against `cwd` and return the injected text. */
+async function inject(cwd: string): Promise<string | undefined> {
+  const fake = createFakePi();
+  sessionStartExtension(fake.pi);
+  const message = await fake.start(cwd);
+  return message?.content;
+}
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const AGENTS_MD = "# AGENTS\n\nProject instructions live here.";
+const PREFERENCES_MD = "# User Preferences\n\nPrefer pnpm over npm.";
+
+describe("session-start injection", () => {
+  let emptyProject: string;
+  let fullProject: string;
+
+  before(() => {
+    emptyProject = mkdtempSync(join(tmpdir(), "session-start-empty-"));
+    fullProject = mkdtempSync(join(tmpdir(), "session-start-full-"));
+    writeFileSync(join(fullProject, "AGENTS.md"), AGENTS_MD, "utf-8");
+    mkdirSync(join(fullProject, "docs"), { recursive: true });
+    writeFileSync(join(fullProject, "docs", "user-preferences.md"), PREFERENCES_MD, "utf-8");
+  });
+
+  after(() => {
+    rmSync(emptyProject, { recursive: true, force: true });
+    rmSync(fullProject, { recursive: true, force: true });
+  });
+
+  it("injects AGENTS.md and docs/user-preferences.md content", async () => {
+    const content = await inject(fullProject);
+    assert.ok(content, "expected the context files to be injected");
+    assert.match(content, /--- AGENTS\.md ---/);
+    assert.match(content, /Project instructions live here\./);
+    assert.match(content, /--- user-preferences\.md ---/);
+    assert.match(content, /Prefer pnpm over npm\./);
+  });
+
+  it("marks the injected message as a hidden session-start message", async () => {
+    const fake = createFakePi();
+    sessionStartExtension(fake.pi);
+    const message = await fake.start(fullProject);
+
+    assert.ok(message);
+    assert.equal(message.customType, "session-start");
+    assert.equal(message.display, false);
+  });
+
+  it("injects nothing for a project without context files", async () => {
+    const content = await inject(emptyProject);
+    assert.equal(content, undefined, "no context files means no injected message");
+  });
+
+  it("never advertises skills with pi-unresolvable /skill: syntax", async () => {
+    const content = await inject(fullProject);
+    assert.ok(content);
+    assert.ok(!content.includes("/skill:"), "pi has no /skill: resolver — drop the hint blurb");
+  });
+
+  it("never enumerates a fixed subset of skill names", async () => {
+    // pi's system prompt already lists every discovered skill with its SKILL.md
+    // path; a hand-maintained subset here drifts from skills/ silently.
+    const content = (await inject(fullProject)) ?? "";
+    for (const skill of ["using-agent-skills", "bd-tool", "git-workflow"]) {
+      assert.ok(!content.includes(skill), `${skill} should not be hardcoded in session-start`);
+    }
+  });
+});

package/extensions/session-start/index.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSessionContext } from "../lib/context-loader.ts";
+
+/**
+ * Session-start extension.
+ *
+ * Injects the project context files (AGENTS.md, docs/user-preferences.md) at
+ * the start of every PI session.
+ *
+ * It deliberately injects nothing about skills: pi's own system prompt already
+ * lists every discovered skill with the absolute path to its SKILL.md, so a
+ * local copy is incomplete by construction and drifts from `skills/` silently.
+ */
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const contextFiles = loadSessionContext(ctx.cwd);
+    if (!contextFiles) return;
+
+    return {
+      message: {
+        customType: "session-start",
+        content: contextFiles,
+        display: false,
+      },
+    };
+  });
+}

package/extensions/session-start/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/session-start",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm index.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/session-start/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/skill-stats/pnpm-lock.yaml

@@ -0,0 +1,329 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.20
+      tsx:
+        specifier: ^4.0.0
+        version: 4.22.4
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.28.0':
+    resolution: {integrity: sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.28.0':
+    resolution: {integrity: sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.28.0':
+    resolution: {integrity: sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.28.0':
+    resolution: {integrity: sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.28.0':
+    resolution: {integrity: sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.28.0':
+    resolution: {integrity: sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.28.0':
+    resolution: {integrity: sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.28.0':
+    resolution: {integrity: sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.28.0':
+    resolution: {integrity: sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.28.0':
+    resolution: {integrity: sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.28.0':
+    resolution: {integrity: sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.28.0':
+    resolution: {integrity: sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.28.0':
+    resolution: {integrity: sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.28.0':
+    resolution: {integrity: sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.28.0':
+    resolution: {integrity: sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.28.0':
+    resolution: {integrity: sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.28.0':
+    resolution: {integrity: sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.0':
+    resolution: {integrity: sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.28.0':
+    resolution: {integrity: sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.0':
+    resolution: {integrity: sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.28.0':
+    resolution: {integrity: sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.0':
+    resolution: {integrity: sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.28.0':
+    resolution: {integrity: sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.28.0':
+    resolution: {integrity: sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.28.0':
+    resolution: {integrity: sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.28.0':
+    resolution: {integrity: sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@22.19.20':
+    resolution: {integrity: sha512-6tELRwSDYWW9EdZhbeZmYGZ1/7Djkt+Ah3/ScEYT9cDord7UJzasR/4D3VONg9tQI5CDp+/CZC1AXj2pCFOvpw==}
+
+  esbuild@0.28.0:
+    resolution: {integrity: sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  tsx@4.22.4:
+    resolution: {integrity: sha512-X8EX+XV4QR5xCsrgxaED954zTDfY8KqlDtskKEL0cHhyS/P8b4IFOvGDQpsC9Q1XnLq915wEfwwY/zzskCtmhg==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.28.0':
+    optional: true
+
+  '@esbuild/android-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/android-arm@0.28.0':
+    optional: true
+
+  '@esbuild/android-x64@0.28.0':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/darwin-x64@0.28.0':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.28.0':
+    optional: true
+
+  '@esbuild/linux-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/linux-arm@0.28.0':
+    optional: true
+
+  '@esbuild/linux-ia32@0.28.0':
+    optional: true
+
+  '@esbuild/linux-loong64@0.28.0':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.28.0':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.28.0':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.28.0':
+    optional: true
+
+  '@esbuild/linux-s390x@0.28.0':
+    optional: true
+
+  '@esbuild/linux-x64@0.28.0':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.28.0':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.28.0':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/sunos-x64@0.28.0':
+    optional: true
+
+  '@esbuild/win32-arm64@0.28.0':
+    optional: true
+
+  '@esbuild/win32-ia32@0.28.0':
+    optional: true
+
+  '@esbuild/win32-x64@0.28.0':
+    optional: true
+
+  '@types/node@22.19.20':
+    dependencies:
+      undici-types: 6.21.0
+
+  esbuild@0.28.0:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.0
+      '@esbuild/android-arm': 0.28.0
+      '@esbuild/android-arm64': 0.28.0
+      '@esbuild/android-x64': 0.28.0
+      '@esbuild/darwin-arm64': 0.28.0
+      '@esbuild/darwin-x64': 0.28.0
+      '@esbuild/freebsd-arm64': 0.28.0
+      '@esbuild/freebsd-x64': 0.28.0
+      '@esbuild/linux-arm': 0.28.0
+      '@esbuild/linux-arm64': 0.28.0
+      '@esbuild/linux-ia32': 0.28.0
+      '@esbuild/linux-loong64': 0.28.0
+      '@esbuild/linux-mips64el': 0.28.0
+      '@esbuild/linux-ppc64': 0.28.0
+      '@esbuild/linux-riscv64': 0.28.0
+      '@esbuild/linux-s390x': 0.28.0
+      '@esbuild/linux-x64': 0.28.0
+      '@esbuild/netbsd-arm64': 0.28.0
+      '@esbuild/netbsd-x64': 0.28.0
+      '@esbuild/openbsd-arm64': 0.28.0
+      '@esbuild/openbsd-x64': 0.28.0
+      '@esbuild/openharmony-arm64': 0.28.0
+      '@esbuild/sunos-x64': 0.28.0
+      '@esbuild/win32-arm64': 0.28.0
+      '@esbuild/win32-ia32': 0.28.0
+      '@esbuild/win32-x64': 0.28.0
+
+  fsevents@2.3.3:
+    optional: true
+
+  tsx@4.22.4:
+    dependencies:
+      esbuild: 0.28.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@6.21.0: {}

package/extensions/subagent/README.md

@@ -58,7 +58,7 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 **Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
 
-**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+**Default behavior:** Only loads **user-level agents** — pi's own `~/.pi/agent/agents`, plus the `agents/` tree of the package this extension ships inside when that is a rendered (staged) tree, e.g. `~/.agent-cortex/pi/agents` after `agent-cortex install pi`.
 
 To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
 
@@ -111,8 +111,8 @@ fire-and-forget orchestration:
 - **`read_agent`** — fallback: read one specific agent's output once you know it has
   finished (or query its `STILL RUNNING` state directly).
 
-These mirror Copilot CLI's `task`/`read_agent` model; `wait_for_agents` adds the
-blocking wait that Copilot's poll loop does manually. Abort (Ctrl+C) propagates: a
+These mirror the `task`/`read_agent` model the skills are authored against;
+`wait_for_agents` adds the blocking wait that a `read_agent` poll loop does manually. Abort (Ctrl+C) propagates: a
 pending `wait_for_agents` returns immediately with whatever is known so far.
 
 ## Output Display