feat(sessions): accept a per-session Claude model on POST /api/sessions

POST /api/sessions takes an optional `model`, and a Claude session
launches with `claude --model <id>`. It wins over the app-wide default
model and writes nothing to disk, unlike `modelOverride`, which stays as
it is and still writes the case's .claude/settings.local.json.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

plugins/codeman/skills/codeman/reference/endpoints.md

@@ -384,7 +384,8 @@ every claude create path installs them, so a linked case and a raw path both get
 
 **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in
 a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`,
-`envOverrides`). Three differences that break copied code:
+`envOverrides`, and for claude a per-session `model` passed as `--model`). Three
+differences that break copied code:
 
 - The id is at **`.data.session.id`**, not quick-start's `.data.sessionId`
   (`session-routes.ts:878` returns `{ session: lightState }`).

skills/codeman/reference/endpoints.md

@@ -384,7 +384,8 @@ every claude create path installs them, so a linked case and a raw path both get
 
 **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in
 a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`,
-`envOverrides`). Three differences that break copied code:
+`envOverrides`, and for claude a per-session `model` passed as `--model`). Three
+differences that break copied code:
 
 - The id is at **`.data.session.id`**, not quick-start's `.data.sessionId`
   (`session-routes.ts:878` returns `{ session: lightState }`).

src/web/routes/session-routes.ts

@@ -1073,9 +1073,10 @@ export function registerSessionRoutes(
     // genuinely different mechanisms:
     //   'flag'                 — the CLI takes --model, so read the value the caller sent
     //                            in that CLI's own config object.
-    //   'claude-settings-file' — claude alone, whose model is written to
-    //                            <case>/.claude/settings.local.json rather than passed as
-    //                            a flag, so the app-wide default applies here.
+    //   'claude-settings-file' — claude alone, whose persistent model is written to
+    //                            <case>/.claude/settings.local.json (`modelOverride`). A
+    //                            per-session `model` from the caller goes out as --model and
+    //                            wins; without one, the app-wide default applies.
     //   'none'                 — shell has no model; deepseek's is a composition entry in
     //                            the profile's config tree, not a session field
     //                            (docs/deepseek-integration.md). Both get nothing.
@@ -1086,7 +1087,7 @@ export function registerSessionRoutes(
             | string
             | undefined)
         : modelSource?.source === 'claude-settings-file'
-          ? modelConfig?.defaultModel || undefined
+          ? body.model || modelConfig?.defaultModel || undefined
           : undefined;
     const claudeModeConfig = await ctx.getClaudeModeConfig();
     // Section 6.3: force non-granted users to a classifier-guarded mode.

src/web/schemas.ts

@@ -526,6 +526,16 @@ export const CreateSessionSchema = z.object({
   effort: effortLevelSchema,
   /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
   modelOverride: z.string().max(50).optional(),
+  /**
+   * Claude model for THIS session only, passed as `claude --model <id>`; nothing is written to
+   * disk. Wins over the app-wide default model. Same character set as the registry's
+   * `model-claude` pattern, so a value accepted here is never rejected at launch.
+   */
+  model: z
+    .string()
+    .max(100)
+    .regex(/^[a-zA-Z0-9._\-[\]]+$/)
+    .optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
   geminiConfig: GeminiConfigSchema,

test/routes/session-routes-claude-model.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview `model` on POST /api/sessions — a Claude model for one session only.
+ *
+ * Claude's model reaches disk only through `modelOverride`, which writes it into the
+ * case's `.claude/settings.local.json` for every later run there. `model` is the
+ * per-session counterpart: it goes out as `claude --model <id>`, wins over the app-wide
+ * default, and writes nothing. What the tests read is the model the session hands the
+ * mux when it starts, which is what becomes the `--model` flag.
+ *
+ * Uses app.inject(), so no real HTTP port is needed.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+
+interface Harness {
+  app: FastifyInstance;
+  ctx: MockRouteContext;
+}
+
+async function createHarness(): Promise<Harness> {
+  const app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  const ctx = createMockRouteContext();
+  registerSessionRoutes(app, ctx);
+  installRouteErrorHandler(app);
+  await app.ready();
+  return { app, ctx };
+}
+
+describe('POST /api/sessions model', () => {
+  let workingDir: string;
+  let harness: Harness;
+
+  beforeEach(async () => {
+    workingDir = await mkdtemp(join(tmpdir(), 'codeman-session-model-'));
+    harness = await createHarness();
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    await rm(workingDir, { recursive: true, force: true });
+  });
+
+  /** Creates a session and starts it, then returns the model it handed the mux. */
+  async function launchedModel(payload: Record<string, unknown>): Promise<unknown> {
+    const res = await harness.app.inject({ method: 'POST', url: '/api/sessions', payload: { workingDir, ...payload } });
+    expect(res.statusCode).toBe(200);
+    const parsed = JSON.parse(res.body);
+    const id = (parsed.data?.session ?? parsed.session).id as string;
+    await harness.app.inject({ method: 'POST', url: `/api/sessions/${id}/interactive`, payload: {} });
+    const calls = harness.ctx.mux.createSession.mock.calls;
+    expect(calls.length).toBeGreaterThan(0);
+    return (calls[calls.length - 1][0] as { model?: string }).model;
+  }
+
+  it('launches a Claude session on the model the caller names', async () => {
+    expect(await launchedModel({ mode: 'claude', model: 'claude-fable-5-1' })).toBe('claude-fable-5-1');
+  });
+
+  it('wins over the app-wide default model', async () => {
+    harness.ctx.getModelConfig.mockResolvedValue({ defaultModel: 'sonnet' });
+    expect(await launchedModel({ mode: 'claude', model: 'opus' })).toBe('opus');
+  });
+
+  it('leaves the app-wide default in charge when the caller names none', async () => {
+    harness.ctx.getModelConfig.mockResolvedValue({ defaultModel: 'sonnet' });
+    expect(await launchedModel({ mode: 'claude' })).toBe('sonnet');
+  });
+
+  it('writes no model into the case directory', async () => {
+    // The create still installs Codeman's workspace hooks into settings.local.json, so the
+    // file exists; what must not be in it is a model that would outlive this session.
+    await launchedModel({ mode: 'claude', model: 'opus' });
+    const settings = await readFile(join(workingDir, '.claude', 'settings.local.json'), 'utf8').catch(() => '{}');
+    expect(JSON.parse(settings)).not.toHaveProperty('model');
+  });
+
+  it('rejects a model with characters the launch pattern refuses', async () => {
+    const res = await harness.app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      payload: { workingDir, mode: 'claude', model: 'opus; rm -rf ~' },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+});