@tmustier/pi-agent-teams 0.4.0-beta.0 → 0.4.0-beta.1

package/README.md

@@ -19,6 +19,7 @@ Additional Pi-specific capabilities:
 
 - **Git worktrees** — optionally give each teammate its own worktree so they work on isolated branches without conflicting edits.
 - **Session branching** — clone the leader's conversation context into a teammate so it starts with full awareness of the work so far, instead of from scratch.
+- **Hooks / quality gates** — optional leader-side hooks on idle / task completion to run scripts (opt-in).
 
 ## UI style (terminology + naming)
 
@@ -38,7 +39,11 @@ You can add your own styles by creating JSON files under:
 
 - `~/.pi/agent/teams/_styles/<style>.json`
 
-The file can override strings and naming rules. Example:
+The file can override strings and naming rules.
+
+Strings include both terminology **and lifecycle copy**, e.g. `killedVerb`, `shutdownRequestedVerb`, `shutdownCompletedVerb`, `shutdownRefusedVerb`, `abortRequestedVerb`, plus templates like `teamEndedAllStopped`.
+
+Example:
 
 ```json
 {
@@ -113,6 +118,8 @@ Or let the model drive it with the delegate tool:
   "action": "delegate",
   "contextMode": "branch",
   "workspaceMode": "worktree",
+  "model": "anthropic/claude-sonnet-4",
+  "thinking": "high",
   "teammates": ["alice", "bob"],
   "tasks": [
     { "text": "Fix failing unit tests" },
@@ -137,7 +144,7 @@ All management commands live under `/team`.
 
 | Command | Description |
 | --- | --- |
-| `/team spawn <name> [fresh\|branch] [shared\|worktree]` | Start a teammate |
+| `/team spawn <name> [fresh\|branch] [shared\|worktree] [plan] [--model <provider>/<modelId>] [--thinking <level>]` | Start a teammate |
 | `/team list` | List teammates and their status |
 | `/team panel` | Interactive widget panel (same as `/tw`) |
 | `/team style` | Show current style + usage |
@@ -178,6 +185,10 @@ All management commands live under `/team`.
 | `PI_TEAMS_ROOT_DIR` | Storage root (absolute or relative to `~/.pi/agent`) | `~/.pi/agent/teams` |
 | `PI_TEAMS_DEFAULT_AUTO_CLAIM` | Whether spawned teammates auto-claim tasks | `1` (on) |
 | `PI_TEAMS_STYLE` | UI style id (built-in: `normal`, `soviet`, `pirate`, or custom) | `normal` |
+| `PI_TEAMS_HOOKS_ENABLED` | Enable leader-side hooks/quality gates | `0` (off) |
+| `PI_TEAMS_HOOKS_DIR` | Hooks directory (absolute or relative to `PI_TEAMS_ROOT_DIR`) | `<teamsRoot>/_hooks` |
+| `PI_TEAMS_HOOK_TIMEOUT_MS` | Hook execution timeout (ms) | `60000` |
+| `PI_TEAMS_HOOKS_CREATE_TASK_ON_FAILURE` | If `1`, create a follow-up task when a task hook fails | `0` (off) |
 
 ## Storage layout
 
@@ -191,6 +202,43 @@ All management commands live under `/team`.
     <agent>.json                        # per-agent inbox
   sessions/                             # teammate session files
   worktrees/<agent>/                    # git worktrees (when enabled)
+
+<teamsRoot>/_hooks/
+  on_idle.{js,sh}                       # optional hook (see below)
+  on_task_completed.{js,sh}             # optional quality gate
+  on_task_failed.{js,sh}                # optional hook
+```
+
+## Hooks / quality gates (optional)
+
+Enable hooks:
+
+```bash
+export PI_TEAMS_HOOKS_ENABLED=1
+```
+
+Then create hook scripts under:
+
+- `<teamsRoot>/_hooks/` (default: `~/.pi/agent/teams/_hooks/`)
+
+Recognized hook names:
+
+- `on_idle.(js|mjs|sh)`
+- `on_task_completed.(js|mjs|sh)`
+- `on_task_failed.(js|mjs|sh)`
+
+Hooks run with working directory = the **leader session cwd** and receive context via env vars:
+
+- `PI_TEAMS_HOOK_EVENT`
+- `PI_TEAMS_TEAM_ID`, `PI_TEAMS_TEAM_DIR`, `PI_TEAMS_TASK_LIST_ID`
+- `PI_TEAMS_STYLE`
+- `PI_TEAMS_MEMBER`
+- `PI_TEAMS_TASK_ID`, `PI_TEAMS_TASK_SUBJECT`, `PI_TEAMS_TASK_OWNER`, `PI_TEAMS_TASK_STATUS`
+
+If you want hook failures to create a follow-up task automatically:
+
+```bash
+export PI_TEAMS_HOOKS_CREATE_TASK_ON_FAILURE=1
 ```
 
 ## Development

