@os-eco/overstory-cli 0.6.7 → 0.6.9

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)
@@ -273,13 +275,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` (2151 tests across 76 files, colocated with source)
+- **Testing**: `bun test` (2186 tests across 77 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2151 tests across 76 files)
+# Run tests (2186 tests across 77 files)
 bun test
 
 # Run a single test
@@ -319,6 +321,7 @@ overstory/
     types.ts                      Shared types and interfaces
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
+    json.ts                       Standardized JSON envelope helpers
     commands/                     One file per CLI subcommand (30 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle

package/agents/coordinator.md

@@ -128,15 +128,15 @@ Coordinator (you, depth 0)
 - **Your agent name** is `coordinator` (or as set by `$OVERSTORY_AGENT_NAME`)
 
 #### Mail Types You Send
-- `dispatch` -- assign a work stream to a lead (includes taskId, objective, file area)
+- `dispatch` -- assign a work stream to a lead (includes beadId, objective, file area)
 - `status` -- progress updates, clarifications, answers to questions
 - `error` -- report unrecoverable failures to the human operator
 
 #### Mail Types You Receive
-- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, taskId, agentName, filesModified)
-- `merged` -- merger confirms successful merge (branch, taskId, tier)
-- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
-- `escalation` -- any agent escalates an issue (severity: warning|error|critical, taskId, context)
+- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, beadId, agentName, filesModified)
+- `merged` -- merger confirms successful merge (branch, beadId, tier)
+- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
+- `escalation` -- any agent escalates an issue (severity: warning|error|critical, beadId, context)
 - `health_check` -- watchdog probes liveness (agentName, checkType)
 - `status` -- leads report progress
 - `result` -- leads report completed work streams

package/agents/lead.md

@@ -81,7 +81,6 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
   - `ov sling` (spawn sub-workers)
-  - `ov spec write <id> --body "..." --agent $OVERSTORY_AGENT_NAME` (write spec files)
   - `ov status` (monitor active agents)
   - `ov mail send`, `ov mail check`, `ov mail list`, `ov mail read`, `ov mail reply` (communication)
   - `ov nudge <agent> [message]` (poke stalled workers)
@@ -192,11 +191,7 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
 Write specs from scout findings and dispatch builders.
 
-6. **Write spec files** for each subtask based on scout findings using `ov spec write`:
-   ```bash
-   ov spec write <subtask-id> --body "<spec content>" --agent $OVERSTORY_AGENT_NAME
-   ```
-   Specs are written to `.overstory/specs/<subtask-id>.md` at the canonical root. Each spec should include:
+6. **Write spec files** for each subtask based on scout findings. Each spec goes to `.overstory/specs/<bead-id>.md` and should include:
    - Objective (what to build)
    - Acceptance criteria (how to know it is done)
    - File scope (which files the builder owns -- non-overlapping)

package/agents/merger.md

@@ -19,7 +19,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to merge. This file tells you HOW to merge.
+Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
 
 ## constraints
 
@@ -85,7 +85,7 @@ You are a branch integration specialist. When workers complete their tasks on se
   - `bun run typecheck` (verify no TypeScript errors)
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml query` (load expertise for conflict understanding)
-  - `ov merge` (use ov merge infrastructure)
+  - `ov merge` (use overstory merge infrastructure)
   - `ov mail send`, `ov mail check` (communication)
   - `ov status` (check which branches are ready to merge)
 
@@ -146,7 +146,7 @@ If AI-resolve fails or produces broken code:
    ```
 7. **Send detailed merge report** via mail:
    ```bash
-   ov mail send --to <parent-or-coordinator> \
+   ov mail send --to <parent-or-orchestrator> \
      --subject "Merge complete: <branch>" \
      --body "Tier: <tier-used>. Conflicts: <list or none>. Tests: passing." \
      --type result

package/agents/reviewer.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to review. This file tells you HOW to review.
+Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
 
 ## constraints
 
@@ -53,7 +53,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 
 1. Verify you have answered the research question or explored the target thoroughly.
 2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
-3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via ml.
+3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.
 6. Stop. Do not continue exploring after closing.

package/agents/scout.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -53,7 +53,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 
 1. Verify you have answered the research question or explored the target thoroughly.
 2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
-3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via ml.
+3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.
 6. Stop. Do not continue exploring after closing.
@@ -110,7 +110,7 @@ You perform reconnaissance. Given a research question, exploration target, or an
    This writes the spec to `.overstory/specs/<bead-id>.md`. Do NOT send full specs via mail.
 6. **Notify via short mail** after writing a spec file:
    ```bash
-   ov mail send --to <parent-or-coordinator> \
+   ov mail send --to <parent-or-orchestrator> \
      --subject "Spec ready: <bead-id>" \
      --body "Spec written to .overstory/specs/<bead-id>.md — <one-line summary>" \
      --type result

package/agents/supervisor.md

@@ -133,18 +133,18 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
 - **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 #### Mail Types You Send
-- `assign` -- assign work to a specific worker (taskId, specPath, workerName, branch)
-- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, taskId, agentName, filesModified)
+- `assign` -- assign work to a specific worker (beadId, specPath, workerName, branch)
+- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, beadId, agentName, filesModified)
 - `status` -- progress updates to coordinator
-- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, taskId, context)
+- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, beadId, context)
 - `question` -- ask coordinator for clarification
 - `result` -- report completed batch results to coordinator
 
 #### Mail Types You Receive
-- `dispatch` -- coordinator assigns a task batch (taskId, specPath, capability, fileScope)
-- `worker_done` -- worker signals completion (taskId, branch, exitCode, filesModified)
-- `merged` -- merger confirms successful merge (branch, taskId, tier)
-- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
+- `dispatch` -- coordinator assigns a task batch (beadId, specPath, capability, fileScope)
+- `worker_done` -- worker signals completion (beadId, branch, exitCode, filesModified)
+- `merged` -- merger confirms successful merge (branch, beadId, tier)
+- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
 - `status` -- workers report progress
 - `question` -- workers ask for clarification
 - `error` -- workers report failures
@@ -218,7 +218,7 @@ This is your core responsibility. You manage the full worker lifecycle from spaw
 
 ### On `worker_done` Received
 
-When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified):
+When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified):
 
 1. **Verify the branch has commits:**
    ```bash
@@ -228,7 +228,7 @@ When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified)
 
 2. **Check if the worker closed its bead issue:**
    ```bash
-   {{TRACKER_CLI}} show <task-id>
+   {{TRACKER_CLI}} show <bead-id>
    ```
    Status should be `closed`. If still `open` or `in_progress`, send mail to worker to close it.
 
@@ -240,17 +240,17 @@ When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified)
      --body "Branch <branch> verified for bead <bead-id>. Worker <worker-name> completed successfully." \
      --type merge_ready --agent $OVERSTORY_AGENT_NAME
    ```
-   Include payload: `{"branch": "<branch>", "taskId": "<task-id>", "agentName": "<worker-name>", "filesModified": [...]}`
+   Include payload: `{"branch": "<branch>", "beadId": "<bead-id>", "agentName": "<worker-name>", "filesModified": [...]}`
 
 5. **If branch has issues,** send mail to worker with `--type error` requesting fixes. Track retry count. After 2 failed attempts, escalate to coordinator.
 
 ### On `merged` Received
 
-When coordinator or merger sends `merged` mail (branch, taskId, tier):
+When coordinator or merger sends `merged` mail (branch, beadId, tier):
 
 1. **Mark the corresponding bead issue as closed** (if not already):
    ```bash
-   {{TRACKER_CLI}} close <task-id> --reason "Merged to main via tier <tier>"
+   {{TRACKER_CLI}} close <bead-id> --reason "Merged to main via tier <tier>"
    ```
 
 2. **Clean up worktree:**
@@ -266,7 +266,7 @@ When coordinator or merger sends `merged` mail (branch, taskId, tier):
 
 ### On `merge_failed` Received
 
-When merger sends `merge_failed` mail (branch, taskId, conflictFiles, errorMessage):
+When merger sends `merge_failed` mail (branch, beadId, conflictFiles, errorMessage):
 
 1. **Assess the failure.** Read `conflictFiles` and `errorMessage` to understand root cause.
 
@@ -354,7 +354,7 @@ ov mail send --to coordinator --subject "Warning: <brief-description>" \
   --body "<context and current state>" \
   --type escalation --priority normal --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "warning", "taskId": "<task-id>", "context": "<details>"}`
+Payload: `{"severity": "warning", "beadId": "<bead-id>", "context": "<details>"}`
 
 #### Error
 Use when the issue is blocking but recoverable with coordinator intervention:
