@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/extensions/subagent/node_modules/.bin/pi

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+fi

package/extensions/subagent/node_modules/.bin/pi-ai

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-ai/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-ai/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-ai/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-ai/dist/cli.js" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/extensions/subagent/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@agent-cortex/subagent-tools",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm wait.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/subagent/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/subagent/wait.test.ts

@@ -0,0 +1,202 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { waitForAgents, type BackgroundEntry } from "./wait.ts";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface Deferred {
+	promise: Promise<void>;
+	resolve: () => void;
+}
+
+function deferred(): Deferred {
+	let resolve!: () => void;
+	const promise = new Promise<void>((res) => {
+		resolve = res;
+	});
+	return { promise, resolve };
+}
+
+/**
+ * A background-run ledger matching the extension's `backgroundRuns` map:
+ * each entry holds a result (null while running) and a promise that resolves
+ * when the run finishes. `finish` mirrors the real run path — result is set
+ * before the promise settles.
+ */
+function makeLedger() {
+	const entries = new Map<string, { entry: BackgroundEntry<string>; done: Deferred }>();
+
+	const spawn: () => string = () => {
+		const agentId = `agent-${entries.size + 1}`;
+		const done = deferred();
+		const entry: BackgroundEntry<string> = {
+			result: null,
+			promise: done.promise,
+		};
+		entries.set(agentId, { entry, done });
+		return agentId;
+	};
+
+	const finish = async (agentId: string, result: string): Promise<void> => {
+		const run = entries.get(agentId);
+		if (!run) throw new Error(`no run for ${agentId}`);
+		// Match production ordering: result committed before the promise settles.
+		run.entry.result = result;
+		run.done.resolve();
+		await delay(0);
+	};
+
+	const finishLater = (agentId: string, result: string, ms: number): void => {
+		const run = entries.get(agentId);
+		if (!run) throw new Error(`no run for ${agentId}`);
+		void delay(ms).then(() => finish(agentId, result));
+	};
+
+	const get = (agentId: string): BackgroundEntry<string> | undefined => entries.get(agentId)?.entry;
+
+	return { spawn, finish, finishLater, get };
+}
+
+// ─── waitForAgents ────────────────────────────────────────────────────────────
+
+describe("waitForAgents", () => {
+	it("returns immediately with the result when an agent already completed", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "done", 1);
+		await delay(15);
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId, result: "done" }]);
+		assert.deepEqual(outcome.running, []);
+		assert.deepEqual(outcome.notFound, []);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, false);
+	});
+
+	it("returns immediately when an agent id has no tracked run", async () => {
+		const ledger = makeLedger();
+		const runningId = ledger.spawn();
+
+		const outcome = await waitForAgents(ledger.get, [runningId, "agent-unknown"], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.notFound, ["agent-unknown"]);
+		assert.deepEqual(outcome.running, [runningId]);
+		assert.deepEqual(outcome.completed, []);
+		assert.equal(outcome.timedOut, false);
+	});
+
+	it("returns the first completion while slower agents stay running", async () => {
+		const ledger = makeLedger();
+		const fastId = ledger.spawn();
+		const slowId = ledger.spawn();
+		ledger.finishLater(fastId, "fast result", 10);
+
+		const outcome = await waitForAgents(ledger.get, [fastId, slowId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId: fastId, result: "fast result" }]);
+		assert.deepEqual(outcome.running, [slowId]);
+		assert.equal(outcome.timedOut, false);
+	});
+
+	it("returns the agent that finished first when completions stagger", async () => {
+		const ledger = makeLedger();
+		const a = ledger.spawn();
+		const b = ledger.spawn();
+		ledger.finishLater(b, "bee", 10);
+		ledger.finishLater(a, "aye", 40);
+
+		const outcome = await waitForAgents(ledger.get, [a, b], { timeoutMs: 1000 });
+		assert.deepEqual(
+			outcome.completed.map((c) => ({ id: c.agentId, result: c.result })),
+			[{ id: b, result: "bee" }],
+		);
+		assert.deepEqual(outcome.running, [a]);
+	});
+
+	it("preserves request order when several agents already completed", async () => {
+		const ledger = makeLedger();
+		const a = ledger.spawn();
+		const b = ledger.spawn();
+		await ledger.finish(a, "aye");
+		await ledger.finish(b, "bee");
+
+		const outcome = await waitForAgents(ledger.get, [a, b], { timeoutMs: 1000 });
+		assert.deepEqual(
+			outcome.completed.map((c) => ({ id: c.agentId, result: c.result })),
+			[
+				{ id: a, result: "aye" },
+				{ id: b, result: "bee" },
+			],
+		);
+		assert.deepEqual(outcome.running, []);
+	});
+
+	it("marks still-running agents STILL RUNNING when the timeout elapses with no completion", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 30 });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, true);
+		assert.equal(outcome.aborted, false);
+	});
+
+	it("can wait again on the same still-running id and pick up its later result", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "eventually", 60);
+
+		const first = await waitForAgents(ledger.get, [agentId], { timeoutMs: 20 });
+		assert.deepEqual(first.completed, []);
+		assert.deepEqual(first.running, [agentId]);
+		assert.equal(first.timedOut, true);
+
+		const second = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(second.completed, [{ agentId, result: "eventually" }]);
+		assert.deepEqual(second.running, []);
+		assert.equal(second.timedOut, false);
+	});
+
+	it("returns immediately when the abort signal already fired", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+		const controller = new AbortController();
+		controller.abort();
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000, signal: controller.signal });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, true);
+	});
+
+	it("stops waiting when the abort signal fires mid-wait instead of timing out", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+		const controller = new AbortController();
+		setTimeout(() => controller.abort(), 20);
+		const started = Date.now();
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000, signal: controller.signal });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, true);
+		assert.ok(Date.now() - started < 500, "returns on abort rather than waiting out the timeout");
+	});
+
+	it("applies no timeout when all requested agents resolve", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "done", 20);
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId, result: "done" }]);
+		assert.equal(outcome.timedOut, false);
+	});
+});

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 };