@ag-eco/agentplate-cli 0.13.0

package/src/agents/capabilities.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import {
+	isPersistentCapability,
+	isStopHookPersistentCapability,
+	isTaskScopedCapability,
+	PERSISTENT_CAPABILITIES,
+	STOP_HOOK_PERSISTENT_CAPABILITIES,
+	TASK_SCOPED_CAPABILITIES,
+	terminalMailTypesFor,
+} from "./capabilities.ts";
+
+describe("TASK_SCOPED_CAPABILITIES", () => {
+	test("contains the five worker capabilities", () => {
+		expect([...TASK_SCOPED_CAPABILITIES].sort()).toEqual([
+			"builder",
+			"lead",
+			"merger",
+			"reviewer",
+			"scout",
+		]);
+	});
+
+	test("excludes persistent capabilities", () => {
+		for (const c of ["coordinator", "orchestrator", "monitor", "supervisor"]) {
+			expect(isTaskScopedCapability(c)).toBe(false);
+		}
+	});
+});
+
+describe("terminalMailTypesFor", () => {
+	test("merger uses merged + merge_failed", () => {
+		expect(terminalMailTypesFor("merger")).toEqual(["merged", "merge_failed"]);
+	});
+
+	test("builder/scout/reviewer/lead accept worker_done and result", () => {
+		// `result` is a legacy/drift fallback (agentplate-1a4c): models often pick
+		// `--type result` for their terminal summary because the prompts also use
+		// `result` for non-terminal updates elsewhere. Accepting both keeps the
+		// lifecycle unstuck without losing the canonical `worker_done` contract.
+		for (const c of ["builder", "scout", "reviewer", "lead"]) {
+			expect(terminalMailTypesFor(c)).toEqual(["worker_done", "result"]);
+		}
+	});
+
+	test("unknown capability falls back to worker_done set", () => {
+		expect(terminalMailTypesFor("unknown")).toEqual(["worker_done", "result"]);
+	});
+});
+
+describe("PERSISTENT_CAPABILITIES", () => {
+	test("contains coordinator, orchestrator, monitor only", () => {
+		expect([...PERSISTENT_CAPABILITIES].sort()).toEqual(["coordinator", "monitor", "orchestrator"]);
+	});
+
+	test("excludes lead and other workers", () => {
+		for (const c of ["lead", "builder", "scout", "reviewer", "merger", "supervisor"]) {
+			expect(isPersistentCapability(c)).toBe(false);
+		}
+	});
+});
+
+describe("STOP_HOOK_PERSISTENT_CAPABILITIES", () => {
+	test("equals PERSISTENT_CAPABILITIES plus lead", () => {
+		// Tmux-mode leads span many model turns within a single dispatch
+		// (agentplate-49a7), so the per-turn Stop hook is NOT a "done" signal.
+		expect([...STOP_HOOK_PERSISTENT_CAPABILITIES].sort()).toEqual([
+			"coordinator",
+			"lead",
+			"monitor",
+			"orchestrator",
+		]);
+	});
+
+	test("isStopHookPersistentCapability is true for lead and the persistent set", () => {
+		for (const c of ["coordinator", "orchestrator", "monitor", "lead"]) {
+			expect(isStopHookPersistentCapability(c)).toBe(true);
+		}
+	});
+
+	test("excludes non-lead workers", () => {
+		for (const c of ["builder", "scout", "reviewer", "merger", "supervisor"]) {
+			expect(isStopHookPersistentCapability(c)).toBe(false);
+		}
+	});
+});