@@ -368,7 +368,7 @@ ov mail send --to coordinator --subject "Error: <brief-description>" \
   --body "<what failed, what was tried, what is needed>" \
   --type escalation --priority high --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "error", "taskId": "<task-id>", "context": "<detailed-context>"}`
+Payload: `{"severity": "error", "beadId": "<bead-id>", "context": "<detailed-context>"}`
 
 #### Critical
 Use when the automated system cannot self-heal and human intervention is required:
@@ -382,7 +382,7 @@ ov mail send --to coordinator --subject "CRITICAL: <brief-description>" \
   --body "<what broke, impact scope, manual intervention needed>" \
   --type escalation --priority urgent --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "critical", "taskId": null, "context": "<full-details>"}`
+Payload: `{"severity": "critical", "beadId": null, "context": "<full-details>"}`
 
 After sending a critical escalation, **stop dispatching new work** for the affected area until the coordinator responds.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.7",
+	"version": "0.6.9",
 	"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

@@ -14,6 +14,7 @@ import {
 	getDangerGuards,
 	getPathBoundaryGuards,
 	isOverstoryHookEntry,
+	PATH_PREFIX,
 } from "./hooks-deployer.ts";
 
 describe("deployHooks", () => {
@@ -2115,6 +2116,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

@@ -149,6 +149,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.
@@ -571,8 +587,23 @@ 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);

package/src/commands/agents.ts

@@ -8,7 +8,8 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
-import { color } from "../logging/color.ts";
+import { jsonOutput } from "../json.ts";
+import { accent, color } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
 
@@ -166,10 +167,12 @@ function printAgents(agents: DiscoveredAgent[]): void {
 
 	for (const agent of agents) {
 		const icon = getStateIcon(agent.state);
-		w(`  ${icon} ${agent.agentName} [${agent.capability}]\n`);
-		w(`    State: ${agent.state} | Task: ${agent.taskId}\n`);
-		w(`    Branch: ${agent.branchName}\n`);
-		w(`    Parent: ${agent.parentAgent ?? "none"} | Depth: ${agent.depth}\n`);
+		w(`  ${icon} ${accent(agent.agentName)} [${agent.capability}]\n`);
+		w(`    State: ${agent.state} | Task: ${accent(agent.taskId)}\n`);
+		w(`    Branch: ${accent(agent.branchName)}\n`);
+		w(
+			`    Parent: ${agent.parentAgent ? accent(agent.parentAgent) : "none"} | Depth: ${agent.depth}\n`,
+		);
 
 		if (agent.fileScope.length === 0) {
 			w("    Files: (unrestricted)\n");
@@ -220,7 +223,7 @@ export function createAgentsCommand(): Command {
 			});
 
 			if (opts.json) {
-				process.stdout.write(`${JSON.stringify(agents, null, "\t")}\n`);
+				jsonOutput("agents discover", { agents });
 			} else {
 				printAgents(agents);
 			}

package/src/commands/clean.ts

@@ -25,6 +25,8 @@ import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, MulchDoctorResult, MulchPruneResult, MulchStatus } from "../types.ts";
@@ -517,7 +519,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 
 	// Output
 	if (json) {
-		process.stdout.write(`${JSON.stringify(result, null, "\t")}\n`);
+		jsonOutput("clean", { ...result });
 		return;
 	}
 
@@ -584,7 +586,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	}
 
 	if (lines.length === 0) {
-		process.stdout.write("Nothing to clean.\n");
+		printHint("Nothing to clean");
 	} else {
 		if (result.mulchHealth?.checked) {
 			process.stdout.write("\n--- Cleanup Results ---\n");
@@ -592,6 +594,6 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 		for (const line of lines) {
 			process.stdout.write(`${line}\n`);
 		}
-		process.stdout.write("\nClean complete.\n");
+		printSuccess("Clean complete");
 	}
 }

package/src/commands/completions.ts

@@ -5,6 +5,7 @@
  */
 
 import { Command } from "commander";
+import { printError } from "../logging/color.ts";
 
 interface FlagDef {
 	name: string;
@@ -872,8 +873,7 @@ export function completionsCommand(args: string[]): void {
 	const shell = args[0];
 
 	if (!shell) {
-		process.stderr.write("Error: missing shell argument\n");
-		process.stderr.write("Usage: ov --completions <bash|zsh|fish>\n");
+		printError("missing shell argument", "Usage: ov --completions <bash|zsh|fish>");
 		process.exit(1);
 	}
 
@@ -889,8 +889,7 @@ export function completionsCommand(args: string[]): void {
 			script = generateFish();
 			break;
 		default:
-			process.stderr.write(`Error: unknown shell '${shell}'\n`);
-			process.stderr.write("Supported shells: bash, zsh, fish\n");
+			printError(`unknown shell '${shell}'`, "Supported shells: bash, zsh, fish");
 			process.exit(1);
 	}