little-coder 1.0.3 → 1.2.0

package/.pi/extensions/llama-cpp-provider/config.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyEnvOverrides, loadProviders, mergeProviders, resolveOverridePath, type ProviderEntry } from "./config.ts";
+
+const sampleProvider = (baseUrl: string, modelId: string): ProviderEntry => ({
+  api: "openai-completions",
+  baseUrl,
+  apiKey: "SAMPLE_KEY",
+  models: [
+    {
+      id: modelId,
+      name: modelId,
+      reasoning: true,
+      input: ["text"],
+      contextWindow: 32768,
+      maxTokens: 4096,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    },
+  ],
+});
+
+describe("resolveOverridePath", () => {
+  it("prefers LITTLE_CODER_MODELS_FILE", () => {
+    expect(resolveOverridePath({ LITTLE_CODER_MODELS_FILE: "/explicit.json", HOME: "/h" })).toBe("/explicit.json");
+  });
+  it("falls back to XDG_CONFIG_HOME", () => {
+    expect(resolveOverridePath({ XDG_CONFIG_HOME: "/xdg", HOME: "/h" })).toBe("/xdg/little-coder/models.json");
+  });
+  it("falls back to HOME/.config", () => {
+    expect(resolveOverridePath({ HOME: "/h" })).toBe("/h/.config/little-coder/models.json");
+  });
+  it("returns undefined when neither is set", () => {
+    expect(resolveOverridePath({})).toBeUndefined();
+  });
+});
+
+describe("mergeProviders", () => {
+  it("returns the package default unchanged when there's no override", () => {
+    const pkg = { llamacpp: sampleProvider("http://a/v1", "m1") };
+    expect(mergeProviders(pkg, undefined)).toEqual(pkg);
+  });
+  it("user provider replaces same-key package provider", () => {
+    const pkg = { llamacpp: sampleProvider("http://a/v1", "pkg-model") };
+    const user = { llamacpp: sampleProvider("http://b/v1", "user-model") };
+    const merged = mergeProviders(pkg, user);
+    expect(merged.llamacpp.baseUrl).toBe("http://b/v1");
+    expect(merged.llamacpp.models[0].id).toBe("user-model");
+  });
+  it("user provider not in package is added", () => {
+    const pkg = { llamacpp: sampleProvider("http://a/v1", "m1") };
+    const user = { custom: sampleProvider("http://c/v1", "c1") };
+    const merged = mergeProviders(pkg, user);
+    expect(Object.keys(merged).sort()).toEqual(["custom", "llamacpp"]);
+  });
+  it("package providers without an override are kept as-is", () => {
+    const pkg = {
+      llamacpp: sampleProvider("http://a/v1", "m1"),
+      ollama: sampleProvider("http://o/v1", "m2"),
+    };
+    const user = { llamacpp: sampleProvider("http://b/v1", "m1b") };
+    const merged = mergeProviders(pkg, user);
+    expect(merged.ollama.baseUrl).toBe("http://o/v1");
+  });
+});
+
+describe("applyEnvOverrides", () => {
+  it("LLAMACPP_BASE_URL overrides llamacpp baseUrl", () => {
+    const providers = { llamacpp: sampleProvider("http://file/v1", "m1") };
+    const out = applyEnvOverrides(providers, { LLAMACPP_BASE_URL: "http://env/v1" });
+    expect(out.llamacpp.baseUrl).toBe("http://env/v1");
+  });
+  it("OLLAMA_BASE_URL overrides ollama baseUrl", () => {
+    const providers = { ollama: sampleProvider("http://file/v1", "m2") };
+    const out = applyEnvOverrides(providers, { OLLAMA_BASE_URL: "http://env/v1" });
+    expect(out.ollama.baseUrl).toBe("http://env/v1");
+  });
+  it("LMSTUDIO_BASE_URL overrides lmstudio baseUrl", () => {
+    const providers = { lmstudio: sampleProvider("http://127.0.0.1:1234/v1", "local-model") };
+    const out = applyEnvOverrides(providers, { LMSTUDIO_BASE_URL: "http://127.0.0.1:5678/v1" });
+    expect(out.lmstudio.baseUrl).toBe("http://127.0.0.1:5678/v1");
+  });
+  it("does not alter providers without a known env knob", () => {
+    const providers = { custom: sampleProvider("http://file/v1", "m") };
+    const out = applyEnvOverrides(providers, { LLAMACPP_BASE_URL: "http://env/v1" });
+    expect(out.custom.baseUrl).toBe("http://file/v1");
+  });
+});
+
+describe("loadProviders (filesystem)", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "lc-providers-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("loads the package default when present", () => {
+    writeFileSync(
+      join(dir, "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://a/v1", "m1") } }),
+    );
+    const result = loadProviders(dir, {});
+    expect(Object.keys(result.providers)).toEqual(["llamacpp"]);
+    expect(result.sources[0]).toMatchObject({ status: "ok" });
+  });
+
+  it("merges a user override file when LITTLE_CODER_MODELS_FILE points at one", () => {
+    writeFileSync(
+      join(dir, "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://a/v1", "pkg") } }),
+    );
+    const userPath = join(dir, "user-models.json");
+    writeFileSync(
+      userPath,
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://b/v1", "user") } }),
+    );
+    const result = loadProviders(dir, { LITTLE_CODER_MODELS_FILE: userPath });
+    expect(result.providers.llamacpp.baseUrl).toBe("http://b/v1");
+    expect(result.providers.llamacpp.models[0].id).toBe("user");
+  });
+
+  it("reports invalid JSON in the package default and returns empty providers", () => {
+    writeFileSync(join(dir, "models.json"), "{ this is not json");
+    const result = loadProviders(dir, {});
+    expect(result.providers).toEqual({});
+    expect(result.sources[0].status).toBe("invalid");
+  });
+
+  it("reports a missing user override without failing the load", () => {
+    writeFileSync(
+      join(dir, "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://a/v1", "m1") } }),
+    );
+    const missing = join(dir, "no-such-dir", "models.json");
+    const result = loadProviders(dir, { LITTLE_CODER_MODELS_FILE: missing });
+    expect(result.providers.llamacpp.baseUrl).toBe("http://a/v1");
+    expect(result.sources.find((s) => s.path === missing)?.status).toBe("missing");
+  });
+
+  it("env var still overrides baseUrl after merge", () => {
+    writeFileSync(
+      join(dir, "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://file/v1", "m") } }),
+    );
+    const result = loadProviders(dir, { LLAMACPP_BASE_URL: "http://env/v1" });
+    expect(result.providers.llamacpp.baseUrl).toBe("http://env/v1");
+  });
+
+  it("XDG_CONFIG_HOME overrides applied when no LITTLE_CODER_MODELS_FILE set", () => {
+    writeFileSync(
+      join(dir, "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://a/v1", "pkg") } }),
+    );
+    const xdg = join(dir, "xdg");
+    mkdirSync(join(xdg, "little-coder"), { recursive: true });
+    writeFileSync(
+      join(xdg, "little-coder", "models.json"),
+      JSON.stringify({ providers: { llamacpp: sampleProvider("http://x/v1", "via-xdg") } }),
+    );
+    const result = loadProviders(dir, { XDG_CONFIG_HOME: xdg });
+    expect(result.providers.llamacpp.models[0].id).toBe("via-xdg");
+  });
+});
+
+describe("shipped models.json", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = resolve(here, "..", "..", "..");
+
+  it("registers lmstudio/local-model on http://127.0.0.1:1234/v1", () => {
+    const result = loadProviders(pkgRoot, {});
+    const lmstudio = result.providers.lmstudio;
+    expect(lmstudio, "lmstudio provider should be present in shipped models.json").toBeDefined();
+    expect(lmstudio.baseUrl).toBe("http://127.0.0.1:1234/v1");
+    expect(lmstudio.api).toBe("openai-completions");
+    expect(lmstudio.apiKey).toBe("LMSTUDIO_API_KEY");
+    expect(lmstudio.models.find((m) => m.id === "local-model")).toBeDefined();
+  });
+
+  it("still registers llamacpp and ollama alongside lmstudio", () => {
+    const result = loadProviders(pkgRoot, {});
+    expect(Object.keys(result.providers).sort()).toEqual(["llamacpp", "lmstudio", "ollama"]);
+  });
+});

