@saadnvd1/agent-os 0.3.519 → 0.3.520

package/README.md

@@ -539,6 +539,21 @@ and **Usage → Compare** splits cost into planned and not. When the plan step
 finishes, the orchestrator gets one event with the plan file's path and a
 3-5 line summary; the handoff to implementation stays automatic.
 
+**Plan only.** A task started with `plan_only` (`start_task`'s `plan_only`,
+`aos task --plan-only`, or `plan_only: true` on `POST /api/tasks`) writes its
+plan on the planning model and then stops: no model switch, no implement
+prompt, even when one model does every role. It sits in a **Plan ready**
+state (`plan_phase` `awaiting`, stored on the task, so it survives a restart)
+that isn't blocked, doesn't count as needing you, and holds no agent process
+(its worker is released; the conversation resumes on approval). The
+orchestrator gets one event with the plan's path, a summary and that the task
+is waiting. **Approve** on the task row (plan viewable there), `POST
+/api/tasks/<id>/approve-plan`, or the orchestrator's `approve_plan(task,
+message?)` continues it on the implementation model, once; a message amends
+the plan and is recorded on the task's brief as a scope change, so the review
+judges against it. Reject with **Drop**. A chat task on this machine only; it
+can't move until approved.
+
 **Per task.** The task draft has a **Model** chip ("Routed by role", or one
 model); `POST /api/tasks` and the orchestrator's `start_task` take `model`, as
 `"provider/model"` for the task's own roles or a map such as

package/app/api/bus/spawn/route.ts

@@ -29,12 +29,15 @@ export async function POST(request: NextRequest) {
       on,
       after,
       view,
+      planOnly,
       from,
     } = await request.json();
     const startedBy = orchestratorFrom(from);
     const given = typeof name === "string" ? name : undefined;
     if (after !== undefined && mode !== "task")
       throw new Error("--after works for tasks only");
+    if (planOnly !== undefined && mode !== "task")
+      throw new Error("--plan-only works for tasks only");
     if (mode === "task") {
       const task = {
         projectId: findProject(String(project ?? "")).id,
@@ -43,6 +46,7 @@ export async function POST(request: NextRequest) {
         model,
         hostId: on ? hostIdNamed(String(on)) : undefined,
         view: startView(view),
+        planOnly: planOnly === true ? true : undefined,
         startedBy,
       };
       const out = await startOrQueue(

package/app/api/tasks/[id]/approve-plan/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { approvePlanNow } from "@/lib/models/plan-step";
+
+// Approves a plan-only task's plan: it continues on the implementation
+// model. An optional message amends the plan (recorded as a scope change).
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const body = await request.json().catch(() => ({}));
+    const message =
+      typeof body?.message === "string" && body.message.trim()
+        ? body.message.trim().slice(0, 8000)
+        : undefined;
+    const out = await approvePlanNow((await params).id, message);
+    return NextResponse.json({ success: true, model: out.ref });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 409 });
+  }
+}

package/app/api/tasks/route.ts

@@ -36,6 +36,7 @@ export async function POST(request: NextRequest) {
       view,
       plan,
       plan_reason,
+      plan_only,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -48,6 +49,7 @@ export async function POST(request: NextRequest) {
       // Checked now, so a queued task can't fail on it later.
       model: parseOverride(model) ?? undefined,
       plan: typeof plan === "boolean" ? plan : undefined,
+      planOnly: plan_only === true ? true : undefined,
       planReason:
         typeof plan_reason === "string" && plan_reason.trim()
           ? plan_reason.trim().slice(0, 200)

package/components/Tasks/TaskRow.tsx

@@ -10,7 +10,13 @@ import {
 import { Button } from "@/components/ui/button";
 import type { TaskView } from "@/lib/tasks";
 import { isFinished } from "@/lib/tasks/state";
-import { useArmTask, useDropTask, useSignOffTask } from "@/data/tasks";
+import {
+  useApprovePlan,
+  useArmTask,
+  useDropTask,
+  useSignOffTask,
+} from "@/data/tasks";
+import { Markdown } from "@/components/Chat/Markdown";
 import { tmuxAttachActions } from "@/stores/tmuxAttach";
 import { tasksUiActions } from "@/stores/tasksUi";
 import { cn } from "@/lib/utils";
@@ -23,6 +29,8 @@ export function TaskRow({ task }: { task: TaskView }) {
   const signOff = useSignOffTask();
   const drop = useDropTask();
   const arm = useArmTask();
+  const approve = useApprovePlan();
+  const [showPlan, setShowPlan] = useState(false);
   const [confirmDrop, setConfirmDrop] = useState(false);
   const [moveError, setMoveError] = useState<string | null>(null);
   const live = !isFinished(task.state);
@@ -30,6 +38,7 @@ export function TaskRow({ task }: { task: TaskView }) {
     signOff.error?.message ||
     drop.error?.message ||
     arm.error?.message ||
+    approve.error?.message ||
     moveError ||
     task.hostError;
   const settingUp = live && task.setup?.status === "running";
@@ -148,6 +157,26 @@ export function TaskRow({ task }: { task: TaskView }) {
               {task.armed ? "Armed" : "Arm merge"}
             </Button>
           )}
+          {task.state === "plan-ready" && (
+            <>
+              <Button
+                size="sm"
+                variant="outline"
+                aria-expanded={showPlan}
+                onClick={() => setShowPlan((v) => !v)}
+              >
+                {showPlan ? "Hide plan" : "View plan"}
+              </Button>
+              <Button
+                size="sm"
+                className="h-11 md:h-8"
+                disabled={approve.isPending}
+                onClick={() => approve.mutate({ id: task.id })}
+              >
+                {approve.isPending ? "Approving..." : "Approve"}
+              </Button>
+            </>
+          )}
           {task.state === "review" && (
             <Button
               size="sm"
@@ -159,6 +188,22 @@ export function TaskRow({ task }: { task: TaskView }) {
           )}
         </div>
       )}
+      {live && task.state === "plan-ready" && showPlan && (
+        <div className="bg-foreground/[0.04] max-h-80 overflow-y-auto rounded-lg p-3 text-sm">
+          {task.plan?.text ? (
+            <Markdown text={task.plan.text} />
+          ) : (
+            <p className="text-muted-foreground text-xs">
+              No plan file was written.
+            </p>
+          )}
+          {task.plan?.truncated && (
+            <p className="text-muted-foreground mt-2 font-mono text-[11px]">
+              Shortened; the whole plan is {task.plan.path} in the worktree.
+            </p>
+          )}
+        </div>
+      )}
       {error && <p className="text-destructive text-xs">{error}</p>}
     </div>
   );

package/components/Tasks/task-state-labels.ts

@@ -8,6 +8,7 @@ export const TASK_STATE: Record<TaskState, { label: string; tone: string }> = {
     tone: "text-amber-600 dark:text-amber-400",
   },
   blocked: { label: "Blocked", tone: "text-amber-600 dark:text-amber-400" },
+  "plan-ready": { label: "Plan ready", tone: "text-primary" },
   review: { label: "Ready for review", tone: "text-primary" },
   "checks-failing": { label: "Checks failing", tone: "text-destructive" },
   exited: { label: "Agent exited", tone: "text-amber-600 dark:text-amber-400" },

package/data/tasks/index.ts

@@ -85,6 +85,18 @@ export function useDropTask() {
   );
 }
 
+export function useApprovePlan() {
+  return useTaskMutation(async (input: { id: string; message?: string }) =>
+    json(
+      await fetch(`/api/tasks/${input.id}/approve-plan`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: input.message }),
+      })
+    )
+  );
+}
+
 export function useResumeTask() {
   return useTaskMutation(async (input: { id: string; force?: boolean }) =>
     json(

package/lib/db/migrations.ts

@@ -1739,6 +1739,21 @@ const migrations: Migration[] = [
       );
     },
   },
+  {
+    id: 75,
+    name: "plan_only_tasks",
+    up: (db) => {
+      // plan_only: 1 for a task that stops after its plan and waits for
+      // approval (plan_phase 'awaiting'); queued tasks keep it until they start.
+      const has = (table: string) =>
+        (
+          db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+        ).some((c) => c.name === "plan_only");
+      for (const table of ["sessions", "task_queue"])
+        if (!has(table))
+          db.exec(`ALTER TABLE ${table} ADD COLUMN plan_only INTEGER`);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/db/types.ts

@@ -19,7 +19,9 @@ export interface Session {
   // A task's own models: "provider/model", or JSON of role to one.
   model_overrides?: string | null;
   // A task's plan step: planning on the planning model, then implementing.
-  plan_phase?: "planning" | "implementing" | null;
+  // 'awaiting': a plan-only task's plan is written; it waits for approval.
+  plan_phase?: "planning" | "awaiting" | "implementing" | null;
+  plan_only?: number | null;
   // The orchestrator session that started this one; null for a person.
   started_by?: string | null;
   // 1 planned, 0 no plan, null not stated; why, in the starter's words.

package/lib/lumifyhub/lists.ts

@@ -26,6 +26,7 @@ export function cardTargetFor(state: TaskState | "queued"): CardTarget {
       return "todo";
     case "working":
     case "needs-input":
+    case "plan-ready":
     case "blocked":
     case "moving":
       return "in_progress";

package/lib/models/plan-step.ts

@@ -19,20 +19,28 @@ import {
 } from "./resolve";
 import { ANTHROPIC } from "./roles";
 import { queueEvent } from "../orchestrator/events";
+import { addNote } from "../orchestrator/notes";
+import { amendBrief, amendmentsOf } from "../orchestrator/amendments";
 
 export const PLAN_FILE = ".agentos/plan.md";
 
-export function planPrompt(task: string): string {
+export function planPrompt(task: string, only = false): string {
+  const after = only
+    ? "it waits for approval before anything is implemented, so don't ask for it"
+    : "the implementation model takes over this conversation next and follows it";
   return `${task}
 
 ---
-Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. End the turn once the plan is written: the implementation model takes over this conversation next and follows it.`;
+Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. End the turn once the plan is written: ${after}.`;
 }
 
-export function implementPrompt(planned: boolean): string {
-  return planned
+export function implementPrompt(planned: boolean, amendment?: string): string {
+  const base = planned
     ? `The plan is in \`${PLAN_FILE}\`. Implement it now, finishing the task as its instructions above say. Where the plan turns out wrong, do what's right and say so.`
     : `No plan was written to \`${PLAN_FILE}\`. Plan briefly, then implement the task, finishing it as its instructions above say.`;
+  return amendment
+    ? `${base}\n\nThe plan was approved with this change, which is now part of the task's scope:\n${amendment}`
+    : base;
 }
 
 // The worktree's plan folder, kept out of git by its own .gitignore.
@@ -72,7 +80,7 @@ export function planSummary(text: string, max = 5): string[] {
 }
 
 // Tells the orchestrator that started a task its plan is written, once.
-function announcePlan(s: Session, ref: string): void {
+function announcePlan(s: Session, ref: string | null): void {
   if (!s.started_by && !s.held_by_device) return;
   const workspaceId = sessionWorkspace(s);
   // A task held for another machine's orchestrator can't reach it: the line
@@ -80,10 +88,13 @@ function announcePlan(s: Session, ref: string): void {
   if (!s.held_by_device && !workspaceId) return;
   if (!s.worktree_path) return;
   const file = path.join(s.worktree_path, PLAN_FILE);
-  let head = `Task "${s.name}": no plan file was written; implementing on ${ref} anyway.`;
+  const next = ref
+    ? `implementing on ${ref}`
+    : "waiting for approval, not implementing (approve_plan to go ahead, drop to reject)";
+  let head = `Task "${s.name}": no plan file was written; ${next}${ref ? " anyway" : ""}.`;
   try {
     const summary = planSummary(fs.readFileSync(file, "utf8"));
-    head = `Task "${s.name}": plan written to ${file}; implementing on ${ref}.`;
+    head = `Task "${s.name}": plan written to ${file}; ${next}.`;
     if (summary.length) head += `\n${summary.map((l) => `- ${l}`).join("\n")}`;
   } catch {
     // No plan file: the line says so.
@@ -101,56 +112,129 @@ function announcePlan(s: Session, ref: string): void {
 export const implementMessageId = (sessionId: string) =>
   `implement-${sessionId}`;
 
-// Called when a chat goes idle. A task whose plan turn has ended (it has a
-// recorded plan turn) moves to implementing, once, and the implementation
-// message is queued under a fixed id, which a restart sends rather than
-// repeats.
-export async function handoffAfterPlan(
-  sessionId: string,
-  send: (sessionId: string, id: string) => Promise<void>
-): Promise<boolean> {
-  const planned = db
-    .prepare(
-      `SELECT 1 FROM chat_turns WHERE session_id = ? AND role = 'plan' LIMIT 1`
-    )
-    .get(sessionId);
-  if (!planned) return false;
-  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
+type Send = (sessionId: string, id: string) => Promise<void>;
+
+function getSession(sessionId: string): Session | undefined {
+  return db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
     | Session
     | undefined;
-  if (s?.plan_phase !== "planning" || !s.worktree_path) return false;
+}
+
+// Planning (or, once approved, awaiting) becomes implementing, once: the
+// phase, the model and the message in one go, so a restart part-way finds
+// either none of them or all, and sends the message on the new model. The
+// message goes under a fixed id, which a restart sends rather than repeats.
+async function startImplementing(
+  s: Session,
+  from: "planning" | "awaiting",
+  send: Send,
+  amendment?: string
+): Promise<string | null> {
+  const sessionId = s.id;
   const routed = resolveRole("implement", {
     workspaceId: sessionWorkspace(s),
     override: taskOverride(s),
   });
   const id = implementMessageId(sessionId);
-  // The phase, the model and the message in one go: a restart part-way
-  // finds either none of them or all, and sends the message on the new model.
   const claimed = db.transaction(() => {
     const changed = db
       .prepare(
         `UPDATE sessions SET plan_phase = 'implementing'
-         WHERE id = ? AND plan_phase = 'planning' AND task_status = 'running'`
+         WHERE id = ? AND plan_phase = ? AND task_status = 'running'`
       )
-      .run(sessionId).changes;
+      .run(sessionId, from).changes;
     if (!changed) return false;
     setSessionModel(sessionId, routed);
     enqueue(sessionId, {
       id,
       text: implementPrompt(
-        fs.existsSync(path.join(s.worktree_path!, PLAN_FILE))
+        fs.existsSync(path.join(s.worktree_path!, PLAN_FILE)),
+        amendment
       ),
       origin: { kind: "decision", label: "Plan step" },
     });
     return true;
   })();
-  if (!claimed) return false;
+  if (!claimed) return null;
+  if (from === "planning") {
+    try {
+      announcePlan(s, routed.ref);
+    } catch (e) {
+      console.error("plan-done event failed:", e);
+    }
+  }
+  await applySessionModel(sessionId, s.model_provider ?? ANTHROPIC, routed);
+  await send(sessionId, id);
+  return routed.ref;
+}
+
+// Called when a chat goes idle. A task whose plan turn has ended (it has a
+// recorded plan turn) moves to implementing, once; a plan-only task instead
+// waits for approval (approvePlan), holding no agent process.
+export async function handoffAfterPlan(
+  sessionId: string,
+  send: Send
+): Promise<boolean> {
+  const planned = db
+    .prepare(
+      `SELECT 1 FROM chat_turns WHERE session_id = ? AND role = 'plan' LIMIT 1`
+    )
+    .get(sessionId);
+  if (!planned) return false;
+  const s = getSession(sessionId);
+  if (s?.plan_phase !== "planning" || !s.worktree_path) return false;
+  if (!s.plan_only)
+    return (await startImplementing(s, "planning", send)) !== null;
+  const waiting = db
+    .prepare(
+      `UPDATE sessions SET plan_phase = 'awaiting'
+       WHERE id = ? AND plan_phase = 'planning' AND task_status = 'running'`
+    )
+    .run(sessionId).changes;
+  if (!waiting) return false;
   try {
-    announcePlan(s, routed.ref);
+    announcePlan(s, null);
   } catch (e) {
     console.error("plan-done event failed:", e);
   }
-  await applySessionModel(sessionId, s.model_provider ?? ANTHROPIC, routed);
-  await send(sessionId, id);
+  // The worker has nothing left to do: it ends at this turn boundary, and
+  // the next message (an approval, or a revision) starts one that resumes.
+  try {
+    await (await import("../chat/runner")).retireChat(sessionId);
+  } catch (e) {
+    console.error(`Releasing the worker of ${sessionId} failed:`, e);
+  }
   return true;
 }
+
+// approvePlan, sending through the chat runner (imported when needed: it
+// imports this file).
+export async function approvePlanNow(sessionId: string, message?: string) {
+  const { sendQueuedNow } = await import("../chat/runner");
+  return approvePlan(sessionId, message, (id, m) => sendQueuedNow(id, m));
+}
+
+// Approves a waiting plan-only task: implementation starts on the
+// implementation model, once. A message amends the plan and is recorded on
+// the task's brief as a scope change, before implementing, so its review
+// judges against it.
+export async function approvePlan(
+  sessionId: string,
+  message: string | undefined,
+  send: Send
+): Promise<{ ref: string; amendments: number }> {
+  const s = getSession(sessionId);
+  if (!s || s.plan_phase !== "awaiting" || s.task_status !== "running")
+    throw new Error(
+      `${s?.name ?? "That task"} isn't waiting for plan approval`
+    );
+  const text = message?.trim() || undefined;
+  const workspaceId = sessionWorkspace(s);
+  if (text && workspaceId) {
+    amendBrief(workspaceId, s.id, text);
+    addNote(workspaceId, `Plan approved with a change for ${s.name}: ${text}`);
+  }
+  const ref = await startImplementing(s, "awaiting", send, text);
+  if (!ref) throw new Error(`${s.name} isn't waiting for plan approval`);
+  return { ref, amendments: amendmentsOf(s.id).length };
+}

package/lib/models/roles.ts

@@ -97,5 +97,7 @@ export function sessionRole(session: {
   // Work an orchestrator started is implementation, not a person's session.
   if (!session.task_status)
     return session.started_by ? "implement" : "interactive";
-  return session.plan_phase === "planning" ? "plan" : "implement";
+  return session.plan_phase === "planning" || session.plan_phase === "awaiting"
+    ? "plan"
+    : "implement";
 }

package/lib/orchestrator/act.ts

@@ -33,6 +33,8 @@ import { treeOrder } from "../stacks/tree";
 import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { amendBrief, amendmentsOf } from "./amendments";
+import type { Session } from "../db";
+import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
@@ -99,9 +101,12 @@ export async function startTask(
     after?: string;
     model?: ModelOverride;
     plan?: boolean;
+    planOnly?: boolean;
     planReason?: string;
   } = {}
 ): Promise<string> {
+  if (opts.planOnly && opts.plan === false)
+    throw new Error("plan_only implies plan; pass plan true");
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
@@ -121,6 +126,7 @@ export async function startTask(
       view,
       model,
       plan: opts.plan,
+      planOnly: opts.planOnly,
       planReason: opts.planReason,
       startedBy,
       baseBranch: opts.base || undefined,
@@ -140,6 +146,7 @@ export async function startTask(
             view,
             model,
             plan: opts.plan,
+            planOnly: opts.planOnly,
             planReason: opts.planReason,
             startedBy,
           }),
@@ -151,11 +158,26 @@ export async function startTask(
     return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}. It starts by itself; you'll get an event when it does.`;
   }
   const task = out.started;
+  const planOnlyNote = opts.planOnly
+    ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
+    : "";
   const skipped =
-    opts.plan && task.plan_phase !== "planning"
+    opts.plan && !opts.planOnly && task.plan_phase !== "planning"
       ? ` Plan step skipped: ${view === "terminal" ? "a terminal task has none" : "planning and implementation use the same model"}.`
       : "";
-  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}`;
+  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}${planOnlyNote}`;
+}
+
+// The orchestrator approves a plan-only task's plan; a message amends it.
+export async function approveTaskPlan(
+  task: Session,
+  message?: string
+): Promise<string> {
+  const out = await approvePlanNow(task.id, message);
+  const amended = message
+    ? ` Recorded as scope change ${out.amendments} on its brief: its review judges against it.`
+    : "";
+  return `Approved the plan of ${task.name}: implementing on ${out.ref}.${amended}`;
 }
 
 export async function startSession(

package/lib/orchestrator/brief.ts

@@ -41,6 +41,7 @@ You may act without asking on anything inside this workspace that's additive or
 Before you start work, decide what it needs, and hand it to the cheapest model that can do it.
 - Small and clear (a known change, a few files, nothing to discover): start_task with plan false and a plan_reason saying why. Write the steps into the prompt yourself, from what Saad or the card said; do not read code in your own context to do it.
 - Big, unclear or cross-cutting (many files, a design choice, unknown ground): start_task with plan true and a plan_reason. The planning model writes the plan, then the implementation model carries it out; you get one event with the plan file's path and a short summary when it is written.
+- Saad (or the card) says plan only, or you want to see a plan before any code is written: start_task with plan_only true (it implies plan true). It writes the plan and then stops: no implementation model, no implement prompt. You get one event with the plan file's path and a short summary saying it is waiting for approval. While it waits it isn't blocked and isn't idle; read the plan, then \`approve_plan\` (a message amends the plan and is recorded as a scope change, so the review judges against it) or \`drop\` it.
 - Not in a repository (research, a document, a machine task): start_session, which runs on the implementation model, with the steps in the prompt.
 - Implementation on Opus only when the work needs deep reasoning (a subtle concurrency or security change, say). Pass model and say why. Sonnet is the default.
 
@@ -102,7 +103,8 @@ Reading:
 Acting:
 - \`${TOOL_NAMES.send}\` (session, message, scope_change?): message a session; it arrives as its next prompt. scope_change records it on the task's brief for its review.
 - \`${TOOL_NAMES.message_orchestrator}\` (workspace, message): message another workspace's orchestrator, the only thing you reach outside this workspace. Use it to hand over a bug or ask for something in its projects; it decides what to do there.
-- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.approve_plan}\` (task, message?): continue a plan_only task whose plan is ready; it implements on the implementation model, once. message amends the plan and is recorded on the task's brief as a scope change. Reject a plan with drop.
 - \`${TOOL_NAMES.set_task_model}\` (task, model, message?): move a paused task to another model and carry on in the same conversation and worktree; it keeps that model from then on. Only when Saad asks.
 - \`${TOOL_NAMES.start_session}\` (project, prompt, name?, view?, model?): a session without a worktree or PR, a chat unless view is terminal. It runs on the implementation model (Sonnet) unless you pass model; use it for work outside a repository, with the steps in the prompt.
 - \`${TOOL_NAMES.quick_change}\` (project, name): a worktree and branch cut from the project's default branch for a small, low-risk edit you make yourself: a typo, a config value, a one-file fix. It returns the worktree's path; edit there with Write and Edit, and run git there only as \`git -C <path> <status|diff|log|show|add|rm|mv|restore|reset>\`. Anything that needs real work, tests or a long investigation is a task: start_task. At most a few open at once.

package/lib/orchestrator/conditions.ts

@@ -135,6 +135,7 @@ function sessionConditions(
     shouldPR &&
     !pr &&
     !finished &&
+    !f.plan?.awaiting &&
     f.status !== "running" &&
     idleFor >= IDLE_NO_PR_MS
   )

package/lib/orchestrator/describe.ts

@@ -39,7 +39,7 @@ function sessionLine(f: SessionFacts): string {
   }
   if (f.plan)
     parts.push(
-      `${f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
+      `${f.plan.awaiting ? "plan ready, awaiting your approve_plan" : f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
     );
   if (f.stack) {
     const card = f.stack.ticket ? ` ${f.stack.ticket}` : "";

package/lib/orchestrator/facts.ts

@@ -50,7 +50,12 @@ export interface SessionFacts {
   // A quick change the orchestrator makes itself (quick.ts): no agent.
   quick?: boolean;
   // The orchestrator's call on a plan step, with its reason, when stated.
-  plan?: { planned: boolean; reason: string | null } | null;
+  plan?: {
+    planned: boolean;
+    reason: string | null;
+    // A plan-only task's plan is written; it waits for approve_plan.
+    awaiting?: boolean;
+  } | null;
   task: {
     state: TaskState;
     pr: TaskPR | null;
@@ -344,7 +349,11 @@ export async function sessionFacts(
         plan:
           s.plan_decided == null
             ? null
-            : { planned: !!s.plan_decided, reason: s.plan_reason ?? null },
+            : {
+                planned: !!s.plan_decided,
+                reason: s.plan_reason ?? null,
+                awaiting: s.plan_phase === "awaiting",
+              },
         task,
         stack: stackOf(s.id),
       };

package/lib/orchestrator/serve.ts

@@ -2,6 +2,7 @@ import { resumeOnModel } from "../models/resume";
 import { workspaceTask } from "./targets";
 import { getWorkspace } from "../workspaces";
 import {
+  approveTaskPlan,
   done,
   drop,
   moveTaskTo,
@@ -48,6 +49,7 @@ const ACTING = new Set<ToolName>([
   "land",
   "drop",
   "move",
+  "approve_plan",
   "stop",
   "done",
   "review",
@@ -114,9 +116,15 @@ export async function runTool(
         after: a.after,
         model: a.model,
         plan: a.plan,
+        planOnly: a.plan_only,
         planReason: a.plan_reason,
       });
     }
+    case "approve_plan": {
+      const a = p(tool, raw);
+      const task = workspaceTask(w, a.task);
+      return approveTaskPlan(task, a.message);
+    }
     case "set_task_model": {
       const a = p(tool, raw);
       const task = workspaceTask(w, a.task);

package/lib/orchestrator/tool-names.ts

@@ -22,6 +22,7 @@ export const TOOL_NAMES = {
   stack: name("stack"),
   stack_status: name("stack_status"),
   land: name("land"),
+  approve_plan: name("approve_plan"),
   drop: name("drop"),
   move: name("move"),
   stop: name("stop"),

package/lib/orchestrator/tool-schemas.ts

@@ -121,6 +121,12 @@ export const TOOL_SHAPES = {
       .describe(
         "Your decision for this job: true to plan first on the planning model, then implement on the implementation model; false to skip the plan and put the steps in the prompt yourself"
       ),
+    plan_only: z
+      .boolean()
+      .optional()
+      .describe(
+        "true: write the plan on the planning model, then stop and wait; implementation starts only when you approve_plan it (drop rejects it). Implies plan true"
+      ),
     plan_reason: z
       .string()
       .trim()
@@ -192,6 +198,18 @@ export const TOOL_SHAPES = {
   },
   stack_status: { id: stackId },
   land: { id: stackId },
+  approve_plan: {
+    task,
+    message: z
+      .string()
+      .trim()
+      .min(1)
+      .max(8000)
+      .optional()
+      .describe(
+        "Amends the plan: recorded on the task's brief as a scope change, so its review judges the PR against it. Only for a change Saad made"
+      ),
+  },
   drop: { task, reason: z.string().trim().min(1).max(2000) },
   move: {
     task,

package/lib/orchestrator/tools.ts

@@ -62,7 +62,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   message_orchestrator:
     "Message another workspace's orchestrator, by workspace name; never any other session there. It arrives as its next prompt, marked as from you and fenced as untrusted.",
   start_task:
-    "Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). With after (a task's id or name, or \"any\"), or over the workspace's running task limit, it's queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason: plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.",
+    "Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). With after (a task's id or name, or \"any\"), or over the workspace's running task limit, it's queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.",
   set_task_model:
     'Resume a paused task on another model ("provider/model", or a map of role to one), keeping its conversation and worktree; it\'s told to carry on (or message). Refused mid-turn.',
   start_session:
@@ -75,6 +75,8 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     "Run a LumifyHub board's open cards as stacked tasks (each start braked), or with plan_only just show the plan.",
   stack_status: "One stack's items, PRs and progress.",
   land: "Merge a whole stack bottom-up, each PR through the sign-off gates at its current head.",
+  approve_plan:
+    'Approve the plan of a plan_only task that is waiting ("plan ready"): it continues on the implementation model, once. An optional message amends the plan and is recorded on the task\'s brief as a scope change. Reject a plan with drop.',
   drop: "Reject a task: close its PR and remove its worktree. A task still waiting in the queue is removed by its id. Logged with the reason.",
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
   stop: "Stop a session's agent mid-turn, even while it's thinking, keeping its conversation, worktree and branch; your next message runs as its next turn.",

package/lib/tasks/index.ts

@@ -100,6 +100,8 @@ export interface TaskView {
   // plan step (lib/models).
   model?: string;
   planning?: boolean;
+  // A plan-only task's plan is written and waits for approval.
+  planReady?: boolean;
   // What its starter decided about a plan step, and why; null if unstated.
   // Its plan: ready to read or approve, with a title and capped text.
   plan?: TaskPlan | null;
@@ -128,6 +130,8 @@ export async function createTask(opts: {
   plan?: boolean;
   // Why the starter chose to plan or not: shown on the task's card.
   planReason?: string | null;
+  // Stop after the plan and wait for approval (implies plan).
+  planOnly?: boolean;
   // The orchestrator session that started it (null: a person).
   startedBy?: string | null;
   // Started from this LumifyHub card, which the task then moves.
@@ -198,6 +202,8 @@ async function startTask(
   const hostId = opts.hostId ?? project.host_id;
   const view = opts.view ?? DEFAULT_START_VIEW;
   if (isRemoteHost(hostId)) {
+    if (opts.planOnly)
+      throw new Error("A plan-only task runs on this machine for now");
     if (opts.base || opts.cardId)
       throw new Error(
         "Stacked and card tasks run on this machine only for now"
@@ -216,11 +222,18 @@ async function startTask(
 
   if (opts.baseBranch !== undefined && !isBranchName(opts.baseBranch))
     throw new Error(`"${opts.baseBranch}" isn't a branch name`);
+  if (opts.planOnly && opts.plan === false)
+    throw new Error(
+      "planOnly implies plan; it can't be combined with plan false"
+    );
+  if (opts.planOnly && view !== "chat")
+    throw new Error("A plan-only task needs a chat, not a terminal");
   const routing = taskRouting(
     project.workspace_id,
     view,
     opts.model,
-    opts.plan
+    opts.plan,
+    opts.planOnly
   );
   const projectPath = expandHome(project.working_directory);
   const naming = await nameFor(prompt, projectPath, opts.name);
@@ -266,7 +279,7 @@ async function startTask(
   // Everything the launch needs is on the row, so a restart can resume it.
   db.prepare(
     `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', setup_status = 'running', name_source = ?, view = ?,
-       model_provider = ?, model_overrides = ?, plan_phase = ?,
+       model_provider = ?, model_overrides = ?, plan_phase = ?, plan_only = ?,
        plan_decided = ?, plan_reason = ?, started_by = ? WHERE id = ?`
   ).run(
     prompt,
@@ -280,7 +293,8 @@ async function startTask(
     routing.first.provider.id === ANTHROPIC ? null : routing.first.provider.id,
     routing.override ? JSON.stringify(routing.override) : null,
     routing.plan ? "planning" : null,
-    opts.plan === undefined ? null : opts.plan ? 1 : 0,
+    routing.planOnly ? 1 : null,
+    routing.planOnly ? 1 : opts.plan === undefined ? null : opts.plan ? 1 : 0,
     opts.planReason?.trim() || null,
     opts.startedBy ?? null,
     id
@@ -356,8 +370,10 @@ export async function taskView(session: Session): Promise<TaskView> {
     sessionStatus !== undefined
       ? await shellOnly(session.tmux_name)
       : false;
+  const planReady = live && session.plan_phase === "awaiting";
+  // A plan waiting for approval isn't a question the agent asked.
   const blocked =
-    live && sessionStatus === "waiting"
+    live && sessionStatus === "waiting" && !planReady
       ? blockedReason(
           chat
             ? saidSinceLastMessage(session.id)
@@ -373,6 +389,7 @@ export async function taskView(session: Session): Promise<TaskView> {
     sessionStatus: agentGone ? "dead" : sessionStatus,
     pr,
     blocked: blocked !== null,
+    planReady,
     settingUp: setup?.status === "running" || setup?.status === "held",
   });
   syncTaskCardInBackground(session, state, pr);
@@ -399,6 +416,7 @@ export async function taskView(session: Session): Promise<TaskView> {
     armed: !!session.merge_armed_at,
     model: sessionModelRef(session),
     planning: session.plan_phase === "planning",
+    planReady,
     plan: taskPlan(session),
     quickOf: session.quick_of ?? null,
     lastActiveAt: session.held_by_device ? lastActiveOf(session) : undefined,
@@ -443,20 +461,23 @@ export function taskRouting(
   workspaceId: string | null,
   view: StartView,
   model: unknown,
-  plan?: boolean
+  plan?: boolean,
+  planOnly?: boolean
 ) {
   const override = parseOverride(model);
   const models = effectiveModels();
   const opts = { workspaceId, override };
   const implement = resolveRole("implement", opts, models);
   const planning = resolveRole("plan", opts, models);
+  // Plan only plans even on one model: the stop is the point, not a switch.
   const planStep =
     view === "chat" &&
-    (plan ?? models.planStep) &&
-    planning.ref !== implement.ref;
+    (!!planOnly ||
+      ((plan ?? models.planStep) && planning.ref !== implement.ref));
   return {
     override,
     plan: planStep,
+    planOnly: planStep && !!planOnly,
     first: planStep ? planning : implement,
   };
 }

package/lib/tasks/move-guard.ts

@@ -25,6 +25,8 @@ export function moveRefusal(session: Session): string | null {
     return "It's a quick change its orchestrator makes on this machine, so it stays here";
   if (escalations(session.id).length)
     return "It's waiting on you (an escalated gate), so it stays here";
+  if (session.plan_only && session.plan_phase !== "implementing")
+    return "It's a plan-only task that hasn't been approved, so it stays here";
   const ask = db
     .prepare(
       `SELECT 1 FROM orchestrator_asks WHERE subject IN (?, ?) AND status = 'open' LIMIT 1`

package/lib/tasks/move.ts

@@ -137,7 +137,11 @@ function orchestratedBundle(session: Session): OrchestratedBundle {
     since: isoUTC(session.task_since ?? session.created_at),
     modelProvider: session.model_provider ?? null,
     modelOverrides: session.model_overrides ?? null,
-    planPhase: session.plan_phase ?? null,
+    // moveRefusal keeps an unapproved plan-only task here.
+    planPhase: (session.plan_phase ?? null) as
+      | "planning"
+      | "implementing"
+      | null,
     planFile: readPlanFile(session.working_directory),
     orchestrator: orchestratorOf(session),
   };

package/lib/tasks/plan-view.ts

@@ -102,7 +102,12 @@ export function taskPlan(session: Session): TaskPlan | null {
       return {
         ...base,
         planned: true,
-        status: phase === "planning" ? "writing" : "approved",
+        status:
+          phase === "planning"
+            ? "writing"
+            : phase === "awaiting"
+              ? "ready"
+              : "approved",
         source: "step",
         title: planTitle(body),
         path: text !== null ? PLAN_FILE : null,

package/lib/tasks/queue.ts

@@ -48,6 +48,7 @@ export interface QueueRow {
   // orchestrator session that started it.
   plan: number | null;
   plan_reason: string | null;
+  plan_only: number | null;
   started_by: string | null;
   view: "chat" | "terminal" | null;
   base_branch: string | null;
@@ -222,6 +223,7 @@ export interface QueueRequest {
   model?: ModelOverride;
   plan?: boolean;
   planReason?: string | null;
+  planOnly?: boolean;
   startedBy?: string | null;
   view?: "chat" | "terminal";
   baseBranch?: string;
@@ -277,9 +279,9 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
   if (!req.prompt.trim()) throw new Error("Describe the task");
   const id = randomUUID();
   db.prepare(
-    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, started_by, view, base_branch,
+    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, plan_only, started_by, view, base_branch,
        host_id, after_task, after_any, origin_workspace_id, position)
-     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @started_by, @view, @base_branch,
+     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @plan_only, @started_by, @view, @base_branch,
        @host_id, @after_task, @after_any, @origin,
        (SELECT COALESCE(MAX(position), 0) + 1 FROM task_queue))`
   ).run({
@@ -294,6 +296,7 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
         : null,
     plan: req.plan === undefined ? null : req.plan ? 1 : 0,
     plan_reason: req.planReason?.trim() || null,
+    plan_only: req.planOnly ? 1 : null,
     started_by: req.startedBy ?? null,
     view: req.view ?? null,
     base_branch: req.baseBranch || null,
@@ -472,6 +475,7 @@ async function startRow(
       : (r.model ?? undefined),
     plan: r.plan == null ? undefined : !!r.plan,
     planReason: r.plan_reason,
+    planOnly: !!r.plan_only,
     startedBy: r.started_by,
     view: r.view ?? undefined,
     baseBranch: r.base_branch ?? undefined,

package/lib/tasks/start.ts

@@ -141,7 +141,7 @@ export async function finishTaskStart(
   const task = (session.task_prompt ?? "") + setupNote(setup);
   const planning = session.plan_phase === "planning";
   if (planning) preparePlanDir(session.worktree_path);
-  const prompt = planning ? planPrompt(task) : task;
+  const prompt = planning ? planPrompt(task, !!session.plan_only) : task;
   try {
     if (session.view === "chat") await launchChat(sessionId, prompt);
     else {

package/lib/tasks/state.ts

@@ -41,6 +41,8 @@ export type TaskState =
   | "blocked"
   | "review"
   | "checks-failing"
+  // A plan-only task's plan is written; it waits for approval.
+  | "plan-ready"
   | "exited"
   | "merged"
   | "dropped"
@@ -56,11 +58,14 @@ export interface TaskStateInput {
   blocked: boolean;
   // Its worktree is still being set up; the agent hasn't started yet.
   settingUp?: boolean;
+  // plan_phase "awaiting": no agent runs, and none is needed.
+  planReady?: boolean;
 }
 
 // Ordered by what needs the human first.
 export function deriveTaskState(input: TaskStateInput): TaskState {
-  const { taskStatus, sessionStatus, pr, blocked, settingUp } = input;
+  const { taskStatus, sessionStatus, pr, blocked, settingUp, planReady } =
+    input;
   if (taskStatus === "merged" || pr?.state === "MERGED") return "merged";
   if (taskStatus === "dropped") return "dropped";
   if (taskStatus === "done" || taskStatus === "moved") return "done";
@@ -70,6 +75,7 @@ export function deriveTaskState(input: TaskStateInput): TaskState {
   if (pr?.state === "OPEN") {
     return pr.checks === "fail" ? "checks-failing" : "review";
   }
+  if (planReady && sessionStatus !== "running") return "plan-ready";
   if (!sessionStatus || sessionStatus === "dead") return "exited";
   if (sessionStatus === "running") return "working";
   return "needs-input";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.519",
+  "version": "0.3.520",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"