@retasc/cli 1.41.1 → 1.42.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.42.0 (2026-09-05)
+
+- **RTSC-821** — a session now reports WHICH MODEL ran it. The MCP handshake carries the
+  client's name and version only, which is the CLI build and not the model, so this could
+  never have come from the connection: `retasc hook session-start` now passes the
+  SessionStart payload's `model` (plus `agent_type` and `agent_id` when the session is a
+  subagent) alongside the transcript id, and the Dash's session panel names it.
+- A second hook, `retasc hook model-switch`, is wired on `PostModelSwitch`, so changing
+  model mid-conversation reaches the Dash and it can say what the session started on.
+  `retasc setup` wires both in one write. It deliberately does NOT touch the record's
+  timestamp: that is the window that stops an old record being adopted by a later session
+  in the same folder, and a switch an hour in must not make an hour-old record look new.
+- The proxy keeps watching for a model change after the id is recorded, under the same
+  bounded budget it already had, so a session that switches model on every turn still
+  cannot make it talk to the server on every turn.
+- Absent stays ordinary. Claude Code omits `model` from some payloads and Codex, Gemini,
+  Cursor and OpenCode have no session hook at all, so a junk or missing model is dropped
+  rather than raised, and never costs the transcript id it travelled with.
+
 ## 1.41.1 (2026-09-04)
 
 - **RTSC-812** — no runtime change. Two comments in `cli/src` said project deletion did

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { findBindingByPath } from "./lib/keystore.js";
-import { parseClaudeHookInput, writeHookRecord } from "./lib/sessionHook.js";
+import { parseClaudeHookInput, parseClaudeModelSwitchInput, updateHookRecordModel, writeHookRecord } from "./lib/sessionHook.js";
 import { Command } from "commander";
 import { VERSION } from "./version.js";
 import { selfCommand, versionStamp } from "./lib/launcher.js";
@@ -614,7 +614,18 @@ hook
             chunks.push(c);
         const parsed = parseClaudeHookInput(Buffer.concat(chunks).toString("utf8"));
         if (parsed && findBindingByPath(parsed.cwd)) {
-            writeHookRecord({ harness: "claude-code", sessionId: parsed.sessionId, cwd: parsed.cwd, at: Date.now() });
+            // RTSC-821 — model/agentType/agentId ride along when the payload has them.
+            // Claude Code omits `model` from some payloads, so the record simply carries
+            // less; the id is what makes the record worth writing.
+            writeHookRecord({
+                harness: "claude-code",
+                sessionId: parsed.sessionId,
+                cwd: parsed.cwd,
+                at: Date.now(),
+                ...(parsed.model ? { model: parsed.model } : {}),
+                ...(parsed.agentType ? { agentType: parsed.agentType } : {}),
+                ...(parsed.agentId ? { agentId: parsed.agentId } : {}),
+            });
         }
     }
     catch {
@@ -624,6 +635,31 @@ hook
         process.exitCode = 0;
     }
 });
+// RTSC-821 — `/model` mid-conversation. Rewrites the model on this folder's record and
+// nothing else; the proxy notices and re-reports. Deliberately does NOT touch `at`: that
+// is the window that stops an old record being adopted by a later session, and a switch
+// an hour in must not make an hour-old record look new.
+hook
+    .command("model-switch")
+    .description("Claude Code PostModelSwitch hook: update this session's model for the proxy.")
+    .action(async () => {
+    try {
+        if (process.stdin.isTTY)
+            return;
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        const parsed = parseClaudeModelSwitchInput(Buffer.concat(chunks).toString("utf8"));
+        if (parsed && findBindingByPath(parsed.cwd))
+            updateHookRecordModel(parsed.cwd, parsed.model, parsed.sessionId);
+    }
+    catch {
+        /* never fail the harness's model switch */
+    }
+    finally {
+        process.exitCode = 0;
+    }
+});
 // Top-level alias so harness config can spawn `retasc mcp-proxy`.
 program
     .command("mcp-proxy", { hidden: true })

package/dist/lib/session.js

@@ -157,7 +157,13 @@ export async function recordSession(opts) {
         ...opts,
         id: RPC_ID.recordSession,
         name: "record_session",
-        args: { transcriptId: opts.transcriptId, ...(opts.harness ? { harness: opts.harness } : {}) },
+        args: {
+            transcriptId: opts.transcriptId,
+            ...(opts.harness ? { harness: opts.harness } : {}),
+            ...(opts.model ? { model: opts.model } : {}),
+            ...(opts.agentType ? { agentType: opts.agentType } : {}),
+            ...(opts.agentId ? { agentId: opts.agentId } : {}),
+        },
         expect: "transcriptId",
     });
     return out === "ok";