package/docs/claude-parity.md

@@ -1,6 +1,6 @@
 # Claude Agent Teams parity roadmap (pi-agent-teams)
 
-Last updated: 2026-02-07
+Last updated: 2026-02-10
 
 This document tracks **feature parity gaps** between:
 
@@ -12,39 +12,50 @@ This document tracks **feature parity gaps** between:
 
 - `pi-agent-teams` (Pi extension)
 
-> Terminology note: the extension supports `PI_TEAMS_STYLE=<style>`. These docs often say "comrade" for parity with Claude Teams, but styles are configurable (built-ins include `normal`, `soviet`, `pirate`).
+> Terminology note: this extension supports `PI_TEAMS_STYLE=<style>`.
+> This doc often uses “comrade” as a generic stand-in for “worker/teammate”, but **styles can customize terminology, naming, and lifecycle copy**.
+> Built-ins: `normal`, `soviet`, `pirate`. Custom styles live under `~/.pi/agent/teams/_styles/`.
 
 ## Scope / philosophy
 
 - Target the **same coordination primitives** as Claude Teams:
   - shared task list
   - mailbox messaging
-  - long-lived comrades
+  - long-lived workers
 - Prefer **inspectable, local-first artifacts** (files + lock files).
 - Avoid guidance that bypasses Claude feature gating; we only document behavior.
 - Accept that some Claude UX (terminal keybindings + split-pane integration) may not be achievable in Pi without deeper TUI/terminal integration.
 
+## Pi-specific extras (not Claude parity)
+
+These are intentional differences / additions:
+
+- **Configurable styles** (`/team style …`) for terminology + naming + lifecycle copy.
+- **Git worktrees** for isolation (`/team spawn <name> … worktree`).
+- **Session branching** (clone leader context into a teammate).
+- A **status widget + interactive panel** (`/tw`, `/team panel`).
+
 ## Parity matrix (docs-oriented)
 
 Legend: ✅ implemented • 🟡 partial • ❌ missing
 
 | Area | Claude docs behavior | Pi Teams status | Notes / next step | Priority |
 | --- | --- | --- | --- | --- |
-| Enablement | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + settings | N/A | Pi extension is always available when installed/loaded. | — |
-| Team config | `~/.claude/teams/<team>/config.json` w/ members | ✅ | Implemented via `extensions/teams/team-config.ts` (stored under `~/.pi/agent/teams/...` or `PI_TEAMS_ROOT_DIR`). | P0 |
+| Enablement | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + settings | N/A | Pi extension is available when installed/loaded. | — |
+| Team config | `~/.claude/teams/<team>/config.json` w/ members | ✅ | `extensions/teams/team-config.ts` (under `~/.pi/agent/teams/...` or `PI_TEAMS_ROOT_DIR`). | P0 |
 | Task list (shared) | `~/.claude/tasks/<taskListId>/` + states + deps | ✅ | File-per-task + deps (`blockedBy`/`blocks`); `/team task dep add|rm|ls`; self-claim skips blocked tasks. | P0 |
