@os-eco/overstory-cli 0.6.8 → 0.6.10

package/README.md

@@ -105,6 +105,8 @@ ov agents discover               Discover agents by capability/state/parent
 
 ov init                          Initialize .overstory/ in current project
                                         (deploys agent definitions automatically)
+  --yes, -y                              Skip interactive prompts
+  --name <name>                          Set project name (default: auto-detect)
 
 ov coordinator start             Start persistent coordinator agent
   --attach / --no-attach                 TTY-aware tmux attach (default: auto)
@@ -214,6 +216,15 @@ ov clean                         Clean up worktrees, sessions, artifacts
 ov doctor                        Run health checks on overstory setup
   --json                                 JSON output
   --category <name>                      Run a specific check category only
+  --fix                                  Auto-fix fixable issues
+
+ov ecosystem                     Show os-eco tool versions and health
+  --json                                 JSON output
+
+ov upgrade                       Upgrade overstory to latest npm version
+  --check                                Compare versions without installing
+  --all                                  Upgrade all 4 ecosystem tools
+  --json                                 JSON output
 
 ov inspect <agent>               Deep per-agent inspection
   --json                                 JSON output
@@ -264,6 +275,7 @@ ov metrics                       Show session metrics
 
 Global Flags:
   --quiet, -q                            Suppress non-error output
+  --timing                               Print command execution time to stderr
   --completions <shell>                  Generate shell completions (bash, zsh, fish)
 ```
 
@@ -273,13 +285,13 @@ Global Flags:
 - **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2167 tests across 77 files, colocated with source)
+- **Testing**: `bun test` (2241 tests across 79 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2167 tests across 77 files)
+# Run tests (2241 tests across 79 files)
 bun test
 
 # Run a single test
@@ -320,7 +332,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (30 commands)
+    commands/                     One file per CLI subcommand (32 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management
@@ -343,7 +355,7 @@ overstory/
       run.ts                      Orchestration run lifecycle
       trace.ts                    Agent/bead timeline viewing
       clean.ts                    Worktree/session cleanup
-      doctor.ts                   Health check runner (9 check modules)
+      doctor.ts                   Health check runner (10 check modules)
       inspect.ts                  Deep per-agent inspection
       spec.ts                     Task spec management
       errors.ts                   Aggregated error view
@@ -351,6 +363,8 @@ overstory/
       stop.ts                     Agent termination
       costs.ts                    Token/cost analysis
       metrics.ts                  Session metrics
+      ecosystem.ts                os-eco tool dashboard
+      upgrade.ts                  npm version upgrades
       completions.ts              Shell completion generation (bash/zsh/fish)
     agents/                       Agent lifecycle management
       manifest.ts                 Agent registry (load + query)
@@ -365,7 +379,7 @@ overstory/
     watchdog/                     Tiered health monitoring (daemon, triage, health)
     logging/                      Multi-format logger + sanitizer + reporter + color control
     metrics/                      SQLite metrics + transcript parsing
-    doctor/                       Health check modules (9 checks)
+    doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch CLI wrapper

package/agents/builder.md

@@ -14,8 +14,8 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **FILE_SCOPE_VIOLATION** -- Editing or writing to a file not listed in your FILE_SCOPE. Read any file for context, but only modify scoped files.
 - **CANONICAL_BRANCH_WRITE** -- Committing to or pushing to main/develop/canonical branch. You commit to your worktree branch only.
 - **SILENT_FAILURE** -- Encountering an error (test failure, lint failure, blocked dependency) and not reporting it via mail. Every error must be communicated to your parent with `--type error`.
-- **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates (`bun test`, `bun run lint`, `bun run typecheck`) and sending a result mail to your parent.
-- **MISSING_WORKER_DONE** -- Closing a bead issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
+- **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates ({{QUALITY_GATE_INLINE}}) and sending a result mail to your parent.
+- **MISSING_WORKER_DONE** -- Closing a {{TRACKER_NAME}} issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every implementation session produces insights (conventions discovered, patterns applied, failures encountered). Skipping `ml record` loses knowledge for future agents.
 
 ## overlay
@@ -29,7 +29,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 - **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the orchestrator or a merger agent.
 - **Never run `git push`** -- your branch lives in the local worktree. The merge process handles integration.
 - **Never spawn sub-workers.** You are a leaf node. If you need something decomposed, ask your parent via mail.
-- **Run quality gates before closing.** Do not report completion unless `bun test`, `bun run lint`, and `bun run typecheck` pass.
+- **Run quality gates before closing.** Do not report completion unless {{QUALITY_GATE_INLINE}} pass.
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## communication-protocol
@@ -49,9 +49,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 
 ## completion-protocol
 
-1. Run `bun test` -- all tests must pass.
-2. Run `bun run lint` -- lint and formatting must be clean.
-3. Run `bun run typecheck` -- no TypeScript errors.
+{{QUALITY_GATE_STEPS}}
 4. Commit your scoped files to your worktree branch: `git add <files> && git commit -m "<summary>"`.
 5. **Record mulch learnings** -- review your work for insights worth preserving (conventions discovered, patterns applied, failures encountered, decisions made) and record them with outcome data:
    ```bash
