@kendoo.agentdesk/agentdesk 0.26.0 → 0.28.0

package/cli/engine/agents/index.mjs

@@ -0,0 +1,151 @@
+// Persona registry → Agent SDK definitions.
+//
+// The team (cli/agents.mjs BUILT_IN_AGENTS + project customisations via
+// resolveTeam) becomes, per phase:
+//   - one lead definition — Jane — that the main thread runs *as* (Options.agent),
+//     with the Agent tool and nothing else. She cannot touch code because the
+//     tools do not exist in her session.
+//   - one AgentDefinition per engineering role, with the tool list that role
+//     needs in that phase and nothing more.
+//
+// Tool lists are the enforcement; prompts describe intent. hooks.mjs is the
+// belt to these braces.
+
+import { BUILT_IN_AGENTS } from "../../agents.mjs";
+
+export const LEAD = "Jane";
+export const READ_ONLY = Object.freeze(["Read", "Grep", "Glob"]);
+const RO_BASH = Object.freeze([...READ_ONLY, "Bash"]);
+const FULL = Object.freeze(["Read", "Edit", "Write", "Bash", "Grep", "Glob"]);
+
+// Which built-in agents take part in each phase, and with which tools.
+export const PHASE_ROSTER = Object.freeze({
+  INTAKE:    { Dennis: RO_BASH },
+  PLAN:      { Dennis: READ_ONLY, Sam: READ_ONLY, Vera: READ_ONLY, Luna: READ_ONLY, Mark: READ_ONLY, Nora: READ_ONLY },
+  EXECUTION: { Dennis: FULL, Sam: READ_ONLY, Vera: FULL, Bart: RO_BASH, Luna: RO_BASH, Mark: READ_ONLY, Nora: FULL },
+  // Reviewers read the diff cold and may run read-only commands (tests, git
+  // log). None of them can edit — fixes happen back in EXECUTION.
+  REVIEW:    { Sam: READ_ONLY, Bart: RO_BASH, Vera: RO_BASH },
+  SUMMARY:   { Dennis: RO_BASH },
+});
+
+// Phases where project-defined custom agents (config.projectAgents) join.
+const CUSTOM_AGENT_PHASES = new Set(["PLAN", "EXECUTION"]);
+
+// Today's defaults: REVIEW and SUMMARY on haiku, the rest on the CLI default.
+// `phaseModels` values are "opus" | "sonnet" | "haiku" | "default" | undefined.
+export function modelForPhase(phase, phaseModels = {}) {
+  const choice = phaseModels?.[phase];
+  if (choice && choice !== "default") return choice;
+  if (phase === "REVIEW" || phase === "SUMMARY") return "haiku";
+  return undefined; // let the SDK/CLI pick its default
+}
+
+const PHASE_GUIDANCE = {
+  INTAKE: "Phase INTAKE: gather the task, its attachments and the repo context. Report facts. Do not plan the implementation and do not write code.",
+  PLAN: "Phase PLAN: assess the approach from your role's angle and report a concrete plan contribution. Do not modify any files.",
+  EXECUTION: "Phase EXECUTION: do your role's part of the plan. Verify every claim with an observation (command output, test result, rendered page) before reporting it.",
+  REVIEW: "Phase REVIEW: you are reviewing a diff you did not write. Report concrete findings with file:line. Be strict but not pedantic — only real gaps against the task and the plan. Do not modify anything.",
+  SUMMARY: "Phase SUMMARY: execute exactly the tracker writes the lead dictates and confirm each with the command's output.",
+};
+
+function executionTasks(a) {
+  const tasks = a.execution?.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) return "";
+  return `\nYour execution checklist:\n${tasks.map((t, i) => `${i + 1}. ${t}`).join("\n")}\n`;
+}
+
+export function agentSystemPrompt(a, phase) {
+  return [
+    `You are ${a.name}, ${a.role} on an AgentDesk software team led by ${LEAD}.`,
+    `Role: ${a.description}.`,
+    a.groundRules ? `Ground rules: ${a.groundRules}` : "",
+    a.codePrinciple ? `Code principle: ${a.codePrinciple}` : "",
+    "",
+    PHASE_GUIDANCE[phase] || "",
+    phase === "EXECUTION" ? executionTasks(a) : "",
+    "",
+    "No announcement without observation: never claim something is done, passes, or works unless you ran the check and read its output. If the observation is out of reach, say so plainly.",
+    `Report back to ${LEAD} concisely. You may prefix a message with [THINK], [ACT], [ARGUE] or [AGREE] to make your stance clear.`,
+  ].filter(l => l !== null && l !== undefined).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function rosterLine(name, def) {
+  return `- ${name} (${def.role}) — ${def.description}. Tools: ${def.tools.join(", ")}.`;
+}
+
+export function leadSystemPrompt(roster, phase) {
+  const jane = BUILT_IN_AGENTS.Jane;
+  const lines = Object.entries(roster).map(([n, d]) => rosterLine(n, d));
+  return [
+    `You are ${LEAD}, ${jane.role}. ${jane.description}.`,
+    "",
+    "You coordinate; you do not build. You have exactly one tool — Agent — and you use it to delegate to the team. You never read files, run commands, or edit anything yourself; when you need technical information, ask an agent for it.",
+    "Your language is product-only: user stories, acceptance criteria, scope, priorities, stakeholder impact.",
+    "",
+    `Team available in phase ${phase}:`,
+    ...lines,
+    "",
+    "When you delegate, give the agent everything it needs in the prompt: the task, the relevant decisions so far, and exactly what to report back. Agents start with no memory of this conversation.",
+    "When an agent reports, relay the substance in one to three lines and move on. Never claim a result you did not receive from an agent.",
+    "Announce a new task id, if you create one, on its own line as `TASK_ID: <id>`, and a short session title as `SESSION_TITLE: <title>`.",
+  ].join("\n");
+}
+
+// Solo mode: the named agent IS the main thread, with the full tool set and
+// no subagents. Its system prompt is the phase template (renderSoloPrompt), so
+// the AgentDefinition prompt stays a short identity line.
+export function soloDefinition(agent) {
+  const def = {
+    description: `${agent.role}: ${agent.description}`,
+    prompt: `You are ${agent.name}, ${agent.role}. You work alone on the task given to you, end to end.`,
+    tools: [...FULL],
+  };
+  return { agents: { [agent.name]: def }, allowedTools: [...FULL], lead: agent.name };
+}
+
+// team        — resolveTeam(config) output (array of { name, role, description, ... })
+// phase       — one of PHASES
+// phaseModels — config.phaseModels
+// Returns { agents: Record<name, AgentDefinition>, allowedTools: string[], lead: "Jane" }
+export function agentsForPhase({ phase, team, phaseModels = {} }) {
+  const roster = PHASE_ROSTER[phase] || {};
+  const subagentModel = (phase === "REVIEW" || phase === "SUMMARY") ? modelForPhase(phase, phaseModels) : "inherit";
+
+  const agents = {};
+  for (const a of team) {
+    if (a.name === LEAD) continue;
+    const isBuiltIn = !!BUILT_IN_AGENTS[a.name];
+    let tools;
+    if (isBuiltIn) {
+      tools = roster[a.name];
+      if (!tools) continue; // this role has no part in this phase
+    } else {
+      if (!CUSTOM_AGENT_PHASES.has(phase)) continue;
+      tools = Array.isArray(a.tools) && a.tools.length ? a.tools : READ_ONLY;
+    }
+    agents[a.name] = {
+      description: `${a.role}: ${a.description}`,
+      prompt: agentSystemPrompt(a, phase),
+      tools: [...tools],
+      model: subagentModel,
+      role: a.role,
+    };
+  }
+
+  // Strip our bookkeeping field before handing definitions to the SDK.
+  const sdkAgents = {};
+  for (const [name, def] of Object.entries(agents)) {
+    sdkAgents[name] = { description: def.description, prompt: def.prompt, tools: def.tools, model: def.model };
+  }
+  sdkAgents[LEAD] = {
+    description: `${BUILT_IN_AGENTS.Jane.role}: ${BUILT_IN_AGENTS.Jane.description}`,
+    prompt: leadSystemPrompt(agents, phase),
+    tools: ["Agent"],
+  };
+
+  const allowed = new Set(["Agent"]);
+  for (const def of Object.values(sdkAgents)) for (const t of def.tools) allowed.add(t);
+
+  return { agents: sdkAgents, allowedTools: [...allowed], lead: LEAD };
+}

package/cli/engine/claude-auth.mjs

@@ -0,0 +1,72 @@
+// Can a *standalone* Claude process authenticate on this machine?
+//
+// Setup used to check GitHub and the tracker and never Claude itself, so a
+// new user reached their first session and got "Not logged in" from deep
+// inside the engine. An interactive `claude` working in the user's terminal
+// is not proof: it may be inheriting auth from a parent session that our
+// child processes cannot reach.
+//
+// The check runs the same binary the engine will spawn, with the same
+// scrubbed environment, and reads `claude auth status`.
+
+import { execFile } from "child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "path";
+import { stripParentSessionVars } from "./env.mjs";
+
+export function bundledClaudePath() {
+  const platformPkg = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`;
+  try {
+    const pkgDir = dirname(createRequire(import.meta.url).resolve(`${platformPkg}/package.json`));
+    return join(pkgDir, process.platform === "win32" ? "claude.exe" : "claude");
+  } catch {
+    return null;
+  }
+}
+
+export function claudeBinary(env = process.env) {
+  return env.AGENTDESK_CLAUDE_PATH || bundledClaudePath() || "claude";
+}
+
+export const CLAUDE_LOGIN_HINT = [
+  "Claude Code has no login that a standalone session can use.",
+  "Fix one of:",
+  "  • run `claude auth login` in this terminal (if you use account profiles,",
+  "    the same CLAUDE_CONFIG_DIR you will run agentdesk with), then re-run;",
+  "  • or add ANTHROPIC_API_KEY=<key> to the project's .env.",
+].join("\n");
+
+function run(exec, bin, args, env, timeoutMs) {
+  return new Promise(resolve => {
+    exec(bin, args, { env, timeout: timeoutMs, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+      resolve({ err, stdout: String(stdout || ""), stderr: String(stderr || "") });
+    });
+  });
+}
+
+// Returns { ok, method, detail, hint? }.
+//   env  — the environment the session child will get (dotenv + sandbox applied)
+//   exec — injectable for tests (child_process.execFile signature)
+export async function checkClaudeAuth({ env = process.env, exec = execFile, timeoutMs = 10000 } = {}) {
+  if (env.ANTHROPIC_API_KEY) return { ok: true, method: "api-key", detail: "ANTHROPIC_API_KEY" };
+
+  const bin = claudeBinary(env);
+  const { err, stdout } = await run(exec, bin, ["auth", "status"], stripParentSessionVars(env), timeoutMs);
+
+  if (err && !stdout) {
+    const detail = err.code === "ENOENT"
+      ? `Claude binary not found (${bin})`
+      : `could not run \`claude auth status\` (${err.message || err.code})`;
+    return { ok: false, method: "unknown", detail, hint: CLAUDE_LOGIN_HINT };
+  }
+
+  let status;
+  try { status = JSON.parse(stdout); } catch {
+    return { ok: false, method: "unknown", detail: "unexpected output from `claude auth status`", hint: CLAUDE_LOGIN_HINT };
+  }
+
+  if (status.loggedIn === true) {
+    return { ok: true, method: status.authMethod || "oauth", detail: status.email || status.authMethod || "logged in" };
+  }
+  return { ok: false, method: "none", detail: "not logged in", hint: CLAUDE_LOGIN_HINT };
+}