-| Self-claim | Comrades can self-claim next unassigned, unblocked task; file locking | ✅ | Implemented: `claimNextAvailableTask()` + locks; enabled by default (`PI_TEAMS_DEFAULT_AUTO_CLAIM=1`). | P0 |
+| Self-claim | Comrades self-claim next unassigned, unblocked task; file locking | ✅ | `claimNextAvailableTask()` + locks; enabled by default (`PI_TEAMS_DEFAULT_AUTO_CLAIM=1`). | P0 |
 | Explicit assign | Lead assigns task to comrade | ✅ | `/team task assign` sets owner + pings via mailbox. | P0 |
-| “Message” vs “broadcast” | Send to one comrade or all comrades | ✅ | `/team dm` + `/team broadcast` use mailbox; `/team send` uses RPC. Broadcast recipients = team config workers + RPC-spawned map + active task owners; manual tmux workers self-register into `config.json` on startup. | P0 |
-| Comrade↔comrade messaging | Comrades can message each other directly | ✅ | Workers register `team_message` LLM-callable tool; sends via mailbox + CC's leader with `peer_dm_sent` notification. | P1 |
-| Display modes | In-process selection (Shift+Up/Down); split panes (tmux/iTerm) | ❌ | Pi has a widget + commands, but no terminal-level comrade navigation/panes. | P2 |
-| Delegate mode | Lead restricted to coordination-only tools | ✅ | `/team delegate [on|off]` toggles; `pi.on("tool_call")` blocks `bash/edit/write`; `PI_TEAMS_DELEGATE_MODE=1` env. Widget shows `[delegate]`. | P1 |
-| Plan approval | Comrade can be "plan required" and needs lead approval to implement | ✅ | `/team spawn <name> plan` sets `PI_TEAMS_PLAN_REQUIRED=1`; worker restricted to read-only tools; submits plan via `plan_approval_request`; `/team plan approve|reject <name>`. | P1 |
-| Shutdown handshake | Lead requests shutdown; comrade can approve/reject | ✅ | Full protocol: `shutdown_request` → `shutdown_approved` or `shutdown_rejected` (when worker is busy). `/team shutdown <name>` (graceful) + `/team kill <name>` (force). | P1 |
+| “Message” vs “broadcast” | Send to one comrade or all comrades | ✅ | `/team dm` + `/team broadcast` use mailbox; `/team send` uses RPC. Recipients = config workers + RPC map + active task owners. | P0 |
+| Comrade↔comrade messaging | Comrades message each other directly | ✅ | Worker tool `team_message`; messages via mailbox + CC leader via `peer_dm_sent`. | P1 |
+| Display modes | In-process selection (Shift+Up/Down); split panes (tmux/iTerm) | ❌ | Pi has widget/panel + commands, but no terminal-level comrade navigation/panes. | P2 |
+| Delegate mode | Lead restricted to coordination-only tools | ✅ | `/team delegate [on|off]`; `tool_call` blocks `bash/edit/write`; widget shows `[delegate]`. | P1 |
+| Plan approval | Comrade can be “plan required” and needs lead approval to implement | ✅ | `/team spawn <name> plan` → read-only tools; sends `plan_approval_request`; `/team plan approve|reject`. | P1 |
+| Shutdown handshake | Lead requests shutdown; comrade can approve/reject | ✅ | Protocol: `shutdown_request` → `shutdown_approved` / `shutdown_rejected`. `/team shutdown <name>` (graceful), `/team kill <name>` (SIGTERM). Wording is style-controlled (e.g. “was asked to shut down”, “walked the plank”). | P1 |
 | Cleanup team | “Clean up the team” removes shared resources after comrades stopped | ✅ | `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks. | P1 |
-| Hooks / quality gates | `ComradeIdle`, `TaskCompleted` hooks | ❌ | Add optional hook runner in leader on idle/task-complete events (script execution + exit-code gating). | P2 |
-| Task list UX | Ctrl+T toggle; show all/clear tasks by asking | 🟡 | Widget + `/team task list` show blocked/deps; `/team task show <id>`; `/team task clear [completed|all]`. No Ctrl+T toggle yet. | P0 |
-| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | ✅ | `PI_TEAMS_TASK_LIST_ID` env is **worker-side** (for manually started workers). The leader switches task lists via `/team task use <taskListId>` (persisted in `config.json`). Newly spawned workers inherit the new task list ID; existing workers need a restart to pick up changes. | P1 |
+| Hooks / quality gates | `ComradeIdle`, `TaskCompleted` hooks | 🟡 | Optional leader-side hook runner (idle/task-complete/task-fail) via `PI_TEAMS_HOOKS_ENABLED=1` + scripts under `_hooks/`. Still missing richer gating UX + standardized hook contract. | P2 |
+| Task list UX | Ctrl+T toggle; show all/clear tasks by asking | 🟡 | Widget + `/team task list` + `/team task show` + `/team task clear`. No Ctrl+T toggle yet. | P0 |
+| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | ✅ | Worker env: `PI_TEAMS_TASK_LIST_ID` (manual workers). Leader: `/team task use <taskListId>` (persisted). Newly spawned workers inherit; existing workers need restart. | P1 |
 
 ## Prioritized roadmap
 
@@ -64,45 +75,38 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 ### P1 (done): governance + lifecycle parity
 
 4) **Shutdown handshake** ✅
-   - Full protocol: `shutdown_request` → `shutdown_approved` / `shutdown_rejected`
+   - `shutdown_request` → `shutdown_approved` / `shutdown_rejected`
    - Worker rejects when busy (streaming + active task), auto-approves when idle
-   - Leader command: `/team shutdown <name> [reason...]` (graceful), `/team kill <name>` as force
+   - `/team shutdown <name> [reason...]` (graceful), `/team kill <name>` (force)
 
 5) **Plan approval** ✅
-   - `/team spawn <name> [fresh|branch] [shared|worktree] plan` sets `PI_TEAMS_PLAN_REQUIRED=1`
-   - Worker starts with read-only tools (`read`, `grep`, `find`, `ls`)
-   - After first `agent_end`, sends `plan_approval_request` to leader via mailbox
-   - `/team plan approve <name>` → worker gets full tools and proceeds
-   - `/team plan reject <name> [feedback...]` → worker revises plan (stays read-only)
+   - `/team spawn <name> ... plan` sets `PI_TEAMS_PLAN_REQUIRED=1`
+   - Worker starts read-only; submits `plan_approval_request`
+   - `/team plan approve|reject <name>`
 
 6) **Delegate mode (leader)** ✅
-   - `/team delegate [on|off]` toggle (or `PI_TEAMS_DELEGATE_MODE=1` env)
-   - `tool_call` hook blocks `bash`, `edit`, `write` when active
-   - Widget shows `[delegate]` indicator
+   - `/team delegate [on|off]` (or `PI_TEAMS_DELEGATE_MODE=1`)
+   - Blocks `bash/edit/write` while active
 
 7) **Cleanup** ✅
    - `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks.