@@ -88,10 +86,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint and format check via biome)
-  - `bun run biome check --write` (auto-fix lint/format issues)
-  - `bun run typecheck` (type checking via tsc)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml record`, `ml query` (expertise)
   - `ov mail send`, `ov mail check` (communication)
@@ -116,11 +111,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
    - Follow project conventions (check existing code for patterns).
    - Write tests alongside implementation.
 5. **Run quality gates:**
-   ```bash
-   bun test              # All tests must pass
-   bun run lint          # Lint and format must be clean
-   bun run typecheck     # No TypeScript errors
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Commit your work** to your worktree branch:
    ```bash
    git add <your-scoped-files>

package/agents/lead.md

@@ -74,9 +74,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint check)
-  - `bun run typecheck` (type checking)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
@@ -230,7 +228,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
     **Self-verification (simple/moderate tasks):**
     1. Read the builder's diff: `git diff main..<builder-branch>`
     2. Check the diff matches the spec
-    3. Run quality gates: `bun test`, `bun run lint`, `bun run typecheck`
+    3. Run quality gates: {{QUALITY_GATE_INLINE}}
     4. If everything passes, send merge_ready directly
 
     **Reviewer verification (complex tasks):**
@@ -250,7 +248,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
       --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \
       --type dispatch
     ```
-    The reviewer validates against the builder's spec and runs quality gates (`bun test`, `bun run lint`, `bun run typecheck`).
+    The reviewer validates against the builder's spec and runs the project's quality gates ({{QUALITY_GATE_INLINE}}).
 13. **Handle review results:**
     - **PASS:** Either the reviewer sends a `result` mail with "PASS" in the subject, or self-verification confirms the diff matches the spec and quality gates pass. Immediately signal `merge_ready` for that builder's branch -- do not wait for other builders to finish:
       ```bash
@@ -286,7 +284,7 @@ Good decomposition follows these principles:
 
 1. **Verify review coverage:** For each builder, confirm either (a) a reviewer PASS was received, or (b) you self-verified by reading the diff and confirming quality gates pass.
 2. Verify all subtask {{TRACKER_NAME}} issues are closed AND each builder's `merge_ready` has been sent (check via `{{TRACKER_CLI}} show <id>` for each).
-3. Run integration tests if applicable: `bun test`.
+3. Run integration tests if applicable: {{QUALITY_GATE_INLINE}}.
 4. **Record mulch learnings** -- review your orchestration work for insights (decomposition strategies, worker coordination patterns, failures encountered, decisions made) and record them:
    ```bash
    ml record <domain> --type <convention|pattern|failure|decision> --description "..."

package/agents/merger.md

@@ -11,7 +11,7 @@ Every mail message and every tool call costs tokens. Be concise in communication
 These are named failures. If you catch yourself doing any of these, stop and correct immediately.
 
 - **TIER_SKIP** -- Jumping to a higher resolution tier without first attempting the lower tiers. Always start at Tier 1 and escalate only on failure.