package/cli/engine/env.mjs

@@ -0,0 +1,56 @@
+// Environment for the Claude child process.
+//
+// The SDK *replaces* the subprocess environment with `Options.env`, so PATH
+// and friends must be spread in from the parent. But the parent may itself be
+// an interactive Claude Code session (a developer running `agentdesk team`
+// from inside Claude Code, or the daemon launched from one). That session
+// stamps its own identity into the environment — session id, messaging
+// socket/token, parent pid, entrypoint — and a child that inherits those
+// believes it is a nested child of that session: it looks for the parent's
+// credentials via the parent's socket, finds none, and reports "Not logged in"
+// even though the machine is logged in. The old orchestrator spread
+// process.env verbatim and had this exposure.
+//
+// CLAUDE_CONFIG_DIR is deliberately kept: it is how a user selects an account
+// profile, and the sandbox allowlists it (session-isolation.mjs).
+
+// Variables that describe a *parent* interactive session, never a child.
+export const PARENT_SESSION_VARS = Object.freeze([
+  "CLAUDECODE",
+  "CLAUDE_CODE_CHILD_SESSION",
+  "CLAUDE_CODE_ENTRYPOINT",
+  "CLAUDE_CODE_EXECPATH",
+  "CLAUDE_CODE_MESSAGING_SOCKET",
+  "CLAUDE_CODE_MESSAGING_TOKEN",
+  "CLAUDE_CODE_SESSION_ID",
+  "CLAUDE_PID",
+  "CLAUDE_EFFORT",
+]);
+
+// Hard caps on what a session may spawn. Depth 1: our subagents may not spawn
+// their own. Concurrency 4: REVIEW fans out three reviewers, plus headroom.
+export const SUBAGENT_CAPS = Object.freeze({
+  CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH: "1",
+  CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS: "4",
+});
+
+export function stripParentSessionVars(env) {
+  const out = { ...env };
+  for (const k of PARENT_SESSION_VARS) delete out[k];
+  return out;
+}
+
+// base       — usually process.env
+// dotenv     — the project's .env (loadDotEnv(cwd)); lets a project supply
+//              ANTHROPIC_API_KEY and its own variables to the child
+// sandboxEnv — createScratchHome().env (git/gh identity, tokens) — wins over .env
+// extra      — per-session additions
+export function buildChildEnv({ base = process.env, dotenv = {}, sandboxEnv = {}, extra = {} } = {}) {
+  return {
+    ...stripParentSessionVars(base),
+    ...dotenv,
+    ...sandboxEnv,
+    ...SUBAGENT_CAPS,
+    ...extra,
+  };
+}