package/src/agents/capabilities.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared capability classification for the runtime layer.
+ *
+ * Three orthogonal classifications:
+ *
+ * - `TASK_SCOPED_CAPABILITIES` — worker capabilities that operate under the
+ *   spawn-per-turn model. Each user turn (mail, nudge, initial dispatch)
+ *   spawns a fresh claude with `--resume <session-id>`, processes the turn,
+ *   and exits on stdin EOF. There is no persistent process between turns.
+ *
+ * - `PERSISTENT_CAPABILITIES` — capabilities that run as long-lived sessions
+ *   for the lifetime of a run/operator interaction (coordinator, orchestrator,
+ *   monitor). Used by the watchdog to exempt them from time-based stale/zombie
+ *   detection and exclude them from run-completion accounting.
+ *
+ * - `STOP_HOOK_PERSISTENT_CAPABILITIES` — capabilities whose Claude Code Stop
+ *   hook fires per model turn rather than once at process exit. The same as
+ *   `PERSISTENT_CAPABILITIES` plus `lead`, because tmux-mode leads still span
+ *   many model turns within a single dispatch (agentplate-49a7).
+ *
+ * Phase 4 (agentplate-2724) consolidated these definitions here as the single
+ * source of truth — previously they were duplicated across log.ts, health.ts,
+ * and daemon.ts with a load-bearing `lead` mismatch.
+ */
+
+import type { Capability } from "../types.ts";
+
+/** Worker capabilities driven by the spawn-per-turn engine. */
+export const TASK_SCOPED_CAPABILITIES = new Set<Capability>([
+	"builder",
+	"scout",
+	"reviewer",
+	"merger",
+	"lead",
+]);
+
+/** True iff `capability` is a task-scoped worker (drives spawn-per-turn). */
+export function isTaskScopedCapability(capability: string): boolean {
+	return TASK_SCOPED_CAPABILITIES.has(capability as Capability);
+}
+
+/**
+ * Capabilities that run as long-lived sessions for the duration of a run /
+ * operator interaction.
+ *
+ * `coordinator` and `orchestrator` are operator-driven persistent agents (one
+ * tmux session per run / multi-run); `monitor` is a continuous fleet patrol
+ * with its own long-lived session. They are expected to have long idle
+ * periods (waiting for worker mail, operator input) and must NOT be flagged
+ * stale/zombie based on `lastActivity` — only tmux/pid liveness applies.
+ *
+ * Consumers:
+ *   - `src/watchdog/health.ts` — exempt from time-based stale/zombie detection
+ *   - `src/watchdog/daemon.ts` — excluded from run-completion accounting
+ *
+ * Note: `lead` is NOT in this set. Under spawn-per-turn (the default), each
+ * lead turn is its own short-lived process; under tmux mode the lead still
+ * runs to a terminal `worker_done` and exits, so it counts toward
+ * run-completion accounting. The per-model-turn nuance for tmux-mode leads
+ * is captured separately by `STOP_HOOK_PERSISTENT_CAPABILITIES`.
+ */
+export const PERSISTENT_CAPABILITIES = new Set<Capability>([
+	"coordinator",
+	"orchestrator",
+	"monitor",
+]);
+
+/** True iff `capability` is a long-lived persistent session. */
+export function isPersistentCapability(capability: string): boolean {
+	return PERSISTENT_CAPABILITIES.has(capability as Capability);
+}
+
+/**
+ * Capabilities whose Claude Code Stop hook fires per **model turn** rather
+ * than once at process exit. Under tmux mode these agents have many model
+ * turns within a single dispatch, so a `session-end` event is NOT a reliable
+ * "agent done" signal — the hook fires every time the model finishes
+ * generating a response and waits for the next user turn.
+ *
+ * Equals `PERSISTENT_CAPABILITIES` plus `lead`. Tmux-mode leads delegate to
+ * sub-workers and process mail injection over many turns (agentplate-49a7);
+ * marking the lead `completed` on the first Stop hook fire makes it vanish
+ * from `getActive()` while its tmux process is still working.
+ *
+ * The tmux-mode-only nuance does not apply to spawn-per-turn (headless) leads:
+ * (a) they run one model turn per process; (b) `hooks-deployer.ts` drops the
+ * Stop hook entirely under `headlessOnly=true`, so this gate is a no-op for
+ * them. Including `lead` here is therefore safe in both modes.
+ *
+ * Consumer:
+ *   - `src/commands/log.ts` — guards `transitionToCompleted`,
+ *     `autoRecordExpertise`, and `appendOutcomeToAppliedRecords` so they do
+ *     not fire on every turn boundary.
+ */
+export const STOP_HOOK_PERSISTENT_CAPABILITIES = new Set<Capability>([
+	...PERSISTENT_CAPABILITIES,
+	"lead" as Capability,
+]);
+
+/** True iff `capability`'s Stop hook is per-model-turn (not per-session-exit). */
+export function isStopHookPersistentCapability(capability: string): boolean {
+	return STOP_HOOK_PERSISTENT_CAPABILITIES.has(capability as Capability);
+}
+
+/**
+ * Mail types that signal an agent's terminal action for its capability.
+ *
+ * The turn-runner watches for any of these from the agent during a turn; when
+ * observed alongside a clean `result` event, the agent is transitioned to
+ * `completed`. Capabilities not listed here use the worker_done set by default.
+ *
+ * - builder | scout | reviewer | lead → `worker_done` (canonical) or `result`
+ *   (legacy/drift fallback). Agent prompts treat `worker_done` as the
+ *   completion signal, but the model frequently picks `result` because it is
+ *   also a valid mail type used for non-terminal summaries elsewhere in the
+ *   protocol. Accepting `result` keeps the lifecycle from getting stuck on
+ *   prompt drift (agentplate-1a4c). Combined with `cleanResult` (claude exited
+ *   cleanly at end-of-turn), this is safe: an interim `result` mid-turn does
+ *   not transition the agent because the turn has not ended yet.
+ * - merger → `merged` (success) or `merge_failed` (failure)
+ */
+export function terminalMailTypesFor(capability: string): readonly string[] {
+	if (capability === "merger") return ["merged", "merge_failed"];
+	return ["worker_done", "result"];
+}

