@saadnvd1/agent-os 0.3.748 → 0.3.749

package/README.md

@@ -19,7 +19,7 @@ and check on all of it from your phone.
 - **Other machines in the same list.** Link another machine that runs AgentOS and start or move work there. [More](docs/reference/machines.md)
 - **Built for your phone.** The whole app works on a phone; pair it with a QR code. [More](docs/guides/phone.md)
 - **Phone to orchestrator.** A paired phone can send a shake report or a shared page or file to a workspace's orchestrator (`POST /api/orchestrators/:workspaceId/intake`, saved under `intake/` beside the database, shared content marked untrusted), and fetch names to improve dictation (`GET /api/voice/vocab?workspace=`). [More](docs/guides/phone.md)
-- **An analyst beside your coding agent.** Pair a chat with a second one that reviews each turn, explains it in plain English, flags issues and drafts the next prompt, which you send, edit or dismiss. Side by side on a desktop, a switch on a phone. [More](docs/decisions/2026-10-21-analyst-sessions.md)
+- **An analyst beside your coding agent.** Pair a chat with a second one that reviews each turn, explains it in plain English, flags issues and drafts the next prompt, which you send, edit or dismiss. It runs on Claude unless you pick another model, local ones included. Side by side on a desktop, a switch on a phone. [More](docs/decisions/2026-10-21-analyst-sessions.md)
 - **Agents that talk to each other.** Sessions message each other with `aos`, and you see every conversation in Messages. [More](docs/guides/agent-network.md)
 - **Chat or terminal, same conversation.** Streaming replies, steps and diffs, plan mode, slash commands, `@file`, undo. [More](docs/guides/chat.md)
 - **Bookmarks.** Star any message, tool call or turn, then find it again from the chat or across every chat, with a search. [More](docs/guides/chat.md)

package/app/api/models/choices/route.ts

@@ -1,9 +1,13 @@
 import { NextResponse } from "next/server";
-import { modelCatalog } from "@/lib/models/catalog";
+import { modelCatalog, unconfiguredChoices } from "@/lib/models/catalog";
 
 // GET /api/models/choices - every model a picker offers, from the server:
 // the enabled providers' models and the ones Pi reaches, each with its
-// locality (local or cloud) and the last availability check.
+// locality (local or cloud), the last availability check and whether it can
+// call tools. Models of a provider that is off, or half set up, are listed
+// with `unusable` saying why, so a picker can grey them rather than hide them.
 export async function GET() {
-  return NextResponse.json({ choices: modelCatalog() });
+  return NextResponse.json({
+    choices: [...modelCatalog(), ...unconfiguredChoices()],
+  });
 }

package/app/api/sessions/[id]/model/route.ts

@@ -1,10 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
 import { db, type Session } from "@/lib/db";
-import { setChatModel } from "@/lib/chat/settings";
-import { providerFor, sessionRole } from "@/lib/models/resolve";
-import { switchSessionModel } from "@/lib/models/session-model";
-import { PI } from "@/lib/models/providers";
-import { formatModelRef, parseModelRef } from "@/lib/models/roles";
+import { switchSessionModelRef } from "@/lib/models/session-model";
 
 // POST /api/sessions/:id/model {ref} - move a running session to another
 // model ("provider/model", or "pi/<provider>/<model>" for a Pi session),