package/cli/engine/events.mjs

@@ -0,0 +1,214 @@
+// SDKMessage → AgentDesk session event protocol.
+//
+// This replaces cli/stream-parser.mjs. The old parser recovered "who is
+// speaking" by regex-matching persona names at the start of lines of a single
+// model's prose. Here attribution is structural: every message that comes from
+// inside a subagent carries `parent_tool_use_id`, which points at the `Agent`
+// tool call that spawned it, whose input names the agent (`subagent_type`).
+// Text with no parent is the phase's lead agent.
+//
+// The emitted events and their fields are the contract the server
+// (server/index.mjs processSessionEvent) and dashboard already consume:
+//   session:model {model}
+//   agent:message {agent, tag, message}
+//   tool:use      {agent, tool, description}
+//   tool:result   {success, summary}
+//   session:update {taskId?, title?}
+// `phase:change` and `session:start|end|error` are emitted by the session
+// loop, not here — phase boundaries are engine facts, not prose signals.
+
+const TAG_RE = /\[(SAY|ACT|THINK|AGREE|ARGUE)\]\s*/gi;
+const AGENT_TOOL_NAMES = new Set(["Agent", "Task"]);
+
+export function timestamp() {
+  const d = new Date();
+  return [d.getHours(), d.getMinutes(), d.getSeconds()].map(n => String(n).padStart(2, "0")).join(":");
+}
+
+export function detectTag(text) {
+  if (/\[ARGUE\]/i.test(text)) return "ARGUE";
+  if (/\[AGREE\]/i.test(text)) return "AGREE";
+  if (/\[THINK\]/i.test(text)) return "THINK";
+  if (/\[ACT\]/i.test(text)) return "ACT";
+  return "SAY";
+}
+
+export function stripTags(text) {
+  return String(text).replace(TAG_RE, "");
+}
+
+// Human-readable one-liner for the dashboard's tool feed. The "Reading|Editing|
+// Writing <path>" forms are load-bearing: cli/daemon.mjs derives
+// filePathsTouched from them.
+function describeBash(cmd) {
+  if (cmd.includes("curl") && /linear/i.test(cmd)) return "Calling Linear API...";
+  if (cmd.includes("curl") && /atlassian|jira/i.test(cmd)) return "Calling Jira API...";
+  if (cmd.includes("curl")) return "Making API request...";
+  return `$ ${cmd.length > 80 ? cmd.slice(0, 80) + "..." : cmd}`;
+}
+
+export function describeTool(name, input = {}) {
+  const shortPath = p => String(p || "").split("/").filter(Boolean).slice(-3).join("/");
+  switch (name) {
+    case "Bash": return describeBash(String(input.command || ""));
+    case "Read": return `Reading ${shortPath(input.file_path)}`;
+    case "Edit": return `Editing ${shortPath(input.file_path)}`;
+    case "Write": return `Writing ${shortPath(input.file_path)}`;
+    case "NotebookEdit": return `Editing ${shortPath(input.notebook_path)}`;
+    case "Glob":
+    case "Grep": return `Searching ${input.pattern || ""}`;
+    case "Agent":
+    case "Task": return `→ ${input.subagent_type || "agent"}: ${input.description || firstLine(input.prompt)}`;
+    default: return `${name}`;
+  }
+}
+
+function firstLine(s) {
+  return String(s || "").split("\n").find(l => l.trim())?.trim().slice(0, 100) || "";
+}
+
+function blockText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.filter(b => b?.type === "text").map(b => b.text).join("\n");
+  return "";
+}
+
+export function summarizeToolResult(block) {
+  const text = blockText(block.content).trim();
+  const looksFailed = block.is_error === true || /\b(error|failed)\b/i.test(text.slice(0, 200));
+  const summary = text.length > 300 ? `Done (${text.length} chars)` : (text || "Done");
+  return { success: !looksFailed, summary };
+}
+
+// Token totals for the dashboard. `modelUsage` is the only per-query figure
+// that includes subagent calls; `usage` covers the main loop only.
+export function totalsFromModelUsage(modelUsage = {}) {
+  let inputTokens = 0, outputTokens = 0, costUsd = 0;
+  for (const u of Object.values(modelUsage)) {
+    inputTokens += (u.inputTokens ?? u.input_tokens ?? 0)
+      + (u.cacheReadInputTokens ?? u.cache_read_input_tokens ?? 0)
+      + (u.cacheCreationInputTokens ?? u.cache_creation_input_tokens ?? 0);
+    outputTokens += u.outputTokens ?? u.output_tokens ?? 0;
+    costUsd += u.costUSD ?? u.cost_usd ?? 0;
+  }
+  return { inputTokens, outputTokens, costUsd };
+}
+
+// leadAgent — name attributed to main-thread text (the phase lead, e.g. "Jane").
+// onEvent  — receives protocol events (without sessionId; the caller adds it).
+export function createEventMapper({ leadAgent = "Jane", onEvent } = {}) {
+  const agents = new Map();      // Agent tool_use id → subagent name
+  const sawText = new Set();     // Agent tool_use ids whose subagent text we forwarded
+  let steps = 0;
+  let reportedModel = null;
+  let result = null;
+
+  function emit(type, fields) {
+    onEvent?.({ type, ...fields, timestamp: timestamp() });
+  }
+
+  function reportModel(model) {
+    // "<synthetic>" is the SDK's placeholder on harness-generated messages
+    // (errors, notices) — not a model the session is running on.
+    if (!model || model === reportedModel || model === "<synthetic>") return;
+    reportedModel = model;
+    emit("session:model", { model });
+  }
+
+  function agentFor(msg) {
+    const pid = msg.parent_tool_use_id;
+    if (!pid) return leadAgent;
+    return agents.get(pid) || "Agent";
+  }
+
+  function handleText(agent, raw, { isLead }) {
+    const text = String(raw).trim();
+    if (!text) return;
+
+    if (isLead) {
+      const taskId = text.match(/TASK_ID:\s*(\S+)/)?.[1];
+      const title = text.match(/SESSION_TITLE:\s*(.+)/)?.[1]?.trim().slice(0, 60);
+      if (taskId || title) emit("session:update", { ...(taskId && { taskId }), ...(title && { title }) });
+    }
+
+    emit("agent:message", { agent, tag: detectTag(text), message: stripTags(text).replace(/\*+/g, "").trim() });
+  }
+
+  function handleAssistant(msg) {
+    reportModel(msg.message?.model);
+    const agent = agentFor(msg);
+    const isLead = !msg.parent_tool_use_id;
+    if (msg.parent_tool_use_id) sawText.add(msg.parent_tool_use_id);
+
+    for (const block of msg.message?.content || []) {
+      if (block.type === "text") {
+        handleText(agent, block.text, { isLead });
+      } else if (block.type === "tool_use") {
+        steps++;
+        if (AGENT_TOOL_NAMES.has(block.name)) {
+          const name = block.input?.subagent_type || "general-purpose";
+          agents.set(block.id, name);
+          emit("agent:message", { agent, tag: "ACT", message: describeTool(block.name, block.input) });
+        }
+        emit("tool:use", { agent, tool: block.name, description: describeTool(block.name, block.input) });
+      }
+    }
+  }
+
+  function handleUser(msg) {
+    const content = msg.message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type !== "tool_result") continue;
+      const { success, summary } = summarizeToolResult(block);
+      emit("tool:result", { success, summary });
+
+      // A subagent reporting back. Its running text was forwarded live (with
+      // parent_tool_use_id); if none arrived, surface its final report so the
+      // dashboard still shows the agent said something.
+      const name = agents.get(block.tool_use_id);
+      if (name && !sawText.has(block.tool_use_id)) {
+        const text = blockText(block.content).trim();
+        if (text) emit("agent:message", { agent: name, tag: "SAY", message: stripTags(text).slice(0, 1200) });
+      }
+    }
+  }
+
+  function handle(msg) {
+    switch (msg?.type) {
+      case "system":
+        if (msg.subtype === "init") reportModel(msg.model);
+        break;
+      case "assistant":
+        handleAssistant(msg);
+        break;
+      case "user":
+        handleUser(msg);
+        break;
+      case "result":
+        result = msg;
+        break;
+      default:
+        break;
+    }
+  }
+
+  function finish() {
+    const totals = totalsFromModelUsage(result?.modelUsage);
+    return {
+      steps,
+      numTurns: result?.num_turns ?? 0,
+      ...totals,
+      costUsd: result?.total_cost_usd ?? totals.costUsd,
+      isError: !!result?.is_error,
+      subtype: result?.subtype || null,
+      errors: result?.errors || [],
+      permissionDenials: result?.permission_denials || [],
+      structuredOutput: result?.structured_output,
+      resultText: result?.result ?? null,
+      agents: [...new Set(agents.values())],
+    };
+  }
+
+  return { handle, finish, agentFor };
+}