package/dist/lib/sessionHook.js

@@ -95,7 +95,52 @@ export function readHookRecord(cwd, opts = {}) {
         return null;
     if (opts.notAfter !== undefined && rec.at > opts.notAfter)
         return null;
-    return rec;
+    // RTSC-821 — a junk model must not take the record down with it: the id is the
+    // valuable part and the model is a bonus, so a bad one is dropped, not fatal.
+    return {
+        harness: rec.harness,
+        sessionId: rec.sessionId,
+        cwd: rec.cwd,
+        at: rec.at,
+        ...(ident(rec.model, 60) ? { model: ident(rec.model, 60) } : {}),
+        ...(ident(rec.agentType, 60) ? { agentType: ident(rec.agentType, 60) } : {}),
+        ...(ident(rec.agentId, 100) ? { agentId: ident(rec.agentId, 100) } : {}),
+    };
+}
+/**
+ * Rewrite the model on the record for this folder, in place (RTSC-821).
+ *
+ * `at` is deliberately LEFT ALONE. It is the freshness window that stops a record
+ * written for an earlier session being adopted by a later one, and a `/model` switch
+ * an hour into a conversation must not make an hour-old record look new. A switch in a
+ * folder with no record is a no-op: there is no session here to describe.
+ *
+ * `sessionId` is REQUIRED to match when the record has one. The file is keyed by FOLDER
+ * (`hookFilePath` is a hash of the cwd, nothing else), so two Claude Code sessions open
+ * in one directory share it: without this check, resuming or switching in session B
+ * would rewrite the model that session A's still-live proxy is about to report, and A
+ * would stamp B's model onto its own key. `PostModelSwitch` also fires on `resume`,
+ * which makes that a routine event rather than a race you would have to try for.
+ */
+export function updateHookRecordModel(cwd, model, sessionId, dir = sessionsDir()) {
+    const path = hookFilePath(cwd, dir);
+    try {
+        if (!existsSync(path))
+            return false;
+        const rec = JSON.parse(readFileSync(path, "utf8"));
+        if (!rec || typeof rec !== "object" || typeof rec.at !== "number")
+            return false;
+        // A payload with no session id cannot prove ownership, so it does not get to write.
+        if (!sessionId || rec.sessionId !== sessionId)
+            return false;
+        if (rec.model === model)
+            return false;
+        writeFileSync(path, JSON.stringify({ ...rec, model }), { mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /** Consume a record once it has been reported, so no later session can adopt it. */
 export function clearHookRecord(cwd, dir = sessionsDir()) {
@@ -106,11 +151,24 @@ export function clearHookRecord(cwd, dir = sessionsDir()) {
         /* already gone */
     }
 }
+/** The shape the server accepts, checked here so a junk value never leaves the machine
+ *  (RTSC-821). Same charset as the transcript id: the Dash renders these. */
+function ident(raw, max) {
+    if (typeof raw !== "string")
+        return undefined;
+    const t = raw.trim();
+    if (!t)
+        return undefined;
+    return new RegExp(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,${max - 1}}$`).test(t) ? t : undefined;
+}
 /**
  * Parse what Claude Code hands a SessionStart hook on stdin. Verified against the hooks
  * reference (2026-09-04): `session_id`, `transcript_path`, `cwd`, `hook_event_name`,
- * `source`. Only the id and the cwd are kept; the path is derivable and would bake in a
- * username (RTSC-791).
+ * `source`, and `model` / `agent_id` / `agent_type` when it has them. The transcript
+ * path is NOT kept: it is derivable and would bake in a username (RTSC-791).
+ *
+ * `model` is absent from some payloads by design, so a parse that finds an id and no
+ * model is a SUCCESS carrying less, never a failure.
  */
 export function parseClaudeHookInput(stdin) {
     let j;
@@ -124,10 +182,45 @@ export function parseClaudeHookInput(stdin) {
     const cwd = typeof j?.cwd === "string" && j.cwd ? j.cwd : process.cwd();
     if (!sessionId)
         return null;
-    return { sessionId, cwd };
+    return {
+        sessionId,
+        cwd,
+        ...(ident(j?.model, 60) ? { model: ident(j.model, 60) } : {}),
+        ...(ident(j?.agent_type, 60) ? { agentType: ident(j.agent_type, 60) } : {}),
+        ...(ident(j?.agent_id, 100) ? { agentId: ident(j.agent_id, 100) } : {}),
+    };
+}
+/**
+ * Parse a `PostModelSwitch` payload (RTSC-821): `to_model` is the model from now on.
+ * `cwd` is the folder, as with SessionStart. `session_id` is present but deliberately
+ * NOT used to re-key the record: the switch updates the record for THIS folder in
+ * place, and re-arming it is exactly what must not happen (see `updateHookRecordModel`).
+ */
+export function parseClaudeModelSwitchInput(stdin) {
+    let j;
+    try {
+        j = JSON.parse(stdin);
+    }
+    catch {
+        return null;
+    }
+    const model = ident(j?.to_model, 60);
+    if (!model)
+        return null;
+    return {
+        model,
+        cwd: typeof j?.cwd === "string" && j.cwd ? j.cwd : process.cwd(),
+        ...(ident(j?.session_id, 200) ? { sessionId: ident(j.session_id, 200) } : {}),
+    };
 }
 // --- wiring the Claude Code hook ---------------------------------------------------
 export const HOOK_MARKER = "hook session-start";
+/** RTSC-821 — the second hook. It must be a marker `HOOK_MARKER` cannot match and that
+ *  cannot match `HOOK_MARKER`, or idempotence would see one entry as the other and
+ *  rewrite a SessionStart hook into a model-switch one on the next `retasc setup`.
+ *  "hook session-start" and "hook model-switch" share no substring, which is the
+ *  property being relied on; a future third hook must keep it. */
+export const MODEL_HOOK_MARKER = "hook model-switch";
 /** A shell word: bare when it is plainly one, single-quoted otherwise. Claude Code runs
  *  hook commands through a shell, and an absolute launcher path can carry a space
  *  (`/Users/John Doe/...`); unquoted, the hook would fail on every session start and
@@ -138,8 +231,8 @@ export function shellWord(part) {
 /** The command the hook runs: the same launcher the MCP marker names, so an `npx`
  *  install and a global one both resolve. The marker verb stays bare, so idempotence
  *  can find the entry by it. */
-export function claudeHookCommand(launcher) {
-    return [...[launcher.command, ...launcher.args].map(shellWord), HOOK_MARKER].join(" ");
+export function claudeHookCommand(launcher, marker = HOOK_MARKER) {
+    return [...[launcher.command, ...launcher.args].map(shellWord), marker].join(" ");
 }
 /**
  * Merge our SessionStart hook into a Claude Code `settings.json` text, and say what
@@ -148,7 +241,12 @@ export function claudeHookCommand(launcher) {
  * other hook, and every other setting, survives untouched. Returns null when the file
  * is not JSON we can read, rather than replacing something we cannot parse.
  */
-export function mergeClaudeHook(text, command) {
+export function mergeClaudeHook(text, command, opts = {}) {
+    const event = opts.event ?? "SessionStart";
+    const marker = opts.marker ?? HOOK_MARKER;
+    // SessionStart is matched on the session's SOURCE; PostModelSwitch has no source to
+    // match, and an empty matcher there means every switch (RTSC-821).
+    const matcher = opts.matcher ?? "startup|resume";
     let settings = {};
     if (text && text.trim()) {
         try {
@@ -161,7 +259,7 @@ export function mergeClaudeHook(text, command) {
             return null;
     }
     const hooks = (settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {});
-    const list = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    const list = Array.isArray(hooks[event]) ? hooks[event] : [];
     let outcome = "unchanged";
     let found = false;
     for (const entry of list) {
@@ -169,7 +267,7 @@ export function mergeClaudeHook(text, command) {
         if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks))
             continue;
         for (const h of entry.hooks) {
-            if (h && typeof h === "object" && h.type === "command" && typeof h.command === "string" && h.command.includes(HOOK_MARKER)) {
+            if (h && typeof h === "object" && h.type === "command" && typeof h.command === "string" && h.command.includes(marker)) {
                 found = true;
                 if (h.command !== command) {
                     h.command = command;
@@ -182,10 +280,10 @@ export function mergeClaudeHook(text, command) {
         // `startup|resume` only: a compaction or a /clear re-fires SessionStart with the
         // same id and would re-arm the record for a session already served. `timeout` in
         // seconds: a hook that hangs (a cold npx offline) must never hold a session start.
-        list.push({ matcher: "startup|resume", hooks: [{ type: "command", command, timeout: 10 }] });
+        list.push({ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command, timeout: 10 }] });
         outcome = "added";
     }
-    hooks.SessionStart = list;
+    hooks[event] = list;
     settings.hooks = hooks;
     return { text: JSON.stringify(settings, null, 2) + "\n", outcome };
 }
@@ -222,12 +320,23 @@ export function claudeSettingsPath(home = process.env.RETASC_HOME || homedir())
 export function wireClaudeHook(launcher, home) {
     const path = claudeSettingsPath(home);
     const before = existsSync(path) ? readFileSync(path, "utf8") : null;
-    const merged = mergeClaudeHook(before, claudeHookCommand(launcher));
-    if (!merged)
+    const start = mergeClaudeHook(before, claudeHookCommand(launcher));
+    if (!start)
+        return { ok: false, reason: `${path} is not JSON I can read; add the hook by hand` };
+    // RTSC-821 — the model-switch hook is merged into the SAME text, so one write lands
+    // both and a failure between them cannot leave a half-wired machine.
+    const both = mergeClaudeHook(start.text, claudeHookCommand(launcher, MODEL_HOOK_MARKER), {
+        event: "PostModelSwitch",
+        marker: MODEL_HOOK_MARKER,
+        matcher: "",
+    });
+    if (!both)
         return { ok: false, reason: `${path} is not JSON I can read; add the hook by hand` };
-    if (merged.outcome !== "unchanged") {
+    // Either hook changing is a change worth writing; "unchanged" only when both agree.
+    const outcome = start.outcome !== "unchanged" ? start.outcome : both.outcome;
+    if (outcome !== "unchanged") {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, merged.text);
+        writeFileSync(path, both.text);
     }
-    return { ok: true, path, outcome: merged.outcome };
+    return { ok: true, path, outcome };
 }

package/dist/proxy.js

@@ -57,6 +57,12 @@ const PROXY_STARTED_AT = Date.now();
 const TRANSCRIPT_LOOKUPS_MAX = 40;
 let transcript = process.env.GROK_SESSION_ID ? { id: process.env.GROK_SESSION_ID, harness: "grok" } : null;
 let transcriptRecorded = false;
+// RTSC-821 — the model we last told the server. A `/model` mid-session rewrites the
+// hook record, and re-reporting is how that reaches the Dash, so recording the id is no
+// longer the end of this proxy's interest in the record.
+let reportedModel;
+let lastModelCheckAt = 0;
+const MODEL_CHECK_INTERVAL_MS = 3_000;
 let transcriptLookups = 0;
 let transcriptInFlight = null;
 // The name the client gave at `initialize` (RTSC-717), so a Codex session started in a
@@ -198,7 +204,11 @@ async function adoptSessionKey() {
  * wired no hook simply never learns its id, and the Dash says so.
  */
 async function reportTranscript() {
-    if (transcriptRecorded || sessionKeyFallback || activeKey === KEY)
+    if (sessionKeyFallback || activeKey === KEY)
+        return;
+    // Once the id is recorded there is still one reason to come back: the model changed.
+    // Grok reports no model at all, so a grok session stops here exactly as before.
+    if (transcriptRecorded && (transcript?.harness === "grok" || !modelMayHaveChanged()))
         return;
     // Startup and the first forwarded call can both get here; one report at a time.
     if (transcriptInFlight)
@@ -206,12 +216,63 @@ async function reportTranscript() {
     transcriptInFlight = reportTranscriptOnce().finally(() => { transcriptInFlight = null; });
     return transcriptInFlight;
 }
+/**
+ * The record for this folder, but only if it is still describing OUR session (RTSC-821).
+ *
+ * The file is keyed by FOLDER alone, so a second session opened in the same directory
+ * overwrites it with its own id and model. `at` cannot separate them here: a switch
+ * deliberately leaves it untouched, so freshness says nothing on this path. The session
+ * id is the only thing that does, and it is what the discovery path already matched on.
+ */
+function ownRecordModel() {
+    if (!transcript)
+        return undefined;
+    // `maxAgeMs: Infinity` on purpose: a switch hours into a long conversation leaves `at`
+    // where it was, so re-checking freshness would make exactly the case this exists for
+    // invisible. The id check below is what makes dropping it safe.
+    const rec = readHookRecord(process.cwd(), { maxAgeMs: Number.POSITIVE_INFINITY });
+    if (!rec || rec.sessionId !== transcript.id)
+        return undefined;
+    return rec.model;
+}
+/**
+ * Has the hook rewritten our record's model since we last reported one? (RTSC-821.)
+ *
+ * Throttled in TIME, not by the lookup budget: the budget is only spent when there is
+ * something to report, so in the steady state (the model never changes) nothing would
+ * ever increment it and every forwarded tool call would pay a realpath + hash + read +
+ * parse on the response path. A switch is a human pressing keys; three seconds of
+ * latency on noticing one is free, and a busy session makes hundreds of calls in that
+ * window.
+ */
+function modelMayHaveChanged() {
+    if (transcriptLookups >= TRANSCRIPT_LOOKUPS_MAX)
+        return false;
+    const now = Date.now();
+    if (now - lastModelCheckAt < MODEL_CHECK_INTERVAL_MS)
+        return false;
+    lastModelCheckAt = now;
+    const model = ownRecordModel();
+    return !!model && model !== reportedModel;
+}
 async function reportTranscriptOnce() {
     // One budget for looking AND for asking: a server that keeps refusing is not asked
     // on every call for the rest of the session either.
     if (transcriptLookups >= TRANSCRIPT_LOOKUPS_MAX)
         return;
     transcriptLookups += 1;
+    if (transcriptRecorded) {
+        // Recorded already, so we are here only for a model change — and only for OURS.
+        const model = ownRecordModel();
+        if (!model || model === reportedModel || !transcript)
+            return;
+        const switched = await recordSession({ url: MCP_URL, key: activeKey, transcriptId: transcript.id, harness: transcript.harness, model, warn: log });
+        if (switched) {
+            reportedModel = model;
+            log(`session model is now ${model}`);
+        }
+        return;
+    }
     if (!transcript) {
         const now = Date.now();
         if (now - PROXY_STARTED_AT > RECORD_SEARCH_MS) {
@@ -232,14 +293,34 @@ async function reportTranscriptOnce() {
         // harness, not our record (a Codex pane opened in a folder a Claude hook wrote for).
         if (rec.harness === "claude-code" && clientName && !/claude/i.test(clientName))
             return;
-        transcript = { id: rec.sessionId, harness: rec.harness };
-    }
-    const ok = await recordSession({ url: MCP_URL, key: activeKey, transcriptId: transcript.id, harness: transcript.harness, warn: log });
+        transcript = { id: rec.sessionId, harness: rec.harness, model: rec.model, agentType: rec.agentType, agentId: rec.agentId };
+    }
+    const ok = await recordSession({
+        url: MCP_URL,
+        key: activeKey,
+        transcriptId: transcript.id,
+        harness: transcript.harness,
+        model: transcript.model,
+        agentType: transcript.agentType,
+        agentId: transcript.agentId,
+        warn: log,
+    });
     if (ok) {
         transcriptRecorded = true;
-        if (transcript.harness !== "grok")
+        reportedModel = transcript.model;
+        // RTSC-821 — claude-code's record is NOT consumed any more, whether or not it came
+        // with a model. Clearing it made `retasc hook model-switch` a permanent no-op for
+        // that folder (`updateHookRecordModel` returns early when the file is gone), and the
+        // session most in need of the switch hook is precisely the one whose SessionStart
+        // payload carried NO model — which Claude Code omits after a /clear and on recovery.
+        //
+        // Nothing adopts it in the meantime: the discovery path still checks `notAfter` and
+        // `maxAge`, and every re-read goes through `ownRecordModel`, which matches the
+        // session id. The next SessionStart in this folder overwrites the file, so it never
+        // accumulates, and an abandoned one is collected by the 24h sweep.
+        if (transcript.harness !== "grok" && transcript.harness !== "claude-code")
             clearHookRecord(process.cwd());
-        log(`session recorded as ${transcript.harness} transcript ${transcript.id}`);
+        log(`session recorded as ${transcript.harness} transcript ${transcript.id}${transcript.model ? ` on ${transcript.model}` : ""}`);
     }
 }
 /**
@@ -551,7 +632,7 @@ async function handleLine(line) {
     // flag the workspace-key fallback on whoami so the AGENT sees the degraded
     // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.
     let reapId;
-    if (msg.method === "tools/call" && !transcriptRecorded) {
+    if (msg.method === "tools/call") {
         reportTranscript().catch((e) => log(`record_session: ${String(e?.message ?? e)}`));
     }
     if (msg.method === "tools/call" && resp) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {