@rallycry/conveyor-agent 3.8.0 → 4.0.0

package/dist/{chunk-GVE6FQ75.js → chunk-Y4TAVPZV.js}

@@ -12,6 +12,7 @@ var ConveyorConnection = class _ConveyorConnection {
   chatMessageCallback = null;
   stopCallback = null;
   modeChangeCallback = null;
+  runStartCommandCallback = null;
   pendingQuestionResolvers = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = config;
@@ -61,6 +62,11 @@ var ConveyorConnection = class _ConveyorConnection {
           this.earlyModeChanges.push(data);
         }
       });
+      this.socket.on("agentRunner:runStartCommand", () => {
+        if (this.runStartCommandCallback) {
+          this.runStartCommandCallback();
+        }
+      });
       this.socket.on("connect", () => {
         if (!settled) {
           settled = true;
@@ -226,9 +232,12 @@ var ConveyorConnection = class _ConveyorConnection {
     }
     this.earlyModeChanges = [];
   }
-  emitModeChanged(mode) {
+  onRunStartCommand(callback) {
+    this.runStartCommandCallback = callback;
+  }
+  emitModeChanged(agentMode) {
     if (!this.socket) return;
-    this.socket.emit("agentRunner:modeChanged", { mode });
+    this.socket.emit("agentRunner:modeChanged", { agentMode });
   }
   trackSpending(params) {
     if (!this.socket) throw new Error("Not connected");
@@ -347,6 +356,66 @@ var ConveyorConnection = class _ConveyorConnection {
       );
     });
   }
+  updateTaskProperties(data) {
+    if (!this.socket) throw new Error("Not connected");
+    this.socket.emit("agentRunner:updateTaskProperties", data);
+  }
+  listIcons() {
+    const socket = this.socket;
+    if (!socket) throw new Error("Not connected");
+    return new Promise((resolve2, reject) => {
+      socket.emit("agentRunner:listIcons", {}, (response) => {
+        if (response.success && response.data) resolve2(response.data);
+        else reject(new Error(response.error ?? "Failed to list icons"));
+      });
+    });
+  }
+  generateTaskIcon(prompt, aspectRatio) {
+    const socket = this.socket;
+    if (!socket) throw new Error("Not connected");
+    return new Promise((resolve2, reject) => {
+      socket.emit(
+        "agentRunner:generateTaskIcon",
+        { prompt, aspectRatio },
+        (response) => {
+          if (response.success && response.data) resolve2(response.data);
+          else reject(new Error(response.error ?? "Failed to generate icon"));
+        }
+      );
+    });
+  }
+  getTaskProperties() {
+    const socket = this.socket;
+    if (!socket) throw new Error("Not connected");
+    return new Promise((resolve2, reject) => {
+      socket.emit(
+        "agentRunner:getTaskProperties",
+        {},
+        (response) => {
+          if (response.success && response.data) resolve2(response.data);
+          else reject(new Error(response.error ?? "Failed to get task properties"));
+        }
+      );
+    });
+  }
+  triggerIdentification() {
+    const socket = this.socket;
+    if (!socket) throw new Error("Not connected");
+    return new Promise((resolve2, reject) => {
+      socket.emit(
+        "agentRunner:triggerIdentification",
+        {},
+        (response) => {
+          if (response.success && response.data) resolve2(response.data);
+          else reject(new Error(response.error ?? "Identification failed"));
+        }
+      );
+    });
+  }
+  emitModeTransition(payload) {
+    if (!this.socket) return;
+    this.socket.emit("agentRunner:modeTransition", payload);
+  }
   disconnect() {
     this.flushEvents();
     this.socket?.disconnect();
@@ -799,6 +868,13 @@ async function processEvents(events, context, host) {
   const turnToolCalls = [];
   for await (const event of events) {
     if (host.isStopped()) break;
+    if (host.pendingModeRestart) {
+      host.pendingModeRestart = false;
+      if (isTyping) {
+        host.connection.sendTypingStop();
+      }
+      return { retriable: false, modeRestart: true };
+    }
     switch (event.type) {
       case "system": {
         const systemEvent = event;
@@ -1007,12 +1083,22 @@ ${context.plan}`);
   }
   return parts;
 }
-function buildInstructions(mode, context, scenario) {
+function buildInstructions(mode, context, scenario, agentMode) {
   const parts = [`
 ## Instructions`];
   const isPm = mode === "pm";
+  const isAutoMode = agentMode === "auto";
   if (scenario === "fresh") {
-    if (isPm && context.isParentTask) {
+    if (isAutoMode && isPm) {
+      parts.push(
+        `You are operating autonomously. Begin planning immediately.`,
+        `1. Explore the codebase to understand the architecture and relevant files`,
+        `2. Draft a clear implementation plan and save it with update_task`,
+        `3. Set story points (set_story_points), tags (set_task_tags), and title (set_task_title)`,
+        `4. When the plan and all required properties are set, call ExitPlanMode to transition to building`,
+        `Do NOT wait for team input \u2014 proceed autonomously.`
+      );
+    } else if (isPm && context.isParentTask) {
       parts.push(
         `You are the project manager for this task and its subtasks.`,
         `Use list_subtasks to review the current state of child tasks.`,
@@ -1091,27 +1177,155 @@ Address the requested changes directly. Do NOT re-investigate the codebase from
   }
   return parts;
 }
+function buildPropertyInstructions(context) {
+  const parts = [];
+  parts.push(
+    ``,
+    `### Proactive Property Management`,
+    `As you plan this task, proactively fill in task properties when you have enough context:`,
+    `- Once you understand the scope, use set_story_points to assign a value`,
+    `- Use set_task_tags to categorize the work`,
+    `- For icons: FIRST call list_icons to check for existing matches. Use set_task_icon if one fits.`,
+    `  Only call generate_task_icon if no existing icon is a good fit.`,
+    `- Use set_task_title if the current title doesn't accurately reflect the plan`,
+    ``,
+    `Don't wait for the user to ask \u2014 fill these in naturally as the plan takes shape.`,
+    `If the user adjusts the plan significantly, update the properties to match.`
+  );
+  if (context.storyPoints && context.storyPoints.length > 0) {
+    parts.push(``, `Available story point tiers:`);
+    for (const sp of context.storyPoints) {
+      const desc = sp.description ? ` \u2014 ${sp.description}` : "";
+      parts.push(`- Value ${sp.value}: "${sp.name}"${desc}`);
+    }
+  }
+  if (context.projectTags && context.projectTags.length > 0) {
+    parts.push(``, `Available project tags:`);
+    for (const tag of context.projectTags) {
+      parts.push(`- ID: "${tag.id}", Name: "${tag.name}"`);
+    }
+  }
+  return parts;
+}
+function buildModePrompt(agentMode, context) {
+  switch (agentMode) {
+    case "discovery": {
+      const parts = [
+        `
+## Mode: Discovery`,
+        `You are in Discovery mode \u2014 helping plan and scope this task.`,
+        `- You have read-only codebase access (can read files, run git commands, search code)`,
+        `- You have MCP tools: update_task (title, description, plan, tags, SP, icon)`,
+        `- You can create and manage subtasks`,
+        `- You cannot write code or edit files (except .claude/plans/)`,
+        `- Goal: collaborate with the user to create a clear plan`,
+        `- Proactively fill task properties (SP, tags, icon) as the plan takes shape`
+      ];
+      if (context) {
+        parts.push(...buildPropertyInstructions(context));
+      }
+      return parts.join("\n");
+    }
+    case "building":
+      return [
+        `
+## Mode: Building`,
+        `You are in Building mode \u2014 executing the plan.`,
+        `- You have full coding access (read, write, edit, bash, git)`,
+        `- Safety rules: no destructive operations, use --force-with-lease instead of --force`,
+        `- If this is a leaf task (no children): execute the plan directly`,
+        `- Goal: implement the plan, run tests, open a PR when done`
+      ].join("\n");
+    case "review":
+      return [
+        `
+## Mode: Review`,
+        `You are in Review mode \u2014 reviewing and coordinating.`,
+        `- You have read-only access plus light edit capability (can suggest fixes, run tests, check linting)`,
+        `- For parent tasks: you can manage children, review child PRs, fire next child builds`,
+        `- You have Pack Runner coordination tools (list_subtasks, fire builds, approve PRs)`,
+        `- Goal: ensure quality, provide feedback, coordinate progression`
+      ].join("\n");
+    case "auto": {
+      const parts = [
+        `
+## Mode: Auto`,
+        `You are in Auto mode \u2014 operating autonomously through planning \u2192 building \u2192 PR.`,
+        ``,
+        `### Phase 1: Discovery & Planning (current)`,
+        `- You have read-only codebase access (can read files, run git commands, search code)`,
+        `- You can write plan files in .claude/plans/ only \u2014 no other file writes`,
+        `- You have MCP tools for task properties: update_task, set_story_points, set_task_tags, set_task_icon, set_task_title`,
+        ``,
+        `### Required before transitioning:`,
+        `Before calling ExitPlanMode, you MUST fill in ALL of these:`,
+        `1. **Plan** \u2014 Save a clear implementation plan using update_task`,
+        `2. **Story Points** \u2014 Assign via set_story_points`,
+        `3. **Title** \u2014 Set an accurate title via set_task_title (if the current one is vague or "Untitled")`,
+        ``,
+        `### Transitioning to Building:`,
+        `When your plan is complete and all required properties are set, call the **ExitPlanMode** tool.`,
+        `- If any required properties are missing, ExitPlanMode will be denied with details on what's missing`,
+        `- Once ExitPlanMode succeeds, the system will automatically restart your session in Building mode with the appropriate model`,
+        `- You do NOT need to do anything after calling ExitPlanMode \u2014 the transition is handled for you`,
+        ``,
+        `### Autonomous Guidelines:`,
+        `- Make decisions independently \u2014 do not ask the team for approval at each step`,
+        `- Only escalate when genuinely blocked (ambiguous requirements, missing access, conflicting instructions)`,
+        `- Be thorough in discovery: read relevant files, understand the codebase architecture, then plan`
+      ];
+      if (context) {
+        parts.push(...buildPropertyInstructions(context));
+      }
+      return parts.join("\n");
+    }
+    default:
+      return null;
+  }
+}
 function buildPackRunnerSystemPrompt(context, config, setupLog) {
   const parts = [
     `You are an autonomous Pack Runner managing child tasks for the "${context.title}" project.`,
     `You are running locally with full access to the repository and task management tools.`,
     `Your job is to sequentially execute child tasks by firing cloud builds, reviewing their PRs, and merging them.`,
     ``,
+    `## Child Task Status Lifecycle`,
+    `- "Planning" \u2014 Not ready for execution. Skip it (or escalate if blocking).`,
+    `- "Open" \u2014 Ready to execute. Use start_child_cloud_build to fire it.`,
+    `- "InProgress" \u2014 Currently being worked on by a Task Runner. Wait \u2014 it will move to ReviewPR when done.`,
+    `- "ReviewPR" \u2014 Task Runner finished and opened a PR. Review and merge it.`,
+    `- "ReviewDev" \u2014 PR was merged to dev. This child is complete. Move on.`,
+    `- "Complete" \u2014 Fully done. Move on.`,
+    ``,
     `## Autonomous Loop`,
-    `Follow this loop continuously until all children are complete:`,
+    `Follow this loop each time you are launched or relaunched:`,
+    ``,
     `1. Call list_subtasks to see the current state of all child tasks.`,
-    `2. If any child is in "ReviewPR" status: review the PR (use get_task to read the child, check quality), then call approve_and_merge_pr to merge it. If CI/CD is failing, post guidance to the child's chat with post_to_chat, or notify the team if stuck.`,
-    `3. Find the next child in "Open" status (by ordinal order) and fire its cloud build with start_child_cloud_build.`,
-    `4. Report to chat which task you fired, then state you are going idle to wait. The system will relaunch you when the child completes.`,
-    `5. When ALL children are complete (no "Open" or "ReviewPR" remaining): do a final review, summarize results in chat, and mark this parent task complete with update_task_status.`,
+    `   The response includes PR info (githubPRNumber, githubPRUrl) and agent assignment (agentId).`,
+    ``,
+    `2. Evaluate each child by status (in ordinal order):`,
+    `   - "ReviewPR": Review and merge its PR with approve_and_merge_pr.`,
+    `     - If merge fails due to pending CI: post a status update to chat, state you are going idle, and the system will relaunch you to try again.`,
+    `     - If merge fails due to failed CI: use get_task_cli(childTaskId) to check what went wrong. Escalate to the team in chat.`,
+    `   - "InProgress": A Task Runner is actively working on this child. Do nothing \u2014 wait for it to finish.`,
+    `   - "Open": This is the next child to execute. Fire it with start_child_cloud_build.`,
+    `     - If it fails because the child is missing story points or an agent: notify the team in chat and go idle.`,
+    `   - "ReviewDev" / "Complete": Already done. Skip.`,
+    `   - "Planning": Not ready. If this is blocking progress, notify the team.`,
+    ``,
+    `3. After merging a PR: run \`git pull origin ${context.baseBranch}\` to get the merged changes before firing the next child.`,
+    ``,
+    `4. After firing a child build: report which task you fired to chat, then explicitly state you are going idle. The system will relaunch you when the child completes or changes status.`,
+    ``,
+    `5. When ALL children are in "ReviewDev" or "Complete" (no "Open", "InProgress", or "ReviewPR" remaining): do a final review, summarize results in chat, and mark this parent task complete with update_task_status("Complete").`,
     ``,
     `## Important Rules`,
     `- Process children ONE at a time, in ordinal order.`,
-    `- After firing a child build, explicitly state you are going idle. The system will disconnect you until the child completes.`,
+    `- After firing a child build OR when waiting on CI, explicitly state you are going idle. The system will disconnect you and relaunch when there's a status change.`,
     `- Do NOT attempt to write code yourself. Your role is coordination only.`,
-    `- If a child task is missing story points or an assigned agent, notify the team in chat and wait.`,
-    `- If a child fails repeatedly, escalate to the team rather than retrying indefinitely.`,
-    `- You can use get_task and get_task_cli to inspect child task details and logs.`,
+    `- If a child is stuck in "InProgress" for an unusually long time, use get_task_cli(childTaskId) to check its logs and escalate to the team if it appears stuck.`,
+    `- You can use get_task(childTaskId) to get a child's full details including PR URL and branch.`,
+    `- list_subtasks returns PR info (githubPRNumber, githubPRUrl) and agent assignment (agentId) for each child \u2014 use this to verify readiness before firing builds.`,
     `- You can use read_task_chat to check for team messages.`
   ];
   if (context.storyPoints && context.storyPoints.length > 0) {
@@ -1159,10 +1373,11 @@ function buildPackRunnerInstructions(context, scenario) {
     );
   } else if (scenario === "idle_relaunch") {
     parts.push(
-      `You have been relaunched \u2014 a child task may have completed.`,
+      `You have been relaunched \u2014 a child task likely changed status (completed work, opened a PR, or was merged).`,
       `Call list_subtasks to check the current state of all children.`,
-      `If a child is in "ReviewPR" status, review and merge its PR.`,
-      `Then continue your autonomous loop with the next "Open" child.`
+      `Look for children in "ReviewPR" status first \u2014 review and merge their PRs.`,
+      `If a child you previously fired is now in "ReviewDev", it was merged. Pull latest with \`git pull origin ${context.baseBranch}\` and continue to the next "Open" child.`,
+      `If no children need action (all InProgress or waiting), state you are going idle.`
     );
   } else {
     const lastAgentIdx = findLastAgentMessageIndex(context.chatHistory);
@@ -1173,12 +1388,12 @@ function buildPackRunnerInstructions(context, scenario) {
 New messages since your last run:`,
       ...newMessages.map((m) => `[${m.userName ?? "user"}]: ${m.content}`),
       `
-Review these messages, then continue your autonomous loop: call list_subtasks and proceed accordingly.`
+After addressing the feedback, resume your autonomous loop: call list_subtasks and proceed accordingly.`
     );
   }
   return parts;
 }
-function buildInitialPrompt(mode, context, isAuto) {
+function buildInitialPrompt(mode, context, isAuto, agentMode) {
   const isPackRunner = mode === "pm" && !!isAuto && !!context.isParentTask;
   if (!isPackRunner) {
     const sessionRelaunch = buildRelaunchWithSession(mode, context);
@@ -1186,12 +1401,12 @@ function buildInitialPrompt(mode, context, isAuto) {
   }
   const scenario = detectRelaunchScenario(context);
   const body = buildTaskBody(context);
-  const instructions = isPackRunner ? buildPackRunnerInstructions(context, scenario) : buildInstructions(mode, context, scenario);
+  const instructions = isPackRunner ? buildPackRunnerInstructions(context, scenario) : buildInstructions(mode, context, scenario, agentMode);
   return [...body, ...instructions].join("\n");
 }
-function buildSystemPrompt(mode, context, config, setupLog, pmSubMode = "planning") {
+function buildSystemPrompt(mode, context, config, setupLog, agentMode) {
   const isPm = mode === "pm";
-  const isPmActive = isPm && pmSubMode === "active";
+  const isPmActive = isPm && agentMode === "building";
   const isPackRunner = isPm && !!config.isAuto && !!context.isParentTask;
   if (isPackRunner) {
     return buildPackRunnerSystemPrompt(context, config, setupLog);
@@ -1317,6 +1532,10 @@ Your responses are sent directly to the task chat \u2014 the team sees everythin
       `Use the create_pull_request tool to open PRs \u2014 do NOT use gh CLI or shell commands for PR creation.`
     );
   }
+  const modePrompt = buildModePrompt(agentMode, context);
+  if (modePrompt) {
+    parts.push(modePrompt);
+  }
   return parts.join("\n");
 }
 
@@ -1599,7 +1818,7 @@ function buildPmTools(connection, storyPoints, options) {
     ),
     tool2(
       "list_subtasks",
-      "List all subtasks under the current parent task",
+      "List all subtasks under the current parent task. Returns status, PR info (githubPRNumber, githubPRUrl), agent assignment (agentId), and plan for each child.",
       {},
       async () => {
         try {
@@ -1634,7 +1853,7 @@ function buildPmTools(connection, storyPoints, options) {
     ),
     tool2(
       "approve_and_merge_pr",
-      "Approve and merge a child task's pull request. Only succeeds if all CI/CD checks are passing. The child task must be in ReviewPR status.",
+      "Approve and merge a child task's pull request. Only succeeds if all CI/CD checks are passing. Returns an error if checks are pending (retry after waiting) or failed (investigate). The child task must be in ReviewPR status.",
       {
         childTaskId: z2.string().describe("The child task ID whose PR should be approved and merged")
       },
@@ -1684,6 +1903,117 @@ function buildTaskTools(connection) {
   ];
 }
 
+// src/tools/discovery-tools.ts
+import { tool as tool4 } from "@anthropic-ai/claude-agent-sdk";
+import { z as z4 } from "zod";
+function buildDiscoveryTools(connection, context) {
+  const spDescription = buildStoryPointDescription(context?.storyPoints);
+  return [
+    tool4(
+      "set_story_points",
+      "Set the story point estimate for this task. Use after understanding the scope of the work.",
+      { value: z4.number().describe(spDescription) },
+      async ({ value }) => {
+        try {
+          connection.updateTaskProperties({ storyPointValue: value });
+          return textResult(`Story points set to ${value}`);
+        } catch (error) {
+          return textResult(
+            `Failed to set story points: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      }
+    ),
+    tool4(
+      "set_task_tags",
+      "Assign tags to this task from the project's available tags. Use the tag IDs from the project tags list.",
+      {
+        tagIds: z4.array(z4.string()).describe("Array of tag IDs to assign")
+      },
+      async ({ tagIds }) => {
+        try {
+          connection.updateTaskProperties({ tagIds });
+          return textResult(`Tags assigned: ${tagIds.length} tag(s)`);
+        } catch (error) {
+          return textResult(
+            `Failed to set tags: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      }
+    ),
+    tool4(
+      "set_task_title",
+      "Update the task title to better reflect the planned work.",
+      {
+        title: z4.string().describe("The new task title")
+      },
+      async ({ title }) => {
+        try {
+          connection.updateTaskProperties({ title });
+          return textResult(`Task title updated to: ${title}`);
+        } catch (error) {
+          return textResult(
+            `Failed to update title: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      }
+    ),
+    tool4(
+      "list_icons",
+      "List available icons (default library + user-created). Returns icon IDs, names, and whether they're defaults. Call this FIRST before set_task_icon to check for existing matches.",
+      {},
+      async () => {
+        try {
+          const icons = await connection.listIcons();
+          return textResult(JSON.stringify(icons, null, 2));
+        } catch (error) {
+          return textResult(
+            `Failed to list icons: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      },
+      { annotations: { readOnlyHint: true } }
+    ),
+    tool4(
+      "set_task_icon",
+      "Assign an existing icon to this task by its ID. Use list_icons first to find a matching icon.",
+      {
+        iconId: z4.string().describe("The icon ID to assign")
+      },
+      async ({ iconId }) => {
+        try {
+          connection.updateTaskProperties({ iconId });
+          return textResult("Icon assigned to task.");
+        } catch (error) {
+          return textResult(
+            `Failed to set icon: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      }
+    ),
+    tool4(
+      "generate_task_icon",
+      "Generate a new SVG icon using AI and assign it to this task. Only use if no existing icon from list_icons is a good fit. Provide a concise visual description.",
+      {
+        prompt: z4.string().describe(
+          "Description of the icon to generate (e.g. 'minimal flat gear and wrench icon')"
+        ),
+        aspectRatio: z4.enum(["auto", "portrait", "landscape", "square"]).optional().describe("Icon aspect ratio, defaults to square")
+      },
+      async ({ prompt, aspectRatio }) => {
+        try {
+          const result = await connection.generateTaskIcon(prompt, aspectRatio ?? "square");
+          return textResult(`Icon generated and assigned: ${result.iconId}`);
+        } catch (error) {
+          return textResult(
+            `Failed to generate icon: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+        }
+      }
+    )
+  ];
+}
+
 // src/tools/index.ts
 function textResult(text) {
   return { content: [{ type: "text", text }] };
@@ -1693,11 +2023,30 @@ function imageBlock(data, mimeType) {
 }
 function createConveyorMcpServer(connection, config, context) {
   const commonTools = buildCommonTools(connection, config);
-  const isPackRunner = config.mode === "pm" && !!config.isAuto && !!context?.isParentTask;
-  const modeTools = config.mode === "pm" ? buildPmTools(connection, context?.storyPoints, { includePackTools: isPackRunner }) : buildTaskTools(connection);
+  const agentMode = context?.agentMode;
+  let modeTools;
+  switch (agentMode) {
+    case "building":
+      modeTools = buildTaskTools(connection);
+      break;
+    case "review":
+      modeTools = buildPmTools(connection, context?.storyPoints, {
+        includePackTools: !!context?.isParentTask
+      });
+      break;
+    case "auto":
+    case "discovery":
+    case "help":
+      modeTools = buildPmTools(connection, context?.storyPoints, { includePackTools: false });
+      break;
+    default:
+      modeTools = config.mode === "pm" ? buildPmTools(connection, context?.storyPoints, { includePackTools: false }) : buildTaskTools(connection);
+      break;
+  }
+  const discoveryTools = agentMode === "discovery" || agentMode === "auto" ? buildDiscoveryTools(connection, context) : [];
   return createSdkMcpServer({
     name: "conveyor",
-    tools: [...commonTools, ...modeTools]
+    tools: [...commonTools, ...modeTools, ...discoveryTools]
   });
 }
 
@@ -1707,84 +2056,159 @@ var IMAGE_ERROR_PATTERN = /Could not process image/i;
 var RETRY_DELAYS_MS = [6e4, 12e4, 18e4, 3e5];
 var PM_PLAN_FILE_TOOLS = /* @__PURE__ */ new Set(["Write", "Edit", "MultiEdit"]);
 var DESTRUCTIVE_CMD_PATTERN = /git\s+push\s+--force(?!\s*-with-lease)|git\s+reset\s+--hard|rm\s+-rf\s+\//;
+function handleDiscoveryToolAccess(toolName, input) {
+  if (PM_PLAN_FILE_TOOLS.has(toolName)) {
+    const filePath = String(input.file_path ?? input.path ?? "");
+    if (filePath.includes(".claude/plans/")) {
+      return { behavior: "allow", updatedInput: input };
+    }
+    return {
+      behavior: "deny",
+      message: "Discovery mode is read-only. File writes are restricted to plan files."
+    };
+  }
+  return { behavior: "allow", updatedInput: input };
+}
+function handleBuildingToolAccess(toolName, input) {
+  if (toolName === "Bash") {
+    const cmd = String(input.command ?? "");
+    if (DESTRUCTIVE_CMD_PATTERN.test(cmd)) {
+      return {
+        behavior: "deny",
+        message: "Destructive operation blocked. Use safer alternatives."
+      };
+    }
+  }
+  return { behavior: "allow", updatedInput: input };
+}
+function handleReviewToolAccess(toolName, input, isParentTask) {
+  if (isParentTask) {
+    return handleBuildingToolAccess(toolName, input);
+  }
+  if (PM_PLAN_FILE_TOOLS.has(toolName)) {
+    const filePath = String(input.file_path ?? input.path ?? "");
+    if (filePath.includes(".claude/plans/")) {
+      return { behavior: "allow", updatedInput: input };
+    }
+    return {
+      behavior: "deny",
+      message: "Review mode restricts file writes. Use bash to run tests and linting instead."
+    };
+  }
+  if (toolName === "Bash") {
+    const cmd = String(input.command ?? "");
+    if (DESTRUCTIVE_CMD_PATTERN.test(cmd)) {
+      return { behavior: "deny", message: "Destructive operation blocked in review mode." };
+    }
+  }
+  return { behavior: "allow", updatedInput: input };
+}
+function handleAutoToolAccess(toolName, input, hasExitedPlanMode, isParentTask) {
+  if (hasExitedPlanMode) {
+    return isParentTask ? handleReviewToolAccess(toolName, input, true) : handleBuildingToolAccess(toolName, input);
+  }
+  if (PM_PLAN_FILE_TOOLS.has(toolName)) {
+    const filePath = String(input.file_path ?? input.path ?? "");
+    if (filePath.includes(".claude/plans/")) {
+      return { behavior: "allow", updatedInput: input };
+    }
+    return {
+      behavior: "deny",
+      message: "You are in auto plan mode. File writes are restricted to plan files. Call ExitPlanMode when your plan is ready to start building."
+    };
+  }
+  return { behavior: "allow", updatedInput: input };
+}
 function buildCanUseTool(host) {
   const QUESTION_TIMEOUT_MS = 5 * 60 * 1e3;
   return async (toolName, input) => {
-    const isPackRunner = host.config.mode === "pm" && !!host.config.isAuto;
-    const isPmPlanning = host.config.mode === "pm" && host.activeMode === "planning";
-    const isPmActive = host.config.mode === "pm" && host.activeMode === "active";
-    if (isPackRunner) {
-      if (toolName === "Bash") {
-        const cmd = String(input.command ?? "");
-        if (DESTRUCTIVE_CMD_PATTERN.test(cmd)) {
+    if (toolName === "ExitPlanMode" && host.agentMode === "auto" && !host.hasExitedPlanMode) {
+      try {
+        const taskProps = await host.connection.getTaskProperties();
+        const missingProps = [];
+        if (!taskProps.plan?.trim()) missingProps.push("plan (save via update_task)");
+        if (!taskProps.storyPointId) missingProps.push("story points (use set_story_points)");
+        if (!taskProps.title || taskProps.title === "Untitled")
+          missingProps.push("title (use set_task_title)");
+        if (missingProps.length > 0) {
           return {
             behavior: "deny",
-            message: "Destructive operation blocked. Use safer alternatives."
+            message: [
+              "Cannot exit plan mode yet. Required task properties are missing:",
+              ...missingProps.map((p) => `- ${p}`),
+              "",
+              "Fill these in using MCP tools, then try ExitPlanMode again."
+            ].join("\n")
           };
         }
-      }
-      return { behavior: "allow", updatedInput: input };
-    }
-    if (isPmPlanning && PM_PLAN_FILE_TOOLS.has(toolName)) {
-      const filePath = String(input.file_path ?? input.path ?? "");
-      if (filePath.includes(".claude/plans/")) {
+        await host.connection.triggerIdentification();
+        host.hasExitedPlanMode = true;
+        const newMode = host.isParentTask ? "review" : "building";
+        host.pendingModeRestart = true;
+        if (host.onModeTransition) {
+          host.onModeTransition(newMode);
+        }
         return { behavior: "allow", updatedInput: input };
+      } catch (err) {
+        return {
+          behavior: "deny",
+          message: `Identification failed: ${err instanceof Error ? err.message : String(err)}. Fix the issue and try again.`
+        };
       }
-      return {
-        behavior: "deny",
-        message: "File write tools are only available for plan files in PM mode."
-      };
     }
-    if (isPmActive && toolName === "Bash") {
-      const cmd = String(input.command ?? "");
-      if (DESTRUCTIVE_CMD_PATTERN.test(cmd)) {
+    if (toolName === "AskUserQuestion") {
+      const questions = input.questions;
+      const requestId = randomUUID();
+      host.connection.emitStatus("waiting_for_input");
+      host.connection.sendEvent({
+        type: "tool_use",
+        tool: "AskUserQuestion",
+        input: JSON.stringify(input)
+      });
+      const answerPromise = host.connection.askUserQuestion(requestId, questions);
+      const timeoutPromise = new Promise((resolve2) => {
+        setTimeout(() => resolve2(null), QUESTION_TIMEOUT_MS);
+      });
+      const answers = await Promise.race([answerPromise, timeoutPromise]);
+      host.connection.emitStatus("running");
+      if (!answers) {
         return {
           behavior: "deny",
-          message: "Destructive operation blocked in active mode. Use safer alternatives."
+          message: "User did not respond to clarifying questions in time. Proceed with your best judgment."
         };
       }
+      return { behavior: "allow", updatedInput: { questions: input.questions, answers } };
+    }
+    switch (host.agentMode) {
+      case "discovery":
+        return handleDiscoveryToolAccess(toolName, input);
+      case "building":
+        return handleBuildingToolAccess(toolName, input);
+      case "review":
+        return handleReviewToolAccess(toolName, input, host.isParentTask);
+      case "auto":
+        return handleAutoToolAccess(toolName, input, host.hasExitedPlanMode, host.isParentTask);
+      default:
+        return { behavior: "allow", updatedInput: input };
     }
-    if (toolName !== "AskUserQuestion") {
-      return { behavior: "allow", updatedInput: input };
-    }
-    const questions = input.questions;
-    const requestId = randomUUID();
-    host.connection.emitStatus("waiting_for_input");
-    host.connection.sendEvent({
-      type: "tool_use",
-      tool: "AskUserQuestion",
-      input: JSON.stringify(input)
-    });
-    const answerPromise = host.connection.askUserQuestion(requestId, questions);
-    const timeoutPromise = new Promise((resolve2) => {
-      setTimeout(() => resolve2(null), QUESTION_TIMEOUT_MS);
-    });
-    const answers = await Promise.race([answerPromise, timeoutPromise]);
-    host.connection.emitStatus("running");
-    if (!answers) {
-      return {
-        behavior: "deny",
-        message: "User did not respond to clarifying questions in time. Proceed with your best judgment."
-      };
-    }
-    return { behavior: "allow", updatedInput: { questions: input.questions, answers } };
   };
 }
 function buildQueryOptions(host, context) {
   const settings = context.agentSettings ?? host.config.agentSettings ?? {};
-  const isPmActive = host.config.mode === "pm" && host.activeMode === "active";
-  const shouldSandbox = isPmActive && context.useSandbox !== false;
+  const mode = host.agentMode;
+  const isActiveMode = mode === "building" || mode === "review" || mode === "auto" && host.hasExitedPlanMode;
+  const shouldSandbox = host.config.mode === "pm" && isActiveMode && context.useSandbox !== false;
   const systemPromptText = buildSystemPrompt(
     host.config.mode,
     context,
     host.config,
     host.setupLog,
-    isPmActive ? "active" : "planning"
+    mode
   );
   const conveyorMcp = createConveyorMcpServer(host.connection, host.config, context);
-  const isPm = host.config.mode === "pm";
-  const pmDisallowedTools = isPm && !isPmActive ? ["TodoWrite", "TodoRead", "NotebookEdit"] : [];
-  const disallowedTools = [...settings.disallowedTools ?? [], ...pmDisallowedTools];
+  const isReadOnlyMode = mode === "discovery" || mode === "help" || mode === "auto" && !host.hasExitedPlanMode;
+  const modeDisallowedTools = isReadOnlyMode ? ["TodoWrite", "TodoRead", "NotebookEdit"] : [];
+  const disallowedTools = [...settings.disallowedTools ?? [], ...modeDisallowedTools];
   const settingSources = settings.settingSources ?? ["user", "project"];
   const hooks = {
     PostToolUse: [
@@ -1897,10 +2321,10 @@ function buildMultimodalPrompt(textPrompt, context, skipImages = false) {
 }
 async function runSdkQuery(host, context, followUpContent) {
   if (host.isStopped()) return;
-  const isPm = host.config.mode === "pm";
-  const isPackRunner = isPm && !!host.config.isAuto;
-  const isPmPlanning = isPm && host.activeMode === "planning" && !isPackRunner;
-  if (isPmPlanning) {
+  const mode = host.agentMode;
+  const isPmMode = host.config.mode === "pm";
+  const isDiscoveryLike = mode === "discovery" || mode === "help";
+  if (isDiscoveryLike) {
     host.snapshotPlanFiles();
   }
   const options = buildQueryOptions(host, context);
@@ -1910,14 +2334,14 @@ async function runSdkQuery(host, context, followUpContent) {
     const followUpImages = typeof followUpContent === "string" ? [] : followUpContent.filter(
       (b) => b.type === "image"
     );
-    const textPrompt = isPm ? `${buildInitialPrompt(host.config.mode, context, host.config.isAuto)}
+    const textPrompt = isPmMode ? `${buildInitialPrompt(host.config.mode, context, host.config.isAuto, mode)}
 
 ---
 
 The team says:
 ${followUpText}` : followUpText;
     let prompt;
-    if (isPm) {
+    if (isPmMode) {
       prompt = buildMultimodalPrompt(textPrompt, context);
       if (followUpImages.length > 0 && Array.isArray(prompt)) {
         prompt.push(...followUpImages);
@@ -1932,10 +2356,10 @@ ${followUpText}` : followUpText;
       options: { ...options, resume }
     });
     await runWithRetry(agentQuery, context, host, options);
-  } else if (isPmPlanning) {
+  } else if (isDiscoveryLike) {
     return;
   } else {
-    const initialPrompt = buildInitialPrompt(host.config.mode, context, host.config.isAuto);
+    const initialPrompt = buildInitialPrompt(host.config.mode, context, host.config.isAuto, mode);
     const prompt = buildMultimodalPrompt(initialPrompt, context);
     const agentQuery = query({
       prompt: host.createInputStream(prompt),
@@ -1943,7 +2367,7 @@ ${followUpText}` : followUpText;
     });
     await runWithRetry(agentQuery, context, host, options);
   }
-  if (isPmPlanning) {
+  if (isDiscoveryLike) {
     host.syncPlanFile();
   }
 }
@@ -1958,7 +2382,7 @@ async function runWithRetry(initialQuery, context, host, options) {
         );
       }
       const retryPrompt = buildMultimodalPrompt(
-        buildInitialPrompt(host.config.mode, context, host.config.isAuto),
+        buildInitialPrompt(host.config.mode, context, host.config.isAuto, host.agentMode),
         context,
         lastErrorWasImage
       );
@@ -1968,7 +2392,12 @@ async function runWithRetry(initialQuery, context, host, options) {
       });
     })();
     try {
-      const { retriable, resultSummary } = await processEvents(agentQuery, context, host);
+      const { retriable, resultSummary, modeRestart } = await processEvents(
+        agentQuery,
+        context,
+        host
+      );
+      if (modeRestart) return;
       if (!retriable || host.isStopped()) return;
       lastErrorWasImage = IMAGE_ERROR_PATTERN.test(resultSummary ?? "");
     } catch (error) {
@@ -1978,7 +2407,7 @@ async function runWithRetry(initialQuery, context, host, options) {
         context.claudeSessionId = null;
         host.connection.storeSessionId("");
         const freshPrompt = buildMultimodalPrompt(
-          buildInitialPrompt(host.config.mode, context, host.config.isAuto),
+          buildInitialPrompt(host.config.mode, context, host.config.isAuto, host.agentMode),
           context
         );
         const freshQuery = query({
@@ -2164,7 +2593,13 @@ var AgentRunner = class _AgentRunner {
   planSync;
   costTracker = new CostTracker();
   worktreeActive = false;
-  activeMode = "planning";
+  agentMode = null;
+  hasExitedPlanMode = false;
+  pendingModeRestart = false;
+  sessionIds = /* @__PURE__ */ new Map();
+  lastQueryModeRestart = false;
+  deferredStartConfig = null;
+  startCommandStarted = false;
   static MAX_SETUP_LOG_LINES = 50;
   constructor(config, callbacks) {
     this.config = config;
@@ -2175,6 +2610,18 @@ var AgentRunner = class _AgentRunner {
   get state() {
     return this._state;
   }
+  /**
+   * Resolve the effective AgentMode from explicit agentMode or legacy config flags.
+   * This is the single axis of behavior for all execution path decisions.
+   */
+  get effectiveAgentMode() {
+    if (this.agentMode) return this.agentMode;
+    if (this.config.mode === "pm") {
+      if (this.config.isAuto) return "auto";
+      return "discovery";
+    }
+    return "building";
+  }
   async setState(status) {
     this._state = status;
     this.connection.emitStatus(status);
@@ -2200,7 +2647,8 @@ var AgentRunner = class _AgentRunner {
     this.connection.onChatMessage(
       (message) => this.injectHumanMessage(message.content, message.files)
     );
-    this.connection.onModeChange((data) => this.handleModeChange(data.mode));
+    this.connection.onModeChange((data) => this.handleModeChange(data.agentMode));
+    this.connection.onRunStartCommand(() => this.runDeferredStartCommand());
     await this.setState("connected");
     this.connection.sendEvent({ type: "connected", taskId: this.config.taskId });
     this.startHeartbeat();
@@ -2239,6 +2687,9 @@ var AgentRunner = class _AgentRunner {
       return;
     }
     this.taskContext._runnerSessionId = randomUUID2();
+    if (this.taskContext.agentMode) {
+      this.agentMode = this.taskContext.agentMode;
+    }
     this.logEffectiveSettings();
     if (process.env.CODESPACES === "true") {
       unshallowRepo(this.config.workspaceDir);
@@ -2275,18 +2726,30 @@ var AgentRunner = class _AgentRunner {
       } catch {
       }
     }
-    const isPm = this.config.mode === "pm";
-    const isPackRunner = isPm && !!this.config.isAuto && !!this.taskContext.isParentTask;
-    if (isPackRunner) {
-      await this.setState("running");
-      await this.runQuerySafe(this.taskContext);
-      if (!this.stopped) await this.setState("idle");
-    } else if (isPm) {
-      await this.setState("idle");
-    } else {
-      await this.setState("running");
-      await this.runQuerySafe(this.taskContext);
-      if (!this.stopped) await this.setState("idle");
+    switch (this.effectiveAgentMode) {
+      case "discovery":
+      case "help":
+        await this.setState("idle");
+        break;
+      case "building":
+        await this.setState("running");
+        await this.runQuerySafe(this.taskContext);
+        if (!this.stopped) await this.setState("idle");
+        break;
+      case "review":
+        if (this.taskContext.isParentTask) {
+          await this.setState("running");
+          await this.runQuerySafe(this.taskContext);
+          if (!this.stopped) await this.setState("idle");
+        } else {
+          await this.setState("idle");
+        }
+        break;
+      case "auto":
+        await this.setState("running");
+        await this.runQuerySafe(this.taskContext);
+        if (!this.stopped) await this.setState("idle");
+        break;
     }
     await this.runCoreLoop();
     this.stopHeartbeat();
@@ -2294,8 +2757,13 @@ var AgentRunner = class _AgentRunner {
     this.connection.disconnect();
   }
   async runQuerySafe(context, followUp) {
+    this.lastQueryModeRestart = false;
     try {
       await runSdkQuery(this.asQueryHost(), context, followUp);
+      if (this.pendingModeRestart) {
+        this.lastQueryModeRestart = true;
+        this.pendingModeRestart = false;
+      }
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       this.connection.sendEvent({ type: "error", message });
@@ -2306,6 +2774,11 @@ var AgentRunner = class _AgentRunner {
   async runCoreLoop() {
     if (!this.taskContext) return;
     while (!this.stopped) {
+      if (this.lastQueryModeRestart) {
+        this.lastQueryModeRestart = false;
+        await this.handleAutoModeRestart();
+        continue;
+      }
       if (this._state === "idle") {
         const msg = await this.waitForUserContent();
         if (!msg) break;
@@ -2319,6 +2792,65 @@ var AgentRunner = class _AgentRunner {
       }
     }
   }
+  /**
+   * Handle auto mode transition after ExitPlanMode.
+   * Saves the current session, switches model/mode, and restarts with a fresh query.
+   */
+  async handleAutoModeRestart() {
+    if (!this.taskContext) return;
+    const currentModel = this.taskContext.model;
+    const currentSessionId = this.taskContext.claudeSessionId;
+    if (currentSessionId && currentModel) {
+      this.sessionIds.set(currentModel, currentSessionId);
+    }
+    const newMode = this.agentMode;
+    const isParentTask = !!this.taskContext.isParentTask;
+    const newModel = this.getModelForMode(newMode, isParentTask);
+    const resumeSessionId = newModel ? this.sessionIds.get(newModel) : null;
+    if (resumeSessionId) {
+      this.taskContext.claudeSessionId = resumeSessionId;
+    } else {
+      this.taskContext.claudeSessionId = null;
+      this.connection.storeSessionId("");
+    }
+    if (newModel) {
+      this.taskContext.model = newModel;
+    }
+    this.taskContext.agentMode = newMode;
+    this.connection.emitModeTransition({
+      fromMode: "auto",
+      toMode: newMode ?? "building"
+    });
+    this.connection.emitModeChanged(newMode);
+    this.connection.postChatMessage(
+      `Transitioning to **${newMode}** mode${newModel ? ` with ${newModel}` : ""}. Restarting session...`
+    );
+    try {
+      const freshContext = await this.connection.fetchTaskContext();
+      freshContext._runnerSessionId = this.taskContext._runnerSessionId;
+      freshContext.claudeSessionId = this.taskContext.claudeSessionId;
+      freshContext.agentMode = newMode;
+      if (newModel) freshContext.model = newModel;
+      this.taskContext = freshContext;
+    } catch {
+    }
+    await this.setState("running");
+    await this.runQuerySafe(this.taskContext);
+    if (!this.stopped && this._state !== "error") {
+      await this.setState("idle");
+    }
+  }
+  /**
+   * Get the appropriate model for a given mode.
+   * Building uses the builder model (Sonnet), Discovery/Review use PM model (Opus).
+   */
+  getModelForMode(mode, isParentTask) {
+    if (!this.taskContext) return null;
+    if (mode === "building" && !isParentTask) {
+      return this.taskContext.builderModel ?? this.taskContext.model;
+    }
+    return this.taskContext.pmModel ?? this.taskContext.model;
+  }
   async runSetupSafe() {
     await this.setState("setup");
     const ports = await loadForwardPorts(this.config.workspaceDir);
@@ -2340,7 +2872,8 @@ var AgentRunner = class _AgentRunner {
       await this.executeSetupConfig(config);
       const setupEvent = {
         type: "setup_complete",
-        previewPort: config.previewPort ?? void 0
+        previewPort: config.previewPort ?? void 0,
+        startCommandDeferred: this.deferredStartConfig !== null ? true : void 0
       };
       this.connection.sendEvent(setupEvent);
       await this.callbacks.onEvent(setupEvent);
@@ -2392,12 +2925,33 @@ The agent cannot start until this is resolved.`
       this.pushSetupLog("(exit 0)");
     }
     if (config.startCommand) {
-      this.pushSetupLog(`$ ${config.startCommand} &  (background)`);
-      runStartCommand(config.startCommand, this.config.workspaceDir, (stream, data) => {
-        this.connection.sendEvent({ type: "start_command_output", stream, data });
-      });
+      if (this.effectiveAgentMode === "auto") {
+        this.deferredStartConfig = config;
+        this.pushSetupLog(`[conveyor] startCommand deferred (auto mode)`);
+      } else {
+        this.pushSetupLog(`$ ${config.startCommand} &  (background)`);
+        runStartCommand(config.startCommand, this.config.workspaceDir, (stream, data) => {
+          this.connection.sendEvent({ type: "start_command_output", stream, data });
+        });
+      }
     }
   }
+  runDeferredStartCommand() {
+    if (!this.deferredStartConfig?.startCommand || this.startCommandStarted) return;
+    this.startCommandStarted = true;
+    const config = this.deferredStartConfig;
+    this.deferredStartConfig = null;
+    this.pushSetupLog(`$ ${config.startCommand} &  (background, deferred)`);
+    this.connection.sendEvent({ type: "start_command_started" });
+    runStartCommand(config.startCommand, this.config.workspaceDir, (stream, data) => {
+      this.connection.sendEvent({ type: "start_command_output", stream, data });
+    });
+    const setupEvent = {
+      type: "setup_complete",
+      previewPort: config.previewPort ?? void 0
+    };
+    this.connection.sendEvent(setupEvent);
+  }
   injectHumanMessage(content, files) {
     let messageContent;
     if (files?.length) {
@@ -2510,28 +3064,59 @@ ${f.content}
     }
   }
   asQueryHost() {
-    const getActiveMode = () => this.activeMode;
+    const getEffectiveAgentMode = () => this.effectiveAgentMode;
+    const getHasExitedPlanMode = () => this.hasExitedPlanMode;
+    const setHasExitedPlanMode = (val) => {
+      this.hasExitedPlanMode = val;
+    };
+    const getPendingModeRestart = () => this.pendingModeRestart;
+    const setPendingModeRestart = (val) => {
+      this.pendingModeRestart = val;
+    };
+    const getIsParentTask = () => !!this.taskContext?.isParentTask;
     return {
       config: this.config,
       connection: this.connection,
       callbacks: this.callbacks,
       setupLog: this.setupLog,
       costTracker: this.costTracker,
-      get activeMode() {
-        return getActiveMode();
+      get agentMode() {
+        return getEffectiveAgentMode();
       },
+      get isParentTask() {
+        return getIsParentTask();
+      },
+      get hasExitedPlanMode() {
+        return getHasExitedPlanMode();
+      },
+      set hasExitedPlanMode(val) {
+        setHasExitedPlanMode(val);
+      },
+      get pendingModeRestart() {
+        return getPendingModeRestart();
+      },
+      set pendingModeRestart(val) {
+        setPendingModeRestart(val);
+      },
+      sessionIds: this.sessionIds,
       isStopped: () => this.stopped,
       createInputStream: (prompt) => this.createInputStream(prompt),
       snapshotPlanFiles: () => this.planSync.snapshotPlanFiles(),
-      syncPlanFile: () => this.planSync.syncPlanFile()
+      syncPlanFile: () => this.planSync.syncPlanFile(),
+      onModeTransition: (newMode) => {
+        this.agentMode = newMode;
+      }
     };
   }
-  handleModeChange(mode) {
+  handleModeChange(newAgentMode) {
     if (this.config.mode !== "pm") return;
-    this.activeMode = mode;
-    this.connection.emitModeChanged(mode);
+    if (newAgentMode) {
+      this.agentMode = newAgentMode;
+    }
+    const effectiveMode = this.effectiveAgentMode;
+    this.connection.emitModeChanged(effectiveMode);
     this.connection.postChatMessage(
-      `Mode switched to **${mode}**${mode === "active" ? " \u2014 I now have direct coding access." : " \u2014 back to planning only."}`
+      `Mode switched to **${effectiveMode}**${effectiveMode === "building" ? " \u2014 I now have direct coding access." : ""}`
     );
   }
   stop() {
@@ -2788,6 +3373,7 @@ var ProjectRunner = class {
           CONVEYOR_MODE: mode,
           CONVEYOR_WORKSPACE: workDir,
           CONVEYOR_USE_WORKTREE: "false",
+          CONVEYOR_AGENT_MODE: isAuto ? "auto" : "",
           CONVEYOR_IS_AUTO: isAuto ? "true" : "false",
           CONVEYOR_USE_SANDBOX: useSandbox === false ? "false" : "true"
         },
@@ -2967,4 +3553,4 @@ export {
   ProjectRunner,
   FileCache
 };
-//# sourceMappingURL=chunk-GVE6FQ75.js.map
+//# sourceMappingURL=chunk-Y4TAVPZV.js.map