package/cli/engine/hooks.mjs

@@ -0,0 +1,112 @@
+// Enforcement hooks. Every "MUST NEVER" that used to live in prompt prose
+// becomes a decision here, applied by the harness before a tool runs.
+//
+// Layering: the AgentDefinition tool lists already make most of this
+// impossible (Jane has only the Agent tool; reviewers have no Edit/Write).
+// These hooks are the belt to those braces, and they carry the one rule tool
+// lists cannot express — "no PR while review findings are open".
+//
+// decidePreToolUse() is pure so the policy is unit-tested without the SDK.
+
+export const MUTATING_TOOLS = Object.freeze(new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]));
+export const CODE_TOOLS = Object.freeze(new Set([...MUTATING_TOOLS, "Bash"]));
+
+// Commands that publish work. Matched loosely on purpose: `gh pr create`,
+// `git push`, `git push --force-with-lease origin HEAD`, chained after `&&`.
+const PUBLISH_RE = /(^|[;&|]\s*)(gh\s+pr\s+create|git\s+push)\b/;
+
+export function isPublishCommand(command) {
+  return PUBLISH_RE.test(String(command || ""));
+}
+
+// The auditor whose sign-off gates publishing. "Sam's audit is a blocking
+// gate — not advisory" used to be prose; now it is the observable fact that a
+// Sam subagent finished in this EXECUTION phase (SubagentStop).
+export const AUDITOR = "Sam";
+
+// Called at the start of every EXECUTION: nothing may be published until the
+// auditor has run in this phase. `openFindings` (from a rejected REVIEW) is
+// carried for the denial message so the team sees what is outstanding.
+export function armPublishGate(state, openFindings = []) {
+  state.awaitingAudit = true;
+  state.openFindings = Array.isArray(openFindings) ? openFindings : [];
+}
+
+export function onSubagentStopped(state, { phase, agentType }) {
+  if (phase === "EXECUTION" && agentType === AUDITOR) {
+    state.awaitingAudit = false;
+    state.openFindings = [];
+  }
+}
+
+// input — the SDK PreToolUseHookInput ({ tool_name, tool_input, agent_id?, agent_type? }).
+//         `agent_id` is present only inside a subagent (BaseHookInput docs).
+// state — mutable session state; reads `awaitingAudit` and `openFindings`.
+export function decidePreToolUse({ phase, input, state = {} }) {
+  const tool = input?.tool_name;
+  const isMainThread = !input?.agent_id;
+
+  // Solo mode: the main thread is the worker, not the lead.
+  if (isMainThread && CODE_TOOLS.has(tool) && !state.mainThreadMayCode) {
+    return { decision: "deny", reason: `The lead does not touch code or run commands — delegate ${tool} to a team agent.` };
+  }
+
+  if (phase === "REVIEW" && MUTATING_TOOLS.has(tool)) {
+    return { decision: "deny", reason: "REVIEW is read-only: report findings; fixes happen back in EXECUTION." };
+  }
+
+  if (phase === "EXECUTION" && tool === "Bash" && isPublishCommand(input?.tool_input?.command)) {
+    const open = Array.isArray(state.openFindings) ? state.openFindings : [];
+    if (state.awaitingAudit || open.length > 0) {
+      const list = open.slice(0, 5).map(f => `- ${f.title || f}`).join("\n");
+      const why = open.length > 0
+        ? `${open.length} review finding(s) are unresolved:\n${list}\n`
+        : "";
+      return {
+        decision: "deny",
+        reason: `Cannot publish yet — ${why}${AUDITOR} must audit the changed files in this phase first (have the lead delegate the audit to ${AUDITOR}, fix what he flags, then publish).`,
+      };
+    }
+  }
+
+  return { decision: "allow" };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+// Build the SDK `hooks` option for one phase.
+//   state         — shared session state (openFindings, ...)
+//   onToolUse     — ({ agentType, tool, input }) for the dashboard
+//   onToolResult  — ({ agentType, tool, response }) for the dashboard
+//   onSubagentStop — ({ agentType }) when a subagent finishes
+export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop } = {}) {
+  return {
+    PreToolUse: [{
+      hooks: [async (input) => {
+        onToolUse?.({ agentType: input.agent_type || null, tool: input.tool_name, input: input.tool_input });
+        const d = decidePreToolUse({ phase, input, state });
+        return d.decision === "deny" ? denyOutput(d.reason) : {};
+      }],
+    }],
+    PostToolUse: [{
+      hooks: [async (input) => {
+        onToolResult?.({ agentType: input.agent_type || null, tool: input.tool_name, response: input.tool_response });
+        return {};
+      }],
+    }],
+    SubagentStop: [{
+      hooks: [async (input) => {
+        onSubagentStop?.({ agentType: input.agent_type || null });
+        return {};
+      }],
+    }],
+  };
+}