-   - Refuses if RPC comrades are running or there are `in_progress` tasks unless `--force`.
 
 8) **Peer-to-peer messaging** ✅
-   - Workers register `team_message` LLM-callable tool (recipient + message params)
-   - Messages go via mailbox in `team` namespace; leader CC'd with `peer_dm_sent` notification
+   - Worker tool `team_message`
+   - Mailbox transport; leader CC notifications
 
 9) **Shared task list across sessions** ✅
-   - `PI_TEAMS_TASK_LIST_ID` env on leader + worker sides
-   - `/team task use <taskListId>` switches the leader (and newly spawned workers); restart existing workers to pick up changes
-   - Task list ID persisted in team config
+   - `/team task use <taskListId>` + persisted `config.json`
 
 ### P2: UX + “product-level” parity
 
-10) **Better comrade interaction UX**
-   - Explore whether Pi’s TUI API can support:
-     - selecting a comrade from the widget
-     - “entering” a comrade transcript view
-   - (Optional) tmux integration for split panes.
+10) **Hooks / quality gates** 🟡 (partial)
+   - Implemented: optional leader-side hook runner (opt-in + timeout + logs).
+   - Still missing: richer gating UX (e.g. surfacing hook failures inline, controlling whether failures reopen tasks / block future work).
 
