little-coder 1.0.0

package/.pi/extensions/shell-session/helpers.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { stripAnsi, dedupLines, truncateLines, formatOutput } from "./helpers.ts";
+
+describe("stripAnsi", () => {
+  it("removes SGR sequences", () => {
+    expect(stripAnsi("\x1b[31mred\x1b[0m text")).toBe("red text");
+  });
+  it("passes through ansi-free text", () => {
+    expect(stripAnsi("hello")).toBe("hello");
+  });
+});
+
+describe("dedupLines", () => {
+  it("collapses consecutive duplicates", () => {
+    const out = dedupLines(["a", "b", "b", "b", "c"]);
+    expect(out).toEqual(["a", "b", "  [... 2 duplicate line(s) collapsed ...]", "c"]);
+  });
+  it("handles trailing duplicates", () => {
+    const out = dedupLines(["a", "a", "a"]);
+    expect(out).toEqual(["a", "  [... 2 duplicate line(s) collapsed ...]"]);
+  });
+});
+
+describe("truncateLines", () => {
+  it("passes through short output", () => {
+    const { lines, truncated } = truncateLines(["a", "b"], 10);
+    expect(lines).toEqual(["a", "b"]);
+    expect(truncated).toBe(false);
+  });
+  it("truncates long output with head/tail", () => {
+    const input = Array.from({ length: 20 }, (_, i) => `line${i}`);
+    const { lines, truncated } = truncateLines(input, 8);
+    expect(truncated).toBe(true);
+    // cap=8 → head=4, tail=2, skipped=14
+    expect(lines.length).toBe(4 + 1 + 2);
+    expect(lines[0]).toBe("line0");
+    expect(lines[4]).toContain("lines truncated");
+  });
+});
+
+describe("formatOutput", () => {
+  it("formats basic exit=0 output", () => {
+    const out = formatOutput("hello\nworld\n", 0, "/tmp", false, "backend=subprocess");
+    expect(out).toContain("hello");
+    expect(out).toContain("world");
+    expect(out).toContain("[exit=0 cwd=/tmp timed_out=false backend=subprocess]");
+  });
+  it("emits footer only for empty body", () => {
+    const out = formatOutput("", 0, "/tmp", false, "");
+    expect(out.startsWith("[")).toBe(true);
+  });
+  it("appends output_truncated when head/tail cut", () => {
+    const big = Array.from({ length: 500 }, (_, i) => `line${i}`).join("\n");
+    const out = formatOutput(big, 0, "/", false, "");
+    expect(out).toContain("output_truncated=true");
+  });
+  it("strips ANSI before line processing", () => {
+    const out = formatOutput("\x1b[32mgreen\x1b[0m", 0, "/", false, "");
+    expect(out).toContain("green");
+    expect(out).not.toContain("\x1b");
+  });
+});

package/.pi/extensions/shell-session/helpers.ts

@@ -0,0 +1,58 @@
+// Shared output-formatting helpers for ShellSession. Mirrors
+// local/tools/shell_session.py's _strip_ansi / _dedup_lines / _truncate_lines
+// so output reaches the model in the same format across backends.
+
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+export const MAX_LINES = 200;
+export const DEFAULT_TIMEOUT = 30;
+
+export function stripAnsi(s: string): string {
+  return s.replace(ANSI_RE, "");
+}
+
+export function dedupLines(lines: string[]): string[] {
+  const out: string[] = [];
+  let last: string | null = null;
+  let dup = 0;
+  for (const ln of lines) {
+    if (ln === last) {
+      dup++;
+      continue;
+    }
+    if (dup > 0) out.push(`  [... ${dup} duplicate line(s) collapsed ...]`);
+    dup = 0;
+    out.push(ln);
+    last = ln;
+  }
+  if (dup > 0) out.push(`  [... ${dup} duplicate line(s) collapsed ...]`);
+  return out;
+}
+
+export function truncateLines(lines: string[], cap = MAX_LINES): { lines: string[]; truncated: boolean } {
+  if (lines.length <= cap) return { lines, truncated: false };
+  const head = Math.floor(cap / 2);
+  const tail = Math.floor(cap / 4);
+  const skipped = lines.length - head - tail;
+  return {
+    lines: [...lines.slice(0, head), `  [... ${skipped} lines truncated ...]`, ...lines.slice(-tail)],
+    truncated: true,
+  };
+}
+
+export function formatOutput(
+  raw: string,
+  code: number,
+  cwd: string,
+  timedOut: boolean,
+  backendNote: string,
+): string {
+  const cleaned = stripAnsi(raw).replace(/\r/g, "");
+  const dedupped = dedupLines(cleaned.split("\n"));
+  const { lines, truncated } = truncateLines(dedupped);
+  const body = lines.join("\n");
+  const footerBits = [`exit=${code}`, `cwd=${cwd}`, `timed_out=${timedOut ? "true" : "false"}`];
+  if (truncated) footerBits.push("output_truncated=true");
+  if (backendNote) footerBits.push(backendNote);
+  const footer = `[${footerBits.join(" ")}]`;
+  return body ? `${body}\n${footer}` : footer;
+}

