@agentprojectcontext/apx 1.34.0 → 1.36.0

package/src/core/agent/skills/inspector.js

@@ -0,0 +1,317 @@
+// Skill Inspector — middleware that mutates the chat each turn so the agent
+// only ever sees the skills it actually needs.
+//
+// Design goals (test feature, opt-in via config.skills.inspector.enabled):
+//   1. NO static slug dump. The "Available skills" hint block listing every
+//      slug in the catalog is suppressed when the inspector is on — the agent
+//      reaches skills via this middleware and the existing load_skill tool.
+//   2. Per-turn re-evaluation. The decision is recomputed from the current
+//      user prompt; a skill that matched last turn but not this one simply
+//      disappears from the next system prompt — natural decay.
+//   3. Two tiers based on confidence:
+//        - LOAD  (sim ≥ load_threshold): the body is inlined as contextNote.
+//          The agent has it right there — no extra tool call.
+//        - HINT  (sim ≥ hint_threshold): only the slug + one-line description
+//          is named, and the agent is told to call load_skill if it actually
+//          needs the syntax.
+//      Below hint_threshold → nothing.
+//   4. Local-first. Uses the same embeddings chain as cross-channel memory
+//      (ollama → gemini → openai → tf). With no provider, the offline TF
+//      fallback runs — works on any machine, zero API key, zero GPU.
+//   5. Never block the request. Any embedding failure → empty contextNote.
+//
+// Returns a structured trace so the daemon can emit `skill_inspector` events
+// to the stream (handy for the web debug panel and CLI inspect).
+
+import { embedOne, cosineSim } from "#core/memory/embeddings.js";
+import { listSkills, loadSkill } from "./loader.js";
+import { readIndex, backgroundRefreshIfStale } from "./index-store.js";
+
+// Defaults — exported so the CLI/web can render them.
+export const INSPECTOR_DEFAULTS = Object.freeze({
+  enabled: false,             // OPT-IN — this is a test feature.
+  load_threshold: 0.55,       // sim ≥ this → inline body
+  hint_threshold: 0.40,       // sim ≥ this → just hint
+  margin: 0.04,               // top must beat runner-up by this for confident pick
+  max_loaded: 1,              // how many bodies to inline at once
+  max_hints: 2,               // how many additional hints to add
+  prompt_floor: 8,            // skip super-short prompts ("ok", "hola")
+  body_char_cap: 6000,        // hard cap on inlined skill bodies (token guard)
+});
+
+function effectiveConfig(globalConfig) {
+  const raw = globalConfig?.skills?.inspector || {};
+  return { ...INSPECTOR_DEFAULTS, ...raw };
+}
+
+/** Quick public probe so the daemon/api can decide whether to suppress the
+ *  static hint block in the system prompt. */
+export function isInspectorEnabled(globalConfig) {
+  return effectiveConfig(globalConfig).enabled === true;
+}
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+function scoreAgainstIndex(promptVec, indexItems) {
+  const out = [];
+  for (const slug of Object.keys(indexItems)) {
+    const it = indexItems[slug];
+    if (!Array.isArray(it.desc_vector)) continue;
+    out.push({
+      slug,
+      source: it.source,
+      desc: it.desc || "",
+      file: it.file,
+      sim: cosineSim(promptVec, it.desc_vector),
+    });
+  }
+  out.sort((a, b) => b.sim - a.sim);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Context block rendering
+// ---------------------------------------------------------------------------
+
+function renderInjectedBlock({ loaded, hinted, embedder }) {
+  if (loaded.length === 0 && hinted.length === 0) return "";
+
+  const lines = [
+    "# Skill Inspector",
+    `Local RAG (${embedder}) matched the user's prompt against your skill catalog.`,
+    "The catalog itself is NOT in your system prompt — only what's below is.",
+    "If none of these is right, call `list_skills` to browse and `load_skill` to fetch one.",
+    "",
+  ];
+
+  if (loaded.length) {
+    lines.push("## Loaded for this turn");
+    for (const s of loaded) {
+      lines.push("");
+      lines.push(`### \`${s.slug}\`  (sim ${s.sim.toFixed(2)}, source: ${s.source})`);
+      lines.push(s.body);
+    }
+    lines.push("");
+  }
+
+  if (hinted.length) {
+    lines.push("## Possibly relevant — load on demand");
+    for (const s of hinted) {
+      lines.push(`- \`${s.slug}\` — sim ${s.sim.toFixed(2)}. ${s.desc}`);
+    }
+    lines.push("");
+    lines.push("Call `load_skill({slug:\"…\"})` for any of these BEFORE answering if you need its exact syntax.");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide what skill context (if any) to inject for this turn.
+ *
+ * @param {object} args
+ * @param {string} args.prompt          the user's current message
+ * @param {string=} args.projectPath    project root (project skills shadow global)
+ * @param {object=} args.globalConfig   passed through to embedOne()
+ * @param {object=} args.embedOpts      optional embedOne overrides
+ *
+ * @returns {{
+ *   contextNote: string,
+ *   trace: {
+ *     enabled: boolean,
+ *     reason?: string,
+ *     embedder?: string,
+ *     scored?: Array<{slug, sim}>,
+ *     loaded?: string[],
+ *     hinted?: string[],
+ *   }
+ * }}
+ */
+export async function inspectPromptForSkills({ prompt, projectPath, globalConfig, embedOpts } = {}) {
+  const cfg = effectiveConfig(globalConfig);
+  if (!cfg.enabled) {
+    return { contextNote: "", trace: { enabled: false, reason: "disabled" } };
+  }
+
+  const text = String(prompt || "").trim();
+  if (text.length < cfg.prompt_floor) {
+    return { contextNote: "", trace: { enabled: true, reason: "prompt_too_short" } };
+  }
+
+  // Self-heal: if a skill was added/edited/removed since the last index, kick a
+  // background rebuild. Non-blocking — this turn uses whatever is already on
+  // disk; the next turn picks up the fresh vectors. This is what lets a user
+  // drop a SKILL.md and have it "just work" without running `apx skills index`.
+  try {
+    backgroundRefreshIfStale({ projectPath, embedOpts: { ...(embedOpts || {}), globalConfig } });
+  } catch { /* best-effort */ }
+
+  // Pull the persistent index. If it's empty (no `apx skills index` ever ran),
+  // we don't fall back to recomputing every skill's vector here — that's the
+  // job of the index command and the daemon startup probe. Instead, we emit a
+  // trace reason so the operator sees "you forgot to index".
+  const idx = readIndex();
+  const items = idx.items || {};
+  const indexedCount = Object.keys(items).length;
+
+  // If the on-disk index has nothing yet, try a JIT pass over the live catalog
+  // using the in-process cache. Slower than a primed index but means a fresh
+  // install still works — the inspector is supposed to "just work" the moment
+  // it's flipped on.
+  if (indexedCount === 0) {
+    return await inspectFromLive({ text, projectPath, cfg, globalConfig, embedOpts });
+  }
+
+  const probe = await embedOne(text, { ...(embedOpts || {}), globalConfig });
+  if (!probe || !Array.isArray(probe.vector) || probe.vector.length === 0) {
+    return { contextNote: "", trace: { enabled: true, reason: "embed_failed" } };
+  }
+
+  // Embedder mismatch — old index was built with a different provider. Don't
+  // mix cosine spaces; the operator needs to re-run `apx skills index`.
+  if (idx.embedder && idx.embedder !== probe.embedder) {
+    return {
+      contextNote: "",
+      trace: {
+        enabled: true,
+        reason: "embedder_mismatch",
+        embedder: probe.embedder,
+        index_embedder: idx.embedder,
+      },
+    };
+  }
+
+  const scored = scoreAgainstIndex(probe.vector, items);
+  return await pickAndRender({ scored, projectPath, probe, cfg });
+}
+
+// ---------------------------------------------------------------------------
+// JIT fallback when the persistent index is empty
+// ---------------------------------------------------------------------------
+
+async function inspectFromLive({ text, projectPath, cfg, globalConfig, embedOpts }) {
+  const skills = listSkills({ projectPath });
+  if (!skills.length) {
+    return { contextNote: "", trace: { enabled: true, reason: "no_skills" } };
+  }
+
+  const probe = await embedOne(text, { ...(embedOpts || {}), globalConfig });
+  if (!probe || !Array.isArray(probe.vector) || probe.vector.length === 0) {
+    return { contextNote: "", trace: { enabled: true, reason: "embed_failed" } };
+  }
+
+  const scored = [];
+  for (const s of skills) {
+    const desc = (s.description || "").slice(0, 600);
+    if (!desc.trim()) continue;
+    const out = await embedOne(desc, { ...(embedOpts || {}), globalConfig });
+    if (!out || !Array.isArray(out.vector)) continue;
+    scored.push({
+      slug: s.slug,
+      source: s.source,
+      desc,
+      file: s.file,
+      sim: cosineSim(probe.vector, out.vector),
+    });
+  }
+  scored.sort((a, b) => b.sim - a.sim);
+  const result = await pickAndRender({ scored, projectPath, probe, cfg });
+  return {
+    contextNote: result.contextNote,
+    trace: { ...result.trace, jit: true },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Common pick + render
+// ---------------------------------------------------------------------------
+
+async function pickAndRender({ scored, projectPath, probe, cfg }) {
+  if (scored.length === 0) {
+    return { contextNote: "", trace: { enabled: true, reason: "no_candidates", embedder: probe.embedder } };
+  }
+  const top = scored[0];
+  const runner = scored[1] || { sim: 0 };
+
+  if (top.sim < cfg.hint_threshold) {
+    return {
+      contextNote: "",
+      trace: {
+        enabled: true,
+        reason: "below_threshold",
+        embedder: probe.embedder,
+        scored: scored.slice(0, 5).map((s) => ({ slug: s.slug, sim: Number(s.sim.toFixed(3)) })),
+      },
+    };
+  }
+
+  const loaded = [];
+  const hinted = [];
+
+  // High-confidence top picks → inline body. Bounded by max_loaded and require
+  // a margin over the runner-up so a flat tie of weak matches doesn't bloat
+  // the prompt.
+  if (top.sim >= cfg.load_threshold && top.sim - runner.sim >= cfg.margin) {
+    for (let i = 0; i < scored.length && loaded.length < cfg.max_loaded; i++) {
+      const cand = scored[i];
+      if (cand.sim < cfg.load_threshold) break;
+      const body = readBodyCapped(cand.slug, projectPath, cfg.body_char_cap);
+      if (!body) continue;
+      loaded.push({ ...cand, body });
+    }
+  }
+
+  // Mid-confidence remainder → hint.
+  for (const cand of scored) {
+    if (loaded.some((l) => l.slug === cand.slug)) continue;
+    if (hinted.length >= cfg.max_hints) break;
+    if (cand.sim < cfg.hint_threshold) break;
+    hinted.push(cand);
+  }
+
+  const contextNote = renderInjectedBlock({ loaded, hinted, embedder: probe.embedder });
+  return {
+    contextNote,
+    trace: {
+      enabled: true,
+      embedder: probe.embedder,
+      scored: scored.slice(0, 5).map((s) => ({ slug: s.slug, sim: Number(s.sim.toFixed(3)) })),
+      loaded: loaded.map((l) => l.slug),
+      hinted: hinted.map((h) => h.slug),
+    },
+  };
+}
+
+function readBodyCapped(slug, projectPath, cap) {
+  try {
+    const { body } = loadSkill(slug, { projectPath });
+    if (!body) return "";
+    if (body.length <= cap) return body;
+    return body.slice(0, cap) + "\n\n…(skill body truncated — call load_skill for the full text)";
+  } catch {
+    return "";
+  }
+}
+
+// Small helper used by the CLI inspect command to print why something fell out.
+export function summarizeTrace(trace) {
+  if (!trace) return "(no trace)";
+  if (!trace.enabled) return `inspector disabled (${trace.reason || "off"})`;
+  if (trace.reason && !trace.loaded && !trace.hinted) {
+    return `no skill injected: ${trace.reason}`;
+  }
+  const parts = [];
+  if (trace.loaded?.length) parts.push(`loaded: ${trace.loaded.join(", ")}`);
+  if (trace.hinted?.length) parts.push(`hinted: ${trace.hinted.join(", ")}`);
+  if (!parts.length) parts.push("nothing injected");
+  return parts.join(" · ");
+}
+
+// Re-exported for callers that want to introspect.
+export { readIndex };

package/src/core/agent/super-agent.js

@@ -10,6 +10,7 @@ import {
 } from "#core/agent/index.js";
 import { resolveAgentName } from "#core/identity/index.js";
 import { memoryBlockFor } from "#core/memory/index.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 export {
   buildIdentityBlock,
@@ -58,6 +59,10 @@ export async function runSuperAgent({
   // Null disables human-in-the-loop (tools that need confirmation fail
   // immediately instead of waiting for user input).
   requestConfirmation = null,
+  // When true, suppress the static "Available skills" slug-dump hint block
+  // because a per-turn skill inspector already injected the right context.
+  // Set by the daemon's super-agent endpoint when config.skills.inspector is on.
+  skipSkillsHint = false,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -74,7 +79,7 @@ export async function runSuperAgent({
     memoryBlock = await memoryBlockFor(prompt, { config: globalConfig, channel });
     // "Hilos activos en otros canales" — pure-recency cross-channel awareness.
     // Skipped for autonomous routines (no human to reference other threads).
-    if (channel !== "routine") {
+    if (channel !== CHANNELS.ROUTINE) {
       try {
         activeThreadsBlock = buildActiveThreadsBlock(channel, { config: globalConfig });
       } catch {
@@ -106,6 +111,7 @@ export async function runSuperAgent({
     // Compact "tools you can activate" block (names only, no schemas). Empty on
     // full channels and tool-free callers, where it's omitted from the prompt.
     lazyToolsBlock: buildLazyToolsBlock(toolSession),
+    skipSkillsHint,
   });
 
   const toolSchemas = noTools ? [] : toolSession.initialSchemas;

package/src/core/agent/tools/handlers/_git.js

@@ -0,0 +1,50 @@
+// Shared git spawn helper. Resolves the working directory from the same
+// project/cwd contract every other shell-aware tool uses (resolveProject),
+// then runs `git <args...>` with no shell so paths with spaces are safe.
+import { spawn } from "node:child_process";
+import { resolveProject } from "../helpers.js";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_OUTPUT_CHARS = 60_000; // ~15K tokens — generous for diffs, cuts runaways
+
+export function runGit(args, { cwd, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, error: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const truncated = stdout.length > MAX_OUTPUT_CHARS;
+      if (truncated) stdout = stdout.slice(0, MAX_OUTPUT_CHARS) + "\n…(output truncated)";
+      resolve({
+        ok: code === 0,
+        code,
+        stdout,
+        stderr: stderr.trim() || null,
+        timedOut,
+        truncated,
+      });
+    });
+  });
+}
+
+/** Resolve the working directory for a git tool from the standard tool args. */
+export function resolveGitCwd(ctx, { project, cwd }) {
+  // 1) If `cwd` was passed, use it directly (advanced override).
+  if (cwd) return cwd;
+  // 2) Otherwise resolve `project` (id, name, or path) → project root.
+  const proj = resolveProject(ctx.projects, project);
+  if (!proj) throw new Error("git: no project resolved (pass project or cwd)");
+  return proj.path;
+}

package/src/core/agent/tools/handlers/git-diff.js

@@ -0,0 +1,44 @@
+// git_diff — show the diff for a project. Defaults to unstaged working-tree
+// changes; pass staged=true for the index, or `ref` to diff against a commit.
+import { runGit, resolveGitCwd } from "./_git.js";
+
+export default {
+  name: "git_diff",
+  category: "code",
+  schema: {
+    type: "function",
+    function: {
+      name: "git_diff",
+      description:
+        "Show the git diff for a project. Defaults to UNSTAGED changes (working tree vs index). Set staged=true for the index vs HEAD, or pass ref (a commit, branch, or 'HEAD~1') to diff the working tree against that ref. Optional path argument limits the diff to a file/directory. Output is capped — use git_status first to choose what to diff if the change is large.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id, name, or path" },
+          cwd: { type: "string", description: "explicit working directory (overrides project)" },
+          staged: { type: "boolean", description: "diff the index vs HEAD instead of the working tree" },
+          ref: { type: "string", description: "ref to diff against (commit / branch / HEAD~N)" },
+          path: { type: "string", description: "limit the diff to this path (file or directory)" },
+          stat: { type: "boolean", description: "summary only (--stat) instead of full diff" },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx) => async ({ project, cwd, staged, ref, path: subPath, stat } = {}) => {
+    const root = resolveGitCwd(ctx, { project, cwd });
+    const args = ["diff", "--no-color"];
+    if (stat) args.push("--stat");
+    if (staged) args.push("--staged");
+    if (ref) args.push(ref);
+    if (subPath) args.push("--", subPath);
+    const r = await runGit(args, { cwd: root });
+    if (!r.ok) return { ok: false, error: r.stderr || `git diff exited ${r.code}` };
+    return {
+      ok: true,
+      cwd: root,
+      diff: r.stdout,
+      truncated: r.truncated,
+      args: args.slice(1),
+    };
+  },
+};

package/src/core/agent/tools/handlers/git-log.js

@@ -0,0 +1,38 @@
+// git_log — recent commits for a project. One-line format by default.
+import { runGit, resolveGitCwd } from "./_git.js";
+
+export default {
+  name: "git_log",
+  category: "code",
+  schema: {
+    type: "function",
+    function: {
+      name: "git_log",
+      description:
+        "List recent commits for a project. Defaults to the last 20 commits in one-line format. Pass path to limit to a file/directory, ref to start from a different commit/branch, or full=true for the full message + stats.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id, name, or path" },
+          cwd: { type: "string", description: "explicit working directory (overrides project)" },
+          limit: { type: "integer", description: "max commits to return (default 20, capped at 200)" },
+          ref: { type: "string", description: "ref to start from (branch / commit / HEAD~N); defaults to HEAD" },
+          path: { type: "string", description: "limit to commits touching this path" },
+          full: { type: "boolean", description: "show full subject + body + stat instead of oneline" },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx) => async ({ project, cwd, limit = 20, ref, path: subPath, full } = {}) => {
+    const root = resolveGitCwd(ctx, { project, cwd });
+    const safeLimit = Math.max(1, Math.min(Number(limit) || 20, 200));
+    const args = ["log", `-n${safeLimit}`, "--no-color"];
+    if (full) args.push("--format=fuller", "--stat");
+    else args.push("--oneline", "--decorate=short");
+    if (ref) args.push(ref);
+    if (subPath) args.push("--", subPath);
+    const r = await runGit(args, { cwd: root });
+    if (!r.ok) return { ok: false, error: r.stderr || `git log exited ${r.code}` };
+    return { ok: true, cwd: root, log: r.stdout, truncated: r.truncated };
+  },
+};

package/src/core/agent/tools/handlers/git-show.js

@@ -0,0 +1,34 @@
+// git_show — inspect a single commit (or branch tip): subject, author, files
+// changed, full diff.
+import { runGit, resolveGitCwd } from "./_git.js";
+
+export default {
+  name: "git_show",
+  category: "code",
+  schema: {
+    type: "function",
+    function: {
+      name: "git_show",
+      description:
+        "Show a single git commit (or any ref) — message, author, files changed, and full diff. Use `ref` to point at a commit hash, branch, or HEAD~N. Defaults to HEAD.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id, name, or path" },
+          cwd: { type: "string", description: "explicit working directory (overrides project)" },
+          ref: { type: "string", description: "ref to show (commit / branch / HEAD~N); defaults to HEAD" },
+          stat: { type: "boolean", description: "show stat summary instead of full diff" },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx) => async ({ project, cwd, ref = "HEAD", stat } = {}) => {
+    const root = resolveGitCwd(ctx, { project, cwd });
+    const args = ["show", "--no-color"];
+    if (stat) args.push("--stat");
+    args.push(ref);
+    const r = await runGit(args, { cwd: root });
+    if (!r.ok) return { ok: false, error: r.stderr || `git show exited ${r.code}` };
+    return { ok: true, cwd: root, ref, output: r.stdout, truncated: r.truncated };
+  },
+};

package/src/core/agent/tools/handlers/git-status.js

@@ -0,0 +1,61 @@
+// git_status — porcelain working-tree status for a project. Returns the raw
+// porcelain text plus a structured list of files so the model doesn't have to
+// re-parse it.
+import { runGit, resolveGitCwd } from "./_git.js";
+
+function parsePorcelain(text) {
+  const files = [];
+  for (const line of String(text).split("\n")) {
+    if (!line) continue;
+    // Format: XY <path>  (optionally `XY <orig> -> <renamed>` for renames)
+    const xy = line.slice(0, 2);
+    const rest = line.slice(3);
+    const renameIdx = rest.indexOf(" -> ");
+    let pathStr = rest;
+    let origPath = null;
+    if (renameIdx >= 0) {
+      origPath = rest.slice(0, renameIdx);
+      pathStr = rest.slice(renameIdx + 4);
+    }
+    files.push({
+      staged: xy[0] !== " " && xy[0] !== "?",
+      unstaged: xy[1] !== " ",
+      untracked: xy === "??",
+      status: xy.trim(),
+      path: pathStr,
+      ...(origPath ? { original_path: origPath } : {}),
+    });
+  }
+  return files;
+}
+
+export default {
+  name: "git_status",
+  category: "code",
+  schema: {
+    type: "function",
+    function: {
+      name: "git_status",
+      description:
+        "Show the git working-tree status (staged + unstaged + untracked) for a project. Returns porcelain output plus a parsed list of files. Pass project (id/name/path) OR cwd. Use this BEFORE summarizing changes or BEFORE staging.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id, name, or path; falls back to the active project if omitted" },
+          cwd: { type: "string", description: "explicit working directory (overrides project)" },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx) => async ({ project, cwd } = {}) => {
+    const root = resolveGitCwd(ctx, { project, cwd });
+    const r = await runGit(["status", "--porcelain=v1", "-uall"], { cwd: root });
+    if (!r.ok) return { ok: false, error: r.stderr || `git status exited ${r.code}` };
+    return {
+      ok: true,
+      cwd: root,
+      files: parsePorcelain(r.stdout),
+      raw: r.stdout,
+    };
+  },
+};

package/src/core/agent/tools/names.js

@@ -56,6 +56,12 @@ export const TOOLS = Object.freeze({
   SET_PERMISSION_MODE: "set_permission_mode",
   TRANSCRIBE_AUDIO:    "transcribe_audio",
 
+  // Git — code-channel tools, lazy on chat
+  GIT_STATUS:          "git_status",
+  GIT_DIFF:            "git_diff",
+  GIT_LOG:             "git_log",
+  GIT_SHOW:            "git_show",
+
   // HTTP-bridged registry tools (not native handlers; served via
   // core/tools/registry.js so the regular generic tools work the same way).
   GREP:                "grep",
@@ -101,6 +107,25 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.SEARCH_SESSIONS,
   TOOLS.TRANSCRIBE_AUDIO,
   TOOLS.DISCOVER_TOOLS,
+  TOOLS.GIT_STATUS,
+  TOOLS.GIT_DIFF,
+  TOOLS.GIT_LOG,
+  TOOLS.GIT_SHOW,
+]);
+
+/**
+ * Tools that belong in code-shaped channels (apx code, web_code) but should
+ * stay lazy on chat surfaces (telegram, web_sidebar, deck, desktop) — there's
+ * no point loading `git_diff` schemas in a Telegram chat.
+ *
+ * Listed separately so registry.js can promote them into the base set when
+ * the channel is a coding surface, without touching the chat base.
+ */
+export const CODE_CHANNEL_TOOLS = Object.freeze([
+  TOOLS.GIT_STATUS,
+  TOOLS.GIT_DIFF,
+  TOOLS.GIT_LOG,
+  TOOLS.GIT_SHOW,
 ]);
 
 /**
@@ -128,6 +153,12 @@ export const CODE_PLAN_TOOLS = Object.freeze([
   TOOLS.ASK_QUESTIONS,
   TOOLS.FETCH,
   TOOLS.SEARCH,
+  // Git tools are read-only on plan mode and let the agent inspect the
+  // working state before proposing edits.
+  TOOLS.GIT_STATUS,
+  TOOLS.GIT_DIFF,
+  TOOLS.GIT_LOG,
+  TOOLS.GIT_SHOW,
 ]);
 
 /**