stagent 0.10.0 → 0.11.0

package/src/lib/chat/context-builder.ts

@@ -5,6 +5,8 @@ import { getMessages } from "@/lib/data/chat";
 import { getProfile } from "@/lib/agents/profiles/registry";
 import { STAGENT_SYSTEM_PROMPT } from "./system-prompt";
 import type { WorkspaceContext } from "@/lib/environment/workspace-context";
+import { expandFileMention } from "./files/expand-mention";
+import { conversations } from "@/lib/db/schema";
 
 // ── Token budget constants ─────────────────────────────────────────────
 
@@ -50,6 +52,121 @@ function buildTier0(
   return parts.join("\n");
 }
 
+// ── Active skill injection (Ollama-first, runtime-agnostic) ────────────
+
+/**
+ * Token budget for a conversation-bound skill's SKILL.md content.
+ *
+ * Per spec §7.1: 1000-4000 tokens typical, with 300 tokens of index/
+ * metadata on top. We cap at ~4000 tokens (≈16K chars) so a large skill
+ * can't blow out a small-context local model. Single-active-skill is
+ * enforced at the MCP-tool layer.
+ */
+const ACTIVE_SKILL_BUDGET = 4_000;
+
+interface ActiveSkillSection {
+  name: string;
+  text: string;
+}
+
+function renderActiveSkillSections(
+  kept: ActiveSkillSection[],
+  omitted: ActiveSkillSection[]
+): string {
+  if (kept.length === 0) return "";
+
+  const parts: string[] = [];
+  if (omitted.length > 0) {
+    const label = omitted.length === 1 ? "skill" : "skills";
+    parts.push(
+      `## Active Skill Note\nOmitted ${omitted.length} older active ${label} to fit the prompt budget: ${omitted
+        .map((section) => section.name)
+        .join(", ")}.`
+    );
+  }
+  parts.push(...kept.map((section) => section.text));
+  return parts.join("\n\n---\n\n");
+}
+
+/**
+ * Build the "Active Skill" section of the system prompt, if one is bound
+ * to the conversation via `conversations.active_skill_id`. Returns "" for
+ * conversations without an active skill.
+ *
+ * Primary use case: Ollama has no SDK-native skill support, so this is
+ * how SKILL.md reaches a local model. Claude and Codex runtimes can
+ * also bind a skill via this path alongside their native Skill tools.
+ *
+ * See `features/chat-ollama-native-skills.md`.
+ */
+async function buildActiveSkill(conversationId: string): Promise<string> {
+  const row = await db
+    .select({
+      activeSkillId: conversations.activeSkillId,
+      activeSkillIds: conversations.activeSkillIds,
+      runtimeId: conversations.runtimeId,
+    })
+    .from(conversations)
+    .where(eq(conversations.id, conversationId))
+    .get();
+
+  // Merge legacy single-active + new composed array. Dynamic import to
+  // avoid loading the chat tools module on the hot path / risk import
+  // cycles per the runtime-catalog smoke-test budget rule in MEMORY.md.
+  const { mergeActiveSkillIds } = await import("@/lib/chat/active-skills");
+  const merged = mergeActiveSkillIds(row?.activeSkillId, row?.activeSkillIds);
+  if (merged.length === 0) return "";
+
+  // Composition (any entry in the new activeSkillIds column) is an
+  // explicit user opt-in to override the SDK-native default. Without
+  // this carve-out, composed skills would silently no-op on Claude/
+  // Codex where stagentInjectsSkills=false. When only the legacy
+  // activeSkillId is set, fall back to the original capability gate
+  // (Ollama-only injection).
+  const isComposed = (row?.activeSkillIds?.length ?? 0) > 0;
+
+  if (!isComposed && row?.runtimeId) {
+    try {
+      const { getRuntimeFeatures } = await import("@/lib/agents/runtime/catalog");
+      const features = getRuntimeFeatures(
+        row.runtimeId as Parameters<typeof getRuntimeFeatures>[0]
+      );
+      if (!features.stagentInjectsSkills) return "";
+    } catch {
+      // Unknown runtime — fall through and inject (safer default than
+      // silently dropping the skill on an unrecognized runtime id).
+    }
+  }
+
+  // Dynamic import keeps the scanner + fs dependency off the hot path for
+  // conversations that don't have an active skill (the common case).
+  const { getSkill } = await import("@/lib/environment/list-skills");
+  const sections: ActiveSkillSection[] = [];
+  for (const id of merged) {
+    const skill = getSkill(id);
+    if (!skill) continue;
+    sections.push({
+      name: skill.name,
+      text: `## Active Skill: ${skill.name}\n\n${skill.content}`,
+    });
+  }
+  if (sections.length === 0) return "";
+
+  const kept = [...sections];
+  const omitted: ActiveSkillSection[] = [];
+  while (
+    kept.length > 1 &&
+    estimateTokens(renderActiveSkillSections(kept, omitted)) > ACTIVE_SKILL_BUDGET
+  ) {
+    const oldest = kept.shift();
+    if (oldest) omitted.push(oldest);
+  }
+
+  const combined = renderActiveSkillSections(kept, omitted);
+  if (estimateTokens(combined) <= ACTIVE_SKILL_BUDGET) return combined;
+  return truncateToTokenBudget(combined, ACTIVE_SKILL_BUDGET);
+}
+
 // ── Tier 1: Conversation history ───────────────────────────────────────
 
 interface HistoryMessage {
@@ -278,6 +395,23 @@ async function buildTier3(mentions: MentionReference[]): Promise<string> {
         }
         break;
       }
