mulmoclaude 0.5.2 → 0.6.0

package/server/api/routes/agent.ts

@@ -19,6 +19,9 @@ import { prependJournalPointer } from "../../agent/prompt.js";
 import { buildTranscriptPreamble, isStaleSessionError } from "../../agent/resumeFailover.js";
 import { getOrCreateSession, beginRun, endRun, cancelRun, pushSessionEvent, pushToolResult, getActiveSessionIds } from "../../events/session-store/index.js";
 import { workspacePath } from "../../workspace/workspace.js";
+import { discoverSkills } from "../../workspace/skills/discovery.js";
+import type { Skill } from "../../workspace/skills/types.js";
+import { isRecord } from "../../utils/types.js";
 import { maybeRunJournal } from "../../workspace/journal/index.js";
 import { maybeIndexSession } from "../../workspace/chat-index/index.js";
 import { maybeAppendWikiBacklinks } from "../../workspace/wiki-backlinks/index.js";
@@ -41,7 +44,9 @@ import { isSessionOrigin, type SessionOrigin } from "../../../src/types/session.
 // import { publishNotification } from "../../events/notifications.js";
 import { env } from "../../system/env.js";
 import type { Attachment } from "@mulmobridge/protocol";
-import { parseDataUrl } from "@mulmobridge/client";
+import { isImagePath, loadImageBase64 } from "../../utils/files/image-store.js";
+import { isAttachmentPath, loadAttachmentBase64, inferMimeFromExtension, saveAttachment } from "../../utils/files/attachment-store.js";
+import { errorMessage } from "../../utils/errors.js";
 
 const router = Router();
 const PORT = env.port;
@@ -73,20 +78,6 @@ router.post(API_ROUTES.agent.internal.toolResult, async (req: Request<object, un
   res.json({ ok: outcome.kind === "processed" });
 });
 