package/cli/engine/phases/EXECUTION.md

@@ -0,0 +1,45 @@
+You are running **Phase 3: EXECUTION + QA**.
+
+Task: {{TASK_ID}}
+{{TASK_LINK}}
+
+{{#RETRY}}
+## THIS IS A RETRY — REVIEW DID NOT APPROVE
+
+The reviewers returned the following. Work from this list; do not re-derive it.
+
+{{RETRY_FINDINGS}}
+{{/RETRY}}
+
+## Rules
+
+- Follow CLAUDE.md conventions (if present). Do not modify files unrelated to the task.
+- **Sam's audit is a blocking gate.** After Dennis implements, Sam must read every changed file and run his full checklist, citing file:line for every finding — "looks clean" without evidence is invalid. Dennis fixes every violation before Bart creates the PR. Publishing is refused while findings are open.
+- Nora's sign-off is a gate too: Bart cannot create the PR until Nora reports either "No doc impact — skipped" or "Docs updated: [files]".
+- Do NOT post the final tracker summary or transition the task here — SUMMARY owns all final tracker writes.
+
+{{#SCREENSHOTS_ENABLED}}
+## Screenshots
+
+Screenshots are **enabled** for this project. For UI changes, Bart captures screenshots after the code is final and before the PR, following Luna's plan, and posts them to the tracker as a separate comment.
+{{/SCREENSHOTS_ENABLED}}
+{{#SCREENSHOTS_DISABLED}}
+## Screenshots
+
+Screenshots are **disabled** for this project. Do not capture any unless the user explicitly asks.
+{{/SCREENSHOTS_DISABLED}}
+
+{{TRACKER_SECTION}}
+
+## Your mission
+
+Drive the plan from session memory step by step. Delegate each step with the Agent tool, give the agent the exact step and the relevant decisions, and require an observation for every claim ("tests pass" means the test output, "endpoint works" means the response). In order:
+
+1. **Dennis implements** — create the branch, implement per the plan, run linter and build, commit. Report files changed and technical decisions.
+2. **Sam audits** — every changed file, full checklist (feature envy, separation of concerns, clear interfaces, layering, god files), file:line for each finding. If there are violations, send Dennis back to fix them, then have Sam re-audit.
+3. **Vera tests** — unit/regression tests for the changed code, run and verified, committed.
+4. **Luna / Mark / Nora** — only where applicable (UI, user-facing copy, user-facing behaviour). Each proposes exact changes; Dennis applies them.
+5. **Bart reviews and publishes** — reads all changed files, checks edge cases and error handling, runs linter and build, captures screenshots if applicable, pushes and creates the PR, posts the PR link on the tracker, posts screenshots as a separate comment.
+6. Ask Dennis, Sam and Bart to post their brief tracker comments (files changed & decisions; architecture findings or clean audit with evidence; PR link, test results, screenshots).
+
+Finish by answering with the JSON object required by the output schema — what was implemented, files changed, the PR URL (empty string if none), QA results, issues fixed, and what the reviewers should look at. Nothing else after it.