package/.pi/extensions/shell-session/index.ts

@@ -0,0 +1,139 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { execSync } from "node:child_process";
+import { formatOutput, DEFAULT_TIMEOUT } from "./helpers.ts";
+
+// Port of local/tools/shell_session.py. Two backends implemented:
+//   1. tmux-proxy — when LITTLE_CODER_TB_MODE=1, route every command to the
+//      parent TB adapter over the extension_ui_request channel. The parent
+//      drives the actual TmuxSession so commands appear in TB's trajectory.
+//   2. subprocess — child_process.execSync for local use (GAIA doesn't use
+//      ShellSession; this is for local REPL + debugging of TB adapter).
+//
+// The sentinel-prompt pexpect backend from the Python version (persistent
+// bash process with state between calls) is deliberately skipped because
+// neither Terminal-Bench nor GAIA requires it; TB uses tmux, GAIA uses Bash.
+
+const TB_MODE_ENV = "LITTLE_CODER_TB_MODE";
+const TB_PROXY_PREFIX = "__LC_TB_SHELL__:";
+
+function inTbMode(): boolean {
+  return process.env[TB_MODE_ENV] === "1";
+}
+
+async function execSubprocess(command: string, timeoutSec: number): Promise<string> {
+  try {
+    const buf = execSync(command, {
+      shell: "/bin/bash",
+      timeout: timeoutSec * 1000,
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    return formatOutput(String(buf), 0, process.cwd(), false, "backend=subprocess");
+  } catch (err: any) {
+    const out = (err.stdout?.toString?.() ?? "") + (err.stderr?.toString?.() ?? "");
+    const timedOut = err.code === "ETIMEDOUT" || err.signal === "SIGTERM";
+    const code = typeof err.status === "number" ? err.status : -1;
+    return formatOutput(out, code, process.cwd(), timedOut, "backend=subprocess");
+  }
+}
+
+async function execTmuxProxy(
+  ctx: any,
+  command: string,
+  timeoutSec: number,
+  sessionId: string,
+): Promise<string> {
+  const payload = {
+    op: "run",
+    session_id: sessionId,
+    command,
+    timeout: timeoutSec,
+  };
+  // Use ctx.ui.input as a generic data-carrying channel. The Python TB adapter
+  // intercepts extension_ui_request with title prefix __LC_TB_SHELL__ and
+  // responds with the formatted tool output string.
+  const title = TB_PROXY_PREFIX + JSON.stringify(payload);
+  const response = await ctx.ui.input(title, "");
+  if (typeof response === "string") return response;
+  return formatOutput(
+    "Error: tmux proxy returned no response",
+    -1, "?", true, "backend=tmux-proxy",
+  );
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "ShellSession",
+    label: "ShellSession",
+    description:
+      "Run a command in a persistent bash session. cd, env vars, and shell state " +
+      "persist across calls. One command per turn. Default timeout 30s (increase to " +
+      "120-300 for installs/builds). Output is line-capped with head/tail truncation " +
+      "and a trailing [exit=N cwd=… timed_out=…] footer.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Shell command to run" }),
+      timeout: Type.Optional(Type.Integer({ description: "Seconds (default 30, max 600)" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const cmd = String(params.command ?? "").trim();
+      if (!cmd) {
+        return {
+          content: [{ type: "text", text: "Error: command is required" }],
+          details: {}, isError: true,
+        };
+      }
+      const rawTimeout = typeof params.timeout === "number" ? params.timeout : DEFAULT_TIMEOUT;
+      const timeoutSec = Math.max(5, Math.min(rawTimeout, 600));
+      const sessionId = process.env.LITTLE_CODER_SESSION_ID || "default";
+
+      let text: string;
+      if (inTbMode()) {
+        text = await execTmuxProxy(ctx, cmd, timeoutSec, sessionId);
+      } else {
+        text = await execSubprocess(cmd, timeoutSec);
+      }
+      return { content: [{ type: "text", text }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "ShellSessionCwd",
+    label: "ShellSessionCwd",
+    description: "Print the current working directory of the shell session.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const sessionId = process.env.LITTLE_CODER_SESSION_ID || "default";
+      let text: string;
+      if (inTbMode()) {
+        text = await execTmuxProxy(ctx, "pwd", 5, sessionId);
+      } else {
+        text = await execSubprocess("pwd", 5);
+      }
+      return { content: [{ type: "text", text }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "ShellSessionReset",
+    label: "ShellSessionReset",
+    description: "Kill and restart the bash session. Use only if it becomes unresponsive.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const sessionId = process.env.LITTLE_CODER_SESSION_ID || "default";
+      if (inTbMode()) {
+        const payload = { op: "reset", session_id: sessionId };
+        await ctx.ui.input(TB_PROXY_PREFIX + JSON.stringify(payload), "");
+        return {
+          content: [{ type: "text", text: `Session '${sessionId}' unstuck and reinitialized.` }],
+          details: {},
+        };
+      }
+      // Subprocess backend is stateless — reset is a no-op
+      return {
+        content: [{ type: "text", text: `Session '${sessionId}' reset (subprocess backend is stateless).` }],
+        details: {},
+      };
+    },
+  });
+}

package/.pi/extensions/skill-inject/frontmatter.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { parseSkillFile } from "./frontmatter.ts";
+
+describe("parseSkillFile", () => {
+  it("parses basic tool-guidance frontmatter", () => {
+    const text = `---
+name: read-guidance
+type: tool-guidance
+target_tool: Read
+priority: 10
+token_cost: 100
+user-invocable: false
+---
+## Read Tool
+Body content here.`;
+    const p = parseSkillFile(text);
+    expect(p).not.toBeNull();
+    expect(p!.frontmatter.name).toBe("read-guidance");
+    expect(p!.frontmatter.target_tool).toBe("Read");
+    expect(p!.frontmatter.token_cost).toBe(100);
+    expect(p!.frontmatter.priority).toBe(10);
+    expect(p!.body.startsWith("## Read Tool")).toBe(true);
+  });
+
+  it("parses knowledge frontmatter with keyword arrays", () => {
+    const text = `---
+name: bfs-state-space
+type: domain-knowledge
+topic: State-Space Search
+token_cost: 120
+keywords: [bucket, pouring, state space, minimum moves, shortest sequence]
+---
+When a problem asks for minimum moves.`;
+    const p = parseSkillFile(text);
+    expect(p).not.toBeNull();
+    expect(p!.frontmatter.topic).toBe("State-Space Search");
+    expect(p!.frontmatter.keywords).toEqual([
+      "bucket", "pouring", "state space", "minimum moves", "shortest sequence",
+    ]);
+  });
+
+  it("parses requires_tools arrays", () => {
+    const text = `---
+name: workspace-docs
+topic: Workspace Documentation
+keywords: [spec, readme]
+requires_tools: [Read, Glob]
+---
+body`;
+    const p = parseSkillFile(text);
+    expect(p!.frontmatter.requires_tools).toEqual(["Read", "Glob"]);
+  });
+
+  it("returns null on missing frontmatter", () => {
+    expect(parseSkillFile("no frontmatter here")).toBeNull();
+  });
+
+  it("handles body with multiple --- separators", () => {
+    const text = `---
+name: x
+topic: X
+---
+body line 1
+---
+body line 2`;
+    const p = parseSkillFile(text);
+    expect(p).not.toBeNull();
+    // Body should preserve everything after the closing ---
+    expect(p!.body).toContain("body line 1");
+    expect(p!.body).toContain("body line 2");
+  });
+});

package/.pi/extensions/skill-inject/frontmatter.ts

@@ -0,0 +1,39 @@
+// Minimal YAML frontmatter parser — enough for the fields little-coder uses.
+// Mirrors skill/loader.py::_parse_skill_file's behavior, no external deps.
+
+export interface Frontmatter {
+  [key: string]: string | string[] | number | boolean | undefined;
+}
+
+export interface ParsedSkill {
+  frontmatter: Frontmatter;
+  body: string;
+}
+
+export function parseSkillFile(text: string): ParsedSkill | null {
+  const parts = text.split("---");
+  if (parts.length < 3) return null;
+  const fmText = parts[1].trim();
+  const body = parts.slice(2).join("---").trim();
+  const fm: Frontmatter = {};
+  for (const line of fmText.split("\n")) {
+    const m = line.match(/^(\w[\w_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1].trim();
+    let val = m[2].trim();
+    if (val.startsWith("[") && val.endsWith("]")) {
+      fm[key] = val
+        .slice(1, -1)
+        .split(",")
+        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+        .filter((s) => s.length > 0);
+    } else if (/^-?\d+$/.test(val)) {
+      fm[key] = parseInt(val, 10);
+    } else if (val === "true" || val === "false") {
+      fm[key] = val === "true";
+    } else {
+      fm[key] = val;
+    }
+  }
+  return { frontmatter: fm, body };
+}

package/.pi/extensions/skill-inject/index.ts

@@ -0,0 +1,256 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile } from "./frontmatter.ts";
+
+// ── Tool-skill registry ─────────────────────────────────────────────────
+// Port of local/skill_augment.py. Loads skills/tools/*.md once, hooks
+// `before_agent_start` to append a `## Tool Usage Guidance` block to the
+// system prompt. Per-user-prompt selection using the whitepaper's 3-priority
+// algorithm (error recovery > recency > intent). Budget-guarded, cached.
+
+interface ToolSkill {
+  targetTool: string;
+  body: string;
+  tokenCost: number;
+}
+
+const skills = new Map<string, ToolSkill>();
+const selectionCache = new Map<string, string>();
+let loaded = false;
+
+// State tracked across the session so we have error-recovery + recency
+// signals by the time the next `before_agent_start` fires.
+const recentToolCalls: string[] = []; // most-recent-first, capped at 8
+let lastFailedTool: string | null = null;
+
+// ── Intent keywords → likely tools ──────────────────────────────────────
+const INTENT_MAP: Record<string, string[]> = {
+  read: ["Read"], show: ["Read"], view: ["Read"], cat: ["Read"],
+  write: ["Write"], create: ["Write", "Bash"],
+  implement: ["Write", "Read"], code: ["Write", "Read"],
+  function: ["Write", "Edit"], class: ["Write", "Edit"],
+  edit: ["Edit"], change: ["Edit"], modify: ["Edit"],
+  fix: ["Edit"], update: ["Edit"], replace: ["Edit"],
+  add: ["Edit", "Write"], refactor: ["Edit", "Read"],
+  run: ["Bash"], execute: ["Bash"], install: ["Bash"],
+  build: ["Bash"], test: ["Bash"],
+  find: ["Glob", "Grep"], search: ["Grep"],
+  grep: ["Grep"], glob: ["Glob"],
+  fetch: ["WebFetch"], download: ["WebFetch"], url: ["WebFetch"],
+  web: ["WebSearch"],
+  // Research / browser / evidence
+  research: ["BrowserNavigate", "BrowserExtract", "EvidenceAdd"],
+  researching: ["BrowserNavigate", "BrowserExtract", "EvidenceAdd"],
+  wikipedia: ["BrowserNavigate", "BrowserExtract", "EvidenceAdd"],
+  article: ["BrowserNavigate", "BrowserExtract", "EvidenceAdd"],
+  citation: ["EvidenceAdd", "BrowserExtract"],
+  cite: ["EvidenceAdd"],
+  source: ["EvidenceAdd", "BrowserExtract"],
+  fact: ["EvidenceAdd"],
+  factcheck: ["EvidenceAdd", "BrowserExtract"],
+  question: ["EvidenceAdd", "BrowserExtract"],
+  answer: ["EvidenceAdd", "EvidenceList"],
+  navigate: ["BrowserNavigate"],
+  browse: ["BrowserNavigate", "BrowserExtract"],
+  page: ["BrowserExtract"],
+  click: ["BrowserClick"],
+  agent: ["Agent"], delegate: ["Agent"], spawn: ["Agent"],
+};
+
+function skillsDir(): string {
+  // Extension lives at .pi/extensions/skill-inject/, repo root is 3 levels up
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "..", "..", "skills", "tools");
+}
+
+function loadSkills(): void {
+  if (loaded) return;
+  loaded = true;
+  const dir = skillsDir();
+  if (!existsSync(dir)) return;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".md")) continue;
+    const parsed = parseSkillFile(readFileSync(join(dir, file), "utf-8"));
+    if (!parsed) continue;
+    const target = parsed.frontmatter.target_tool;
+    if (typeof target !== "string" || !target) continue;
+    const cost = typeof parsed.frontmatter.token_cost === "number"
+      ? parsed.frontmatter.token_cost
+      : 150;
+    skills.set(target, { targetTool: target, body: parsed.body, tokenCost: cost });
+  }
+}
+
+function predictTools(userText: string): string[] {
+  const words = new Set(userText.toLowerCase().split(/\s+/).filter(Boolean));
+  const predicted: string[] = [];
+  for (const [kw, toolNames] of Object.entries(INTENT_MAP)) {
+    if (!words.has(kw)) continue;
+    for (const tn of toolNames) if (!predicted.includes(tn)) predicted.push(tn);
+  }
+  return predicted;
+}
+
+function selectSkills(prompt: string, budget: number, allowed?: Set<string>): ToolSkill[] {
+  const selected: ToolSkill[] = [];
+  let used = 0;
+  const tryAdd = (name: string): void => {
+    const sk = skills.get(name);
+    if (!sk || selected.includes(sk)) return;
+    if (allowed && !allowed.has(name)) return;
+    if (used + sk.tokenCost > budget) return;
+    selected.push(sk);
+    used += sk.tokenCost;
+  };
+
+  // 1. Error recovery — last failed tool
+  if (lastFailedTool) tryAdd(lastFailedTool);
+
+  // 2. Recency — last 2 tool calls
+  for (const name of recentToolCalls.slice(0, 4)) {
+    if (used >= budget) break;
+    tryAdd(name);
+  }
+
+  // 3. Intent prediction on the user's current prompt
+  if (used < budget) {
+    for (const name of predictTools(prompt)) {
+      if (used >= budget) break;
+      tryAdd(name);
+    }
+  }
+
+  return selected;
+}
+
+function buildBlock(selected: ToolSkill[]): string {
+  let out = "\n\n## Tool Usage Guidance\n";
+  for (const s of selected) out += `\n### ${s.targetTool}\n${s.body}\n`;
+  return out;
+}
+
+// Keyword-triggered directive: when the user's prompt smells like a
+// research / web-lookup task, prepend an explicit "browse-first, then
+// edit-write" rule. Without it, qwen-class small models often skip
+// straight to Edit/Write on free-form questions, never gathering evidence.
+const RESEARCH_TRIGGERS = [
+  /\bbrows(?:e|ing|er)\b/i,
+  /\bonline\b/i,
+  /\bresearch(?:ing)?\b/i,
+  /\blook\s+up\b/i,
+  /\blookup\b/i,
+  /\bsearch\s+(?:the|for)\b/i,
+  /\bweb\s*search\b/i,
+  /\bwikipedia\b/i,
+  /\bwebsite\b/i,
+  /\bweb\s*page\b/i,
+  /\bgoogle\b/i,
+  /\bcite|citation\b/i,
+  /\bfact[-\s]?check/i,
+];
+
+function looksLikeResearchTask(text: string): boolean {
+  if (!text) return false;
+  for (const re of RESEARCH_TRIGGERS) {
+    if (re.test(text)) return true;
+  }
+  return false;
+}
+
+const RESEARCH_DIRECTIVE = [
+  "",
+  "## Research-first directive",
+  "This task involves online research. Before producing a final answer:",
+  "1. Use BrowserNavigate / BrowserExtract (or WebSearch for first hops) to gather facts.",
+  "2. Save each citable fact via EvidenceAdd before relying on it.",
+  "3. Only after evidence is in place should you consider any Edit/Write tool calls.",
+  "Skipping the gather step (going straight to Edit/Write or guessing from memory) is wrong — restart with the browse step instead.",
+  "",
+].join("\n");
+
+export default function (pi: ExtensionAPI) {
+  // Track tool usage across the whole session so recency + error-recovery
+  // state is available on the next before_agent_start.
+  pi.on("tool_result", async (event) => {
+    const name = (event as any).toolName || (event as any).name;
+    if (typeof name === "string") {
+      // prepend, keep deduplicated recency list capped
+      const idx = recentToolCalls.indexOf(name);
+      if (idx !== -1) recentToolCalls.splice(idx, 1);
+      recentToolCalls.unshift(name);
+      if (recentToolCalls.length > 8) recentToolCalls.length = 8;
+    }
+    const isError = (event as any).isError === true;
+    lastFailedTool = isError && typeof name === "string" ? name : null;
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    loadSkills();
+    if (skills.size === 0) return;
+
+    const opts: any = (event as any).systemPromptOptions ?? {};
+    const lc = opts.littleCoder ?? {};
+    const budget: number = lc.skillTokenBudget ?? 300;
+    if (budget <= 0) return;
+
+    // Allow-list source: prefer systemPromptOptions (set by tool-gating's
+    // before_agent_start), but fall back to LITTLE_CODER_ALLOWED_TOOLS env
+    // directly. Pi runs before_agent_start handlers in extension load order
+    // (alphabetical), so skill-inject fires before tool-gating and
+    // lc.allowedTools is undefined on the first turn unless we read env here.
+    let allowedList: string[] | undefined = lc.allowedTools;
+    if (!allowedList && process.env.LITTLE_CODER_ALLOWED_TOOLS) {
+      allowedList = process.env.LITTLE_CODER_ALLOWED_TOOLS
+        .split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    const allowed = allowedList && allowedList.length > 0 ? new Set(allowedList) : undefined;
+
+    // Knowledge-inject may publish required_tools on systemPromptOptions —
+    // pre-add those before selecting so they win even when budget is tight.
+    // Benchmark profiles can also publish requiredTools (e.g. GAIA -> Browser+Evidence).
+    const preferred: string[] = Array.isArray(lc.requiredTools) ? lc.requiredTools : [];
+    for (const t of preferred) {
+      if (!recentToolCalls.includes(t)) recentToolCalls.unshift(t);
+    }
+
+    const selected = selectSkills(event.prompt ?? "", budget, allowed);
+    const researchTask = looksLikeResearchTask(event.prompt ?? "");
+
+    if (selected.length === 0 && !researchTask) return;
+
+    const skillBlock = selected.length > 0
+      ? (() => {
+          const key = selected.map((s) => s.targetTool).sort().join("|");
+          let b = selectionCache.get(key);
+          if (b === undefined) {
+            b = buildBlock(selected);
+            selectionCache.set(key, b);
+          }
+          return b;
+        })()
+      : "";
+
+    const directive = researchTask ? RESEARCH_DIRECTIVE : "";
+
+    // Fire-and-forget notify so the benchmark harness can count per-turn
+    // skill injections without having to reconstruct the system prompt.
+    try {
+      const parts: string[] = [];
+      if (selected.length > 0) {
+        parts.push(`+${selected.length} [${selected.map((s) => s.targetTool).join(",")}]`);
+      }
+      if (researchTask) parts.push("+research-directive");
+      ctx.ui.notify(`skill-inject: ${parts.join(" ")}`, "info");
+    } catch {
+      // UI unavailable in some run modes — silent best-effort
+    }
+
+    // Order: [AGENTS.md] [tool skill cards] [research directive].
+    // The directive is the LAST block in the system prompt by design —
+    // small models show strong recency bias and the per-task instruction
+    // is exactly what we want freshest in their attention.
+    return { systemPrompt: (event.systemPrompt ?? "") + skillBlock + directive };
+  });
+}