-// Called by the MCP server to trigger a role switch on the frontend
-interface SwitchRoleBody {
-  roleId: string;
-}
-
-router.post(API_ROUTES.agent.internal.switchRole, async (req: Request<object, unknown, SwitchRoleBody>, res: Response<OkResponse>) => {
-  const chatSessionId = getSessionQuery(req);
-  pushSessionEvent(chatSessionId, {
-    type: EVENT_TYPES.switchRole,
-    roleId: req.body.roleId,
-  });
-  res.json({ ok: true });
-});
-
 // Cancel a running agent session by killing the Claude CLI process.
 interface CancelBody {
   chatSessionId: string;
@@ -111,6 +102,18 @@ export interface StartChatParams {
   message: string;
   roleId: string;
   chatSessionId: string;
+  /** Bridge-only legacy carrier for "the user picked this image".
+   *  No in-tree bridge sets it today; it remains on the type so
+   *  external bridge clients that populate it from older protocol
+   *  versions continue to work. Only workspace paths
+   *  (`data/attachments/...` or `artifacts/images/...`) are accepted
+   *  — `data:` URLs are no longer supported and are dropped with a
+   *  warn. Bridges that need to ship raw bytes should use the
+   *  modern `attachments[]` field with `{ mimeType, data }` entries;
+   *  those get persisted to `data/attachments/YYYY/MM/` server-side
+   *  and rewritten as path-bearing attachments. The Vue UI never
+   *  sets this — paste/drop and sidebar picks ride on
+   *  `attachments[]` as path-only entries directly. */
   selectedImageData?: string;
   attachments?: Attachment[];
   /** Where this session originates (#486). Accepts string for
@@ -133,6 +136,10 @@ export type StartChatResult = { kind: "started"; chatSessionId: string } | { kin
 
 export async function startChat(params: StartChatParams): Promise<StartChatResult> {
   const { message, roleId, chatSessionId, selectedImageData, attachments, userTimezone } = params;
+  // Bridge-only compat: external bridge clients may still populate
+  // `selectedImageData`. Fold it into `attachments` so the rest of
+  // this function only deals with one input shape.
+  const normalisedAttachments = mergeBridgeSelectedImage(selectedImageData, attachments);
 
   if (!message || !roleId || !chatSessionId) {
     return {
@@ -159,7 +166,6 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
   getOrCreateSession(chatSessionId, {
     roleId,
     resultsFilePath,
-    selectedImageData,
     startedAt: now,
     updatedAt: now,
     hasUnread: persistedHasUnread,
@@ -176,10 +182,40 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
     return { kind: "error", error: "Session is already running", status: 409 };
   }
 
-  // Run is committed. Now persist the user message so callers (and
-  // other tabs) see the turn. Metadata first — it powers the sidebar
-  // title cache; the append follows so the jsonl is always a
-  // superset of what metadata advertised.
+  // Run is committed. Process attachments next so any failure here
+  // rolls the run back via `endRun` before we persist or broadcast a
+  // user message — leaving an orphan turn on disk when the request
+  // ultimately rejects would mislead every viewer of this session.
+  // Three things happen in this block, all guarded together:
+  //   1. Bridge inline-bytes (`{ data, mimeType }`) get saved to
+  //      `data/attachments/YYYY/MM/` and rewritten as path-bearing
+  //      attachments. After this every Attachment has a `path`.
+  //   2. `collectAttachedPaths` extracts the workspace paths to
+  //      persist on the user JSONL line and broadcast on the SSE
+  //      event so the UI can render chips for the turn.
+  //   3. `prepareRequestExtras` loads bytes off disk for the LLM
+  //      request. With (1) above this is now a pure path-only walk.
+  // A malformed body (e.g. `attachments` not an array) or a
+  // filesystem I/O failure is logged and converted to a 400 here;
+  // beginRun is rolled back so subsequent turns aren't rejected with
+  // 409 forever.
+  let attachedPaths: string[];
+  let extras: RequestExtras;
+  try {
+    const persistedAttachments = await persistInlineBytesAsPaths(normalisedAttachments);
+    attachedPaths = collectAttachedPaths(persistedAttachments);
+    extras = await prepareRequestExtras(persistedAttachments);
+  } catch (err) {
+    log.warn("agent", "attachment processing failed — rolling back run", { chatSessionId, error: errorMessage(err) });
+    abortController.abort();
+    endRun(chatSessionId);
+    return { kind: "error", error: "Invalid attachments payload", status: 400 };
+  }
+
+  // Now persist the user message so callers (and other tabs) see the
+  // turn. Metadata first — it powers the sidebar title cache; the
+  // append follows so the jsonl is always a superset of what metadata
+  // advertised.
   const validOrigin = isSessionOrigin(params.origin) ? params.origin : undefined;
   if (isFirstTurn) {
     await createSessionMeta(chatSessionId, roleId, message, undefined, validOrigin);
@@ -191,7 +227,10 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
   }
 
   // Append user message for this turn
-  await appendSessionLine(chatSessionId, JSON.stringify({ source: "user", type: EVENT_TYPES.text, message }));
+  await appendSessionLine(
+    chatSessionId,
+    JSON.stringify({ source: "user", type: EVENT_TYPES.text, message, ...(attachedPaths.length > 0 ? { attachments: attachedPaths } : {}) }),
+  );
 
   // Broadcast the user message so other tabs viewing this session
   // see the input in real time. Runs AFTER beginRun so a 409 never
@@ -200,6 +239,7 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
     type: EVENT_TYPES.text,
     source: "user",
     message,
+    ...(attachedPaths.length > 0 ? { attachments: attachedPaths } : {}),
   });
 
   const role = getRole(roleId);
@@ -213,7 +253,8 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
     resumed: Boolean(claudeSessionId),
   });
 
-  const decoratedMessage = claudeSessionId ? message : prependJournalPointer(message, workspacePath);
+  const baseMessage = claudeSessionId ? message : prependJournalPointer(message, workspacePath);
+  const decoratedMessage = withAttachedFileMarker(baseMessage, extras.attachedFilePaths);
 
   runAgentInBackground({
     decoratedMessage,
@@ -224,7 +265,7 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
     resultsFilePath,
     requestStartedAt,
     toolArgsCache: createArgsCache(),
-    attachments: mergeAttachments(selectedImageData, attachments),
+    attachments: extras.attachments,
     userTimezone,
     origin: validOrigin,
   });
@@ -234,35 +275,244 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
-/** Convert legacy `selectedImageData` (data URL from the Vue UI) into
- *  the generic Attachment format, then merge with any explicitly-
- *  provided attachments from the bridge protocol. Returns undefined
- *  when there's nothing to attach. */
-function mergeAttachments(selectedImageData: string | undefined, explicit: Attachment[] | undefined): Attachment[] | undefined {
+interface RequestExtras {
+  attachments: Attachment[] | undefined;
+  /** Workspace-relative paths of every file the user attached or
+   *  selected for this turn, in declaration order. Surfaced to the
+   *  LLM via one `[Attached file: <path>]` line per entry, prepended
+   *  to the user message so path-passing tools (e.g. `editImages`)
+   *  and the LLM itself can reference each file by path.
+   *  `persistInlineBytesAsPaths` ensures every well-formed attachment
+   *  carries a path before this runs, so this is empty only when the
+   *  request had no attachments at all (or every entry was malformed
+   *  and dropped). */
+  attachedFilePaths: string[];
+}
+
+/** Pluck workspace-relative paths out of `attachments[]`. Used for
+ *  persistence + broadcast of the user message: the Vue UI renders
+ *  these as attachment chips next to the chat bubble.
+ *  `persistInlineBytesAsPaths` runs first, so by the time we get
+ *  here every well-formed entry already carries a `path` and chips
+ *  round-trip for bridge attachments too — not just Vue uploads.
+ *  Order matches declaration order so chip order matches the order
+ *  the user attached them.
+ *
+ *  Each path is validated against the same allow-list `loadFromPath`
+ *  uses (`data/attachments/...` or `artifacts/images/...png`). A
+ *  request can otherwise pin a bogus path on the chat record + SSE
+ *  + LLM marker even though `loadFromPath` would refuse to read it
+ *  (#1052 review).
+ *
+ *  Defensive: `Array.isArray` guards against a malformed HTTP body
+ *  where `attachments` is a truthy non-array. Without it `for...of`
+ *  would throw and bypass the rollback path that calls `endRun`,
+ *  leaving the session locked as running (#1052 review). */
+export function collectAttachedPaths(attachments: Attachment[] | undefined): string[] {
+  if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  const paths: string[] = [];
+  for (const att of attachments) {
+    if (typeof att.path !== "string" || att.path.length === 0) continue;
+    if (!isAttachmentPath(att.path) && !isImagePath(att.path)) continue;
+    paths.push(att.path);
+  }
+  return paths;
+}
+
+/** Bridge-only compat: external bridge clients may still ship a
+ *  picked image via `StartChatParams.selectedImageData`. Convert
+ *  that single value to a synthetic `Attachment` and prepend it to
+ *  the explicit `attachments` array so downstream code only has to
+ *  understand one input shape. The Vue UI never reaches this branch
+ *  — it sends path-only attachments directly. */
+function mergeBridgeSelectedImage(selectedImageData: string | undefined, attachments: Attachment[] | undefined): Attachment[] | undefined {
+  const synthetic = synthesiseBridgeAttachment(selectedImageData);
+  if (!synthetic) return Array.isArray(attachments) ? attachments : undefined;
+  return Array.isArray(attachments) && attachments.length > 0 ? [synthetic, ...attachments] : [synthetic];
+}
+
+/** Convert a legacy `selectedImageData` carrier to an `Attachment`.
+ *  Only workspace paths (`data/attachments/...` or `artifacts/images/
+ *  ...`) are accepted — `data:` URLs are no longer supported. A
+ *  bridge that still wants to ship raw bytes should populate the
+ *  modern `attachments[]` field with `{ mimeType, data }` instead;
+ *  `persistInlineBytesAsPaths` then writes those to
+ *  `data/attachments/YYYY/MM/` and turns them into path-bearing
+ *  entries before any other processing. */
+function synthesiseBridgeAttachment(selectedImageData: string | undefined): Attachment | undefined {
+  if (!selectedImageData) return undefined;
+  if (isAttachmentPath(selectedImageData) || isImagePath(selectedImageData)) {
+    return { path: selectedImageData };
+  }
+  log.warn("agent", "bridge selectedImageData is not a workspace path — dropping (data: URLs are no longer supported)", {
+    valuePreview: selectedImageData.slice(0, 64),
+  });
+  return undefined;
+}
+
+/** Persist any inline-bytes attachment to disk as a path-bearing
+ *  entry. Bridges over the socket transport (Telegram, LINE, ...)
+ *  ship raw bytes via `Attachment.data` + `Attachment.mimeType`; the
+ *  Vue UI uploads to disk before posting and already carries a
+ *  `path`. By rewriting inline bytes into
+ *  `data/attachments/YYYY/MM/<id>.<ext>` here we get two properties
+ *  the rest of the pipeline relies on:
+ *
+ *    1. Every well-formed attachment carries a workspace path, so
+ *       chips can round-trip for bridge turns the same way they do
+ *       for Vue paste/drop turns (no `data:` chips, no special
+ *       cases downstream).
+ *    2. `prepareRequestExtras` becomes a path-only walk — the inline
+ *       (`{ data, mimeType }`) shape no longer flows past this layer.
+ *
+ *  Defensive: `Array.isArray` mirrors the guard in
+ *  `collectAttachedPaths` so a malformed payload doesn't throw and
+ *  bypass `endRun`. A failed save bubbles up so the caller can
+ *  reject the turn — silently dropping the file would persist the
+ *  user message without the attachment they sent and breaks the
+ *  persistence/broadcast contract this layer is enforcing (#1052
+ *  review). The caller's try/catch wraps the whole attachment-prep
+ *  block and rolls the run back via `endRun`, so the failure path
+ *  is well-defined: the user gets a 400, the session unlocks, and
+ *  no orphan turn lands in jsonl. Entries with neither path nor
+ *  inline bytes are still dropped (warn) — that's a malformed entry,
+ *  not an I/O failure. */
+async function persistInlineBytesAsPaths(attachments: Attachment[] | undefined): Promise<Attachment[] | undefined> {
+  if (!Array.isArray(attachments) || attachments.length === 0) return undefined;
   const result: Attachment[] = [];
-  if (selectedImageData) {
-    const parsed = parseDataUrl(selectedImageData);
-    if (parsed) {
-      result.push({ mimeType: parsed.mimeType, data: parsed.data });
+  for (const att of attachments) {
+    if (typeof att.path === "string" && att.path.length > 0) {
+      result.push(att);
+      continue;
     }
-  }
-  if (explicit) {
-    result.push(...explicit);
+    if (typeof att.data === "string" && att.data.length > 0 && typeof att.mimeType === "string" && att.mimeType.length > 0) {
+      const saved = await saveAttachment(att.data, att.mimeType);
+      result.push({ path: saved.relativePath, mimeType: saved.mimeType });
+      continue;
+    }
+    log.warn("agent", "attachment has neither path nor inline bytes — dropping");
   }
   return result.length > 0 ? result : undefined;
 }
 
+/** Walk `attachments[]` once, loading bytes from disk for every
+ *  path-bearing entry, and collect every path so the caller can emit
+ *  one `[Attached file: <path>]` marker per file. Two path roots
+ *  are accepted:
+ *
+ *    - `data/attachments/...` — paste/drop/file-picker uploads (any
+ *      MIME type from the chat input's accept list) and the persisted
+ *      form of bridge inline-bytes attachments. MIME is inferred from
+ *      the extension chosen at save time.
+ *    - `artifacts/images/...png` — generated / canvas / edited images
+ *      a user picked from the sidebar. Always image/png.
+ *
+ *  Bytes are loaded so Claude still "sees" each file as a content
+ *  block on this turn, AND every path is returned separately so the
+ *  caller marks them in the LLM-bound message. If a file can't be
+ *  read, its path hint is still emitted — the LLM knows what was
+ *  attached and can call Read to load it. Multi-file flows (e.g.
+ *  paste one image + pick another in the sidebar → "combine these")
+ *  rely on every path showing up in the marker so `editImages` can
+ *  receive the full list in `imagePaths`.
+ *
+ *  Inline (`{ data, mimeType }`) entries no longer reach this layer —
+ *  `persistInlineBytesAsPaths` rewrites them as path-bearing entries
+ *  before this runs. */
+export async function prepareRequestExtras(attachments: Attachment[] | undefined): Promise<RequestExtras> {
+  if (!Array.isArray(attachments) || attachments.length === 0) {
+    return { attachments: undefined, attachedFilePaths: [] };
+  }
+  const result: Attachment[] = [];
+  const attachedFilePaths: string[] = [];
+  for (const att of attachments) {
+    if (typeof att.path !== "string" || att.path.length === 0) {
+      log.warn("agent", "attachment has no path after normalisation — dropping");
+      continue;
+    }
+    const resolved = await loadFromPath(att.path, att.mimeType);
+    if (!resolved) continue;
+    // Only emit the `[Attached file: …]` marker when the file was
+    // actually loaded — otherwise the LLM gets told a bogus path
+    // exists (Codex review on PR #1084 follow-up to #1052).
+    result.push(resolved);
+    attachedFilePaths.push(att.path);
+  }
+  return {
+    attachments: result.length > 0 ? result : undefined,
+    attachedFilePaths,
+  };
+}
+
+async function loadFromPath(value: string, declaredMimeType: string | undefined): Promise<Attachment | undefined> {
+  if (isAttachmentPath(value)) return loadAttachmentFromPath(value, declaredMimeType);
+  if (isImagePath(value)) return loadImageFromPath(value, declaredMimeType);
+  log.warn("agent", "attachment path is outside allowed roots — dropping", { path: value });
+  return undefined;
+}
+
+async function loadAttachmentFromPath(value: string, declaredMimeType: string | undefined): Promise<Attachment | undefined> {
+  const mimeType = declaredMimeType ?? inferMimeFromExtension(value);
+  if (!mimeType) {
+    log.warn("agent", "attachment path has unknown extension — skipping bytes", { path: value });
+    return undefined;
+  }
+  try {
+    const data = await loadAttachmentBase64(value);
+    return { mimeType, data, path: value };
+  } catch (err) {
+    log.warn("agent", "failed to load attachment bytes from path", { path: value, error: errorMessage(err) });
+    return undefined;
+  }
+}
+
+async function loadImageFromPath(value: string, declaredMimeType: string | undefined): Promise<Attachment | undefined> {
+  try {
+    const data = await loadImageBase64(value);
+    return { mimeType: declaredMimeType ?? "image/png", data, path: value };
+  } catch (err) {
+    log.warn("agent", "failed to load selected-image bytes from path", { path: value, error: errorMessage(err) });
+    return undefined;
+  }
+}
+
+// Drop any path containing characters that could break the
+// `[Attached file: <path>]` marker line (`\r`, `\n`) or its closing
+// bracket (`]`). Such a path would let request-controlled input
+// inject arbitrary text into the privileged prompt prefix — the
+// path itself reaches the marker straight from the request body.
+// CodeRabbit review on #1045.
+const UNSAFE_MARKER_CHARS_RE = /[\r\n\]]/;
+
+/** Marker prepended to the LLM-bound user message that tells the
+ *  model which workspace files are attached / selected for this turn.
+ *  One `[Attached file: <path>]` line is emitted per path so multi-
+ *  file flows (e.g. paste one image + pick another → "combine these")
+ *  surface every path to the model — `editImages` then receives the
+ *  full list in `imagePaths`. The user's persisted (jsonl) and
+ *  broadcast (UI) message is the raw text — these marker lines are
+ *  added strictly on the path to Claude. The system prompt teaches
+ *  the model how to interpret them. */
+export function withAttachedFileMarker(message: string, attachedFilePaths: string[]): string {
+  const safePaths = attachedFilePaths.filter((relPath) => !UNSAFE_MARKER_CHARS_RE.test(relPath));
+  if (safePaths.length === 0) return message;
+  const markerLines = safePaths.map((relPath) => `[Attached file: ${relPath}]`).join("\n");
+  return `${markerLines}\n\n${message}`;
+}
+
 // ── HTTP route ──────────────────────────────────────────────────────
 
-// HTTP route body — used by the Vue UI only. `selectedImageData` is
-// the legacy data-URL path; new bridge clients send `attachments`
-// via the socket relay instead. mergeAttachments() unifies both
-// paths inside startChat(). See #382 for the rationale.
+// HTTP route body — used by the Vue UI only. Paste/drop and sidebar
+// pick both ride on `attachments[]` as path-only entries; the server
+// reads bytes from disk and emits the `[Attached file: <path>]`
+// marker. Bridges go through the socket relay (see chat-service)
+// and supply attachments with inline base64 bytes; both shapes
+// share the same `Attachment` type. See plans/done/refactor-edit-images-array.md.
 interface AgentBody {
   message: string;
   roleId: string;
   chatSessionId: string;
-  selectedImageData?: string;
+  attachments?: Attachment[];
   userTimezone?: string;
 }
 
@@ -308,13 +558,77 @@ interface BackgroundRunParams {
 // `textAccumulator` collects streaming text chunks so we write
 // one consolidated line to the jsonl instead of per-chunk lines
 // (which would appear as separate cards on session reload).
+//
+// `pendingSkill` is set when a `tool_call` with `toolName === "Skill"`
+// arrives. The next non-empty text flush IS the SKILL.md body that
+// Claude CLI synthesises — gets tagged as `type: "skill"` instead of
+// `type: "text"` and consumes the flag. (#1218)
+//
+// `toolUseId` is tracked alongside the slug so we can recognise the
+// matching `tool_call_result` (which Claude CLI emits between the
+// Skill tool_call and the body) and let it pass without clearing.
+// Any OTHER non-text event between the Skill tool_call and the body
+// flush is treated as a sequence break and clears the flag — covers
+// the leak path Codex iter-2 flagged where a tool_call_result with
+// a different `toolUseId` (or a `claudeSessionId`, or a flush at
+// run-end) would otherwise leave `pendingSkill` set so a much-later
+// unrelated assistant text gets mis-tagged as `type: "skill"`.
 interface EventContext {
   chatSessionId: string;
   resultsFilePath: string;
   toolArgsCache: ReturnType<typeof createArgsCache>;
   textAccumulator: string[];
+  pendingSkill: { skillName: string; toolUseId: string } | null;
 }
 
+const CLAUDE_CLI_SKILL_BODY_PREFIX = "Base directory for this skill: ";
+
+// #1218 — state-machine helpers for `pendingSkill`. Extracted so
+// `handleAgentEvent` stays under the cognitive-complexity cap and so
+// the leak-fix logic (Codex iter-2: clear on mismatched
+// tool_call_result + claudeSessionId, in addition to the iter-1
+// "non-Skill tool_call" clear) lives in one named place.
+//
+// When the model invokes a skill, Claude CLI emits the SKILL.md
+// body as the next assistant text. We track that expectation here:
+// the structural signal is `toolName === "Skill"` + `args.skill`
+// slug, not a body-text prefix, so it survives any rewording Claude
+// CLI might do to the synthesised body.
+
+// Narrow the helpers to only the slot they read/mutate so the
+// state-machine unit test in test/agent/ doesn't have to construct
+// the full `EventContext` (chatSessionId, resultsFilePath, etc).
+type PendingSkillSlot = Pick<EventContext, "pendingSkill">;
+
+function updatePendingSkillOnToolCall(ctx: PendingSkillSlot, event: { toolName: string; toolUseId: string; args: unknown }): void {
+  // Any non-Skill tool_call resets the pending state. Without this,
+  // a Skill call followed by another tool (Bash, etc.) without a
+  // body flush in between would leak `pendingSkill` and miscategorise
+  // a later unrelated assistant text as a skill body.
+  if (event.toolName !== "Skill") {
+    ctx.pendingSkill = null;
+    return;
+  }
+  const skillSlug = isRecord(event.args) && typeof event.args.skill === "string" ? event.args.skill : null;
+  ctx.pendingSkill = skillSlug ? { skillName: skillSlug, toolUseId: event.toolUseId } : null;
+}
+
+// The Skill's own tool_call_result (matching toolUseId) carries
+// "Launching skill: X" content; the body follows in the next text
+// event so we leave `pendingSkill` set. A tool_call_result with any
+// OTHER id means a different tool's result interleaved before the
+// body — sequence broken, clear the flag so a later unrelated
+// assistant text isn't mis-tagged as `type: "skill"`.
+function updatePendingSkillOnToolCallResult(ctx: PendingSkillSlot, toolUseId: string): void {
+  if (ctx.pendingSkill && toolUseId !== ctx.pendingSkill.toolUseId) {
+    ctx.pendingSkill = null;
+  }
+}
+
+// Exported for the unit test in test/agent/test_pendingSkillStateMachine.ts.
+export const _updatePendingSkillOnToolCallForTest = updatePendingSkillOnToolCall;
+export const _updatePendingSkillOnToolCallResultForTest = updatePendingSkillOnToolCallResult;
+
 // Returns true if the event was handled "out of band" (no pub-sub
 // broadcast, no jsonl append). Right now only `claudeSessionId`
 // events fall into that bucket — they update meta and are otherwise
@@ -323,6 +637,10 @@ interface EventContext {
 async function handleAgentEvent(event: Awaited<ReturnType<typeof runAgent>> extends AsyncGenerator<infer E> ? E : never, ctx: EventContext): Promise<void> {
   if (event.type === EVENT_TYPES.claudeSessionId) {
     await flushTextAccumulator(ctx);
+    // claudeSessionId is a meta event — never part of a Skill→body
+    // sequence. Clear pendingSkill so a flag set earlier in the run
+    // can't leak into a later unrelated assistant text.
+    ctx.pendingSkill = null;
     await setClaudeId(ctx.chatSessionId, event.id);
     return;
   }
@@ -340,6 +658,7 @@ async function handleAgentEvent(event: Awaited<ReturnType<typeof runAgent>> exte
   // lose already-streamed text.
   await flushTextAccumulator(ctx);
   if (event.type === EVENT_TYPES.toolCall) {
+    updatePendingSkillOnToolCall(ctx, event);
     log.info("agent-tool", "call", {
       chatSessionId: ctx.chatSessionId,
       toolName: event.toolName,
@@ -347,6 +666,7 @@ async function handleAgentEvent(event: Awaited<ReturnType<typeof runAgent>> exte
       argsPreview: previewJson(event.args),
     });
   } else if (event.type === EVENT_TYPES.toolCallResult) {
+    updatePendingSkillOnToolCallResult(ctx, event.toolUseId);
     // Look up the toolName from the cache *before* recordToolEvent
     // runs (it deletes the cache entry on result).
     const cached = ctx.toolArgsCache.get(event.toolUseId);
@@ -373,11 +693,26 @@ async function handleAgentEvent(event: Awaited<ReturnType<typeof runAgent>> exte
 // jsonl line. Called at the end of each agent run (success or error)
 // so the session transcript has exactly one assistant text entry
 // per response, not N per-chunk entries.
+//
+// When `ctx.pendingSkill` is set (preceding tool_call had
+// `toolName === "Skill"`), the flushed text is the SKILL.md body
+// Claude CLI synthesised — write it as `type: "skill"` instead of
+// `type: "text"` and consume the flag (#1218).
 async function flushTextAccumulator(ctx: EventContext): Promise<void> {
   if (ctx.textAccumulator.length === 0) return;
   const fullText = ctx.textAccumulator.join("");
   ctx.textAccumulator.length = 0;
   if (!fullText) return;
+
+  // Empty-string flushes (already handled above) don't consume
+  // pendingSkill — only the actual skill body should clear it.
+  const skill = ctx.pendingSkill;
+  ctx.pendingSkill = null;
+
+  if (skill) {
+    await writeSkillEntry(ctx, skill.skillName, fullText);
+    return;
+  }
   await appendSessionLine(
     ctx.chatSessionId,
     JSON.stringify({
@@ -388,6 +723,133 @@ async function flushTextAccumulator(ctx: EventContext): Promise<void> {
   );
 }
 
+// Resolve the loaded skill against `discoverSkills()` to attach
+// scope + path metadata, then write the consolidated assistant entry
+// as `type: "skill"`. The body's full text is preserved in `message`
+// (archival + the canvas's expand-on-click affordance). A live SSE
+// `type: "skill"` event is also broadcast so observing tabs can
+// replace the streamed text bubble with a collapsed skill card
+// without waiting for a session reload.
+//
+// Claude CLI sometimes concatenates the LLM's actual reply to the
+// synthesised SKILL.md body in the same text block (no `tool_call`
+// or `content_block_stop` boundary between them — see PR #1220
+// comment for the shiritori reproducer). We split that here using
+// the SKILL.md body on disk as a structural delimiter; the reply
+// portion gets persisted as a SECOND entry of `type: "text"` so it
+// stays visible after the user collapses the skill card.
+async function writeSkillEntry(ctx: EventContext, skillName: string, body: string): Promise<void> {
+  const resolved = await resolveSkillMetadata(skillName);
+  // Canary: skill detection is sequence-based (not body-prefix based),
+  // but we still cross-check the prefix as a format-drift signal.
+  // If Claude CLI ever changes its synthesised body shape, this warn
+  // surfaces before any user-visible regression.
+  if (!body.startsWith(CLAUDE_CLI_SKILL_BODY_PREFIX)) {
+    log.warn("agent", "Skill tool followed by text NOT starting with the expected Claude CLI prefix — body shape may have changed", {
+      skillName,
+      expectedPrefix: CLAUDE_CLI_SKILL_BODY_PREFIX,
+      actualPreview: body.slice(0, 80),
+    });
+  }
+  // A second canary: the SKILL.md body should appear verbatim inside
+  // the synthesised text. Failure means either discovery missed the
+  // skill (already logged by `resolveSkillMetadata`) or Claude CLI
+  // changed how it inlines the body (worth investigating).
+  if (resolved.body && !body.includes(resolved.body.trim())) {
+    log.warn("agent", "Claude CLI text does not contain the SKILL.md body verbatim — body split may be incorrect", {
+      skillName,
+      bodyBytes: body.length,
+      skillFileBytes: resolved.body.length,
+    });
+  }
+  const { skillPart, replyPart } = splitSkillAndReply(body, resolved.body);
+
+  const skillPayload = {
+    source: "assistant",
+    type: EVENT_TYPES.skill,
+    skillName,
+    skillScope: resolved.scope,
+    skillPath: resolved.path,
+    skillDescription: resolved.description,
+    message: skillPart,
+  };
+  pushSessionEvent(ctx.chatSessionId, skillPayload as Record<string, unknown>);
+  await appendSessionLine(ctx.chatSessionId, JSON.stringify(skillPayload));
+
+  if (replyPart) {
+    const textPayload = { source: "assistant", type: EVENT_TYPES.text, message: replyPart };
+    pushSessionEvent(ctx.chatSessionId, textPayload as Record<string, unknown>);
+    await appendSessionLine(ctx.chatSessionId, JSON.stringify(textPayload));
+  }
+}
+
+interface SkillMetadata {
+  scope: "user" | "project" | "unknown";
+  path: string | null;
+  /** From the SKILL.md frontmatter `description:` field. Used by the
+   *  host's collapsed-skill card — Claude CLI strips frontmatter from
+   *  the synthesised body, so the renderer can't re-extract this from
+   *  `message`. Resolved here from `discoverSkills()` instead. */
+  description: string | null;
+  /** SKILL.md body (frontmatter already stripped by `discoverSkills`).
+   *  Used as a structural delimiter to split the text Claude CLI
+   *  emits — the body Claude CLI inlines is character-for-character
+   *  this same string, with the LLM's actual reply concatenated
+   *  after. */
+  body: string | null;
+}
+
+async function resolveSkillMetadata(skillName: string): Promise<SkillMetadata> {
+  try {
+    const skills: Skill[] = await discoverSkills({ workspaceRoot: workspacePath });
+    const found = skills.find((skill) => skill.name === skillName);
+    if (!found) return { scope: "unknown", path: null, description: null, body: null };
+    return { scope: found.source, path: found.path, description: found.description, body: found.body };
+  } catch (err) {
+    // Discovery failure is benign — keep tagging the entry so the UI
+    // can still collapse it; just leave metadata empty.
+    log.warn("agent", "skill metadata lookup failed — emitting entry without scope/path/description/body", {
+      skillName,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return { scope: "unknown", path: null, description: null, body: null };
+  }
+}
+
+/** Split the consolidated text Claude CLI emits after a `Skill`
+ *  tool_call into the SKILL.md body half (synthesised by Claude CLI)
+ *  and the LLM's actual reply half. Without this, the entire blob
+ *  gets tagged `type: "skill"`, so when the user collapses the
+ *  card their actual reply disappears (#1218 reproducer: shiritori
+ *  skill, where the body ends with a "respond now" instruction and
+ *  the LLM's first move is concatenated to the same text block).
+ *
+ *  Structural split: the SKILL.md body is on disk, available via
+ *  `discoverSkills()`. We find that exact substring inside the
+ *  message and slice. Optional `ARGUMENTS: <user_input>` line that
+ *  Claude CLI appends when the SKILL.md uses `{{ARGUMENTS}}` is
+ *  consumed too. Returns the whole message as `skillPart` with
+ *  empty `replyPart` when `skillBody` is empty (discovery missed)
+ *  or not found verbatim (Claude CLI changed the inlining format —
+ *  the canary log warn fires in that case). */
+function splitSkillAndReply(message: string, skillBody: string | null): { skillPart: string; replyPart: string } {
+  if (!skillBody) return { skillPart: message, replyPart: "" };
+  const trimmedBody = skillBody.trim();
+  if (!trimmedBody) return { skillPart: message, replyPart: "" };
+  const idx = message.indexOf(trimmedBody);
+  if (idx < 0) return { skillPart: message, replyPart: "" };
+  let cursor = idx + trimmedBody.length;
+  // Skip the optional ARGUMENTS line + trailing whitespace.
+  const argMatch = /^\s*ARGUMENTS:[^\n]*\n?/.exec(message.slice(cursor));
+  if (argMatch) cursor += argMatch[0].length;
+  const skillPart = message.slice(0, cursor).trimEnd();
+  const replyPart = message.slice(cursor).replace(/^\s+/, "");
+  return { skillPart, replyPart };
+}
+
+// Exported for the unit test in test/agent/test_skillBodySplit.ts.
+export const _splitSkillAndReplyForTest = splitSkillAndReply;
+
 // Helper kept commented (instead of deleted) alongside the
 // publishNotification call below — see the duplicate-notification
 // comment near `endRun()` in `runAgentInBackground` for context.
@@ -418,6 +880,7 @@ async function runAgentInBackground(params: BackgroundRunParams): Promise<void>
     resultsFilePath,
     toolArgsCache,
     textAccumulator: [],
+    pendingSkill: null,
   };
 
   // Retry budget for the stale `--resume` id fail-over (#211). Only
@@ -431,17 +894,17 @@ async function runAgentInBackground(params: BackgroundRunParams): Promise<void>
   try {
     while (true) {
       let staleSessionDetected = false;
-      for await (const event of runAgent(
-        currentMessage,
+      for await (const event of runAgent({
+        message: currentMessage,
         role,
         workspacePath,
-        chatSessionId,
-        PORT,
-        currentClaudeSessionId,
+        sessionId: chatSessionId,
+        port: PORT,
+        claudeSessionId: currentClaudeSessionId,
         abortSignal,
         attachments,
         userTimezone,
-      )) {
+      })) {
         if (failoverAttemptsRemaining > 0 && event.type === EVENT_TYPES.error && typeof event.message === "string" && isStaleSessionError(event.message)) {
           // Swallow the error — we're about to recover. `break`
           // abandons the current generator; since the event is only