-- **UNVERIFIED_MERGE** -- Completing a merge without running `bun test`, `bun run lint`, and `bun run typecheck` to verify the result. A merge that breaks tests is not complete.
+- **UNVERIFIED_MERGE** -- Completing a merge without running {{QUALITY_GATE_INLINE}} to verify the result. A merge that breaks tests is not complete.
 - **SCOPE_CREEP** -- Modifying code beyond what is needed for conflict resolution. Your job is to merge, not refactor or improve.
 - **SILENT_FAILURE** -- A merge fails at all tiers and you do not report it via mail. Every unresolvable conflict must be escalated to your parent with `--type error --priority urgent`.
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first verifying tests pass and sending a merge report mail to your parent.
@@ -28,7 +28,7 @@ Your task-specific context (task ID, branches to merge, target branch, merge ord
 - **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the orchestrator or a merger agent.
 - **Never run `git push`** -- your branch lives in the local worktree. The merge process handles integration.
 - **Never spawn sub-workers.** You are a leaf node. If you need something decomposed, ask your parent via mail.
-- **Run quality gates before closing.** Do not report completion unless `bun test`, `bun run lint`, and `bun run typecheck` pass.
+- **Run quality gates before closing.** Do not report completion unless {{QUALITY_GATE_INLINE}} pass.
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## communication-protocol
@@ -48,9 +48,7 @@ Your task-specific context (task ID, branches to merge, target branch, merge ord
 
 ## completion-protocol
 
-1. Run `bun test` -- all tests must pass after merge.
-2. Run `bun run lint` -- lint must be clean after merge.
-3. Run `bun run typecheck` -- no TypeScript errors after merge.
+{{QUALITY_GATE_STEPS}}
 4. **Record mulch learnings** -- capture merge resolution insights (conflict patterns, resolution strategies, branch integration issues):
    ```bash
    ml record <domain> --type <convention|pattern|failure> --description "..."
@@ -80,9 +78,7 @@ You are a branch integration specialist. When workers complete their tasks on se
   - `git merge`, `git merge --abort`, `git merge --no-edit`
   - `git log`, `git diff`, `git show`, `git status`, `git blame`
   - `git checkout`, `git branch`
-  - `bun test` (verify merged code passes tests)
-  - `bun run lint` (verify merged code passes lint)
-  - `bun run typecheck` (verify no TypeScript errors)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml query` (load expertise for conflict understanding)
   - `ov merge` (use overstory merge infrastructure)
@@ -135,11 +131,7 @@ If AI-resolve fails or produces broken code:
 - This is a last resort -- report that reimagine was needed.
 
 5. **Verify the merge:**
-   ```bash
-   bun test              # All tests must pass after merge
-   bun run lint          # Lint must be clean after merge
-   bun run typecheck     # No TypeScript errors after merge
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Report the result:**
    ```bash
    {{TRACKER_CLI}} close <task-id> --reason "Merged <branch>: <tier used>, tests passing"

package/agents/reviewer.md

@@ -75,10 +75,7 @@ You are a validation specialist. Given code to review, you check it for correctn
 - **Glob** -- find files by name pattern
 - **Grep** -- search file contents with regex
 - **Bash** (observation and test commands only):
-  - `bun test` (run test suite)
-  - `bun test <specific-file>` (run targeted tests)
-  - `bun run lint` (lint and format check)
-  - `bun run typecheck` (type checking)
+{{QUALITY_GATE_CAPABILITIES}}
   - `git log`, `git diff`, `git show`, `git blame`
   - `git diff <base-branch>...<feature-branch>` (review changes)
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready` (read {{TRACKER_NAME}} state)
@@ -107,11 +104,7 @@ You are a validation specialist. Given code to review, you check it for correctn
    - Check for: security issues, hardcoded secrets, missing input validation.
    - Check for: adequate test coverage, meaningful test assertions.
 5. **Run quality gates:**
-   ```bash
-   bun test              # Do all tests pass?
-   bun run lint          # Does lint and formatting pass?
-   bun run typecheck     # Are there any TypeScript errors?
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Report results** via `{{TRACKER_CLI}} close` with a clear pass/fail summary:
    ```bash
    {{TRACKER_CLI}} close <task-id> --reason "PASS: <summary>"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.8",
+	"version": "0.6.10",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

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

@@ -9,11 +9,13 @@ import {
 	buildPathBoundaryGuardScript,
 	deployHooks,
 	escapeForSingleQuotedShell,
+	extractQualityGatePrefixes,
 	getBashPathBoundaryGuards,
 	getCapabilityGuards,
 	getDangerGuards,
 	getPathBoundaryGuards,
 	isOverstoryHookEntry,
+	PATH_PREFIX,
 } from "./hooks-deployer.ts";
 
 describe("deployHooks", () => {
@@ -1233,6 +1235,49 @@ describe("getDangerGuards", () => {
 			);
 		}
 	});
+
+	test("custom quality gates appear in safe prefix list for non-implementation capabilities", () => {
+		const guards = getCapabilityGuards("scout", [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		]);
+		// Find the Bash guard for file modifications (last Bash entry for non-implementation)
+		const bashGuards = guards.filter((g) => g.matcher === "Bash");
+		const fileGuard = bashGuards.find((g) =>
+			g.hooks.some((h) => h.command.includes("cannot modify files")),
+		);
+		expect(fileGuard).toBeDefined();
+		const command = fileGuard?.hooks[0]?.command ?? "";
+		expect(command).toContain("pytest");
+		expect(command).toContain("ruff check .");
+		// Should NOT contain default bun commands
+		expect(command).not.toContain("bun test");
+	});
+});
+
+describe("extractQualityGatePrefixes", () => {
+	test("extracts command from each gate", () => {
+		const gates = [
+			{ name: "Test", command: "bun test", description: "all tests pass" },
+			{ name: "Lint", command: "bun run lint", description: "zero errors" },
+		];
+		const prefixes = extractQualityGatePrefixes(gates);
+		expect(prefixes).toEqual(["bun test", "bun run lint"]);
+	});
+
+	test("returns empty array for empty gates", () => {
+		expect(extractQualityGatePrefixes([])).toEqual([]);
+	});
+
+	test("works with non-bun quality gates", () => {
+		const gates = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+			{ name: "Type", command: "mypy src/", description: "type check" },
+		];
+		const prefixes = extractQualityGatePrefixes(gates);
+		expect(prefixes).toEqual(["pytest", "ruff check .", "mypy src/"]);
+	});
 });
 
 describe("buildBashFileGuardScript", () => {
@@ -1260,6 +1305,14 @@ describe("buildBashFileGuardScript", () => {
 		expect(script).toContain("git log");
 		expect(script).toContain("git diff");
 		expect(script).toContain("mulch ");
+		// Quality gate commands (bun test, bun run lint, etc.) are no longer
+		// hardcoded in SAFE_BASH_PREFIXES — they come from config via
+		// extractQualityGatePrefixes() and are passed as extraSafePrefixes
+		// through getCapabilityGuards().
+	});
+
+	test("includes quality gate prefixes when passed as extraSafePrefixes", () => {
+		const script = buildBashFileGuardScript("scout", ["bun test", "bun run lint"]);
 		expect(script).toContain("bun test");
 		expect(script).toContain("bun run lint");
 	});
@@ -2115,6 +2168,185 @@ describe("bash path boundary integration", () => {
 	});
 });
 
+describe("PATH_PREFIX", () => {
+	test("PATH_PREFIX is exported and is a non-empty string", () => {
+		expect(typeof PATH_PREFIX).toBe("string");
+		expect(PATH_PREFIX.length).toBeGreaterThan(0);
+	});
+
+	test("PATH_PREFIX contains ~/.bun/bin for bun-installed CLIs", () => {
+		expect(PATH_PREFIX).toContain(".bun/bin");
+	});
+
+	test("PATH_PREFIX extends PATH (not replaces it)", () => {
+		// Must preserve original PATH via :$PATH
+		expect(PATH_PREFIX).toContain(":$PATH");
+	});
+
+	test("PATH_PREFIX sets PATH via export", () => {
+		expect(PATH_PREFIX).toMatch(/^export PATH=/);
+	});
+});
+
+describe("PATH prefix in deployed hooks", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-path-prefix-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	test("SessionStart hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ss-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.SessionStart) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+				expect(hook.command).toContain(".bun/bin");
+			}
+		}
+	});
+
+	test("UserPromptSubmit hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ups-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.UserPromptSubmit) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("PostToolUse hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ptu-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.PostToolUse) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("Stop hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-stop-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.Stop) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+				expect(hook.command).toContain(".bun/bin");
+			}
+		}
+	});
+
+	test("PreCompact hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-pc-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.PreCompact) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("PATH prefix appears before CLI command in SessionStart", async () => {
+		const worktreePath = join(tempDir, "path-order-wt");
+		await deployHooks(worktreePath, "path-order-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+		// PATH export must come before the CLI invocation
+		const pathIdx = cmd.indexOf("export PATH=");
+		const ovIdx = cmd.indexOf("ov prime");
+		expect(pathIdx).toBeGreaterThanOrEqual(0);
+		expect(ovIdx).toBeGreaterThan(pathIdx);
+	});
+
+	test("PATH prefix appears before ml learn in Stop hook", async () => {
+		const worktreePath = join(tempDir, "path-ml-wt");
+		await deployHooks(worktreePath, "path-ml-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const stopHooks = parsed.hooks.Stop[0].hooks;
+		// Second Stop hook is "ml learn"
+		const mlCmd = stopHooks[1].command as string;
+		const pathIdx = mlCmd.indexOf("export PATH=");
+		const mlIdx = mlCmd.indexOf("ml learn");
+		expect(pathIdx).toBeGreaterThanOrEqual(0);
+		expect(mlIdx).toBeGreaterThan(pathIdx);
+	});
+
+	test("generated guard commands do NOT have PATH prefix (they use only built-ins)", async () => {
+		const worktreePath = join(tempDir, "path-guards-wt");
+		await deployHooks(worktreePath, "path-guards-agent", "builder");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const preToolUse = parsed.hooks.PreToolUse;
+
+		// Path boundary guards (Write/Edit/NotebookEdit) are generated — no PATH prefix
+		const writeGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Write" && h.hooks[0]?.command?.includes("OVERSTORY_WORKTREE_PATH"),
+		);
+		expect(writeGuard).toBeDefined();
+		expect(writeGuard.hooks[0].command).not.toContain("export PATH=");
+
+		// Danger guard (generated) — no PATH prefix
+		const dangerGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Bash" && h.hooks[0]?.command?.includes("git reset --hard"),
+		);
+		expect(dangerGuard).toBeDefined();
+		expect(dangerGuard.hooks[0].command).not.toContain("export PATH=");
+	});
+
+	test("re-deployment is idempotent: PATH prefix not duplicated", async () => {
+		const worktreePath = join(tempDir, "path-idem-wt");
+
+		await deployHooks(worktreePath, "path-idem-agent");
+		await deployHooks(worktreePath, "path-idem-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+
+		// PATH prefix should appear exactly once, not doubled
+		const occurrences = cmd.split("export PATH=").length - 1;
+		expect(occurrences).toBe(1);
+	});
+
+	test("PATH prefix uses $HOME expansion (not hardcoded path)", async () => {
+		const worktreePath = join(tempDir, "path-home-wt");
+		await deployHooks(worktreePath, "home-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+		// Should use $HOME not a hardcoded path like /Users/...
+		expect(cmd).toContain("$HOME");
+	});
+});
+
 describe("escapeForSingleQuotedShell", () => {
 	test("no single quotes: string passes through unchanged", () => {
 		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");

package/src/agents/hooks-deployer.ts

@@ -1,6 +1,8 @@
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { DEFAULT_QUALITY_GATES } from "../config.ts";
 import { AgentError } from "../errors.ts";
+import type { QualityGate } from "../types.ts";
 
 /**
  * Capabilities that must never modify project files.
@@ -117,12 +119,20 @@ const SAFE_BASH_PREFIXES = [
 	"git blame",
 	"git branch",
 	"mulch ",
-	"bun test",
-	"bun run lint",
-	"bun run typecheck",
-	"bun run biome",
 ];
 
+/**
+ * Extract command prefixes from quality gate configurations.
+ *
+ * Each gate's command is used as a safe prefix so non-implementation agents
+ * can still run quality gate commands (e.g., reviewers running tests).
+ * This makes the safe prefix list configurable instead of hardcoding
+ * specific tool commands like "bun test".
+ */
+export function extractQualityGatePrefixes(gates: QualityGate[]): string[] {
+	return gates.map((g) => g.command);
+}
+
 /** Hook entry shape matching Claude Code's settings.local.json format. */
 interface HookEntry {
 	matcher: string;
@@ -149,6 +159,22 @@ function getTemplatePath(): string {
  */
 const ENV_GUARD = '[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;';
 
+/**
+ * PATH setup prefix for hook commands.
+ *
+ * Claude Code executes hook commands via /bin/sh with a minimal PATH
+ * (/usr/bin:/bin:/usr/sbin:/sbin). Bun-installed CLIs — ov, ml, sd, cn, bd —
+ * live in ~/.bun/bin which is absent from that PATH, causing hooks like
+ * `ov prime` (SessionStart) and `ml learn` (Stop) to fail with
+ * "command not found".
+ *
+ * Prepend this to any hook command that invokes one of those CLIs so they
+ * resolve correctly regardless of how Claude Code was launched.
+ *
+ * Exported so tests can verify the exact prefix value.
+ */
+export const PATH_PREFIX = 'export PATH="$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH";';
+
 /**
  * Build a PreToolUse guard script that validates file paths are within
  * the agent's worktree boundary.
@@ -454,8 +480,10 @@ export function getBashPathBoundaryGuards(): HookEntry[] {
  *
  * Note: All capabilities also receive Bash danger guards via getDangerGuards().
  */
-export function getCapabilityGuards(capability: string): HookEntry[] {
+export function getCapabilityGuards(capability: string, qualityGates?: QualityGate[]): HookEntry[] {
 	const guards: HookEntry[] = [];
+	const gates = qualityGates ?? DEFAULT_QUALITY_GATES;
+	const gatePrefixes = extractQualityGatePrefixes(gates);
 
 	// Block Claude Code native team/task tools for ALL overstory agents.
 	// Agents must use `overstory sling` for delegation, not native Task/Team tools.
@@ -485,7 +513,9 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 		guards.push(...toolGuards);
 
 		// Coordination capabilities get git add/commit whitelisted for beads/mulch sync
-		const extraSafe = COORDINATION_CAPABILITIES.has(capability) ? COORDINATION_SAFE_PREFIXES : [];
+		const extraSafe = COORDINATION_CAPABILITIES.has(capability)
+			? [...COORDINATION_SAFE_PREFIXES, ...gatePrefixes]
+			: gatePrefixes;
 		const bashFileGuard: HookEntry = {
 			matcher: "Bash",
 			hooks: [
@@ -544,6 +574,7 @@ export async function deployHooks(
 	worktreePath: string,
 	agentName: string,
 	capability = "builder",
+	qualityGates?: QualityGate[],
 ): Promise<void> {
 	const templatePath = getTemplatePath();
 	const file = Bun.file(templatePath);
@@ -571,11 +602,26 @@ export async function deployHooks(
 		content = content.replace("{{AGENT_NAME}}", agentName);
 	}
 
-	// Parse the base config and merge guards into PreToolUse
+	// Parse the base config from the template
 	const config = JSON.parse(content) as { hooks: Record<string, HookEntry[]> };
+
+	// Extend PATH in all template hook commands.
+	// Claude Code invokes hooks with PATH=/usr/bin:/bin:/usr/sbin:/sbin — ~/.bun/bin
+	// (where ov, ml, sd, etc. live) is not included. Prepend PATH_PREFIX so CLIs resolve.
+	for (const entries of Object.values(config.hooks)) {
+		for (const entry of entries) {
+			for (const hook of entry.hooks) {
+				hook.command = `${PATH_PREFIX} ${hook.command}`;
+			}
+		}
+	}
+
+	// Merge capability-specific PreToolUse guards into the config.
+	// Guards are generated scripts using only shell built-ins (grep, sed, echo, exit)
+	// and do not require PATH extension.
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
-	const capabilityGuards = getCapabilityGuards(capability);
+	const capabilityGuards = getCapabilityGuards(capability, qualityGates);
 	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards];
 
 	if (allGuards.length > 0) {