-11) **Hooks / quality gates**
-   - Support scripts that run on idle/task completion (similar to Claude hooks).
+11) **Better comrade interaction UX (within Pi constraints)**
+   - Improve the existing widget/panel affordances (selection, transcript view, actions)
+   - (Optional) tmux integration for split panes.
 
 12) **Join/attach flow**
    - Allow a running session to attach to an existing team (discover + approve join).
@@ -116,11 +120,12 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 - Task store + locking: `extensions/teams/task-store.ts`, `extensions/teams/fs-lock.ts`
 - Mailbox store + locking: `extensions/teams/mailbox.ts`
 - Team config: `extensions/teams/team-config.ts`
+- Styles + naming: `extensions/teams/teams-style.ts`
 - Optional workspace isolation: `extensions/teams/worktree.ts`
 
 ## Testing strategy
 
 - Keep tests hermetic by setting `PI_TEAMS_ROOT_DIR` to a temp directory.
 - Extend:
-  - `scripts/smoke-test.mts` (run via `npm run smoke-test`) for filesystem-only behaviors (deps, claiming, locking)
+  - `scripts/smoke-test.mts` (run via `npm run smoke-test`) for filesystem-only behaviors
   - `scripts/e2e-rpc-test.mjs` for protocol flows (shutdown handshake, plan approval)

package/extensions/teams/hooks.ts