@@ -23,24 +19,7 @@ export async function POST(
   if (typeof ref !== "string" || !ref.trim())
     return NextResponse.json({ error: "ref is required" }, { status: 400 });
   try {
-    const parsed = parseModelRef(ref);
-    if (session.agent_type === "pi") {
-      if (parsed.provider !== PI)
-        throw new Error(
-          "A Pi session runs on a Pi model (pi/<provider>/<model>)"
-        );
-      await setChatModel(id, parsed.model);
-    } else {
-      if (parsed.provider === PI)
-        throw new Error("Only a Pi session can move to a Pi model");
-      await switchSessionModel(id, {
-        role: sessionRole(session),
-        ref: formatModelRef(parsed),
-        provider: providerFor(parsed.provider),
-        model: parsed.model,
-        source: "task",
-      });
-    }
+    await switchSessionModelRef(session, ref);
     return NextResponse.json({ ok: true });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/components/Analyst/StartAnalystSheet.tsx

@@ -13,8 +13,10 @@ import {
 } from "@/components/ui/dialog";
 import { Switch } from "@/components/ui/switch";
 import { RoleModelSelect } from "@/components/Models/RoleModelSelect";
+import { useSessionsQuery } from "@/data/sessions/queries";
 import { analystUi, analystUiActions } from "@/stores/analystUi";
 import { useStartAnalystBeside } from "./pair";
+import { useAnalystModels } from "./useAnalystModels";
 
 // Pairs an analyst with a chat: it reviews each turn the coding agent
 // finishes and recommends the next prompt, which the user sends or not.
@@ -46,6 +48,9 @@ function StartAnalystForm({
   const [model, setModel] = useState<string | null>(null);
   const [reviewLast, setReviewLast] = useState(false);
   const start = useStartAnalystBeside();
+  const { data } = useSessionsQuery();
+  const coder = data?.sessions.find((s) => s.id === sessionId);
+  const models = useAnalystModels(coder?.project_id);
 
   return (
     <DialogContent className="sm:max-w-[460px]">
@@ -68,8 +73,8 @@ function StartAnalystForm({
         <RoleModelSelect
           id="analyst-model"
           value={model}
-          inheritLabel="The analyst role's model"
-          claudeOnly
+          inheritLabel={models.defaultLabel}
+          blockedBy={models.blockedBy}
           onChange={setModel}
         />
       </div>

package/components/Analyst/useAnalystModels.ts

@@ -0,0 +1,19 @@
+import { useAgentRolesQuery, useModelChoices } from "@/data/models";
+import { analystBlock, defaultAnalystLabel } from "@/lib/models/usable";
+
+// What an analyst's model pickers need, all from the server: the list, the
+// reason a model can't be picked, and the label of the default (the model
+// the analyst role resolves to in the project the analyst starts in).
+export function useAnalystModels(projectId?: string | null) {
+  const { data: choices = [] } = useModelChoices();
+  const roles = useAgentRolesQuery(
+    projectId ? "project" : "settings",
+    projectId
+  );
+  const bound = roles.data?.roles.find((r) => r.id === "analyst")?.binding;
+  return {
+    choices,
+    defaultLabel: defaultAnalystLabel(bound?.ref, choices),
+    blockedBy: analystBlock,
+  };
+}

package/components/Chat/ModelPicker.tsx

@@ -53,6 +53,7 @@ export function ModelPicker({
           <DropdownMenuItem
             key={m.value}
             onSelect={() => onPick(m.value)}
+            disabled={!!m.disabled}
             className="flex min-h-11 items-start gap-2 md:min-h-9"
           >
             <Check
@@ -60,9 +61,9 @@ export function ModelPicker({
             />
             <span className="flex flex-col">
               <span className="text-sm">{m.label}</span>
-              {m.description && (
+              {(m.disabled || m.description) && (
                 <span className="text-muted-foreground line-clamp-2 text-xs">
-                  {m.description}
+                  {m.disabled ?? m.description}
                 </span>
               )}
             </span>

package/components/Draft/AnalystModelChip.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { Cpu } from "lucide-react";
+import {
+  AvailabilityDot,
+  LocalityBadge,
+} from "@/components/Models/ModelBadges";
+import { useAnalystModels } from "@/components/Analyst/useAnalystModels";
+import type { Draft } from "@/lib/drafts";
+import { ChipItem, ChipMenu } from "./Chip";
+
+// The model of the analyst a new chat starts with: the analyst role's
+// default unless one is picked. The list is the server's; a model that
+// can't serve an analyst is greyed with the reason.
+export function AnalystModelChip({
+  draft,
+  projectId,
+  onChange,
+}: {
+  draft: Draft;
+  projectId: string | null;
+  onChange: (patch: Partial<Draft>) => void;
+}) {
+  const { choices, defaultLabel, blockedBy } = useAnalystModels(projectId);
+  const picked = choices.find((c) => c.ref === draft.analystModel);
+  return (
+    <ChipMenu
+      icon={Cpu}
+      name="Analyst model"
+      label={picked?.label ?? draft.analystModel ?? defaultLabel}
+    >
+      <ChipItem
+        checked={!draft.analystModel}
+        onSelect={() => onChange({ analystModel: null })}
+      >
+        {defaultLabel}
+      </ChipItem>
+      {choices.map((c) => {
+        const why = c.unusable ?? blockedBy(c);
+        return (
+          <ChipItem
+            key={c.ref}
+            checked={c.ref === draft.analystModel}
+            onSelect={() => onChange({ analystModel: c.ref })}
+            disabled={!!why}
+            hint={why ?? c.group}
+          >
+            <span className="flex items-center gap-1.5">
+              <AvailabilityDot availability={c.availability} />
+              {c.label}
+              <LocalityBadge locality={c.locality} />
+            </span>
+          </ChipItem>
+        );
+      })}
+    </ChipMenu>
+  );
+}

package/components/Draft/DraftChips.tsx

@@ -20,6 +20,7 @@ import { modelChoices, useModelsQuery } from "@/data/models";
 import { useBrowserMachine } from "@/data/machines";
 import { machineLabel } from "@/lib/machines/label";
 import { RoleChips } from "./RoleChips";
+import { AnalystModelChip } from "./AnalystModelChip";
 import { AgentModelChip } from "./AgentModelChip";
 import { ChipHeading, ChipItem, ChipMenu, ChipToggle } from "./Chip";
 import {
@@ -232,6 +233,13 @@ export function DraftChips({
           onChange={(withAnalyst) => onChange({ withAnalyst })}
         />
       )}
+      {project && !draft.openPr && local && draft.withAnalyst && (
+        <AnalystModelChip
+          draft={draft}
+          projectId={project.id}
+          onChange={onChange}
+        />
+      )}
       {project && draft.openPr && local && (
         <ChipMenu
           icon={Cpu}

package/components/Draft/DraftPanel.tsx

@@ -179,7 +179,13 @@ export function DraftPanel({
       );
       if (draft.withAnalyst && project && draft.hostId === "local") {
         if (session.view === "chat")
-          void startAnalyst.run({ coderSessionId: session.id }, paneId);
+          void startAnalyst.run(
+            {
+              coderSessionId: session.id,
+              analystModel: draft.analystModel ?? undefined,
+            },
+            paneId
+          );
         else toast("An analyst reviews chats: this session runs in a terminal");
       }
     } catch (error) {

package/components/Draft/RoleChips.tsx

@@ -7,6 +7,7 @@ import {
 } from "@/components/Models/ModelBadges";
 import { useAgentRolesQuery, useModelChoices } from "@/data/models";
 import type { Draft } from "@/lib/drafts";
+import { analystBlock, defaultAnalystLabel } from "@/lib/models/usable";
 import {
   AGENT_ROLES,
   AGENT_ROLE_DEFS,
@@ -34,6 +35,9 @@ export function RoleChips({
   const current = override ?? bound?.choice ?? null;
   const modelName = (ref: string | undefined | null) =>
     ref ? ref.split("/").slice(1).join("/") : "…";
+  const analyst = role === "analyst";
+  const whyNot = (c: (typeof choices)[number]) =>
+    c.unusable ?? (analyst ? analystBlock(c) : null);
   return (
     <>
       <ChipMenu
@@ -71,7 +75,9 @@ export function RoleChips({
           label={
             draft.roleModel
               ? modelName(draft.roleModel)
-              : `Role model: ${modelName(bound?.binding?.ref)}`
+              : analyst
+                ? defaultAnalystLabel(bound?.binding?.ref, choices)
+                : `Role model: ${modelName(bound?.binding?.ref)}`
           }
         >
           <ChipItem
@@ -79,14 +85,17 @@ export function RoleChips({
             onSelect={() => onChange({ roleModel: null })}
             hint={bound?.binding ? modelName(bound.binding.ref) : undefined}
           >
-            Role model
+            {analyst
+              ? defaultAnalystLabel(bound?.binding?.ref, choices)
+              : "Role model"}
           </ChipItem>
           {choices.map((c) => (
             <ChipItem
               key={c.ref}
               checked={c.ref === draft.roleModel}
               onSelect={() => onChange({ roleModel: c.ref })}
-              hint={c.group}
+              disabled={!!whyNot(c)}
+              hint={whyNot(c) ?? c.group}
             >
               <span className="flex items-center gap-1.5">
                 <AvailabilityDot availability={c.availability} />

package/components/Models/AgentRoleCard.tsx

@@ -2,6 +2,7 @@
 
 import { AlertTriangle } from "lucide-react";
 import type { AgentRoleView } from "@/lib/models/agent-roles-view";
+import { analystBlock, defaultAnalystLabel } from "@/lib/models/usable";
 import { cn } from "@/lib/utils";
 import { RoleModelSelect } from "./RoleModelSelect";
 
@@ -33,7 +34,11 @@ export function AgentRoleCard({
   onFallback: (ref: string | null) => void;
 }) {
   const down = role.choice?.availability.state === "down";
-  const label = `Default (${role.default.split("/").slice(1).join("/")})`;
+  const analyst = role.id === "analyst";
+  const label = analyst
+    ? defaultAnalystLabel(role.default, [])
+    : `Default (${role.default.split("/").slice(1).join("/")})`;
+  const blockedBy = analyst ? analystBlock : undefined;
   const inheritLabel =
     scope === "settings"
       ? role.modelRole === "advise"
@@ -66,6 +71,7 @@ export function AgentRoleCard({
             ? `${inheritLabel} · ${role.binding.ref.split("/").slice(1).join("/")}`
             : inheritLabel
         }
+        blockedBy={blockedBy}
         disabled={pending}
         onChange={onChange}
       />
@@ -102,7 +108,8 @@ export function AgentRoleCard({
               id={`agent-role-fallback-${role.id}`}
               value={role.fallback}
               inheritLabel="None (don't fall back)"
-              claudeOnly
+              claudeOnly={!analyst}
+              blockedBy={blockedBy}
               disabled={pending}
               onChange={onFallback}
             />

package/components/Models/RoleModelSelect.tsx

@@ -15,25 +15,35 @@ import { AvailabilityDot, LocalityBadge } from "./ModelBadges";
 
 const INHERIT = "__inherit";
 
-function Row({ choice }: { choice: ModelChoice }) {
+function Row({ choice, why }: { choice: ModelChoice; why?: string | null }) {
   return (
-    <span className="flex min-w-0 flex-1 items-center gap-2">
-      <AvailabilityDot availability={choice.availability} />
-      <span className="truncate">{choice.label}</span>
-      <LocalityBadge locality={choice.locality} />
+    <span className="flex min-w-0 flex-1 flex-col">
+      <span className="flex min-w-0 items-center gap-2">
+        <AvailabilityDot availability={choice.availability} />
+        <span className="truncate">{choice.label}</span>
+        <LocalityBadge locality={choice.locality} />
+      </span>
+      {why && (
+        <span className="text-muted-foreground text-xs whitespace-normal">
+          {why}
+        </span>
+      )}
     </span>
   );
 }
 
 // A model picker over the server's list: grouped by provider, each model
 // labelled Local or Cloud with whether its server answers. `claudeOnly`
-// leaves out the models that run through Pi.
+// leaves out the models that run through Pi. `blockedBy` greys a model with
+// the reason it can't be picked instead of hiding it; a model whose provider
+// isn't set up is always greyed.
 export function RoleModelSelect({
   id,
   value,
   inheritLabel,
   claudeOnly,
   gateOnly,
+  blockedBy,
   disabled,
   onChange,
 }: {
@@ -43,11 +53,16 @@ export function RoleModelSelect({
   claudeOnly?: boolean;
   // Only models that can serve a merge gate are selectable.
   gateOnly?: boolean;
+  blockedBy?: (c: ModelChoice) => string | null;
   disabled?: boolean;
   onChange: (ref: string | null) => void;
 }) {
   const { data } = useModelChoices();
   const choices = (data ?? []).filter((c) => !claudeOnly || c.agent !== "pi");
+  const whyNot = (c: ModelChoice) =>
+    c.unusable ??
+    blockedBy?.(c) ??
+    (gateOnly && !c.gateCapable ? "Can't serve a merge gate" : null);
   const groups = [...new Set(choices.map((c) => c.group))];
   const current = value ? choices.find((c) => c.ref === value) : undefined;
   return (
@@ -73,10 +88,10 @@ export function RoleModelSelect({
                 <SelectItem
                   key={c.ref}
                   value={c.ref}
-                  disabled={gateOnly && !c.gateCapable}
+                  disabled={!!whyNot(c)}
                   className="min-h-11 md:min-h-0"
                 >
-                  <Row choice={c} />
+                  <Row choice={c} why={whyNot(c)} />
                 </SelectItem>
               ))}
           </SelectGroup>

package/lib/chat/events.ts

@@ -27,6 +27,8 @@ export interface ChatModel {
   value: string;
   label: string;
   description?: string;
+  // Why it can't be picked now; it is listed greyed with this.
+  disabled?: string;
 }
 
 export type ToolStatus = "running" | "done" | "error" | "stopped";

package/lib/chat/role-models.ts

@@ -0,0 +1,46 @@
+/**
+ * The model list in a role session's composer. A chat's own list is whatever
+ * its agent reports (for Claude Code, only Claude's aliases), so an analyst
+ * would never be offered Qwen, Pi's models or DeepSeek. An analyst's list is
+ * the server's one catalog instead, with each model it can't move to greyed
+ * and given the reason.
+ */
+
+import type { Session } from "../db";
+import { modelDisplayName } from "../model-catalog";
+import { modelCatalog, unconfiguredChoices } from "../models/catalog";
+import { PI } from "../models/providers";
+import { sessionModelRef } from "../models/resolve";
+import { ANTHROPIC } from "../models/roles";
+import { analystBlock } from "../models/usable";
+import type { ChatModel } from "./events";
+
+const isAnalystChat = (s: Session) =>
+  s.agent_role === "analyst" &&
+  (s.agent_type === "claude" || s.agent_type === "pi");
+
+// The session's model as a ref, which is what its list's values are.
+export const composerModelValue = (s: Session): string =>
+  s.agent_type === "pi" ? `${PI}/${s.model}` : sessionModelRef(s);
+
+export function roleComposerModels(
+  session: Session,
+  own: ChatModel[]
+): ChatModel[] {
+  if (!isAnalystChat(session)) return own;
+  const agent = session.agent_type === "pi" ? "pi" : "claude";
+  const list = [...modelCatalog(), ...unconfiguredChoices()].map(
+    (c): ChatModel => {
+      const disabled = analystBlock(c, { agent });
+      return {
+        value: c.ref,
+        label: c.ref.startsWith(`${ANTHROPIC}/`)
+          ? modelDisplayName(c.label)
+          : c.label,
+        description: c.group,
+        ...(disabled && { disabled }),
+      };
+    }
+  );
+  return list.length ? list : own;
+}

package/lib/chat/settings.ts

@@ -9,6 +9,7 @@ import { db, type Session } from "../db";
 import { agentEnv } from "../agents/launch";
 import { modelDisplayName, resolveModelForAgent } from "../model-catalog";
 import { chatDriverFor } from "./drivers";
+import { composerModelValue, roleComposerModels } from "./role-models";
 import {
   CHAT_ACCESS,
   type ChatAccess,
@@ -75,15 +76,17 @@ export function cachedCommands(session: Session): ChatCommand[] {
 export function emitCapabilities(session: Session, listener?: Listener): void {
   const caps = registry.caps.get(capsKey(session));
   if (!caps) return;
-  const model = chatModel(session);
+  const models = roleComposerModels(session, caps.models);
+  const model =
+    models === caps.models ? chatModel(session) : composerModelValue(session);
   const m: ChatServerMessage = {
     type: "capabilities",
     commands: visibleCommands(caps),
-    models: caps.models,
+    models,
     model,
     modelLabel:
-      caps.models.find((o) => o.value === model)?.label ??
-      modelDisplayName(model),
+      models.find((o) => o.value === model)?.label ??
+      modelDisplayName(chatModel(session)),
     access: effectiveChatAccess(session.chat_access),
     plan: canPlan(session) ? !!session.chat_plan && !noApprovalsOn() : null,
     background: chatDriverFor(session.agent_type)?.backgroundTasks === true,

package/lib/chat/socket.ts

@@ -24,12 +24,12 @@ import {
   sendChat,
   sendQueuedNow,
   setChatAccess,
-  setChatModel,
   setChatPlan,
   stopChatTask,
   undoChat,
   watchChat,
 } from "./runner";
+import { setComposerModel } from "../models/session-model";
 import { stopChatTurn } from "./stop";
 import { clientSend } from "./client-send";
 import { searchChat } from "./search";
@@ -189,7 +189,8 @@ function onChatMessage(
         .then(answer)
     );
   } else if (msg.type === "interrupt") run(stopChatTurn(sessionId));
-  else if (msg.type === "set_model") run(setChatModel(sessionId, msg.model));
+  else if (msg.type === "set_model")
+    run(setComposerModel(sessionId, msg.model));
   else if (msg.type === "set_access") run(setChatAccess(sessionId, msg.access));
   else if (msg.type === "set_plan") run(setChatPlan(sessionId, !!msg.plan));
   else if (msg.type === "refresh_commands") run(refreshCapabilities(sessionId));

package/lib/drafts.ts

@@ -35,6 +35,8 @@ export interface Draft {
   roleModel?: string | null;
   // Pair it with an analyst that reviews each turn (a local chat only).
   withAnalyst?: boolean;
+  // The analyst's model, "provider/model"; unset, the analyst role's.
+  analystModel?: string | null;
   // A task's priority in the queue; unset: normal.
   taskPriority?: Priority;
   createdAt: number;

package/lib/models/agent-binding.ts

@@ -9,6 +9,7 @@ import { AGENT_ROLE_DEFS, type AgentRole } from "./agent-roles";
 import { modelAvailability, choiceFor } from "./catalog";
 import { savedModelSettings } from "./config";
 import { PI } from "./providers";
+import { checkToolUse, ollamaOrigin } from "./tool-use";
 import { resolveRole, type RoleSource, type RoutedModel } from "./resolve";
 
 export interface RoleBinding {
@@ -50,6 +51,22 @@ export class ModelUnavailableError extends Error {
   }
 }
 
+// An analyst reads code and transcripts through tools: a model its server
+// says can't call them is refused, with the reason.
+export async function assertCanCallTools(
+  role: AgentRole,
+  ref: string
+): Promise<void> {
+  if (role !== "analyst") return;
+  const choice = choiceFor(ref);
+  if (!choice || choice.locality !== "local" || !choice.endpoint) return;
+  const model = choice.ref.split("/").slice(choice.agent === "pi" ? 2 : 1);
+  if (!(await checkToolUse(ollamaOrigin(choice.endpoint), model.join("/"))))
+    throw new Error(
+      `${choice.label} can't call tools; an analyst reads code through tools`
+    );
+}
+
 export interface RoleStart {
   role: AgentRole;
   routed: RoutedModel;
@@ -82,13 +99,17 @@ export async function prepareRoleStart(
 ): Promise<RoleStart> {
   const binding = bindingFor(role, opts);
   const state = await modelAvailability(binding.routed.ref);
-  if (state.state !== "down")
+  if (state.state !== "down") {
+    await assertCanCallTools(role, binding.routed.ref);
     return startFrom(role, binding.routed, binding.routed.source);
+  }
   if (opts.useFallback && binding.fallback) {
     const alt = bindingFor(role, { ...opts, override: binding.fallback });
     const altState = await modelAvailability(alt.routed.ref);
-    if (altState.state !== "down")
+    if (altState.state !== "down") {
+      await assertCanCallTools(role, alt.routed.ref);
       return startFrom(role, alt.routed, "fallback");
+    }
   }
   throw new ModelUnavailableError(
     role,

package/lib/models/catalog.ts

@@ -10,7 +10,8 @@ import os from "os";
 import path from "path";
 import { effectiveModels, type EffectiveModels } from "./config";
 import { ANTHROPIC } from "./roles";
-import { PI, type ModelProvider } from "./providers";
+import { PI, providerProblem, type ModelProvider } from "./providers";
+import { cachedToolUse, ollamaOrigin } from "./tool-use";
 import { hostLocality, type Locality } from "./locality";
 import {
   cachedAvailability,
@@ -31,6 +32,10 @@ export interface ModelChoice {
   availability: Availability;
   // May serve a merge gate: Claude Code can run it.
   gateCapable: boolean;
+  // May call tools, which an analyst needs (lib/models/tool-use).
+  toolUse: boolean;
+  // Why it can't be started at all (its provider is off or half set up).
+  unusable?: string;
   // Where the server is (never a key).
   endpoint?: string;
 }
@@ -84,6 +89,16 @@ export function piProviders(file = piModelsFile()): PiProvider[] {
 const providerEndpoint = (p: ModelProvider) =>
   p.baseUrl ? probeUrl(p.baseUrl, p.api) : undefined;
 
+// Anthropic's and cloud models can; a model on a local server is asked of it.
+const toolUseOf = (
+  baseUrl: string | undefined,
+  locality: Locality,
+  model: string
+) =>
+  baseUrl && locality === "local"
+    ? cachedToolUse(ollamaOrigin(baseUrl), model)
+    : true;
+
 export function modelCatalog(
   effective: EffectiveModels = effectiveModels(),
   pi: PiProvider[] = piProviders()
@@ -98,6 +113,7 @@ export function modelCatalog(
         : locality === "local" && endpoint
           ? cachedAvailability(endpoint)
           : { state: "unknown", checkedAt: null };
+    const unusable = providerProblem(p) ?? undefined;
     for (const m of p.models)
       out.push({
         ref: `${p.id}/${m}`,
@@ -107,6 +123,8 @@ export function modelCatalog(
         locality,
         availability,
         gateCapable: p.api === "anthropic",
+        toolUse: toolUseOf(p.baseUrl, locality, m),
+        ...(unusable && { unusable }),
         endpoint: p.baseUrl,
       });
   }
@@ -126,12 +144,36 @@ export function modelCatalog(
         locality,
         availability,
         gateCapable: false,
+        toolUse: toolUseOf(p.baseUrl, locality, m.id),
         endpoint: p.baseUrl,
       });
   }
   return out;
 }
 
+// The models of providers that are turned off, so a picker can show them
+// greyed with the reason rather than leave them out.
+export function unconfiguredChoices(
+  effective: EffectiveModels = effectiveModels()
+): ModelChoice[] {
+  return effective.providers
+    .filter((p) => !p.enabled)
+    .flatMap((p) =>
+      p.models.map((m) => ({
+        ref: `${p.id}/${m}`,
+        label: m,
+        group: p.label,
+        agent: "claude" as const,
+        locality: hostLocality(p.baseUrl),
+        availability: { state: "unknown" as const, checkedAt: null },
+        gateCapable: false,
+        toolUse: true,
+        unusable: providerProblem(p) ?? undefined,
+        endpoint: p.baseUrl,
+      }))
+    );
+}
+
 export const choiceFor = (
   ref: string,
   effective?: EffectiveModels

package/lib/models/providers.ts

@@ -50,6 +50,18 @@ export interface ModelPrice {
   output: number;
 }
 
+// Why a provider can't run a Claude Code session, or null when it can.
+export function providerProblem(p: ModelProvider): string | null {
+  if (!p.enabled) return `The ${p.label} provider is turned off`;
+  // Anthropic runs on the Claude login: no URL or key of ours.
+  if (p.id === ANTHROPIC) return null;
+  if (!p.baseUrl || !p.auth)
+    return `The ${p.label} provider needs a base URL and a key`;
+  if (p.api !== "anthropic")
+    return `${p.label} speaks the OpenAI API; Claude Code needs an Anthropic-compatible endpoint`;
+  return null;
+}
+
 export const ANTHROPIC_PROVIDER: ModelProvider = {
   id: ANTHROPIC,
   label: "Anthropic (Claude login)",

package/lib/models/resolve.ts

@@ -21,6 +21,7 @@ import {
   ANTHROPIC_PROVIDER,
   PI,
   PI_PROVIDER,
+  providerProblem,
   type ModelProvider,
 } from "./providers";
 import {
@@ -111,13 +112,8 @@ export function providerFor(
   }
   const p = models.providers.find((x) => x.id === id);
   if (!p) throw new Error(`No model provider "${id}" (Settings > Models)`);
-  if (!p.enabled) throw new Error(`The ${p.label} provider is turned off`);
-  if (!p.baseUrl || !p.auth)
-    throw new Error(`The ${p.label} provider needs a base URL and a key`);
-  if (p.api !== "anthropic")
-    throw new Error(
-      `${p.label} speaks the OpenAI API; Claude Code needs an Anthropic-compatible endpoint`
-    );
+  const problem = providerProblem(p);
+  if (problem) throw new Error(problem);
   return p;
 }
 

package/lib/models/session-model.ts

@@ -7,10 +7,18 @@
  */
 
 import { db, type Session } from "../db";
-import { registry } from "../chat/registry";
-import { setChatModel } from "../chat/settings";
-import { setSessionModel, type RoutedModel } from "./resolve";
-import { ANTHROPIC } from "./roles";
+import { getSession, registry } from "../chat/registry";
+import { emitCapabilities, setChatModel } from "../chat/settings";
+import {
+  providerFor,
+  sessionRole,
+  setSessionModel,
+  type RoutedModel,
+} from "./resolve";
+import { PI } from "./providers";
+import { isAgentRole } from "./agent-roles";
+import { assertCanCallTools } from "./agent-binding";
+import { ANTHROPIC, formatModelRef, parseModelRef } from "./roles";
 
 export async function switchSessionModel(
   sessionId: string,
@@ -38,3 +46,61 @@ export async function applySessionModel(
   if (registry.live.has(sessionId))
     (await import("../chat/runner")).stopChat(sessionId);
 }
+
+// Moves a session to "provider/model" (or "pi/<provider>/<model>" for a Pi
+// session), keeping its conversation. Only this session's row changes: no
+// other session's model and no role setting.
+export async function switchSessionModelRef(
+  session: Session,
+  ref: string
+): Promise<void> {
+  const parsed = parseModelRef(ref);
+  if (isAgentRole(session.agent_role))
+    await assertCanCallTools(session.agent_role, formatModelRef(parsed));
+  if (session.agent_type === "pi") {
+    if (parsed.provider !== PI)
+      throw new Error(
+        "A Pi session runs on a Pi model (pi/<provider>/<model>)"
+      );
+    await setChatModel(session.id, parsed.model);
+    return;
+  }
+  if (parsed.provider === PI)
+    throw new Error("Only a Pi session can move to a Pi model");
+  await switchSessionModel(session.id, {
+    role: sessionRole(session),
+    ref: formatModelRef(parsed),
+    provider: providerFor(parsed.provider),
+    model: parsed.model,
+    source: "task",
+  });
+}
+
+// A pick in a chat's model list. A full ref ("provider/model") moves the
+// session across providers; a bare model on a session routed to another
+// provider goes back to Anthropic, so "opus" is never asked of another
+// provider's endpoint. Anything else is the agent's own model name.
+export async function setComposerModel(
+  sessionId: string,
+  value: string
+): Promise<void> {
+  const session = db
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
+    .get(sessionId) as Session | undefined;
+  const model = value.trim();
+  if (!session || !model) return;
+  const claude = session.agent_type === "claude";
+  const ref = claude
+    ? model.includes("/")
+      ? model
+      : session.model_provider
+        ? `${ANTHROPIC}/${model}`
+        : null
+    : session.agent_type === "pi" && model.startsWith(`${PI}/`)
+      ? model
+      : null;
+  if (!ref) return setChatModel(sessionId, model);
+  await switchSessionModelRef(session, ref);
+  // A move across providers stops the worker, which tells nobody.
+  emitCapabilities(getSession(sessionId));
+}

package/lib/models/tool-use.ts

@@ -0,0 +1,78 @@
+/**
+ * Whether a model can call tools, which an analyst needs to read code and
+ * transcripts. There is no list of it to read, so the server asks: an Ollama
+ * server reports each model's capabilities (POST /api/show), and one that
+ * answers without "tools" is out. Anything that can't be told (a server with
+ * no such endpoint, one that doesn't answer, a cloud provider) counts as
+ * able: Pi turns text tool calls into real ones, and hiding a model we can't
+ * judge is worse than letting it try. Cached, and never awaited by a request
+ * handler unless it asks to.
+ */
+
+const TTL_MS = 10 * 60_000;
+const TIMEOUT_MS = 1_500;
+
+interface Entry {
+  toolUse: boolean;
+  at: number;
+}
+const cache = new Map<string, Entry>();
+const probing = new Map<string, Promise<boolean>>();
+
+// Where Ollama's own API lives for an OpenAI- or Anthropic-style base URL.
+export const ollamaOrigin = (baseUrl: string): string =>
+  baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+
+const key = (origin: string, model: string) => `${origin}\n${model}`;
+
+async function probe(origin: string, model: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${origin}/api/show`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      redirect: "manual",
+    });
+    if (!res.ok) return true;
+    const body = (await res.json()) as { capabilities?: unknown };
+    return Array.isArray(body.capabilities)
+      ? body.capabilities.includes("tools")
+      : true;
+  } catch {
+    return true;
+  }
+}
+
+// The last answer, probing in the background when it is stale.
+export function cachedToolUse(origin: string, model: string): boolean {
+  const k = key(origin, model);
+  const hit = cache.get(k);
+  if (!hit || Date.now() - hit.at >= TTL_MS) void checkToolUse(origin, model);
+  return hit?.toolUse ?? true;
+}
+
+export async function checkToolUse(
+  origin: string,
+  model: string
+): Promise<boolean> {
+  const k = key(origin, model);
+  const hit = cache.get(k);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit.toolUse;
+  let running = probing.get(k);
+  if (!running) {
+    running = probe(origin, model)
+      .then((toolUse) => {
+        cache.set(k, { toolUse, at: Date.now() });
+        return toolUse;
+      })
+      .finally(() => probing.delete(k));
+    probing.set(k, running);
+  }
+  return running;
+}
+
+export function clearToolUse(): void {
+  cache.clear();
+  probing.clear();
+}

package/lib/models/usable.ts

@@ -0,0 +1,45 @@
+/**
+ * Why a model in the server's list can't be picked for a role, and the name
+ * a role's default shows. Imported by the browser too, so no Node modules.
+ */
+
+import { modelDisplayName } from "../model-catalog";
+import { ANTHROPIC } from "./roles";
+import type { ModelChoice } from "./catalog";
+
+// Why a model can't be picked for an analyst, or null when it can. An
+// analyst reads code and transcripts through tools, so a model that can't
+// call them is out; one whose server isn't answering is too.
+export function analystBlock(
+  c: Pick<ModelChoice, "unusable" | "toolUse" | "availability" | "agent">,
+  opts: { agent?: "claude" | "pi" } = {}
+): string | null {
+  if (c.unusable) return c.unusable;
+  if (!c.toolUse) return "Can't call tools";
+  if (c.availability.state === "down")
+    return c.availability.error
+      ? `Not answering (${c.availability.error})`
+      : "Not answering";
+  if (opts.agent && c.agent !== opts.agent)
+    return c.agent === "pi"
+      ? "Runs on Pi: start a new analyst on it"
+      : "Runs on Claude Code: start a new analyst on it";
+  return null;
+}
+
+// "Opus 5.5" for an Anthropic ref, the list's own label for any other.
+export function defaultModelName(
+  ref: string | null | undefined,
+  choices: Pick<ModelChoice, "ref" | "label">[]
+): string {
+  if (!ref) return "…";
+  const found = choices.find((c) => c.ref === ref);
+  if (ref.startsWith(`${ANTHROPIC}/`))
+    return modelDisplayName(ref.slice(ANTHROPIC.length + 1));
+  return found?.label ?? ref.split("/").slice(1).join("/");
+}
+
+export const defaultAnalystLabel = (
+  ref: string | null | undefined,
+  choices: Pick<ModelChoice, "ref" | "label">[]
+) => `Default analyst model (${defaultModelName(ref, choices)})`;

package/package.json

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