+      case "file": {
+        // `entityId` is a relative path scoped to the active project's
+        // workingDirectory (preferred) or the stagent launch cwd (fallback).
+        // Security is enforced inside expandFileMention — the caller cannot
+        // influence cwd.
+        const { getLaunchCwd } = await import("@/lib/environment/workspace-context");
+        let cwd = getLaunchCwd();
+        // If the mention has a known project context in scope, prefer the
+        // project's workingDirectory. We don't have it at this scope today,
+        // so launch cwd is the safe default — matches the API route.
+        // (Future: plumb projectId into buildTier3 so file expansion honors
+        // per-project cwds exactly the same way as the search API.)
+        void cwd;
+        cwd = getLaunchCwd();
+        parts.push(...expandFileMention(mention.entityId, cwd));
+        break;
+      }
     }
   }
 
@@ -304,16 +438,22 @@ export async function buildChatContext(opts: {
   workspace?: WorkspaceContext | null;
   mentions?: MentionReference[];
 }): Promise<ChatContext> {
-  const [history, tier2, tier3] = await Promise.all([
+  const [history, tier2, tier3, activeSkill] = await Promise.all([
     buildTier1(opts.conversationId),
     buildTier2(opts.projectId),
     buildTier3(opts.mentions ?? []),
+    buildActiveSkill(opts.conversationId),
   ]);
 
   const tier0 = buildTier0(opts.projectName, opts.workspace);
 
   const systemParts = [tier0];
 
+  // Active skill (from conversations.active_skill_id) sits right below
+  // Tier 0 so its instructions carry the most weight. Empty string when
+  // no skill is bound — common case.
+  if (activeSkill) systemParts.push(activeSkill);
+
   if (tier3) systemParts.push(tier3);
   if (tier2) systemParts.push(tier2);
 

package/src/lib/chat/dismissals.ts

@@ -0,0 +1,73 @@
+export const DISMISSAL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface DismissalStore {
+  read(): string | null;
+  write(value: string): void;
+}
+
+export type DismissalMap = Record<string, Record<string, number>>;
+
+export function loadDismissals(store: DismissalStore): DismissalMap {
+  const raw = store.read();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as DismissalMap;
+  } catch {
+    // corrupt — fall through
+  }
+  return {};
+}
+
+export function saveDismissal(
+  store: DismissalStore,
+  conversationId: string,
+  skillId: string,
+  nowMs: number = Date.now()
+): void {
+  const current = loadDismissals(store);
+  current[conversationId] = current[conversationId] ?? {};
+  current[conversationId][skillId] = nowMs;
+  try {
+    store.write(JSON.stringify(current));
+  } catch {
+    // silent — in-memory state won't persist
+  }
+}
+
+export function activeDismissedIds(
+  store: DismissalStore,
+  conversationId: string,
+  nowMs: number = Date.now()
+): Set<string> {
+  const all = loadDismissals(store);
+  const conv = all[conversationId];
+  if (!conv) return new Set();
+  const out = new Set<string>();
+  for (const [skillId, ts] of Object.entries(conv)) {
+    if (nowMs - ts < DISMISSAL_TTL_MS) out.add(skillId);
+  }
+  return out;
+}
+
+/** Browser store adapter around localStorage for a given key. */
+export function browserLocalStore(key: string): DismissalStore {
+  return {
+    read() {
+      if (typeof window === "undefined") return null;
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    write(value) {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(key, value);
+      } catch {
+        // quota / disabled — silent
+      }
+    },
+  };
+}

package/src/lib/chat/engine.ts

@@ -3,7 +3,12 @@ import { db } from "@/lib/db";
 import { projects, chatMessages } from "@/lib/db/schema";
 import { eq } from "drizzle-orm";
 import { getAuthEnv } from "@/lib/settings/auth";
-import { buildClaudeSdkEnv } from "@/lib/agents/runtime/claude-sdk";
+import {
+  buildClaudeSdkEnv,
+  CLAUDE_SDK_SETTING_SOURCES,
+  CLAUDE_SDK_ALLOWED_TOOLS,
+  CLAUDE_SDK_READ_ONLY_FS_TOOLS,
+} from "@/lib/agents/runtime/claude-sdk";
 import {
   extractUsageSnapshot,
   mergeUsageSnapshot,
@@ -42,7 +47,7 @@ import {
 } from "./permission-bridge";
 import { isToolAllowed } from "@/lib/settings/permissions";
 import { getLaunchCwd, getWorkspaceContext } from "@/lib/environment/workspace-context";
-import { createStagentMcpServer } from "./stagent-tools";
+import { createToolServer } from "./stagent-tools";
 import {
   getBrowserMcpServers,
   getBrowserAllowedToolPatterns,
@@ -53,6 +58,36 @@ import {
   isExaTool,
   isExaReadOnly,
 } from "@/lib/agents/browser-mcp";
+import { resolveChatExecutionTarget } from "@/lib/agents/runtime/execution-target";
+
+// Re-exported from runtime/claude-sdk.ts so chat/engine.ts remains a stable
+// import surface for the Phase 1a test suite. The canonical definitions
+// live in the runtime module since task execution needs them too — see
+// features/task-runtime-skill-parity.md Task 1.
+export {
+  CLAUDE_SDK_SETTING_SOURCES,
+  CLAUDE_SDK_ALLOWED_TOOLS,
+  CLAUDE_SDK_READ_ONLY_FS_TOOLS,
+} from "@/lib/agents/runtime/claude-sdk";
+
+/**
+ * Pure auto-allow policy for SDK filesystem + Skill tools. Exposed for tests.
+ * Returns `{ behavior: "allow" }` for auto-allowed tools, or
+ * `{ behavior: "pending" }` to signal "route through permission flow".
+ * The real canUseTool in query() options uses the full side-channel bridge.
+ */
+export async function canUseToolForTest(
+  toolName: string,
+  _input: Record<string, unknown>
+): Promise<ToolPermissionResponse | { behavior: "pending" }> {
+  if (CLAUDE_SDK_READ_ONLY_FS_TOOLS.has(toolName)) {
+    return { behavior: "allow" };
+  }
+  if (toolName === "Skill") {
+    return { behavior: "allow" };
+  }
+  return { behavior: "pending" };
+}
 
 // ── Streaming input wrapper (required for MCP tools) ─────────────────
 
@@ -151,21 +186,43 @@ export async function* sendMessage(
     return;
   }
 
+  let target;
+  try {
+    target = await resolveChatExecutionTarget({
+      requestedRuntimeId: conversation.runtimeId,
+      requestedModelId: conversation.modelId,
+    });
+  } catch (error) {
+    yield {
+      type: "error",
+      message: error instanceof Error ? error.message : "No chat runtime is available",
+    };
+    return;
+  }
+
+  if (target.fallbackApplied && target.fallbackReason) {
+    yield {
+      type: "status",
+      phase: "runtime_fallback",
+      message: target.fallbackReason,
+    };
+  }
+
   // Route to Codex App Server for OpenAI models
-  if (conversation.runtimeId === "openai-codex-app-server") {
+  if (target.effectiveRuntimeId === "openai-codex-app-server") {
     const { sendCodexMessage } = await import("./codex-engine");
-    yield* sendCodexMessage(conversationId, userContent, signal);
+    yield* sendCodexMessage(conversationId, userContent, signal, target);
     return;
   }
 
   // Route to Ollama for local models
-  if (conversation.runtimeId === "ollama") {
+  if (target.effectiveRuntimeId === "ollama") {
     const { sendOllamaMessage } = await import("./ollama-engine");
     yield* sendOllamaMessage(conversationId, userContent, signal);
     return;
   }
 
-  const runtimeId = conversation.runtimeId;
+  const runtimeId = target.effectiveRuntimeId;
   const providerId = getProviderForRuntime(runtimeId);
 
   // Enforce budget before the turn
@@ -277,10 +334,11 @@ export async function* sendMessage(
 
     // Create in-process MCP server for Stagent CRUD tools
     const toolResults: ToolResultCapture[] = [];
-    const stagentServer = createStagentMcpServer(
+    const stagentServer = createToolServer(
       conversation.projectId,
-      (toolName, result) => { toolResults.push({ toolName, result }); }
-    );
+      (toolName, result) => { toolResults.push({ toolName, result }); },
+      projectCwd,
+    ).asMcpServer();
 
     yield { type: "status", phase: "connecting", message: "Connecting to model..." };
 
@@ -300,7 +358,7 @@ export async function* sendMessage(
     const response = query({
       prompt: generatePrompt(fullPrompt),
       options: {
-        model: conversation.modelId || undefined,
+        model: target.effectiveModelId || conversation.modelId || undefined,
         maxTurns,
         abortController,
         includePartialMessages: true,
@@ -312,7 +370,13 @@ export async function* sendMessage(
           if (stderrChunks.length > 50) stderrChunks.shift();
         },
         mcpServers: { stagent: stagentServer, ...browserServers, ...externalServers },
-        allowedTools: ["mcp__stagent__*", ...browserToolPatterns, ...externalToolPatterns],
+        allowedTools: [
+          "mcp__stagent__*",
+          ...browserToolPatterns,
+          ...externalToolPatterns,
+          ...CLAUDE_SDK_ALLOWED_TOOLS,
+        ],
+        settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
         // @ts-expect-error Agent SDK canUseTool types are incomplete — our async handler is compatible at runtime
         canUseTool: async (
           toolName: string,
@@ -369,6 +433,32 @@ export async function* sendMessage(
             // Mutation browser tools fall through to permission check below
           }
 
+          // SDK filesystem read-only tools: auto-allow (mirror browser/exa pattern)
+          if (CLAUDE_SDK_READ_ONLY_FS_TOOLS.has(toolName)) {
+            emitSideChannelEvent(conversationId, {
+              type: "status",
+              phase: "tool_use",
+              message: `Filesystem: ${toolName.toLowerCase()}...`,
+            });
+            return { behavior: "allow", updatedInput: input };
+          }
+
+          // Skill tool: auto-allow. Rationale: the Skill tool loads skills from
+          // ~/.claude/skills/ and .claude/skills/ — the same sources the Claude Code
+          // CLI trusts unconditionally. Any tool the skill subsequently invokes
+          // (Bash, Edit, etc.) goes through this same canUseTool check. The trust
+          // assumption here is identical to using `claude` directly; no new attack
+          // surface is introduced. See: features/chat-claude-sdk-skills.md, Error
+          // & Rescue Registry row "settingSources loads hostile skill".
+          if (toolName === "Skill") {
+            emitSideChannelEvent(conversationId, {
+              type: "status",
+              phase: "tool_use",
+              message: `Skill: ${(input as { skill?: string }).skill ?? "unknown"}...`,
+            });
+            return { behavior: "allow", updatedInput: input };
+          }
+
           const isQuestion = toolName === "AskUserQuestion";
 
           // Layer 1: Check saved user permissions (skip for questions)
@@ -615,7 +705,11 @@ export async function* sendMessage(
 
     // Save usage metadata + quick access links + screenshot attachments
     const metadata = JSON.stringify({
-      modelId: usage.modelId ?? conversation.modelId,
+      modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId,
+      runtimeId,
+      requestedRuntimeId: target.requestedRuntimeId ?? conversation.runtimeId,
+      requestedModelId: target.requestedModelId ?? conversation.modelId,
+      ...(target.fallbackReason ? { fallbackReason: target.fallbackReason } : {}),
       inputTokens: usage.inputTokens,
       outputTokens: usage.outputTokens,
       ...(quickAccess.length > 0 ? { quickAccess } : {}),
@@ -632,7 +726,7 @@ export async function* sendMessage(
       activityType: "chat_turn",
       runtimeId,
       providerId,
-      modelId: usage.modelId ?? conversation.modelId ?? null,
+      modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
       inputTokens: usage.inputTokens ?? null,
       outputTokens: usage.outputTokens ?? null,
       totalTokens: usage.totalTokens ?? null,
@@ -695,7 +789,7 @@ export async function* sendMessage(
         activityType: "chat_turn",
         runtimeId,
         providerId,
-        modelId: usage.modelId ?? conversation.modelId ?? null,
+        modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
         inputTokens: usage.inputTokens ?? null,
         outputTokens: usage.outputTokens ?? null,
         totalTokens: usage.totalTokens ?? null,
@@ -722,7 +816,7 @@ export async function* sendMessage(
         activityType: "chat_turn",
         runtimeId,
         providerId,
-        modelId: usage.modelId ?? conversation.modelId ?? null,
+        modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
         inputTokens: usage.inputTokens ?? null,
         outputTokens: usage.outputTokens ?? null,
         totalTokens: usage.totalTokens ?? null,

package/src/lib/chat/files/__tests__/search.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Hoist mutable state so the mock factories can read it.
+const { mockState } = vi.hoisted(() => ({
+  mockState: {
+    stdout: "" as string,
+    execFileThrows: false as boolean | Error,
+    files: new Map<string, { size: number; mtimeMs: number }>(),
+    realpathMap: new Map<string, string>(),
+  },
+}));
+
+vi.mock("node:child_process", () => {
+  const execFileSync = vi.fn(() => {
+    if (mockState.execFileThrows) {
+      throw mockState.execFileThrows instanceof Error
+        ? mockState.execFileThrows
+        : new Error("git not available");
+    }
+    return mockState.stdout;
+  });
+  return {
+    default: { execFileSync },
+    execFileSync,
+  };
+});
+
+vi.mock("node:fs", () => {
+  const realpathSync = (p: string) => mockState.realpathMap.get(p) ?? p;
+  const statSync = (absPath: string) => {
+    const f = mockState.files.get(absPath);
+    if (!f) throw new Error(`ENOENT: ${absPath}`);
+    return { size: f.size, mtimeMs: f.mtimeMs };
+  };
+  return {
+    default: { realpathSync, statSync },
+    realpathSync,
+    statSync,
+  };
+});
+
+import { searchFiles } from "../search";
+
+// Helper: all test files live under this fake cwd
+const CWD = "/repo";
+
+function file(relPath: string, size: number, mtimeMs: number) {
+  mockState.files.set(`${CWD}/${relPath}`, { size, mtimeMs });
+}
+
+beforeEach(() => {
+  mockState.stdout = "";
+  mockState.execFileThrows = false;
+  mockState.files.clear();
+  mockState.realpathMap.clear();
+  mockState.realpathMap.set(CWD, CWD);
+  vi.clearAllMocks();
+});
+
+describe("searchFiles", () => {
+  it("returns all files when query is empty, mtime-sorted newest first", () => {
+    mockState.stdout = ["src/a.ts", "src/b.ts", "src/c.ts", ""].join("\n");
+    file("src/a.ts", 100, 1_000);
+    file("src/b.ts", 200, 3_000);
+    file("src/c.ts", 300, 2_000);
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/b.ts", "src/c.ts", "src/a.ts"]);
+    expect(hits[0].sizeBytes).toBe(200);
+  });
+
+  it("ranks filename matches above directory-path matches", () => {
+    mockState.stdout = [
+      "src/schema/other.ts", // directory match for "schema"
+      "src/lib/db/schema.ts", // filename match for "schema"
+      ""
+    ].join("\n");
+    file("src/schema/other.ts", 100, 1_000);
+    file("src/lib/db/schema.ts", 100, 500); // older but should still rank first
+
+    const hits = searchFiles(CWD, "schema", 10);
+    expect(hits[0].path).toBe("src/lib/db/schema.ts");
+    expect(hits[1].path).toBe("src/schema/other.ts");
+  });
+
+  it("performs case-insensitive substring match", () => {
+    mockState.stdout = ["src/Foo.TSX", "src/bar.ts", ""].join("\n");
+    file("src/Foo.TSX", 100, 1_000);
+    file("src/bar.ts", 100, 1_000);
+
+    const hits = searchFiles(CWD, "foo", 10);
+    expect(hits).toHaveLength(1);
+    expect(hits[0].path).toBe("src/Foo.TSX");
+  });
+
+  it("respects limit cap", () => {
+    const lines: string[] = [];
+    for (let i = 0; i < 50; i++) {
+      const p = `src/file${i}.ts`;
+      lines.push(p);
+      file(p, 100, i * 10);
+    }
+    mockState.stdout = lines.join("\n");
+
+    const hits = searchFiles(CWD, "", 5);
+    expect(hits).toHaveLength(5);
+  });
+
+  it("returns [] when execFileSync throws (not a git repo)", () => {
+    mockState.execFileThrows = new Error("not a git repository");
+    const hits = searchFiles(CWD, "anything", 10);
+    expect(hits).toEqual([]);
+  });
+
+  it("skips files that disappeared between ls-files and stat", () => {
+    mockState.stdout = ["src/exists.ts", "src/ghost.ts", ""].join("\n");
+    file("src/exists.ts", 100, 1_000);
+    // src/ghost.ts intentionally absent from the files map — statSync throws
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/exists.ts"]);
+  });
+
+  it("excludes files that would resolve outside cwd (defense-in-depth)", () => {
+    // git ls-files should never emit such a path, but if it did we must reject.
+    mockState.stdout = ["../escape.ts", "src/ok.ts", ""].join("\n");
+    // Do NOT register the escape path in files — resolve() would point outside
+    // /repo, and the startsWith check in search.ts will discard it before
+    // statSync is even called.
+    file("src/ok.ts", 100, 1_000);
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/ok.ts"]);
+  });
+});

package/src/lib/chat/files/expand-mention.ts

@@ -0,0 +1,76 @@
+import { realpathSync, statSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Format a single `entityType: "file"` mention for Tier 3.
+ *
+ * Security:
+ *  - `cwd` is resolved by the caller from a trusted source (active project's
+ *    workingDirectory, else `getLaunchCwd()`) — NEVER from the mention itself.
+ *  - The mention's `relPath` is treated as a relative path; any path that
+ *    resolves outside `cwd` is rejected without opening the file.
+ *
+ * Size semantics (matches spec §3 "tiered expansion"):
+ *  - < 8 KB: inline content inside a fenced code block with path header.
+ *  - >= 8 KB and < MAX_SIZE: emit a short reference line so agents with a
+ *    `Read` tool can fetch the file on demand; agents without one degrade
+ *    gracefully ("I can't read large files on this runtime").
+ *  - >= MAX_SIZE (50 MB): skip silently — pathological.
+ *
+ * Non-crashing by design: any read/stat failure becomes a short note in
+ * the output, not a thrown error that would break the whole prompt build.
+ */
+export function expandFileMention(relPath: string, cwd: string): string[] {
+  const lines: string[] = [];
+
+  let cwdReal: string;
+  try {
+    cwdReal = realpathSync(cwd);
+  } catch {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(cwd does not exist)");
+    return lines;
+  }
+
+  const abs = resolve(cwdReal, relPath);
+  if (!abs.startsWith(cwdReal)) {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(invalid path — escapes working directory)");
+    return lines;
+  }
+
+  let stat: { size: number };
+  try {
+    stat = statSync(abs);
+  } catch {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(file not found at context-build time)");
+    return lines;
+  }
+
+  const INLINE_LIMIT = 8 * 1024;
+  const MAX_SIZE = 50 * 1024 * 1024;
+  if (stat.size > MAX_SIZE) return []; // skip silently
+
+  if (stat.size < INLINE_LIMIT) {
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf8");
+    } catch {
+      lines.push(`\n### File: ${relPath}`);
+      lines.push("(file could not be read as UTF-8)");
+      return lines;
+    }
+    const ext = relPath.split(".").pop() ?? "";
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("```" + ext);
+    lines.push(content);
+    lines.push("```");
+  } else {
+    lines.push(
+      `\n### File (by reference): ${relPath} (${Math.round(stat.size / 1024)} KB)`
+    );
+    lines.push("Use the Read tool to load this file if you need its content.");
+  }
+  return lines;
+}