@@ -0,0 +1,258 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { getTeamsHooksDir } from "./paths.js";
+import type { TeamTask } from "./task-store.js";
+
+export type TeamsHookEvent = "idle" | "task_completed" | "task_failed";
+
+export type TeamsHookInvocation = {
+	event: TeamsHookEvent;
+	teamId: string;
+	teamDir: string;
+	taskListId: string;
+	style: string;
+	memberName?: string;
+	timestamp?: string;
+	completedTask?: TeamTask | null;
+};
+
+export type TeamsHookRunResult = {
+	ran: boolean;
+	hookPath?: string;
+	command?: readonly string[];
+	exitCode: number | null;
+	timedOut: boolean;
+	durationMs: number;
+	stdout: string;
+	stderr: string;
+	error?: string;
+};
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+	return typeof err === "object" && err !== null && "code" in err;
+}
+
+function isExecutable(st: fs.Stats): boolean {
+	// Owner/group/other execute bit.
+	return (st.mode & 0o111) !== 0;
+}
+
+function trimOutput(s: string, limit = 12_000): string {
+	if (s.length <= limit) return s;
+	return s.slice(0, limit) + `\n… (truncated, ${s.length - limit} bytes omitted)`;
+}
+
+function parseTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env.PI_TEAMS_HOOK_TIMEOUT_MS;
+	if (!raw) return 60_000;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : 60_000;
+}
+
+export function areTeamsHooksEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env.PI_TEAMS_HOOKS_ENABLED === "1";
+}
+
+export function getHookBaseName(event: TeamsHookEvent): string {
+	switch (event) {
+		case "idle":
+			return "on_idle";
+		case "task_completed":
+			return "on_task_completed";
+		case "task_failed":
+			return "on_task_failed";
+	}
+}
+
+type HookCommand = { cmd: string; args: string[]; hookPath: string; display: readonly string[] };
+
+function resolveHookCommand(hooksDir: string, event: TeamsHookEvent): HookCommand | null {
+	const base = getHookBaseName(event);
+	const candidates = [
+		path.join(hooksDir, base),
+		path.join(hooksDir, `${base}.sh`),
+		path.join(hooksDir, `${base}.js`),
+		path.join(hooksDir, `${base}.mjs`),
+	];
+
+	for (const file of candidates) {
+		try {
+			if (!fs.existsSync(file)) continue;
+			const st = fs.statSync(file);
+			if (!st.isFile()) continue;
+
+			const ext = path.extname(file).toLowerCase();
+			if (ext === ".js" || ext === ".mjs") {
+				return { cmd: "node", args: [file], hookPath: file, display: ["node", file] };
+			}
+
+			if (ext === ".sh") {
+				return { cmd: "bash", args: [file], hookPath: file, display: ["bash", file] };
+			}
+
+			if (isExecutable(st)) {
+				return { cmd: file, args: [], hookPath: file, display: [file] };
+			}
+
+			// Non-executable with unknown extension: ignore.
+		} catch {
+			// ignore
+		}
+	}
+
+	return null;
+}
+
+async function runWithTimeout(opts: {
+	cmd: string;
+	args: readonly string[];
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	timeoutMs: number;
+}): Promise<{ exitCode: number | null; timedOut: boolean; stdout: string; stderr: string; error?: string }> {
+	return await new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+
+		const child = spawn(opts.cmd, [...opts.args], {
+			cwd: opts.cwd,
+			env: opts.env,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		child.stdout?.on("data", (d: Buffer) => {
+			stdout += d.toString("utf8");
+		});
+		child.stderr?.on("data", (d: Buffer) => {
+			stderr += d.toString("utf8");
+		});
+
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				// ignore
+			}
+			setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// ignore
+				}
+			}, 1000);
+		}, opts.timeoutMs);
+
+		child.on("close", (code) => {
+			clearTimeout(timeout);
+			resolve({
+				exitCode: code,
+				timedOut,
+				stdout: trimOutput(stdout),
+				stderr: trimOutput(stderr),
+			});
+		});
+
+		child.on("error", (err: unknown) => {
+			clearTimeout(timeout);
+			const msg = err instanceof Error ? err.message : String(err);
+			resolve({ exitCode: null, timedOut: false, stdout: trimOutput(stdout), stderr: trimOutput(stderr), error: msg });
+		});
+	});
+}
+
+export async function runTeamsHook(opts: {
+	invocation: TeamsHookInvocation;
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<TeamsHookRunResult> {
+	const env = opts.env ?? process.env;
+	if (!areTeamsHooksEnabled(env)) {
+		return {
+			ran: false,
+			exitCode: null,
+			timedOut: false,
+			durationMs: 0,
+			stdout: "",
+			stderr: "",
+		};
+	}
+
+	const hooksDir = getTeamsHooksDir();
+	const hook = resolveHookCommand(hooksDir, opts.invocation.event);
+	if (!hook) {
+		return {
+			ran: false,
+			exitCode: null,
+			timedOut: false,
+			durationMs: 0,
+			stdout: "",
+			stderr: "",
+		};
+	}
+
+	const timeoutMs = parseTimeoutMs(env);
+	const start = Date.now();
+
+	const baseEnv: NodeJS.ProcessEnv = {
+		...env,
+		PI_TEAMS_HOOK_EVENT: opts.invocation.event,
+		PI_TEAMS_TEAM_ID: opts.invocation.teamId,
+		PI_TEAMS_TEAM_DIR: opts.invocation.teamDir,
+		PI_TEAMS_TASK_LIST_ID: opts.invocation.taskListId,
+		PI_TEAMS_STYLE: opts.invocation.style,
+		...(opts.invocation.memberName ? { PI_TEAMS_MEMBER: opts.invocation.memberName } : {}),
+		...(opts.invocation.timestamp ? { PI_TEAMS_EVENT_TIMESTAMP: opts.invocation.timestamp } : {}),
+	};
+
+	const t = opts.invocation.completedTask;
+	const envWithTask: NodeJS.ProcessEnv = {
+		...baseEnv,
+		...(t?.id ? { PI_TEAMS_TASK_ID: t.id } : {}),
+		...(t?.subject ? { PI_TEAMS_TASK_SUBJECT: t.subject } : {}),
+		...(t?.owner ? { PI_TEAMS_TASK_OWNER: t.owner } : {}),
+		...(t?.status ? { PI_TEAMS_TASK_STATUS: t.status } : {}),
+	};
+
+	let res;
+	try {
+		res = await runWithTimeout({ cmd: hook.cmd, args: hook.args, cwd: opts.cwd, env: envWithTask, timeoutMs });
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			ran: true,
+			hookPath: hook.hookPath,
+			command: hook.display,
+			exitCode: null,
+			timedOut: false,
+			durationMs: Date.now() - start,
+			stdout: "",
+			stderr: "",
+			error: msg,
+		};
+	}
+
+	return {
+		ran: true,
+		hookPath: hook.hookPath,
+		command: hook.display,
+		exitCode: res.exitCode,
+		timedOut: res.timedOut,
+		durationMs: Date.now() - start,
+		stdout: res.stdout,
+		stderr: res.stderr,
+		error: res.error,
+	};
+}
+
+export async function ensureHooksDirExists(): Promise<void> {
+	const dir = getTeamsHooksDir();
+	try {
+		await fs.promises.mkdir(dir, { recursive: true });
+	} catch (err) {
+		// ignore permission errors; caller can surface if needed
+		if (isErrnoException(err) && err.code === "EACCES") return;
+	}
+}

package/extensions/teams/leader-inbox.ts

@@ -10,7 +10,9 @@ import {
 	isShutdownRejected,
 } from "./protocol.js";
 import { ensureTeamConfig, setMemberStatus, upsertMember } from "./team-config.js";
+import { getTask } from "./task-store.js";
 
+import type { TeamsHookInvocation } from "./hooks.js";
 import type { TeamsStyle } from "./teams-style.js";
 import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
 
@@ -22,8 +24,9 @@ export async function pollLeaderInbox(opts: {
 	leadName: string;
 	style: TeamsStyle;
 	pendingPlanApprovals: Map<string, { requestId: string; name: string; taskId?: string }>;
+	enqueueHook?: (invocation: TeamsHookInvocation) => void;
 }): Promise<void> {
-	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals } = opts;
+	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals, enqueueHook } = opts;
 	const strings = getTeamsStrings(style);
 
 	let msgs: Awaited<ReturnType<typeof popUnreadMessages>>;