package/.pi/extensions/llama-cpp-provider/config.ts

@@ -0,0 +1,148 @@
+// Pure config-loading logic for the providers extension. Kept separate from
+// the pi wiring in index.ts so it can be unit-tested without a pi runtime.
+//
+// Schema (all required unless noted):
+//   {
+//     "providers": {
+//       "<name>": {
+//         "api": "openai-completions",
+//         "baseUrl": "http://...",
+//         "apiKey": "ENV_VAR_NAME",
+//         "models": [ { id, name, reasoning, input, contextWindow, maxTokens, cost }, ... ]
+//       }, ...
+//     }
+//   }
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ProviderModelEntry {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ("text" | "image")[];
+  contextWindow: number;
+  maxTokens: number;
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+}
+
+export interface ProviderEntry {
+  api: string;
+  baseUrl: string;
+  apiKey: string;
+  models: ProviderModelEntry[];
+}
+
+export interface ModelsFile {
+  providers: Record<string, ProviderEntry>;
+}
+
+export interface LoadResult {
+  providers: Record<string, ProviderEntry>;
+  /** Files that were attempted, in resolution order. Useful for diagnostics. */
+  sources: { path: string; status: "ok" | "missing" | "invalid"; error?: string }[];
+}
+
+/** Provider env knob: if set, overrides the provider's baseUrl. Originally a
+ *  back-compat shim for the two providers we shipped before the data-driven
+ *  refactor; kept as the per-provider env-override pattern for any provider
+ *  whose baseUrl changes between deployments. */
+const LEGACY_BASE_URL_ENV: Record<string, string> = {
+  llamacpp: "LLAMACPP_BASE_URL",
+  ollama: "OLLAMA_BASE_URL",
+  lmstudio: "LMSTUDIO_BASE_URL",
+};
+
+/** Resolution order for the user-override file. First existing path wins. */
+export function resolveOverridePath(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (env.LITTLE_CODER_MODELS_FILE) return env.LITTLE_CODER_MODELS_FILE;
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg) return join(xdg, "little-coder", "models.json");
+  if (env.HOME) return join(env.HOME, ".config", "little-coder", "models.json");
+  return undefined;
+}
+
+function parseModelsFile(raw: string): ModelsFile {
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || !parsed.providers || typeof parsed.providers !== "object") {
+    throw new Error("expected top-level { providers: { ... } }");
+  }
+  return parsed as ModelsFile;
+}
+
+function readIfPresent(path: string): { kind: "ok"; data: ModelsFile } | { kind: "missing" } | { kind: "invalid"; error: string } {
+  if (!existsSync(path)) return { kind: "missing" };
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return { kind: "ok", data: parseModelsFile(raw) };
+  } catch (err) {
+    return { kind: "invalid", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export function applyEnvOverrides(providers: Record<string, ProviderEntry>, env: NodeJS.ProcessEnv = process.env): Record<string, ProviderEntry> {
+  const out: Record<string, ProviderEntry> = {};
+  for (const [name, entry] of Object.entries(providers)) {
+    const envVar = LEGACY_BASE_URL_ENV[name];
+    if (envVar && env[envVar]) {
+      out[name] = { ...entry, baseUrl: env[envVar]! };
+    } else {
+      out[name] = entry;
+    }
+  }
+  return out;
+}
+
+/**
+ * Merge: user file's providers fully replace package providers with the same
+ * key. Providers only in the user file are added. Providers only in the
+ * package default are kept. (We deliberately avoid deep per-model merging —
+ * the user redeclares the whole provider entry if they want to change it,
+ * which is far less surprising than "your override silently inherited fields
+ * from a future package release.")
+ */
+export function mergeProviders(
+  pkgDefault: Record<string, ProviderEntry>,
+  userOverride: Record<string, ProviderEntry> | undefined,
+): Record<string, ProviderEntry> {
+  if (!userOverride) return { ...pkgDefault };
+  return { ...pkgDefault, ...userOverride };
+}
+
+/**
+ * Load the package default models.json + (optionally) the user override file,
+ * apply env-var baseUrl overrides for the legacy providers, and return the
+ * merged provider map plus diagnostics for each source.
+ */
+export function loadProviders(pkgRoot: string, env: NodeJS.ProcessEnv = process.env): LoadResult {
+  const sources: LoadResult["sources"] = [];
+  const defaultPath = join(pkgRoot, "models.json");
+  const defaultRead = readIfPresent(defaultPath);
+  let pkgDefault: Record<string, ProviderEntry> = {};
+  if (defaultRead.kind === "ok") {
+    pkgDefault = defaultRead.data.providers;
+    sources.push({ path: defaultPath, status: "ok" });
+  } else if (defaultRead.kind === "missing") {
+    sources.push({ path: defaultPath, status: "missing" });
+  } else {
+    sources.push({ path: defaultPath, status: "invalid", error: defaultRead.error });
+  }
+
+  const overridePath = resolveOverridePath(env);
+  let userOverride: Record<string, ProviderEntry> | undefined;
+  if (overridePath) {
+    const userRead = readIfPresent(overridePath);
+    if (userRead.kind === "ok") {
+      userOverride = userRead.data.providers;
+      sources.push({ path: overridePath, status: "ok" });
+    } else if (userRead.kind === "missing") {
+      sources.push({ path: overridePath, status: "missing" });
+    } else {
+      sources.push({ path: overridePath, status: "invalid", error: userRead.error });
+    }
+  }
+
+  const merged = mergeProviders(pkgDefault, userOverride);
+  const withEnv = applyEnvOverrides(merged, env);
+  return { providers: withEnv, sources };
+}

package/.pi/extensions/llama-cpp-provider/index.ts

@@ -1,58 +1,44 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadProviders } from "./config.ts";
 
-const LLAMACPP_BASE_URL = process.env.LLAMACPP_BASE_URL || "http://127.0.0.1:8888/v1";
-const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || "http://127.0.0.1:11434/v1";
+// Data-driven provider registration. Reads:
+//   1. <pkgRoot>/models.json                       (shipped default)
+//   2. $LITTLE_CODER_MODELS_FILE (if set), else
+//      $XDG_CONFIG_HOME/little-coder/models.json, else
+//      $HOME/.config/little-coder/models.json     (user override; per-provider replace)
+//   3. LLAMACPP_BASE_URL / OLLAMA_BASE_URL env    (per-provider baseUrl override)
+//
+// Issue #13: previously the model list was hardcoded here and models.json was
+// only documentation, which made any user edit a no-op until they forked.
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..", "..", "..");
 
 export default function (pi: ExtensionAPI) {
-  pi.registerProvider("llamacpp", {
-    baseUrl: LLAMACPP_BASE_URL,
-    apiKey: "LLAMACPP_API_KEY",
-    api: "openai-completions",
-    models: [
-      {
-        id: "qwen3.6-27b",
-        name: "Qwen3.6-27B (dense, local llama.cpp)",
-        reasoning: true,
-        input: ["text"],
-        contextWindow: 32768,
-        maxTokens: 4096,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      },
-      {
-        id: "qwen3.6-35b-a3b",
-        name: "Qwen3.6-35B-A3B (MoE, local llama.cpp)",
-        reasoning: true,
-        input: ["text"],
-        contextWindow: 32768,
-        maxTokens: 4096,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      },
-      {
-        id: "qwen3.5-9b",
-        name: "Qwen3.5-9B (local llama.cpp)",
-        reasoning: true,
-        input: ["text"],
-        contextWindow: 32768,
-        maxTokens: 4096,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      },
-    ],
-  });
+  const result = loadProviders(pkgRoot);
+
+  for (const src of result.sources) {
+    if (src.status === "invalid") {
+      console.error(`[llama-cpp-provider] ignoring ${src.path}: ${src.error}`);
+    }
+  }
+
+  const providerCount = Object.keys(result.providers).length;
+  if (providerCount === 0) {
+    console.error(
+      `[llama-cpp-provider] no providers loaded — checked: ${result.sources.map((s) => `${s.path} [${s.status}]`).join(", ")}`,
+    );
+    return;
+  }
 
-  pi.registerProvider("ollama", {
-    baseUrl: OLLAMA_BASE_URL,
-    apiKey: "OLLAMA_API_KEY",
-    api: "openai-completions",
-    models: [
-      {
-        id: "qwen3.5",
-        name: "Qwen3.5 (ollama)",
-        reasoning: true,
-        input: ["text"],
-        contextWindow: 32768,
-        maxTokens: 4096,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      },
-    ],
-  });
+  for (const [name, entry] of Object.entries(result.providers)) {
+    pi.registerProvider(name, {
+      baseUrl: entry.baseUrl,
+      apiKey: entry.apiKey,
+      api: entry.api,
+      models: entry.models,
+    });
+  }
 }

package/.pi/extensions/permission-gate/index.ts

@@ -5,8 +5,13 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 // "accept-all" mode all commands pass (benchmark runs set this explicitly).
 // Write/Edit confirmations are deferred to the TUI's own prompt; we simply
 // add an extra guardrail on bash here to match little-coder's behavior.
+//
+// Per-deployment customization (issue #15):
+//   LITTLE_CODER_PERMISSION_MODE=auto|accept-all|manual
+//   LITTLE_CODER_BASH_ALLOW="cmd1,cmd2 sub,..."  extra allow-prefixes,
+//                                                merged with the built-in list.
 
-const SAFE_PREFIXES: readonly string[] = [
+const BUILTIN_SAFE_PREFIXES: readonly string[] = [
   "ls", "cat", "head", "tail", "wc", "pwd", "echo", "printf", "date",
   "which", "type", "env", "printenv", "uname", "whoami", "id",
   "git log", "git status", "git diff", "git show", "git branch",
@@ -18,9 +23,25 @@ const SAFE_PREFIXES: readonly string[] = [
   "curl -I", "curl --head",
 ];
 
-export function isSafeBash(command: string): boolean {
+// Trailing whitespace is meaningful — it acts as a word boundary in startsWith
+// matching ("find " refuses "findbug"). We only strip leading whitespace so
+// callers retain control over that boundary.
+export function parseExtraPrefixes(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((s) => s.trimStart())
+    .map((s) => (s.length > 0 && s !== " ".repeat(s.length) ? s : ""))
+    .filter((s) => s.length > 0);
+}
+
+export function getSafePrefixes(): string[] {
+  return [...BUILTIN_SAFE_PREFIXES, ...parseExtraPrefixes(process.env.LITTLE_CODER_BASH_ALLOW)];
+}
+
+export function isSafeBash(command: string, prefixes: readonly string[] = getSafePrefixes()): boolean {
   const c = command.trim();
-  return SAFE_PREFIXES.some((p) => c.startsWith(p));
+  return prefixes.some((p) => c.startsWith(p));
 }
 
 function getPermissionMode(): "auto" | "accept-all" | "manual" {

package/.pi/extensions/permission-gate/permission.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isSafeBash } from "./index.ts";
+import { isSafeBash, parseExtraPrefixes, getSafePrefixes } from "./index.ts";
 
 describe("isSafeBash", () => {
   it("allows whitelisted read-only commands", () => {
@@ -23,4 +23,45 @@ describe("isSafeBash", () => {
     expect(isSafeBash("git push origin main")).toBe(false);
     expect(isSafeBash("git commit -m x")).toBe(false);
   });
+  it("respects an explicit prefix list (LITTLE_CODER_BASH_ALLOW shape)", () => {
+    const extra = ["make ", "docker compose ps"];
+    expect(isSafeBash("make test", extra)).toBe(true);
+    expect(isSafeBash("docker compose ps", extra)).toBe(true);
+    expect(isSafeBash("docker compose down", extra)).toBe(false);
+  });
+});
+
+describe("parseExtraPrefixes", () => {
+  it("returns empty for undefined / empty / whitespace", () => {
+    expect(parseExtraPrefixes(undefined)).toEqual([]);
+    expect(parseExtraPrefixes("")).toEqual([]);
+    expect(parseExtraPrefixes("   ")).toEqual([]);
+  });
+  it("splits on comma and trims leading whitespace, preserving trailing space as word boundary", () => {
+    expect(parseExtraPrefixes("make , docker compose ps,  bun run")).toEqual([
+      "make ",
+      "docker compose ps",
+      "bun run",
+    ]);
+  });
+  it("drops empty / whitespace-only segments", () => {
+    expect(parseExtraPrefixes("a,,b,")).toEqual(["a", "b"]);
+    expect(parseExtraPrefixes("a,   ,b")).toEqual(["a", "b"]);
+  });
+});
+
+describe("getSafePrefixes", () => {
+  it("merges builtins with LITTLE_CODER_BASH_ALLOW from the env", () => {
+    const prev = process.env.LITTLE_CODER_BASH_ALLOW;
+    process.env.LITTLE_CODER_BASH_ALLOW = "make ,docker compose ps";
+    try {
+      const all = getSafePrefixes();
+      expect(all).toContain("ls"); // builtin still present
+      expect(all).toContain("make ");
+      expect(all).toContain("docker compose ps");
+    } finally {
+      if (prev === undefined) delete process.env.LITTLE_CODER_BASH_ALLOW;
+      else process.env.LITTLE_CODER_BASH_ALLOW = prev;
+    }
+  });
 });

package/.pi/extensions/quality-monitor/index.ts

@@ -2,9 +2,9 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { assessResponse, buildCorrectionMessage, type ToolCall } from "./quality.ts";
 
 // Port of local/quality.py. Hooks turn_end, inspects the assistant message
-// + previous turn's tool calls, and — if we detect a failure mode — queues
-// a correction user message via session.followUp() so the model gets a
-// chance to recover on its next turn.
+// + previous turn's tool calls, and — if we detect a failure mode — sends
+// a correction user message with deliverAs:"steer" so the model gets it
+// immediately on its next turn rather than waiting for the next user input.
 
 // Session-scoped state. Pi reuses extensions across turns within a session;
 // a fresh extension instance is loaded per session via the session lifecycle.
@@ -62,9 +62,12 @@ export default function (pi: ExtensionAPI) {
 
     const correction = buildCorrectionMessage(verdict.reason);
     ctx.ui.notify(
-      `quality-monitor: ${verdict.reason} → queued correction`,
+      `quality-monitor: ${verdict.reason} → injecting correction`,
       "warning",
     );
-    pi.sendUserMessage(correction, { deliverAs: "followUp" });
+    // "steer" delivers the correction promptly to the in-flight loop. The
+    // prior "followUp" mode parked the message until the *next* user input,
+    // by which point it was no longer relevant (issue #16).
+    pi.sendUserMessage(correction, { deliverAs: "steer" });
   });
 }

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

@@ -56,7 +56,6 @@ const INTENT_MAP: Record<string, string[]> = {
   browse: ["BrowserNavigate", "BrowserExtract"],
   page: ["BrowserExtract"],
   click: ["BrowserClick"],
-  agent: ["Agent"], delegate: ["Agent"], spawn: ["Agent"],
 };
 
 function skillsDir(): string {

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

@@ -21,7 +21,6 @@ const INTENT_MAP: Record<string, string[]> = {
   grep: ["Grep"], glob: ["Glob"],
   fetch: ["WebFetch"], download: ["WebFetch"], url: ["WebFetch"],
   web: ["WebSearch"],
-  agent: ["Agent"], delegate: ["Agent"], spawn: ["Agent"],
 };
 
 function predictTools(userText: string): string[] {
@@ -61,10 +60,10 @@ describe("skills directory loads from repo", () => {
   const here = dirname(fileURLToPath(import.meta.url));
   const toolsDir = join(here, "..", "..", "..", "skills", "tools");
 
-  it("exists and has 14 markdown files", () => {
+  it("exists and has 13 markdown files", () => {
     expect(existsSync(toolsDir)).toBe(true);
     const files = readdirSync(toolsDir).filter((f) => f.endsWith(".md"));
-    expect(files.length).toBe(14);
+    expect(files.length).toBe(13);
   });
 
   it("every tool skill has target_tool in frontmatter", () => {

package/.pi/settings.json

@@ -70,6 +70,14 @@
         "skill_token_budget": 300,
         "knowledge_token_budget": 200,
         "temperature": 0.3
+      },
+      "lmstudio/local-model": {
+        "context_limit": 32768,
+        "max_tokens": 4096,
+        "thinking_budget": 2048,
+        "skill_token_budget": 300,
+        "knowledge_token_budget": 200,
+        "temperature": 0.3
       }
     }
   }

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to little-coder are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and little-coder's public interface (CLI, providers, tools, skills) follows semver starting at `v0.0.1` post-rename.
 
+## [v1.2.0] — 2026-05-10
+
+Issue-cleanup release that also ships built-in LM Studio support. Closes [#17](https://github.com/itayinbarr/little-coder/issues/17) (Windows), [#19](https://github.com/itayinbarr/little-coder/issues/19) (phantom Agent tool), [#21](https://github.com/itayinbarr/little-coder/issues/21) (skill param mismatch).
+
+### Added
+- **Built-in `lmstudio/local-model` provider.** [LM Studio](https://lmstudio.ai/) exposes an OpenAI-compatible server on `http://127.0.0.1:1234/v1` by default, and previously the only way to use it was to overload `LLAMACPP_BASE_URL`. Now you can run `little-coder --model lmstudio/local-model` and it routes to whatever model LM Studio currently has loaded — no extra config for the single-model case. New env knobs `LMSTUDIO_BASE_URL` (overrides baseUrl, parity with `LLAMACPP_BASE_URL`/`OLLAMA_BASE_URL`) and `LMSTUDIO_API_KEY` (any value; LM Studio ignores it locally but pi requires the env var to exist). README has a new **Option C — LM Studio** under *Local model setup*. `.pi/settings.json` ships a `lmstudio/local-model` profile so the same context/thinking-budget tuning as the llamacpp profiles applies.
+
+### Fixed
+- **Windows launch ([#17](https://github.com/itayinbarr/little-coder/issues/17), thanks @Grogger for [PR #18](https://github.com/itayinbarr/little-coder/pull/18)).** On Windows, `node_modules/.bin/pi` is a `.cmd` shim that Node 20's `spawn()` can't execute directly without `shell: true`, and `shell: true` reintroduces the CVE-2024-27980 / DEP0190 shell-injection class. The launcher now resolves `pi.cmd` on Windows and invokes `cmd.exe /c pi.cmd ...` with args as an array — works on Windows 11, no Linux/macOS regression.
+- **Edit skill documentation ([#21](https://github.com/itayinbarr/little-coder/issues/21)).** `skills/tools/edit.md` advertised `old_string` / `new_string`, but pi's Edit tool only accepts `oldText` / `newText` (single-edit form) or `edits: [{oldText, newText}]` (array form). Rewritten to show the canonical array form *and* the single-edit back-compat form. While in there, also corrected `skills/tools/read.md` and `skills/tools/write.md` (`file_path` → `path` — pi aliases both, but the canonical name is now in the docs) and `skills/tools/grep.md` (`include` → `glob`, `max_results` → `limit`; pi does not alias these, so the old skill could genuinely produce tool-call errors on the grep path the same way Edit did).
+
+### Changed
+- **Removed phantom `Agent` skill ([#19](https://github.com/itayinbarr/little-coder/issues/19)).** `skills/tools/agent.md` documented an `Agent` tool that little-coder never actually registered — pi ships `examples/extensions/subagent/` as a reference impl, but it was not wired up by default. Deleted the skill card and the `agent` / `delegate` / `spawn` keys from `.pi/extensions/skill-inject/index.ts`'s `INTENT_MAP` so the model is no longer told it has a delegation tool. The `skills/protocols/task_decomposition.md` cheatsheet is untouched — decomposition guidance does not depend on a delegation tool.
+
+### Notes for upgraders
+- No CLI flag, settings, or skill-pack breaks. `--model lmstudio/local-model` works out of the box if LM Studio is serving on its default port 1234 with a model loaded.
+- If you'd been overloading `LLAMACPP_BASE_URL=http://127.0.0.1:1234/v1` to point at LM Studio, that keeps working — but the cleaner path is now `--model lmstudio/local-model` with no env tweaking.
+
+---
+
+## [v1.1.0] — 2026-05-03
+
+Issue-cleanup release. Three small features and one bug fix, driven by GitHub issues #12 / #13 / #15 / #16.
+
+### Added
+- **`models.json` is now the canonical provider registration.** ([#13](https://github.com/itayinbarr/little-coder/issues/13))
+  Previously `.pi/extensions/llama-cpp-provider/index.ts` hardcoded the model list and `models.json` was decorative; editing it had no effect. Now the extension loads providers and models from `models.json` at startup and registers them dynamically. **User override file** (first match wins): `$LITTLE_CODER_MODELS_FILE` → `$XDG_CONFIG_HOME/little-coder/models.json` → `~/.config/little-coder/models.json`. Per-provider replace semantics — your override fully replaces a same-keyed provider in the shipped file. Diagnostics for missing/invalid sources surface via `console.error`. The legacy `LLAMACPP_BASE_URL` / `OLLAMA_BASE_URL` env vars still beat both files for those two providers. New unit-test module `.pi/extensions/llama-cpp-provider/config.test.ts` covers merge, env override, and resolution-order semantics. README has a new **Configuring models** section.
+- **`LITTLE_CODER_BASH_ALLOW` env var** ([#15](https://github.com/itayinbarr/little-coder/issues/15)) — comma-separated extra prefixes merged with the built-in `permission-gate` whitelist, so deployments can allow extra bash commands without forking. Trailing whitespace is meaningful (acts as a word boundary, matching the built-in convention). README has a new **Permissions** section that also documents the existing `LITTLE_CODER_PERMISSION_MODE=accept-all` escape hatch (which was undocumented before).
+- **`bun add -g little-coder` install path documented** ([#12](https://github.com/itayinbarr/little-coder/issues/12)). Node ≥ 20.6 is still required at runtime because of the launcher shebang; users who want a fully node-less setup get a one-line shebang-swap recipe.
+- `qwen3.6-27b` re-added to `models.json` so the data-driven extension preserves the four-model lineup (`llamacpp/qwen3.6-27b`, `llamacpp/qwen3.6-35b-a3b`, `llamacpp/qwen3.5-9b`, `ollama/qwen3.5`) that `.pi/settings.json` profiles already reference.
+
+### Fixed
+- **Empty-response correction is no longer parked until the next user input.** ([#16](https://github.com/itayinbarr/little-coder/issues/16))
+  `quality-monitor` was sending its correction message via `pi.sendUserMessage(..., { deliverAs: "followUp" })`, which queued the message until the user typed something — by which point "your previous response was empty" had nothing to steer. Switched to `deliverAs: "steer"` so the correction injects into the in-flight loop. Same fix applies to the other quality-monitor reasons (`unknown_tool`, `repeated_tool_call`, `malformed_args`, `empty_tool_name`); they all benefit from prompt delivery for the same reason. The `thinking-budget` extension's deliberate use of `followUp` (post-abort retry; see commit `50becc3`) is unchanged.
+
+### Changed
+- README architecture diagram: `llama-cpp-provider/` is now described as "data-driven provider registration from models.json (+ user override file)"; `models.json` is now described as "canonical provider registration", reflecting the actual load path.
+
+### Notes for upgraders
+- No CLI flag, settings.json, or skill-pack breaks. Existing `.pi/settings.json` `model_profiles` keys (`llamacpp/qwen3.6-27b`, `llamacpp/qwen3.6-35b-a3b`, `llamacpp/qwen3.5-9b`, `ollama/qwen3.5`) all still match.
+- If you'd been editing the installed package's `models.json` manually, those edits will keep working — but they're erased on the next `npm install -g little-coder@latest`. Move them to `~/.config/little-coder/models.json` to make them survive upgrades.
+
+---
+
 ## [v1.0.3] — 2026-04-28
 
 ### Changed

package/README.md

@@ -26,8 +26,16 @@ Or with npm directly:
 npm install -g little-coder
 ```
 
+Or with [bun](https://bun.sh):
+
+```bash
+bun add -g little-coder
+```
+
 That's the whole install. No clone, no `npm install` in a workspace, no PATH fiddling. `little-coder` is now on your PATH and works from any directory.
 
+> **Note for `bun add -g` users.** The launcher (`bin/little-coder.mjs`) is a Node.js script with `#!/usr/bin/env node` at the top, so Node ≥ 20.6 still has to be on your PATH for the binary to start — bun is fine for installing/updating the package, but the runtime is Node. If you want a fully node-less setup, replace the shebang in `$(bun pm bin -g)/little-coder` with `#!/usr/bin/env bun`.
+
 ## Run
 
 ```bash
@@ -43,19 +51,21 @@ Cloud models work the same way:
 little-coder --model anthropic/claude-haiku-4-5
 little-coder --model openai/gpt-4o-mini "What does this codebase do?"
 little-coder --model ollama/qwen3.5             # local Ollama
+little-coder --model lmstudio/local-model       # local LM Studio (whatever model you have loaded)
 little-coder --list-models                      # see everything pi knows about
 ```
 
 The agent uses the directory you launched it from as its working directory — `Read` / `Write` / `Edit` / `Bash` operate on your project, not on little-coder's install path.
 
-For local providers (llama.cpp, Ollama) pi expects *some* value in the API-key env even though local servers ignore it:
+For local providers (llama.cpp, Ollama, LM Studio) pi expects *some* value in the API-key env even though local servers ignore it:
 
 ```bash
 export LLAMACPP_API_KEY=noop
 export OLLAMA_API_KEY=noop
+export LMSTUDIO_API_KEY=noop
 ```
 
-`LLAMACPP_BASE_URL` and `OLLAMA_BASE_URL` override the defaults (`http://127.0.0.1:8888/v1`, `http://127.0.0.1:11434/v1`).
+`LLAMACPP_BASE_URL`, `OLLAMA_BASE_URL`, and `LMSTUDIO_BASE_URL` override the defaults (`http://127.0.0.1:8888/v1`, `http://127.0.0.1:11434/v1`, `http://127.0.0.1:1234/v1`).
 
 For cloud providers, set the standard env (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) and pi will discover it.
 
@@ -89,10 +99,91 @@ ollama pull qwen3.5        # 9.7B — the paper's model
 # or: ollama pull qwen3.6-35b-a3b
 ```
 
+**Option C — LM Studio** (GUI; OpenAI-compatible server on port 1234):
+
+1. Install [LM Studio](https://lmstudio.ai/) and download a model (e.g. Qwen3.6 35B A3B GGUF).
+2. Open the **Developer** / **Local Server** tab, load the model, and click **Start Server** (default `http://127.0.0.1:1234`).
+3. Run little-coder:
+   ```bash
+   export LMSTUDIO_API_KEY=noop
+   little-coder --model lmstudio/local-model
+   ```
+   The shipped `lmstudio/local-model` id routes to whatever model LM Studio currently has loaded — no extra config needed for the single-model case. If you serve on a non-default port, set `LMSTUDIO_BASE_URL=http://127.0.0.1:<port>/v1`. To target a specific model when you have several loaded, add an entry to `~/.config/little-coder/models.json` (see **Configuring models** below).
+
 All small-model-specific extensions auto-disable for large/cloud models so they don't interfere.
 
 ---
 
+## Configuring models
+
+The shipped model list lives in **`models.json`** at the package root. The `llama-cpp-provider` extension reads it at startup and registers each provider via pi's `registerProvider()`. Editing this file in your global install **does** take effect — but it's overwritten on `npm install -g little-coder@latest`, so for anything you want to keep, use a user override file instead.
+
+User override resolution (first match wins):
+
+1. `$LITTLE_CODER_MODELS_FILE` — explicit path, useful for ad-hoc tests.
+2. `$XDG_CONFIG_HOME/little-coder/models.json`
+3. `~/.config/little-coder/models.json`
+
+Merge semantics: each top-level provider key in your override file **fully replaces** the same key in the shipped `models.json`. Providers only in your file are added; providers only in the shipped file are kept. (We don't deep-merge per-model fields — you redeclare the whole provider entry, which avoids "your override silently inherited new fields from a future package release" surprises.)
+
+Example — switch the llama.cpp port and bump `qwen3.6-35b-a3b` to a 150K context, leave ollama untouched:
+
+```json
+{
+  "providers": {
+    "llamacpp": {
+      "api": "openai-completions",
+      "baseUrl": "http://127.0.0.1:1234/v1",
+      "apiKey": "LLAMACPP_API_KEY",
+      "models": [
+        {
+          "id": "qwen3.6-35b-a3b",
+          "name": "Qwen3.6-35B-A3B (local llama.cpp, 150K)",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 150000,
+          "maxTokens": 4096,
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
+        }
+      ]
+    }
+  }
+}
+```
+
+Then verify with `little-coder --list-models` — you should see your overridden entry.
+
+`LLAMACPP_BASE_URL`, `OLLAMA_BASE_URL`, and `LMSTUDIO_BASE_URL` env vars still beat both files for those three providers.
+
+`.pi/settings.json` is a separate concern: it controls per-model **profiles** (context_limit, thinking_budget, temperature, benchmark_overrides) referenced by the `<provider>/<id>` key. Profiles don't register or describe models — they only tune how little-coder runs against models that are already registered.
+
+---
+
+## Permissions
+
+little-coder gates `Bash` tool calls against a built-in safe-prefix whitelist (`ls`, `cat`, `git log/status/diff`, `find`, `grep`, etc.) before pi's own confirmation flow ever sees them.
+
+Two env vars control the gate:
+
+| Env var | Values | Effect |
+|---|---|---|
+| `LITTLE_CODER_PERMISSION_MODE` | `auto` *(default)* / `accept-all` / `manual` | `auto`: block any bash command not on the whitelist. `accept-all`: skip the gate entirely, every bash call passes (the benchmark runner sets this). `manual`: same as `auto` but with a different rejection message. |
+| `LITTLE_CODER_BASH_ALLOW` | comma-separated prefixes | Extra allow-prefixes merged with the built-in list. **Trailing whitespace is meaningful**: `"make "` allows `make test` but not `makefoo`; `"make"` allows both. |
+
+Examples:
+
+```bash
+# Add 'make' (with word-boundary) and 'docker compose ps' on top of the defaults
+export LITTLE_CODER_BASH_ALLOW="make ,docker compose ps"
+
+# Skip the gate entirely (use this only inside controlled environments)
+export LITTLE_CODER_PERMISSION_MODE=accept-all
+```
+
+Write/Edit confirmations are pi's responsibility; little-coder doesn't intercept those.
+
+---
+
 ## Paper / benchmark results
 
 | Release | Model | Benchmark | Result |
@@ -163,7 +254,7 @@ little-coder/
 ├── .pi/
 │   ├── settings.json               # per-model profiles + benchmark_overrides (terminal_bench, gaia)
 │   └── extensions/                 # 20 TypeScript extensions, auto-discovered by pi
-│       ├── llama-cpp-provider/     # registers llamacpp/* and ollama/* as OpenAI-compat providers
+│       ├── llama-cpp-provider/     # data-driven provider registration from models.json — ships llamacpp, ollama, lmstudio (+ user override file)
 │       ├── write-guard/            # Write refuses on existing files — the whitepaper invariant
 │       ├── extra-tools/            # glob, webfetch, websearch (pi ships grep/find)
 │       ├── skill-inject/           # per-turn tool-skill selection (error > recency > intent)
@@ -193,7 +284,7 @@ little-coder/
 │   ├── tb_status.sh / harbor_status.sh
 │   └── test_rpc_client.py
 ├── AGENTS.md                       # project system prompt (pi discovers it automatically)
-├── models.json                     # documented provider registration (extension is canonical)
+├── models.json                     # canonical provider registration (loaded by llama-cpp-provider; user override at $XDG_CONFIG_HOME/little-coder/models.json)
 └── docs/
     ├── benchmark-*.md              # per-benchmark narratives
     └── architecture.md             # v0.0.5-era Python architecture (historical)

package/bin/little-coder.mjs

@@ -29,7 +29,9 @@ const here = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(here, "..");
 
 // ---- 3. Resolve the bundled pi binary ----
-const piBin = join(pkgRoot, "node_modules", ".bin", "pi");
+const isWindows = process.platform === "win32";
+const piBinBase = join(pkgRoot, "node_modules", ".bin", "pi");
+const piBin = isWindows && existsSync(`${piBinBase}.cmd`) ? `${piBinBase}.cmd` : piBinBase;
 if (!existsSync(piBin)) {
   console.error(
     `little-coder: cannot find pi at ${piBin}.\n` +
@@ -86,7 +88,11 @@ const piArgs = [
 ];
 
 // ---- 7. Spawn pi in the user's cwd ----
-const child = spawn(piBin, piArgs, {
+const [spawnCmd, spawnArgs] = isWindows
+  ? ["cmd.exe", ["/c", piBin, ...piArgs]]
+  : [piBin, piArgs];
+
+const child = spawn(spawnCmd, spawnArgs, {
   stdio: "inherit",
   cwd: process.cwd(),
   env: process.env,

package/models.json

@@ -5,9 +5,18 @@
       "baseUrl": "http://127.0.0.1:8888/v1",
       "apiKey": "LLAMACPP_API_KEY",
       "models": [
+        {
+          "id": "qwen3.6-27b",
+          "name": "Qwen3.6-27B (dense, local llama.cpp)",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 32768,
+          "maxTokens": 4096,
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
+        },
         {
           "id": "qwen3.6-35b-a3b",
-          "name": "Qwen3.6-35B-A3B (local llama.cpp)",
+          "name": "Qwen3.6-35B-A3B (MoE, local llama.cpp)",
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 32768,
@@ -40,6 +49,22 @@
           "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
         }
       ]
+    },
+    "lmstudio": {
+      "api": "openai-completions",
+      "baseUrl": "http://127.0.0.1:1234/v1",
+      "apiKey": "LMSTUDIO_API_KEY",
+      "models": [
+        {
+          "id": "local-model",
+          "name": "LM Studio (currently-loaded local model)",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 32768,
+          "maxTokens": 4096,
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
+        }
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "little-coder",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "A pi-based coding agent optimized for small local language models. Reproduces the whitepaper's scaffold-model-fit adaptations as pi extensions.",
   "homepage": "https://github.com/itayinbarr/little-coder",
   "repository": {

package/skills/tools/edit.md

@@ -9,22 +9,28 @@ user-invocable: false
 ## Edit Tool
 Replace exact text in a file. This is the **default tool for changing any existing file** — prefer it over Write for anything except creating a new file from scratch.
 
-REQUIRED: file_path (absolute), old_string (exact text to find), new_string (replacement)
-OPTIONAL: replace_all (boolean, replace all occurrences)
+REQUIRED: path (absolute), edits (array of {oldText, newText})
+OPTIONAL: none
 
 RULES:
-- old_string must match EXACTLY (whitespace, indentation, line endings all matter)
-- old_string must appear exactly ONCE unless replace_all=true
-- Include enough surrounding context (2-3 lines) to make old_string unique
-- To delete text: set new_string to ""
+- Each `oldText` must match EXACTLY (whitespace, indentation, line endings all matter)
+- Each `oldText` must be unique in the file — include 2-3 lines of surrounding context if needed
+- `edits` is matched against the **original** file, not after earlier edits apply — do not overlap or nest
+- To delete text: set `newText` to ""
 - Read the file first if you do not already have its current content
+- Batch multiple disjoint changes in one call by passing multiple `edits[]` entries
 
-EXAMPLE:
+EXAMPLE (single change):
 ```tool
-{"name": "Edit", "input": {"file_path": "/absolute/path/file.py", "old_string": "def hello():\n    return 1", "new_string": "def hello():\n    return 2"}}
+{"name": "Edit", "input": {"path": "/absolute/path/file.py", "edits": [{"oldText": "def hello():\n    return 1", "newText": "def hello():\n    return 2"}]}}
+```
+
+EXAMPLE (two changes in one call):
+```tool
+{"name": "Edit", "input": {"path": "/absolute/path/file.py", "edits": [{"oldText": "MAX = 10", "newText": "MAX = 20"}, {"oldText": "TIMEOUT = 5", "newText": "TIMEOUT = 30"}]}}
 ```
 
 RECOVERY WHEN Edit FAILS:
 - "String not found" → Read the file to get the exact current content (whitespace often differs), then retry Edit with the exact string
-- "Found multiple times" → include more surrounding context so old_string is unique, then retry Edit
-- Do NOT fall back to Write just because Edit failed once — re-read, fix old_string, retry. Write is almost always the wrong recovery here for an existing file.
+- "Found multiple times" → include more surrounding context so `oldText` is unique, then retry Edit
+- Do NOT fall back to Write just because Edit failed once — re-read, fix `oldText`, retry. Write is almost always the wrong recovery here for an existing file.

package/skills/tools/grep.md

@@ -10,17 +10,18 @@ user-invocable: false
 Search file contents with regex. Uses ripgrep.
 
 REQUIRED: pattern (regex pattern)
-OPTIONAL: path (directory/file), include (file glob filter like "*.py"), max_results (limit)
+OPTIONAL: path (directory/file), glob (file glob filter like "*.py"), ignoreCase (bool), literal (bool — treat pattern as literal text), context (lines of context before/after), limit (max matches, default 100)
 
 RULES:
-- Supports full regex syntax
-- Use include to filter by file type (e.g. "*.py", "*.js")
+- Supports full regex syntax (unless `literal: true`)
+- Use `glob` to filter by file type (e.g. "*.py", "*.js")
+- Use `limit` to cap results; default 100
 - Returns matching lines with file path and line number
 - Good for finding function definitions, imports, references
 
 EXAMPLE:
 ```tool
-{"name": "Grep", "input": {"pattern": "def main", "include": "*.py"}}
+{"name": "Grep", "input": {"pattern": "def main", "glob": "*.py"}}
 ```
 
 EXAMPLE with path:

package/skills/tools/read.md

@@ -9,7 +9,7 @@ user-invocable: false
 ## Read Tool
 Read a file's contents with line numbers.
 
-REQUIRED: file_path (absolute path)
+REQUIRED: path (absolute path)
 OPTIONAL: limit (max lines), offset (start line, 0-indexed)
 
 RULES:
@@ -19,10 +19,10 @@ RULES:
 
 EXAMPLE:
 ```tool
-{"name": "Read", "input": {"file_path": "/absolute/path/to/file.py"}}
+{"name": "Read", "input": {"path": "/absolute/path/to/file.py"}}
 ```
 
 EXAMPLE with range:
 ```tool
-{"name": "Read", "input": {"file_path": "/absolute/path/to/file.py", "limit": 50, "offset": 100}}
+{"name": "Read", "input": {"path": "/absolute/path/to/file.py", "limit": 50, "offset": 100}}
 ```

package/skills/tools/write.md

@@ -9,7 +9,7 @@ user-invocable: false
 ## Write Tool
 Create a **new** file with the given content. Creates parent directories automatically.
 
-REQUIRED: file_path (absolute), content (full file content)
+REQUIRED: path (absolute), content (full file content)
 
 **Write is for creating new files only.** If the file already exists, Write will be **refused** by the tool and return an error telling you to use Edit instead. Do not retry Write on the same path — it will be refused again.
 
@@ -17,13 +17,13 @@ WHEN TO USE Write:
 - The file does not exist yet and you are creating it from scratch
 
 WHEN TO USE Edit INSTEAD:
-- ANY change to an existing file — bug fixes, refactors, format tweaks, adding a function, renaming a variable, everything. Edit takes old_string + new_string and patches in place.
+- ANY change to an existing file — bug fixes, refactors, format tweaks, adding a function, renaming a variable, everything. Edit takes `path` + `edits: [{oldText, newText}]` and patches in place.
 - Iterating after a failed test — never retype the whole file
 
-If you need to completely replace an existing file's content, Edit can still do that: pass the entire current content as old_string and the full new content as new_string. Read the file first if you don't already have its current content.
+If you need to completely replace an existing file's content, Edit can still do that: pass the entire current content as `oldText` and the full new content as `newText`. Read the file first if you don't already have its current content.
 
 EXAMPLE:
 ```tool
-{"name": "Write", "input": {"file_path": "/tmp/example/new_module.py", "content": "def hello():\n    return 'hi'\n"}}
+{"name": "Write", "input": {"path": "/tmp/example/new_module.py", "content": "def hello():\n    return 'hi'\n"}}
 ```
 NOTE: Always use the EXACT file path given in the task, never a placeholder.

package/skills/tools/agent.md

@@ -1,24 +0,0 @@
----
-name: agent-guidance
-type: tool-guidance
-target_tool: Agent
-priority: 6
-token_cost: 120
-user-invocable: false
----
-## Agent Tool
-Spawn a sub-agent to handle a task autonomously.
-
-REQUIRED: prompt (task description for the sub-agent)
-OPTIONAL: subagent_type (coder/reviewer/researcher/tester/general-purpose), name (for messaging), isolation ("worktree" for git isolation)
-
-RULES:
-- Use for independent tasks that don't need your direct attention
-- Sub-agents get their own context and can use all tools
-- Use subagent_type to get specialized behavior
-- Use isolation="worktree" when the agent needs to modify files independently
-
-EXAMPLE:
-```tool
-{"name": "Agent", "input": {"prompt": "Find all Python files that import requests and list them", "subagent_type": "researcher"}}
-```