@saadnvd1/agent-os 0.3.485 → 0.3.486

package/README.md

@@ -494,8 +494,13 @@ The most specific setting wins: a task's own model, then its workspace's
 `AGENTOS_REVIEW_MODEL` (gate review and scope check) and
 `AGENTOS_TITLE_MODEL` (helpers) in the server's environment still replace a
 role's default where Settings names none. A
-Claude session started without a model (the orchestrator's `start_session`,
-the API) runs on the interactive role's; one you pick a model for keeps it.
+Claude session you start without a model runs on the interactive role's. One
+an orchestrator starts (its `start_session`, or `aos spawn` run from an
+orchestrator) is recorded as started by it (`started_by`) and runs on the
+implementation role instead, so delegated work doesn't use Opus by default;
+`start_session` takes a `model` (`"provider/model"`, checked like a task's:
+gate roles can't be set, other providers must be enabled). One you pick a
+model for keeps it.
 
 **Plan, then implement.** A chat task whose planning and implementation
 models differ starts with a plan step: its first turn runs on the planning
@@ -503,7 +508,13 @@ model and writes the plan to `.agentos/plan.md` in its worktree (ignored by
 git), changing nothing else. When that turn ends, the same conversation
 switches to the implementation model (a live model switch, or a resume with
 `--model` when the provider changes) and is told to follow the plan. Turn it
-off in Settings, or per task with `plan: false`. Terminal tasks skip it.
+off in Settings, or per task with `plan: false`. Terminal tasks skip it. An
+orchestrator decides it for every task: `start_task` requires `plan` and a
+short `plan_reason`, stored on the task and shown on its card ("Planned:
+touches 6 files across gates and UI" / "No plan: one-line default change"),
+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.
 
 **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
@@ -1044,6 +1055,11 @@ it may do on its own, and the lines that always come back to you as asks.
   approve, answer an ask or pass a gate. The route
   they call answers only the orchestrator's worker, by a per-orchestrator
   secret. Its shell runs only `aos` commands that read.
+- **Triage:** its brief has it decide each job: small and clear is a task with
+  `plan: false` and the steps written into the brief; big, unclear or
+  cross-cutting is `plan: true`; work outside a repository is a
+  `start_session` (Sonnet) with the steps in the prompt. It puts
+  implementation on Opus only when the work needs deep reasoning, and says why.
 - **Files:** it reads anywhere and writes (Write, Edit, NotebookEdit) anywhere
   except a project repository, a task worktree (`~/.agent-os/worktrees`),
   AgentOS's own install and state (all of `~/.agent-os` but its own folder),

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

@@ -4,6 +4,17 @@ import { createTask } from "@/lib/tasks";
 import { startOrQueue } from "@/lib/tasks/queue";
 import { hostIdNamed } from "@/lib/hosts";
 import { startView } from "@/lib/sessions/launch";
+import { db } from "@/lib/db";
+
+// The calling session, when it's an orchestrator: what it starts runs on the
+// implementation model. A made-up `from` can only pick that cheaper role.
+function orchestratorFrom(from: unknown): string | null {
+  if (typeof from !== "string" || !from) return null;
+  const row = db
+    .prepare(`SELECT 1 FROM sessions WHERE id = ? AND role = 'orchestrator'`)
+    .get(from);
+  return row ? from : null;
+}
 
 // mode "session" starts an interactive agent; "task" starts one that ends in
 // a PR, or queues it (over the workspace's limit, or with `after`).
@@ -18,7 +29,9 @@ export async function POST(request: NextRequest) {
       on,
       after,
       view,
+      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");
@@ -30,6 +43,7 @@ export async function POST(request: NextRequest) {
         model,
         hostId: on ? hostIdNamed(String(on)) : undefined,
         view: startView(view),
+        startedBy,
       };
       const out = await startOrQueue(
         { ...task, after: typeof after === "string" ? after : undefined },
@@ -44,6 +58,7 @@ export async function POST(request: NextRequest) {
       prompt,
       name: given,
       model,
+      startedBy,
     });
     return NextResponse.json({ session }, { status: 201 });
   } catch (error) {

package/app/api/tasks/route.ts

@@ -35,6 +35,7 @@ export async function POST(request: NextRequest) {
       after,
       view,
       plan,
+      plan_reason,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -47,6 +48,10 @@ 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,
+      planReason:
+        typeof plan_reason === "string" && plan_reason.trim()
+          ? plan_reason.trim().slice(0, 200)
+          : undefined,
       name: typeof name === "string" ? name : undefined,
       hostId: typeof hostId === "string" && hostId ? hostId : undefined,
       baseBranch: typeof baseBranch === "string" ? baseBranch : undefined,

package/components/Tasks/TaskRow.tsx

@@ -47,6 +47,12 @@ export function TaskRow({ task }: { task: TaskView }) {
             {task.model &&
               ` · ${task.model}${task.planning ? " (planning)" : ""}`}
           </p>
+          {task.plan && (
+            <p className="text-muted-foreground truncate text-[11px]">
+              {task.plan.planned ? "Planned" : "No plan"}
+              {task.plan.reason && `: ${task.plan.reason}`}
+            </p>
+          )}
           {task.cardUrl && (
             <a
               href={task.cardUrl}

package/components/Usage/CompareView.tsx

@@ -197,14 +197,26 @@ function CompareTables({ data }: { data: Comparison }) {
         }))}
         total={sumSpend(data.roles)}
       />
+      {data.plans.length > 0 && (
+        <SpendTable
+          title="Planned · not planned"
+          rows={data.plans.map((r) => ({
+            ...r.spend,
+            key: r.key,
+            label: `${{ planned: "Planned", unplanned: "No plan", unstated: "Not stated" }[r.key]} · ${r.tasks} ${r.tasks === 1 ? "task" : "tasks"}`,
+          }))}
+          total={sumSpend(data.plans.map((r) => r.spend))}
+        />
+      )}
       <p className="text-muted-foreground text-[11px]">
         A task counts under the provider its own turns ran on (anthropic is the
         baseline); its reviews and checks count toward its cost. Dollars are
         list-price estimates; for Claude, the plan&apos;s real measure is its
         5-hour window, shared out by how far each turn moved it (an estimate).
-        Outcomes come from the orchestrator&apos;s checks, so only its tasks
-        have them. Under 10 tasks a column is a small sample: read it as a hint,
-        not a result.
+        Planned or not is the orchestrator&apos;s own call, recorded when it
+        started the task. Outcomes come from the orchestrator&apos;s checks, so
+        only its tasks have them. Under 10 tasks a column is a small sample:
+        read it as a hint, not a result.
       </p>
     </>
   );

package/lib/agents/spawn.ts

@@ -3,6 +3,8 @@ import os from "os";
 import { db, queries, type Session } from "../db";
 import { getProject, getAllProjects } from "../projects";
 import { resolveModelForAgent } from "../model-catalog";
+import { parseOverride, resolveRole, setSessionModel } from "../models/resolve";
+import { ANTHROPIC } from "../models/roles";
 import { launchClaude } from "./launch";
 import { nameFor } from "../session-titles";
 
@@ -29,7 +31,10 @@ export async function spawnSession(opts: {
   prompt: string;
   // Its name; generated from the prompt when absent.
   name?: string;
-  model?: string;
+  model?: string | null;
+  // The orchestrator session that starts it: the implementation role's
+  // model unless `model` is given.
+  startedBy?: string | null;
 }): Promise<Session> {
   const prompt = opts.prompt.trim();
   if (!prompt) throw new Error("Give the new session a prompt");
@@ -41,10 +46,17 @@ export async function spawnSession(opts: {
 
   const id = randomUUID();
   const tmuxName = `claude-${id}`;
-  const model = resolveModelForAgent(
-    "claude",
-    opts.model || project.default_model
-  );
+  const routed = opts.startedBy
+    ? resolveRole("implement", {
+        workspaceId: project.workspace_id,
+        override: parseOverride(opts.model),
+      })
+    : null;
+  if (routed && routed.provider.id !== ANTHROPIC)
+    throw new Error("Another provider's models run only as a chat");
+  const model = routed
+    ? routed.model
+    : resolveModelForAgent("claude", opts.model || project.default_model);
   const cwd = project.working_directory.replace(/^~/, os.homedir());
   const naming = await nameFor(prompt, cwd, opts.name);
 
@@ -64,10 +76,10 @@ export async function spawnSession(opts: {
       project.id,
       "local"
     );
-  db.prepare(`UPDATE sessions SET name_source = ? WHERE id = ?`).run(
-    naming.source,
-    id
-  );
+  db.prepare(
+    `UPDATE sessions SET name_source = ?, started_by = ? WHERE id = ?`
+  ).run(naming.source, opts.startedBy ?? null, id);
+  if (routed) setSessionModel(id, routed);
   void naming.refine?.(id);
   await launchClaude({ sessionId: id, tmuxName, cwd, model, prompt });
   return queries.getSession(db).get(id) as Session;

package/lib/db/migrations.ts

@@ -1472,6 +1472,27 @@ const migrations: Migration[] = [
         db.exec(`ALTER TABLE chat_compactions ADD COLUMN phase TEXT`);
     },
   },
+  {
+    id: 65,
+    name: "orchestrator_triage",
+    up: (db) => {
+      // started_by: the orchestrator session that started this one (null: a
+      // person). plan_decided: 1 planned, 0 no plan, null not stated.
+      const add = (table: string, col: string, type: string) => {
+        const columns = db.prepare(`PRAGMA table_info(${table})`).all() as {
+          name: string;
+        }[];
+        if (!columns.some((c) => c.name === col))
+          db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`);
+      };
+      add("sessions", "started_by", "TEXT");
+      add("sessions", "plan_decided", "INTEGER");
+      add("sessions", "plan_reason", "TEXT");
+      add("task_queue", "plan", "INTEGER");
+      add("task_queue", "plan_reason", "TEXT");
+      add("task_queue", "started_by", "TEXT");
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/db/types.ts

@@ -20,6 +20,11 @@ export interface Session {
   model_overrides?: string | null;
   // A task's plan step: planning on the planning model, then implementing.
   plan_phase?: "planning" | "implementing" | 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.
+  plan_decided?: number | null;
+  plan_reason?: string | null;
   system_prompt: string | null;
   group_path: string; // Deprecated - use project_id
   project_id: string | null;

package/lib/models/plan-step.ts

@@ -18,6 +18,7 @@ import {
   taskOverride,
 } from "./resolve";
 import { ANTHROPIC } from "./roles";
+import { queueEvent } from "../orchestrator/events";
 
 export const PLAN_FILE = ".agentos/plan.md";
 
@@ -41,6 +42,52 @@ export function preparePlanDir(worktree: string): void {
   fs.writeFileSync(path.join(dir, ".gitignore"), "*\n");
 }
 
+const SUMMARY_LINE = 120;
+
+// The plan's first few headings and bullets, trimmed: what the orchestrator
+// needs to know what was decided, with no model call.
+export function planSummary(text: string, max = 5): string[] {
+  const clean = (l: string) =>
+    l
+      .replace(/^\s*(?:#+|[-*+]|\d+[.)])\s+/, "")
+      .replace(/[*`_]/g, "")
+      .trim();
+  const trim = (l: string) =>
+    l.length > SUMMARY_LINE ? `${l.slice(0, SUMMARY_LINE - 1)}…` : l;
+  const lines: { text: string; key: boolean }[] = [];
+  let fenced = false;
+  for (const raw of text.split("\n")) {
+    if (/^\s*```/.test(raw)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced || !raw.trim() || /^\s*(?:---+|\|)/.test(raw)) continue;
+    const t = clean(raw);
+    if (t)
+      lines.push({ text: t, key: /^\s*(?:#+|[-*+]|\d+[.)])\s+/.test(raw) });
+  }
+  const keyed = lines.filter((l) => l.key);
+  const picked = (keyed.length >= 3 ? keyed : lines).slice(0, max);
+  return picked.map((l) => trim(l.text));
+}
+
+// Tells the orchestrator that started a task its plan is written, once.
+function announcePlan(s: Session, ref: string): void {
+  if (!s.started_by) return;
+  const workspaceId = sessionWorkspace(s);
+  if (!workspaceId || !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.`;
+  try {
+    const summary = planSummary(fs.readFileSync(file, "utf8"));
+    head = `Task "${s.name}": plan written to ${file}; implementing on ${ref}.`;
+    if (summary.length) head += `\n${summary.map((l) => `- ${l}`).join("\n")}`;
+  } catch {
+    // No plan file: the line says so.
+  }
+  queueEvent(workspaceId, `plan-done:${s.id}`, s.id, head);
+}
+
 export const implementMessageId = (sessionId: string) =>
   `implement-${sessionId}`;
 
@@ -88,6 +135,11 @@ export async function handoffAfterPlan(
     return true;
   })();
   if (!claimed) return false;
+  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 true;

package/lib/models/roles.ts

@@ -91,8 +91,11 @@ export function sessionRole(session: {
   role?: string | null;
   task_status?: string | null;
   plan_phase?: string | null;
+  started_by?: string | null;
 }): ModelRole {
   if (session.role === "orchestrator") return "orchestrator";
-  if (!session.task_status) return "interactive";
+  // 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";
 }

package/lib/orchestrator/act.ts

@@ -4,7 +4,11 @@
  * the brakes.
  */
 
-import { parseOverride, type ModelOverride } from "../models/resolve";
+import {
+  parseOverride,
+  sessionModelRef,
+  type ModelOverride,
+} from "../models/resolve";
 import { sendMessage } from "../bus";
 import { chatState } from "../chat/runner";
 import { stopSession } from "../sessions/stop";
@@ -88,10 +92,12 @@ export async function startTask(
     after?: string;
     model?: ModelOverride;
     plan?: boolean;
+    planReason?: string;
   } = {}
 ): Promise<string> {
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
+  const startedBy = orchestratorId(workspaceId);
   // Its brakes read this machine's usage, not the other machine's account.
   if (isRemoteHost(project.host_id))
     throw new Error(
@@ -107,6 +113,9 @@ export async function startTask(
       name: opts.name,
       view,
       model,
+      plan: opts.plan,
+      planReason: opts.planReason,
+      startedBy,
       baseBranch: opts.base || undefined,
       after: opts.after,
       originWorkspaceId: workspaceId,
@@ -124,6 +133,8 @@ export async function startTask(
             view,
             model,
             plan: opts.plan,
+            planReason: opts.planReason,
+            startedBy,
           }),
         (s) => s.id
       )
@@ -133,16 +144,24 @@ 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;
-  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.`;
+  const skipped =
+    opts.plan && 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}`;
 }
 
 export async function startSession(
   workspaceId: string,
   projectRef: string,
   prompt: string,
-  opts: { name?: string; view?: StartView } = {}
+  opts: { name?: string; view?: StartView; model?: string } = {}
 ): Promise<string> {
   const project = workspaceProject(workspaceId, projectRef);
+  const startedBy = orchestratorId(workspaceId);
+  const model = parseOverride(opts.model);
+  if (model && typeof model !== "string")
+    throw new Error(`model: a session takes one "provider/model"`);
   const view = opts.view ?? DEFAULT_START_VIEW;
   if (view === "chat" && isRemoteHost(project.host_id))
     throw new Error("Spawning on other machines isn't supported yet");
@@ -159,12 +178,20 @@ export async function startSession(
               name: opts.name,
               view,
               access: "full",
+              model,
+              startedBy,
             })
           ).session
-        : spawnSession({ project: project.id, prompt, name: opts.name }),
+        : spawnSession({
+            project: project.id,
+            prompt,
+            name: opts.name,
+            model,
+            startedBy,
+          }),
     (s) => s.id
   );
-  return `Started session "${session.name}" (id ${session.id.slice(0, 8)}, ${session.view}) in ${project.name}.`;
+  return `Started session "${session.name}" (id ${session.id.slice(0, 8)}, ${session.view}) in ${project.name} on ${sessionModelRef(session)}.`;
 }
 
 function itemLine(i: StackItemView): string {

package/lib/orchestrator/brief.ts

@@ -36,6 +36,14 @@ Events reach you as short lines from "agentos" (a PR opened, CI finished, a sess
 
 You may act without asking on anything inside this workspace that's additive or reversible: start, steer, stop and drop sessions and tasks; answer blockers; create, update and move cards; run stacks; review PRs; merge what passes the gates. Your tools only reach this workspace's projects, sessions, tasks and stacks; outside it, you can only message other workspaces' orchestrators.
 
+## Triage every job
+
+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.
+- 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.
+
 ## Merging: the gates
 
 Merge only through the gates: \`arm\` or \`sign_off\`. \`sign_off\` merges a task's PR, with the project's merge method (squash unless set otherwise), only if all of these hold, and otherwise refuses naming the gate:
@@ -93,9 +101,9 @@ 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?): 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); pass model ("provider/model", or a map of role to one) only when Saad asks for one, and another provider than anthropic only then.
+- \`${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.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?): an interactive session, a chat unless view is terminal.
+- \`${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.
 - \`${TOOL_NAMES.quick_pr}\` (change, title, body): commit everything in a quick change, push its branch (never the default branch) and open its PR, or push to the PR it has; its review starts at once. Then it's gated like any task: CI, that review (also its code-review gate), scope, then sign_off or arm. It's in \`sessions\` as your quick change; drop it to throw it away, and it's cleaned up like a task when it merges or is dropped.
 - \`${TOOL_NAMES.stack}\` (target, plan_only?): run a board's open cards as stacked tasks; plan_only shows the plan without starting.

package/lib/orchestrator/describe.ts

@@ -37,6 +37,10 @@ function sessionLine(f: SessionFacts): string {
       task += `, BLOCKED: ${untrusted(f.name, f.task.blocked)}`;
     parts.push(task);
   }
+  if (f.plan)
+    parts.push(
+      `${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}` : "";
     parts.push(

package/lib/orchestrator/facts.ts

@@ -41,6 +41,8 @@ export interface SessionFacts {
   branch: string | null;
   // 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;
   task: {
     state: TaskState;
     pr: TaskPR | null;
@@ -279,6 +281,10 @@ export async function sessionFacts(
         ),
         branch: s.branch_name,
         quick: !!s.quick_of,
+        plan:
+          s.plan_decided == null
+            ? null
+            : { planned: !!s.plan_decided, reason: s.plan_reason ?? null },
         task,
         stack: stackOf(s.id),
       };

package/lib/orchestrator/serve.ts

@@ -107,6 +107,7 @@ export async function runTool(
         after: a.after,
         model: a.model,
         plan: a.plan,
+        planReason: a.plan_reason,
       });
     }
     case "set_task_model": {
@@ -122,6 +123,7 @@ export async function runTool(
       return startSession(w, a.project, a.prompt, {
         name: a.name,
         view: a.view,
+        model: a.model,
       });
     }
     case "quick_change": {

package/lib/orchestrator/tool-schemas.ts

@@ -105,9 +105,16 @@ export const TOOL_SHAPES = {
     model: modelOverride,
     plan: z
       .boolean()
-      .optional()
       .describe(
-        "Plan first on the planning model, then implement on the implementation model (default: Settings)"
+        "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_reason: z
+      .string()
+      .trim()
+      .min(3)
+      .max(200)
+      .describe(
+        'Why, in a few words Saad reads on the task card: "touches 6 files across gates and UI", "one-line default change"'
       ),
   },
   set_task_model: {
@@ -134,6 +141,11 @@ export const TOOL_SHAPES = {
       .optional()
       .describe("A short name, 2-6 words (default: one made from the prompt)"),
     view,
+    model: modelRef
+      .optional()
+      .describe(
+        'One model for the session, "provider/model"; default: the implementation model. Opus only when the work needs deep reasoning'
+      ),
   },
   quick_change: {
     project,

package/lib/orchestrator/tools.ts

@@ -61,11 +61,11 @@ 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. 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 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:
-    "Start an interactive agent session in a project with a prompt. It runs as a chat unless view is terminal (only for a job that needs a TUI). Refused while a brake holds.",
+    'Start an agent session in a project with a prompt, for work that isn\'t a PR task. It runs on the implementation model unless you give model (one "provider/model"; Opus only when the work needs deep reasoning), as a chat unless view is terminal (only for a job that needs a TUI). Refused while a brake holds.',
   quick_change:
     "Make a small, low-risk edit yourself (a typo, a config value, a one-file fix): cuts a worktree and branch from the project's default branch and returns its path. You may write there (Write, Edit) and run git there as `git -C <path> ...` (status, diff, add, rm, mv, restore, reset, log, show); nowhere else in a project. Anything needing real work, tests or an investigation is a task (start_task).",
   quick_pr:

package/lib/sessions/launch.ts

@@ -11,7 +11,7 @@ import { db, queries, type Session } from "../db";
 import type { AgentType } from "../providers";
 import type { ChatAccess, ChatImage } from "../chat/events";
 import { resolveModelForAgent } from "../model-catalog";
-import { resolveRole, setSessionModel } from "../models/resolve";
+import { parseOverride, resolveRole, setSessionModel } from "../models/resolve";
 import { ANTHROPIC } from "../models/roles";
 import { getProject } from "../projects";
 import { getHost, isRemoteHost } from "../hosts";
@@ -71,6 +71,9 @@ export interface LaunchInput {
   name?: string | null;
   view?: "chat" | "terminal";
   parentSessionId?: string | null;
+  // The orchestrator session that starts it: it runs on the implementation
+  // role's model (or `model`), not the interactive one's.
+  startedBy?: string | null;
   groupPath?: string;
   systemPrompt?: string | null;
 }
@@ -222,10 +225,20 @@ async function launch(input: LaunchInput, id: string): Promise<Launched> {
       : DEFAULT_START_VIEW;
   // Claude with no model picked runs on the interactive role's, here; on
   // another provider only as a chat, whose worker carries its endpoint.
+  const role = input.startedBy ? "implement" : "interactive";
+  // An orchestrator's explicit model is validated like a task's.
+  const picked = input.startedBy ? parseOverride(input.model) : null;
+  if (picked && typeof picked !== "string")
+    throw new Error(`model: a session takes one "provider/model"`);
   const routed =
-    agentType === "claude" && !input.model?.trim() && !remote
-      ? resolveRole("interactive", { workspaceId: project?.workspace_id })
+    agentType === "claude" && (picked || !input.model?.trim()) && !remote
+      ? resolveRole(role, {
+          workspaceId: project?.workspace_id,
+          override: picked,
+        })
       : null;
+  if (picked && routed && routed.provider.id !== ANTHROPIC && view !== "chat")
+    throw new Error("Another provider's models run only as a chat");
   const interactive =
     routed && (routed.provider.id === ANTHROPIC || view === "chat")
       ? routed
@@ -264,8 +277,14 @@ async function launch(input: LaunchInput, id: string): Promise<Launched> {
       runOn
     );
   db.prepare(
-    `UPDATE sessions SET view = ?, name_source = ?, setup_status = ? WHERE id = ?`
-  ).run(view, naming.source, useWorktree ? "running" : null, id);
+    `UPDATE sessions SET view = ?, name_source = ?, setup_status = ?, started_by = ? WHERE id = ?`
+  ).run(
+    view,
+    naming.source,
+    useWorktree ? "running" : null,
+    input.startedBy ?? null,
+    id
+  );
   if (interactive) setSessionModel(id, interactive);
   if (input.access)
     db.prepare(`UPDATE sessions SET chat_access = ? WHERE id = ?`).run(

package/lib/tasks/index.ts

@@ -96,6 +96,8 @@ export interface TaskView {
   // plan step (lib/models).
   model?: string;
   planning?: boolean;
+  // What its starter decided about a plan step, and why; null if unstated.
+  plan?: { planned: boolean; reason: string | null } | null;
   // A quick change: the orchestrator session that makes it (no agent).
   quickOf?: string | null;
 }
@@ -111,6 +113,10 @@ export async function createTask(opts: {
   model?: ModelOverride;
   // Plan first on the planning model (Settings' default otherwise).
   plan?: boolean;
+  // Why the starter chose to plan or not: shown on the task's card.
+  planReason?: string | null;
+  // The orchestrator session that started it (null: a person).
+  startedBy?: string | null;
   // Started from this LumifyHub card, which the task then moves.
   cardId?: string;
   // Stacked: cut from another task's pushed branch, at this exact commit.
@@ -247,7 +253,8 @@ 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 = ? WHERE id = ?`
+       model_provider = ?, model_overrides = ?, plan_phase = ?,
+       plan_decided = ?, plan_reason = ?, started_by = ? WHERE id = ?`
   ).run(
     prompt,
     buildTaskBrief({
@@ -260,6 +267,9 @@ 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,
+    opts.planReason?.trim() || null,
+    opts.startedBy ?? null,
     id
   );
   opts.onCreated?.(id);
@@ -376,6 +386,13 @@ export async function taskView(session: Session): Promise<TaskView> {
     armed: !!session.merge_armed_at,
     model: sessionModelRef(session),
     planning: session.plan_phase === "planning",
+    plan:
+      session.plan_decided == null
+        ? null
+        : {
+            planned: !!session.plan_decided,
+            reason: session.plan_reason ?? null,
+          },
     quickOf: session.quick_of ?? null,
   };
 }

package/lib/tasks/queue.ts

@@ -44,6 +44,11 @@ export interface QueueRow {
   model: string | null;
   // A per-role model map (lib/models), when that's what it was given.
   model_overrides: string | null;
+  // The starter's plan decision (1/0, null: not stated), its reason, and the
+  // orchestrator session that started it.
+  plan: number | null;
+  plan_reason: string | null;
+  started_by: string | null;
   view: "chat" | "terminal" | null;
   base_branch: string | null;
   host_id: string | null;
@@ -205,6 +210,9 @@ export interface QueueRequest {
   prompt: string;
   name?: string;
   model?: ModelOverride;
+  plan?: boolean;
+  planReason?: string | null;
+  startedBy?: string | null;
   view?: "chat" | "terminal";
   baseBranch?: string;
   hostId?: string;
@@ -251,9 +259,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, view, base_branch,
+    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, started_by, view, base_branch,
        host_id, after_task, after_any, origin_workspace_id, position)
-     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @view, @base_branch,
+     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @started_by, @view, @base_branch,
        @host_id, @after_task, @after_any, @origin,
        (SELECT COALESCE(MAX(position), 0) + 1 FROM task_queue))`
   ).run({
@@ -266,6 +274,9 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
       req.model && typeof req.model === "object"
         ? JSON.stringify(req.model)
         : null,
+    plan: req.plan === undefined ? null : req.plan ? 1 : 0,
+    plan_reason: req.planReason?.trim() || null,
+    started_by: req.startedBy ?? null,
     view: req.view ?? null,
     base_branch: req.baseBranch || null,
     host_id: req.hostId || null,
@@ -440,6 +451,9 @@ async function startRow(
     model: r.model_overrides
       ? (JSON.parse(r.model_overrides) as ModelOverride)
       : (r.model ?? undefined),
+    plan: r.plan == null ? undefined : !!r.plan,
+    planReason: r.plan_reason,
+    startedBy: r.started_by,
     view: r.view ?? undefined,
     baseBranch: r.base_branch ?? undefined,
     hostId: r.host_id ?? undefined,

package/lib/usage/compare.ts

@@ -35,6 +35,8 @@ export interface CompareTurn extends ModelTurnRow {
 export interface TaskOutcome {
   id: string;
   status: string | null;
+  // The decision on a plan step: null when none was recorded.
+  planned: boolean | null;
   // The first finished CI run, and review, on its PR: passed or not; null
   // when it never had one (no PR, or not under an orchestrator).
   ciFirstGreen: boolean | null;
@@ -74,11 +76,19 @@ export interface RoleModelRow extends TokenSpend {
   wallMs: number;
 }
 
+// Tasks split by whether the orchestrator chose a plan step for them.
+export interface PlanSplitRow {
+  key: "planned" | "unplanned" | "unstated";
+  tasks: number;
+  spend: TokenSpend;
+}
+
 export interface Comparison {
   from: number;
   to: number;
   cohorts: Cohort[];
   roles: RoleModelRow[];
+  plans: PlanSplitRow[];
 }
 
 const rate = (): Rate => ({ yes: 0, of: 0 });
@@ -154,6 +164,17 @@ export function compareRuns(
   }
   for (const c of cohorts.values()) c.smallSample = c.tasks < SMALL_SAMPLE;
 
+  const plans = new Map<PlanSplitRow["key"], PlanSplitRow>();
+  for (const [id, ts] of byTask) {
+    const planned = outcomes.get(id)!.planned;
+    const key =
+      planned === null ? "unstated" : planned ? "planned" : "unplanned";
+    let r = plans.get(key);
+    if (!r) plans.set(key, (r = { key, tasks: 0, spend: emptySpend() }));
+    r.tasks += 1;
+    for (const t of ts) addRow(r.spend, t, prices);
+  }
+
   const roles = new Map<string, RoleModelRow>();
   for (const t of inRange) {
     const { provider, model } = rowModel(t);
@@ -179,6 +200,9 @@ export function compareRuns(
     roles: [...roles.values()].sort(
       (a, b) => a.role.localeCompare(b.role) || b.costUsd - a.costUsd
     ),
+    plans: (["planned", "unplanned", "unstated"] as const)
+      .map((k) => plans.get(k))
+      .filter((r): r is PlanSplitRow => !!r),
   };
 }
 
@@ -201,10 +225,14 @@ export function taskOutcomes(ids: string[]): Map<string, TaskOutcome> {
   const marks = ids.map(() => "?").join(",");
   const tasks = db
     .prepare(
-      `SELECT id, task_status FROM sessions
+      `SELECT id, task_status, plan_decided FROM sessions
        WHERE id IN (${marks}) AND task_status IS NOT NULL`
     )
-    .all(...ids) as { id: string; task_status: string }[];
+    .all(...ids) as {
+    id: string;
+    task_status: string;
+    plan_decided: number | null;
+  }[];
   const checks = db
     .prepare(
       `SELECT id, session_id, sha, kind, status FROM orchestrator_checks
@@ -227,6 +255,7 @@ export function taskOutcomes(ids: string[]): Map<string, TaskOutcome> {
     out.set(t.id, {
       id: t.id,
       status: t.task_status,
+      planned: t.plan_decided === null ? null : t.plan_decided === 1,
       ciFirstGreen: null,
       reviewFirstPass: null,
       gateFailures: 0,

package/lib/usage/turns.ts

@@ -60,7 +60,7 @@ export function recordTurn(
     const current = db
       .prepare(
         `SELECT name, workspace_id, model, model_provider, role, task_status,
-           plan_phase FROM sessions WHERE id = ?`
+           plan_phase, started_by FROM sessions WHERE id = ?`
       )
       .get(session.id) as
       | Pick<
@@ -72,6 +72,7 @@ export function recordTurn(
           | "role"
           | "task_status"
           | "plan_phase"
+          | "started_by"
         >
       | undefined;
     const provider = current?.model_provider ?? ANTHROPIC;

package/package.json

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