@@ -55,7 +58,7 @@ export async function pollLeaderInbox(opts: {
 					shutdownApprovedAt: approved.timestamp ?? new Date().toISOString(),
 				},
 			});
-			ctx.ui.notify(`${formatMemberDisplayName(style, name)} shut down`, "info");
+			ctx.ui.notify(`${formatMemberDisplayName(style, name)} ${strings.shutdownCompletedVerb}`, "info");
 			continue;
 		}
 
@@ -69,7 +72,7 @@ export async function pollLeaderInbox(opts: {
 					shutdownRejectedReason: rejected.reason,
 				},
 			});
-			ctx.ui.notify(`${formatMemberDisplayName(style, name)} refused shutdown: ${rejected.reason}`, "warning");
+			ctx.ui.notify(`${formatMemberDisplayName(style, name)} ${strings.shutdownRefusedVerb}: ${rejected.reason}`, "warning");
 			continue;
 		}
 
@@ -95,6 +98,42 @@ export async function pollLeaderInbox(opts: {
 		const idle = isIdleNotification(m.text);
 		if (idle) {
 			const name = sanitizeName(idle.from);
+
+			// Hook: always emit "idle" (best-effort, non-blocking)
+			try {
+				enqueueHook?.({
+					event: "idle",
+					teamId,
+					teamDir,
+					taskListId,
+					style,
+					memberName: name,
+					timestamp: idle.timestamp,
+					completedTask: null,
+				});
+			} catch {
+				// ignore hook enqueue errors
+			}
+
+			// Hook: task completion / failure
+			if (idle.completedTaskId) {
+				const completedTask = await getTask(teamDir, taskListId, idle.completedTaskId);
+				try {
+					enqueueHook?.({
+						event: idle.completedStatus === "failed" ? "task_failed" : "task_completed",
+						teamId,
+						teamDir,
+						taskListId,
+						style,
+						memberName: name,
+						timestamp: idle.timestamp,
+						completedTask,
+					});
+				} catch {
+					// ignore hook enqueue errors
+				}
+			}
+
 			if (idle.failureReason) {
 				const cfg = await ensureTeamConfig(teamDir, {
 					teamId,

package/extensions/teams/leader-lifecycle-commands.ts

@@ -16,6 +16,7 @@ import {
 	listAvailableTeamsStyles,
 	normalizeTeamsStyleId,
 	resolveTeamsStyleDefinition,
+	formatTeamsTemplate,
 } from "./teams-style.js";
 import type { TeammateRpc } from "./teammate-rpc.js";
 
@@ -101,20 +102,11 @@ export async function handleTeamStyleCommand(opts: {
 		const file = path.join(dir, `${styleId}.json`);
 		try {
 			await fs.promises.mkdir(dir, { recursive: true });
+			const base = resolveTeamsStyleDefinition(extendsId);
 			const template = {
 				extends: extendsId,
-				strings: {
-					memberTitle: "Member",
-					memberPrefix: "Member ",
-				},
-				naming: {
-					requireExplicitSpawnName: false,
-					autoNameStrategy: {
-						kind: "pool",
-						pool: ["member1", "member2"],
-						fallbackBase: "member",
-					},
-				},
+				strings: base.strings,
+				naming: base.naming,
 			};
 			await fs.promises.writeFile(file, JSON.stringify(template, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
 		} catch (err) {
@@ -295,7 +287,7 @@ export async function handleTeamShutdownCommand(opts: {
 			},
 		});
 
-		ctx.ui.notify(`Shutdown requested for ${formatMemberDisplayName(style, name)}`, "info");
+		ctx.ui.notify(`${formatMemberDisplayName(style, name)} ${strings.shutdownRequestedVerb}`, "info");
 
 		// Optional fallback for RPC teammates: force stop if it doesn't exit.
 		const t = teammates.get(name);
@@ -333,13 +325,18 @@ export async function handleTeamShutdownCommand(opts: {
 	for (const m of cfgWorkersOnline) activeNames.add(m.name);
 
 	if (activeNames.size === 0) {
-		ctx.ui.notify(`No ${strings.memberTitle.toLowerCase()}s to shut down`, "info");
+		const members = `${strings.memberTitle.toLowerCase()}s`;
+		ctx.ui.notify(formatTeamsTemplate(strings.noMembersToShutdown, { members, count: "0" }), "info");
 		return;
 	}
 
 	if (process.stdout.isTTY && process.stdin.isTTY) {
 		const plural = activeNames.size === 1 ? "" : "s";
-		const msg = `Stop all ${String(activeNames.size)} ${strings.memberTitle.toLowerCase()}${plural}?`;
+		const members = `${strings.memberTitle.toLowerCase()}${plural}`;
+		const msg = formatTeamsTemplate(strings.shutdownAllPrompt, {
+			count: String(activeNames.size),
+			members,
+		});
 		const ok = await ctx.ui.confirm("Shutdown team", msg);
 		if (!ok) return;
 	}
@@ -391,10 +388,8 @@ export async function handleTeamShutdownCommand(opts: {
 	}
 
 	renderWidget();
-	ctx.ui.notify(
-		`Team ended: all ${strings.memberTitle.toLowerCase()}s stopped (leader session remains active)`,
-		"info",
-	);
+	const members = `${strings.memberTitle.toLowerCase()}s`;
+	ctx.ui.notify(formatTeamsTemplate(strings.teamEndedAllStopped, { members, count: String(activeNames.size) }), "info");
 }
 
 export async function handleTeamPruneCommand(opts: {
@@ -517,10 +512,10 @@ export async function handleTeamStopCommand(opts: {
 		await t.abort();
 	}
 
-	ctx.ui.notify(
-		`Abort requested for ${formatMemberDisplayName(style, name)}${taskId ? ` (task #${taskId})` : ""}${t ? "" : " (mailbox only)"}`,
-		"warning",
-	);
+	let msg = `${formatMemberDisplayName(style, name)} ${getTeamsStrings(style).abortRequestedVerb}`;
+	if (taskId) msg += ` (task #${taskId})`;
+	if (!t) msg += " (mailbox only)";
+	ctx.ui.notify(msg, "warning");
 	renderWidget();
 }