package/src/agents/checkpoint.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { SessionCheckpoint } from "../types.ts";
+import { clearCheckpoint, loadCheckpoint, saveCheckpoint } from "./checkpoint.ts";
+
+function makeCheckpoint(overrides?: Partial<SessionCheckpoint>): SessionCheckpoint {
+	return {
+		agentName: "test-agent",
+		taskId: "agentplate-abc1",
+		sessionId: "session-001",
+		timestamp: "2025-01-01T00:00:00.000Z",
+		progressSummary: "Implemented checkpoint module",
+		filesModified: ["src/agents/checkpoint.ts"],
+		currentBranch: "agentplate/test-agent/agentplate-abc1",
+		pendingWork: "Write tests",
+		loamDomains: ["agents"],
+		...overrides,
+	};
+}
+
+describe("checkpoint", () => {
+	let agentsDir: string;
+
+	beforeEach(async () => {
+		agentsDir = await mkdtemp(join(tmpdir(), "agentplate-checkpoint-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(agentsDir);
+	});
+
+	test("save and load a checkpoint", async () => {
+		const checkpoint = makeCheckpoint();
+
+		await saveCheckpoint(agentsDir, checkpoint);
+		const loaded = await loadCheckpoint(agentsDir, "test-agent");
+
+		expect(loaded).not.toBeNull();
+		expect(loaded?.agentName).toBe("test-agent");
+		expect(loaded?.taskId).toBe("agentplate-abc1");
+		expect(loaded?.sessionId).toBe("session-001");
+		expect(loaded?.progressSummary).toBe("Implemented checkpoint module");
+		expect(loaded?.filesModified).toEqual(["src/agents/checkpoint.ts"]);
+		expect(loaded?.currentBranch).toBe("agentplate/test-agent/agentplate-abc1");
+		expect(loaded?.pendingWork).toBe("Write tests");
+		expect(loaded?.loamDomains).toEqual(["agents"]);
+	});
+
+	test("load returns null when no checkpoint exists", async () => {
+		const result = await loadCheckpoint(agentsDir, "nonexistent-agent");
+		expect(result).toBeNull();
+	});
+
+	test("clear removes the checkpoint file", async () => {
+		const checkpoint = makeCheckpoint();
+
+		await saveCheckpoint(agentsDir, checkpoint);
+		const before = await loadCheckpoint(agentsDir, "test-agent");
+		expect(before).not.toBeNull();
+
+		await clearCheckpoint(agentsDir, "test-agent");
+		const after = await loadCheckpoint(agentsDir, "test-agent");
+		expect(after).toBeNull();
+	});
+
+	test("clear does not error when file does not exist", async () => {
+		// Should not throw
+		await clearCheckpoint(agentsDir, "nonexistent-agent");
+	});
+
+	test("overwrite existing checkpoint", async () => {
+		const first = makeCheckpoint({ progressSummary: "First pass" });
+		await saveCheckpoint(agentsDir, first);
+
+		const second = makeCheckpoint({
+			progressSummary: "Second pass",
+			filesModified: ["src/agents/checkpoint.ts", "src/agents/lifecycle.ts"],
+		});
+		await saveCheckpoint(agentsDir, second);
+
+		const loaded = await loadCheckpoint(agentsDir, "test-agent");
+		expect(loaded?.progressSummary).toBe("Second pass");
+		expect(loaded?.filesModified).toEqual(["src/agents/checkpoint.ts", "src/agents/lifecycle.ts"]);
+	});
+});

package/src/agents/checkpoint.ts

@@ -0,0 +1,101 @@
+import { mkdir, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LifecycleError } from "../errors.ts";
+import type { SessionCheckpoint } from "../types.ts";
+
+const CHECKPOINT_FILENAME = "checkpoint.json";
+
+/**
+ * Save a session checkpoint to disk.
+ *
+ * Writes to `{agentsDir}/{checkpoint.agentName}/checkpoint.json`.
+ * Creates the directory if it doesn't exist.
+ */
+export async function saveCheckpoint(
+	agentsDir: string,
+	checkpoint: SessionCheckpoint,
+): Promise<void> {
+	const filePath = join(agentsDir, checkpoint.agentName, CHECKPOINT_FILENAME);
+	const dir = dirname(filePath);
+
+	try {
+		await mkdir(dir, { recursive: true });
+	} catch (err) {
+		throw new LifecycleError(`Failed to create checkpoint directory: ${dir}`, {
+			agentName: checkpoint.agentName,
+			sessionId: checkpoint.sessionId,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(filePath, `${JSON.stringify(checkpoint, null, "\t")}\n`);
+	} catch (err) {
+		throw new LifecycleError(`Failed to write checkpoint: ${filePath}`, {
+			agentName: checkpoint.agentName,
+			sessionId: checkpoint.sessionId,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Load a session checkpoint from disk.
+ *
+ * Reads from `{agentsDir}/{agentName}/checkpoint.json`.
+ * Returns null if the file doesn't exist.
+ */
+export async function loadCheckpoint(
+	agentsDir: string,
+	agentName: string,
+): Promise<SessionCheckpoint | null> {
+	const filePath = join(agentsDir, agentName, CHECKPOINT_FILENAME);
+	const file = Bun.file(filePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		return null;
+	}
+
+	let text: string;
+	try {
+		text = await file.text();
+	} catch (err) {
+		throw new LifecycleError(`Failed to read checkpoint: ${filePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		return JSON.parse(text) as SessionCheckpoint;
+	} catch (err) {
+		throw new LifecycleError(`Failed to parse checkpoint JSON: ${filePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}
+
+/**
+ * Clear (delete) a session checkpoint from disk.
+ *
+ * Removes `{agentsDir}/{agentName}/checkpoint.json`.
+ * No error if the file doesn't exist.
+ */
+export async function clearCheckpoint(agentsDir: string, agentName: string): Promise<void> {
+	const filePath = join(agentsDir, agentName, CHECKPOINT_FILENAME);
+
+	try {
+		await unlink(filePath);
+	} catch (err) {
+		// ENOENT means file doesn't exist — that's fine
+		if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+			return;
+		}
+		throw new LifecycleError(`Failed to clear checkpoint: ${filePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}

package/src/agents/copilot-hooks-deployer.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { deployCopilotHooks } from "./copilot-hooks-deployer.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+describe("deployCopilotHooks", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "agentplate-copilot-hooks-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("writes hooks.json to .github/hooks/ directory", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "my-builder");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const exists = await Bun.file(hooksPath).exists();
+		expect(exists).toBe(true);
+	});
+
+	test("creates .github/hooks/ directory if it does not exist", async () => {
+		const worktreePath = join(tempDir, "new-worktree");
+		// Directory does not exist before the call
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		expect(await Bun.file(hooksPath).exists()).toBe(true);
+	});
+
+	test("output file is valid JSON", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+
+	test("output has Copilot schema structure (top-level hooks with onSessionStart)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as Record<string, unknown>;
+
+		expect(config).toHaveProperty("hooks");
+		const hooks = config.hooks as Record<string, unknown>;
+		expect(hooks).toHaveProperty("onSessionStart");
+		expect(Array.isArray(hooks.onSessionStart)).toBe(true);
+	});
+
+	test("replaces {{AGENT_NAME}} with agentName in all commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "scout-agent-42");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+
+		expect(raw).toContain("scout-agent-42");
+		expect(raw).not.toContain("{{AGENT_NAME}}");
+	});
+
+	test("prepends PATH_PREFIX to all hook commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		expect(allCommands.length).toBeGreaterThan(0);
+		for (const cmd of allCommands) {
+			expect(cmd).toStartWith(PATH_PREFIX);
+		}
+	});
+
+	test("onSessionStart entries are objects with command field only (no matcher, no type)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<Record<string, unknown>> };
+		};
+
+		for (const entry of config.hooks.onSessionStart) {
+			expect(typeof entry.command).toBe("string");
+			// Copilot schema has no matcher or type fields
+			expect(entry).not.toHaveProperty("matcher");
+			expect(entry).not.toHaveProperty("type");
+		}
+	});
+
+	test("onSessionStart includes ap prime command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "prime-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(commands.some((c) => c.includes("ap prime") && c.includes("prime-test-agent"))).toBe(
+			true,
+		);
+	});
+
+	test("onSessionStart includes ap mail check --inject command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "mail-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(
+			commands.some((c) => c.includes("ap mail check --inject") && c.includes("mail-test-agent")),
+		).toBe(true);
+	});
+
+	test("all hook commands include ENV_GUARD pattern", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "guard-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		for (const cmd of allCommands) {
+			expect(cmd).toContain("AGENTPLATE_AGENT_NAME");
+		}
+	});
+
+	test("template file exists and is valid JSON after substitution", async () => {
+		// Verify template file is present and parseable (basic template health check).
+		const templatePath = join(import.meta.dir, "..", "..", "templates", "copilot-hooks.json.tmpl");
+		const exists = await Bun.file(templatePath).exists();
+		expect(exists).toBe(true);
+
+		const raw = (await Bun.file(templatePath).text()).replace(/\{\{AGENT_NAME\}\}/g, "test");
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+});

package/src/agents/copilot-hooks-deployer.ts

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AgentError } from "../errors.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+/** Copilot hook entry shape — simpler than Claude Code (no matcher, no type field). */
+interface CopilotHookEntry {
+	command: string;
+}
+
+/**
+ * Resolve the path to the Copilot hooks template file.
+ * The template lives at `templates/copilot-hooks.json.tmpl` relative to the repo root.
+ */
+function getTemplatePath(): string {
+	// src/agents/copilot-hooks-deployer.ts -> repo root is ../../
+	return join(dirname(import.meta.dir), "..", "templates", "copilot-hooks.json.tmpl");
+}
+
+/**
+ * Deploy Copilot lifecycle hooks to an agent's worktree.
+ *
+ * Reads `templates/copilot-hooks.json.tmpl`, replaces all `{{AGENT_NAME}}` tokens,
+ * prepends PATH_PREFIX to every hook command so CLIs (ap, lm, sr) resolve correctly
+ * under Copilot's minimal PATH, then writes the result to
+ * `<worktreePath>/.github/hooks/hooks.json`.
+ *
+ * Phase 1: lifecycle hooks only (onSessionStart). No security guards.
+ *
+ * @param worktreePath - Absolute path to the agent's git worktree
+ * @param agentName - The unique name of the agent (replaces {{AGENT_NAME}} in template)
+ * @throws {AgentError} If the template is missing or the write fails
+ */
+export async function deployCopilotHooks(worktreePath: string, agentName: string): Promise<void> {
+	const templatePath = getTemplatePath();
+	const file = Bun.file(templatePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		throw new AgentError(`Copilot hooks template not found: ${templatePath}`, {
+			agentName,
+		});
+	}
+
+	let template: string;
+	try {
+		template = await file.text();
+	} catch (err) {
+		throw new AgentError(`Failed to read Copilot hooks template: ${templatePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	// Replace all occurrences of {{AGENT_NAME}}
+	let content = template;
+	while (content.includes("{{AGENT_NAME}}")) {
+		content = content.replace("{{AGENT_NAME}}", agentName);
+	}
+
+	// Parse the base config from the template
+	const config = JSON.parse(content) as { hooks: Record<string, CopilotHookEntry[]> };
+
+	// Extend PATH in all hook commands.
+	// Copilot CLI executes hooks with a minimal PATH — ~/.bun/bin (where ap, lm, sr live)
+	// is not included. Prepend PATH_PREFIX so CLIs resolve correctly.
+	for (const entries of Object.values(config.hooks)) {
+		for (const entry of entries) {
+			entry.command = `${PATH_PREFIX} ${entry.command}`;
+		}
+	}
+
+	const hooksDir = join(worktreePath, ".github", "hooks");
+	const outputPath = join(hooksDir, "hooks.json");
+
+	try {
+		await mkdir(hooksDir, { recursive: true });
+	} catch (err) {
+		throw new AgentError(`Failed to create .github/hooks/ directory at: ${hooksDir}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(outputPath, `${JSON.stringify(config, null, "\t")}\n`);
+	} catch (err) {
+		throw new AgentError(`Failed to write Copilot hooks config to: ${outputPath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}