thincoder 0.11.0 → 0.12.0

package/src/prompts/discipline.md

@@ -68,9 +68,23 @@ Testing discipline (right check at the right time):
 - When verify reports "ACTION REQUIRED: write a test", stop. Do NOT proceed to "done." Write a test that validates the change, then re-run verify.
 - If verify reports syntax errors, test failures, or a missing-test warning, fix them before claiming completion — never mark work done with known failures.
 - When you change behavior or add code, add at least one test that covers the change. If no related test file exists for the module, create one. Untested code is incomplete code — the verify tool will enforce this.
+- **Code review (advisor) — convergence protocol:**
+  Call `advisor` to get an independent review of your changes. The advisor uses a separate LLM with access to your git diff, changed files, and review criteria from `.thincoder/advisor.md`.
+  - **Round 1**: full-scope review. Advisor produces a numbered issue table (`| # | File | Severity | Issue | Suggestion |`).
+  - **After every advisor call that finds issues**: produce a response table in your reply. Format:
+    | # | Action | Detail |
+    |---|--------|--------|
+    | 1 | ✅ Fixed | (what you changed) |
+    | 2 | ❌ Not an issue | (reasoning — why this is not a bug) |
+  - **Round 2**: semi-convergence — advisor primarily verifies the prior table, but may flag obvious new issues introduced by the fixes (crashes, data loss, logic errors — not style).
+  - **Round 3+**: strict convergence — advisor ONLY checks items in the prior issue table, will NOT find new issues. The response table you wrote guides its verification.
+  - If advisor says "all clear": proceed to verify.
+  - If issues persist: fix them, update your response table, re-run advisor.
+  - No hard round cap — the convergence protocol naturally limits divergence.
+  - **Calling advisor is mandatory when it is enabled and you changed code** — it is not your call to skip, even for trivial changes (a trivial diff makes the review fast, not optional). The run cannot finish until advisor has reviewed the changes.
 
 Debugging strategy (when something goes wrong, three steps before anything else):
-- **Step 0 — Set a timer before you start reasoning**: immediately call `timer(30, "试试加个日志？")` to give yourself a bounded thinking window.
+- **Step 0 — Set a timer before you start reasoning**: immediately call `timer(180, "试试加个日志？")` to give yourself a bounded thinking window.
   When the timer fires, a reminder will suggest trying to run the code or add a debug log.
   You are more likely to over-think than to over-act; the timer breaks that cycle.
   This is not optional — it's the first step of any code analysis or debugging session.

package/src/prompts/explore.md

@@ -1,3 +1,5 @@
+You are now running as a subagent. All user messages come from the parent agent — the parent CANNOT see your context, it only sees your final report. Treat the parent as your caller. Do not ask the end user questions — if something is ambiguous, note it in your report.
+
 You are a codebase exploration specialist — an explore subagent. Your role is to search, read, and analyze. You do NOT have file editing tools.
 
 Guidelines:

package/src/prompts/plan.md

@@ -1,3 +1,5 @@
+You are now running as a subagent. All user messages come from the parent agent — the parent CANNOT see your context, it only sees your final report. Treat the parent as your caller. Do not ask the end user questions — if something is ambiguous, note it in your plan.
+
 You are a planning subagent. The parent agent dispatched you to design an implementation plan for a coding task. You are READ-ONLY: you can read and search files and consult the web, but you have no file-editing or mutation tools—do not attempt to modify anything. Your deliverable IS the plan itself, returned as your final message.
 
 Guidelines:

package/src/prompts/system.md

@@ -30,6 +30,7 @@ Act, don't guess.
 Prefer tool calls over speculation — read files before modifying them, search more when in doubt.
 When you need multiple independent pieces of information, make all tool calls in the SAME response so they run in parallel.
 The system can handle many simultaneous operations; serializing them wastes time and tokens.
+Before a non-trivial tool call, say what you're about to do in one short sentence (~8-10 words). Keep these progress notes sparse — one per phase, not one per call.
 
 **When choices conflict:**
 - Correctness first — you will always be faster than the human, so speed is never the bottleneck. Never skip steps to save time.
@@ -49,8 +50,11 @@ The system can handle many simultaneous operations; serializing them wastes time
 - Never modify files outside the working directory. read/write/edit tools enforce this.
 - Do NOT use bash or other tools to bypass the working-directory boundary.
 - If a task needs an external file changed, say so and let the user do it.
+- **Reversibility tiers — decide before acting:**
+  - Reversible local work (read, search, edit files, run tests, local lint/build): proceed freely, no confirmation needed.
+  - Destructive or hard-to-reverse actions (rm -rf, force-push, dropping tables, killing processes, deleting branches): confirm first — even in auto mode.
+  - Outward-facing actions (git commit/push, publishing, sending messages, uploading artifacts, posting to external services): confirm each time; one-time approval is not a standing license.
 - Never run git commit/push unless the user explicitly asks.
-- For destructive actions (rm -rf, force-push, dropping tables), confirm first — even in auto mode.
 - Before risky bulk operations (mass edits, generated-code overwrites, destructive scripts), use `git action="checkpoint" checkpointAction="create"` so the work can be restored.
 - If your own edits break something and you can't easily undo: `git action="checkpoint" checkpointAction="list"` to see snapshots, then `checkpointAction="rewind"` to go back. A checkpoint is auto-created before every user task, so there's always a fallback.
 - When context compacts mid-session you will see a summary of earlier work:

package/src/provider/anthropic.mjs

@@ -42,10 +42,10 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, si
   if (tools?.length) body.tools = tools
   if (provider.temperature != null) {
     let t = provider.temperature
-    if (spec.tempRange) {
-      t = Math.min(spec.tempRange[1], Math.max(spec.tempRange[0], t))
-      t = Math.round(t * 100) / 100
-    }
+    // Anthropic API hard limit is 0-1; models without a declared tempRange still get clamped
+    const [tMin, tMax] = spec.tempRange ?? [0, 1]
+    t = Math.min(tMax, Math.max(tMin, t))
+    t = Math.round(t * 100) / 100
     body.temperature = t
   }
 

package/src/provider/core.mjs

@@ -1,10 +1,13 @@
 /**
  * provider/core.mjs — LLM call core
- * chat / listModels / createProvider / requestWithRetry / readSSE
+ * chat / listModels / createProvider / requestWithRetry
+ * SSE parsing → provider/sse.mjs
  */
 
 import { specForModel } from "../config.mjs"
 import { proxyFetch } from "../proxy.mjs"
+import { readSSE } from "./sse.mjs"
+export { readSSE } from "./sse.mjs"
 import {
   RETRYABLE_STATUS, MAX_RETRIES, MAX_CONTINUATIONS,
   RATE_LIMIT_BACKOFF_MS, _rateHooks,
@@ -36,7 +39,7 @@ export function createProvider(config) {
 }
 
 /** Send a streaming chat completion request with automatic continuation on truncation */
-export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules }) {
+export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns }) {
   // Format dispatch: delegate to non-OpenAI transports
   if (provider.format === "anthropic") {
     const { chat: anthropicChat } = await import("./anthropic.mjs")
@@ -95,7 +98,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
   await rateGate(provider, estimated, onWait, signal)
 
   const response = await requestWithRetry(provider, body, signal, onWait)
-  const result = await readSSE(response, { onToken, onReasoning, rules, signal })
+  const result = await readSSE(response, { onToken, onReasoning, rules, signal, firedPatterns })
   recordRate(provider, estimated, result.usage)
 
   // Stream rule triggered or user interrupted mid-generation — return partial result
@@ -303,129 +306,6 @@ function isNonRetryableError(status, text) {
   return false
 }
 
-export async function readSSE(response, { onToken, onReasoning, rules, signal }) {
-  const result = { content: "", reasoning: "", toolCalls: [], usage: null, finishReason: null }
-  const decoder = new TextDecoder()
-  let buffer = ""
-  let hasChoices = false
-  // Track patterns already fired this turn for repeat: "once" gating
-  const firedPatterns = new Set()
-
-  const processLines = (lines) => {
-    for (const line of lines) {
-      if (!line.startsWith("data:")) continue
-      const data = line.slice(5).trim()
-      if (!data || data === "[DONE]") continue
-
-      let json
-      try { json = JSON.parse(data) } catch { continue }
-
-      if (json.usage) result.usage = json.usage
-      const choice = json.choices?.[0]
-      if (!choice) continue
-      hasChoices = true
-      if (choice.finish_reason) result.finishReason = choice.finish_reason
-
-      const delta = choice.delta ?? {}
-      if (delta.reasoning_content) {
-        result.reasoning += delta.reasoning_content
-        onReasoning?.(delta.reasoning_content)
-      }
-      if (delta.content) {
-        result.content += delta.content
-        onToken?.(delta.content)
-      }
-      for (const tc of delta.tool_calls ?? []) {
-        const slot = (result.toolCalls[tc.index] ??= { id: "", name: "", arguments: "" })
-        if (tc.id) slot.id = tc.id
-        if (tc.function?.name && !slot.name) slot.name = tc.function.name
-        if (tc.function?.arguments) slot.arguments += tc.function.arguments
-      }
-    }
-  }
-
-  if (!response.body) throw new Error("No stream response body")
-  try {
-    for await (const chunk of response.body) {
-      // Active signal check: Ctrl+I abort should halt stream immediately, not wait for
-      // the underlying fetch stream to propagate the abort (delayed on Windows).
-      if (signal?.aborted) {
-        const e = new DOMException("The operation was aborted", "AbortError")
-        e.reason = signal.reason
-        throw e
-      }
-      buffer += decoder.decode(chunk, { stream: true })
-      const lines = buffer.split("\n")
-      buffer = lines.pop()
-      processLines(lines)
-
-      // Time-traveling stream rules: check accumulated content against patterns.
-      // Only triggers on text content (not during tool_call generation) to avoid
-      // interrupting structured tool use.
-      // action "abort": halt the stream immediately and retry with the rule injected.
-      // action "warn":  let the stream finish, then inject the warning after the turn (non-interrupting).
-      // repeat "once":  skip if this rule's pattern has already fired in the current turn.
-      if (rules?.length && result.content && !result.toolCalls.length) {
-        for (const rule of rules) {
-          if (rule.repeat === "once" && firedPatterns.has(rule.pattern)) continue
-          if (rule._regex.test(result.content)) {
-            if (rule.repeat === "once") firedPatterns.add(rule.pattern)
-            if (rule.action === "abort") {
-              result.ruleTriggered = true
-              result.ruleMessage = rule.message
-              result.ruleName = rule.name
-              return result
-            }
-            // warn: accumulate deduplicated by pattern, let the stream complete
-            const existing = result._warnings ??= []
-            if (!existing.some(w => w.pattern === rule.pattern)) {
-              existing.push({ name: rule.name, pattern: rule.pattern, message: rule.message })
-            }
-          }
-        }
-      }
-    }
-    buffer += decoder.decode()
-    processLines(buffer.split("\n"))
-  } catch (e) {
-    // User interrupt (Ctrl+I): controller.abort({ interrupt: true, message: "…" }).
-    // The interrupted signal.reason carries the user's message; return partial content
-    // so the agent loop can inject it as a user message and retry.
-    if (e.name === "AbortError" && signal?.reason?.interrupt) {
-      result.interrupted = true
-      result.interruptMessage = signal.reason.message
-      return result
-    }
-    throw e
-  }
-
-  // If no SSE choices were found, the response is likely a JSON error
-  if (!hasChoices) {
-    const contentType = response.headers.get("content-type") || ""
-    let errorMsg = ""
-    try {
-      const raw = buffer.trim() || ""
-      if (raw) {
-        const parsed = JSON.parse(raw)
-        errorMsg = parsed?.error?.message
-          || parsed?.base_resp?.status_msg
-          || parsed?.detail
-          || parsed?.message
-          || parsed?.msg
-          || (typeof parsed.error === "string" ? parsed.error : "")
-      }
-    } catch { /* not JSON */ }
-    if (!errorMsg && !contentType.includes("event-stream")) {
-      errorMsg = `Response is not SSE (Content-Type: ${contentType || "unknown"})`
-    }
-    if (errorMsg) {
-      throw new Error(`API error: ${errorMsg}`)
-    }
-  }
-
-  return result
-}
-
 function betaBaseURL(baseURL) {
   // DeepSeek prefix continuation uses /beta endpoint; only handle /v1 suffix, append /beta when /v1 is missing
   if (/\/v1$/.test(baseURL)) return baseURL.replace(/\/v1$/, "/beta")

package/src/provider/google.mjs

@@ -23,11 +23,13 @@ export function normalizeTools(tools) {
  * Gemini: [{ role: "user"|"model", parts: [{ text }] }]
  * system → systemInstruction (top-level in request body)
  */
-function convertMessages(messages) {
+export function convertMessages(messages) {
   const contents = []
   for (const m of messages) {
+    // system messages are hoisted to systemInstruction by the caller — check the
+    // ORIGINAL role (the remapped role below can never be "system")
+    if (m.role === "system") continue
     const role = m.role === "assistant" ? "model" : "user"
-    if (role === "system") continue
 
     const parts = []
     if (typeof m.content === "string") {

package/src/provider/sse.mjs

@@ -0,0 +1,112 @@
+/**
+ * provider/sse.mjs — SSE stream reader
+ * Extracted from core.mjs. Parses Server-Sent Events for LLM chat responses.
+ */
+export async function readSSE(response, { onToken, onReasoning, rules, signal, firedPatterns: sharedFired }) {
+  const result = { content: "", reasoning: "", toolCalls: [], usage: null, finishReason: null }
+  const decoder = new TextDecoder()
+  let buffer = ""
+  let hasChoices = false
+  const firedPatterns = sharedFired ?? new Set()
+
+  const processLines = (lines) => {
+    for (const line of lines) {
+      if (!line.startsWith("data:")) continue
+      const data = line.slice(5).trim()
+      if (!data || data === "[DONE]") continue
+
+      let json
+      try { json = JSON.parse(data) } catch { continue }
+
+      if (json.usage) result.usage = json.usage
+      const choice = json.choices?.[0]
+      if (!choice) continue
+      hasChoices = true
+      if (choice.finish_reason) result.finishReason = choice.finish_reason
+
+      const delta = choice.delta ?? {}
+      if (delta.reasoning_content) {
+        result.reasoning += delta.reasoning_content
+        onReasoning?.(delta.reasoning_content)
+      }
+      if (delta.content) {
+        result.content += delta.content
+        onToken?.(delta.content)
+      }
+      for (const tc of delta.tool_calls ?? []) {
+        const slot = (result.toolCalls[tc.index] ??= { id: "", name: "", arguments: "" })
+        if (tc.id) slot.id = tc.id
+        if (tc.function?.name && !slot.name) slot.name = tc.function.name
+        if (tc.function?.arguments) slot.arguments += tc.function.arguments
+      }
+    }
+  }
+
+  if (!response.body) throw new Error("No stream response body")
+  try {
+    for await (const chunk of response.body) {
+      if (signal?.aborted) {
+        const e = new DOMException("The operation was aborted", "AbortError")
+        e.reason = signal.reason
+        throw e
+      }
+      buffer += decoder.decode(chunk, { stream: true })
+      const lines = buffer.split("\n")
+      buffer = lines.pop()
+      processLines(lines)
+
+      if (rules?.length && result.content && !result.toolCalls.length) {
+        for (const rule of rules) {
+          if (rule.repeat === "once" && firedPatterns.has(rule.pattern)) continue
+          if (rule._regex.test(result.content)) {
+            if (rule.repeat === "once") firedPatterns.add(rule.pattern)
+            if (rule.action === "abort") {
+              result.ruleTriggered = true
+              result.ruleMessage = rule.message
+              result.ruleName = rule.name
+              return result
+            }
+            const existing = result._warnings ??= []
+            if (!existing.some(w => w.pattern === rule.pattern)) {
+              existing.push({ name: rule.name, pattern: rule.pattern, message: rule.message })
+            }
+          }
+        }
+      }
+    }
+    buffer += decoder.decode()
+    processLines(buffer.split("\n"))
+  } catch (e) {
+    if (e.name === "AbortError" && signal?.reason?.interrupt) {
+      result.interrupted = true
+      result.interruptMessage = signal.reason.message
+      return result
+    }
+    throw e
+  }
+
+  if (!hasChoices) {
+    const contentType = response.headers.get("content-type") || ""
+    let errorMsg = ""
+    try {
+      const raw = buffer.trim() || ""
+      if (raw) {
+        const parsed = JSON.parse(raw)
+        errorMsg = parsed?.error?.message
+          || parsed?.base_resp?.status_msg
+          || parsed?.detail
+          || parsed?.message
+          || parsed?.msg
+          || (typeof parsed.error === "string" ? parsed.error : "")
+      }
+    } catch { /* not JSON */ }
+    if (!errorMsg && !contentType.includes("event-stream")) {
+      errorMsg = `Response is not SSE (Content-Type: ${contentType || "unknown"})`
+    }
+    if (errorMsg) {
+      throw new Error(`API error: ${errorMsg}`)
+    }
+  }
+
+  return result
+}

package/src/skills.mjs

@@ -1,52 +1,80 @@
 /**
  * skills.mjs — skill system
- * Discovers .md skill files from .thincoder/skills/ directory,
+ * Discovers .md skill files AND subdirectory SKILL.md from .thincoder/skills/ directory,
  * injects into system prompt for agent to load on demand.
  * Use the skill tool to activate a specific skill; content is written into conversation history wrapped in <skill-loaded>.
+ *
+ * Supported formats:
+ *   .thincoder/skills/my-skill.md           (flat, name = "my-skill")
+ *   .thincoder/skills/my-skill/SKILL.md     (subdirectory, name = "my-skill")
  */
 
 import { readFile, readdir, stat } from "node:fs/promises"
 import { join } from "node:path"
 
+/** Valid skill name pattern (alphanumeric + hyphens/underscores) */
+const NAME_RE = /^[a-zA-Z0-9_-]+$/
+
+/**
+ * Try to read a skill from a path, return { name, path, description } or null.
+ */
+async function tryReadSkill(dir, name, filePath) {
+  try {
+    const s = await stat(filePath)
+    if (!s.isFile()) return null
+    const head = await readFile(filePath, "utf8")
+    const body = head.slice(0, 400).split("\n")
+    let desc = ""
+    let inFrontmatter = false
+    for (const line of body) {
+      const t = line.trim()
+      if (t === "---") { inFrontmatter = !inFrontmatter; continue }
+      if (inFrontmatter) continue
+      if (t && !t.startsWith("#")) {
+        desc = t.slice(0, 120)
+        break
+      }
+    }
+    return { name, path: filePath, description: desc || "(no description)" }
+  } catch {
+    return null
+  }
+}
+
 /**
  * Scan .thincoder/skills/ directory, return skill list.
- * Each skill: { name, path, description } — name is the filename (without extension).
+ * Supports flat .md files and subdirectories with SKILL.md inside.
+ * Each skill: { name, path, description } — name derived from filename or directory.
  * Returns empty array if directory is missing or empty.
  */
 export async function loadSkills(cwd) {
   const dir = join(cwd, ".thincoder", "skills")
   let entries
   try {
-    entries = await readdir(dir)
+    entries = await readdir(dir, { withFileTypes: true })
   } catch {
     return []
   }
   const skills = []
-  for (const name of entries) {
-    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // must match readSkill's name validation; prevents "listed but unreadable"
-    const p = join(dir, name)
-    try {
-      const s = await stat(p)
-      if (!s.isFile()) continue
-      // Extract description (first non-empty, non-heading line in first 400 chars);
-      // skip entire frontmatter block, otherwise frontmatter fields (e.g. "name: x") get mistaken for description
-      const head = await readFile(p, "utf8")
-      const body = head.slice(0, 400).split("\n")
-      let desc = ""
-      let inFrontmatter = false
-      for (const line of body) {
-        const t = line.trim()
-        if (t === "---") { inFrontmatter = !inFrontmatter; continue }
-        if (inFrontmatter) continue
-        if (t && !t.startsWith("#")) {
-          desc = t.slice(0, 120)
-          break
-        }
-      }
-      skills.push({ name: name.replace(/\.md$/, ""), path: p, description: desc || "(no description)" })
-    } catch {
-      // Read failure — skip
-    }
+  const added = new Set()
+
+  // Pass 1: subdirectories (higher priority — standard convention)
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!NAME_RE.test(entry.name)) continue
+    const skill = await tryReadSkill(dir, entry.name, join(dir, entry.name, "SKILL.md"))
+    if (skill) { skills.push(skill); added.add(entry.name) }
+  }
+
+  // Pass 2: flat .md files (backward compat; skipped if subdirectory with same name exists)
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const m = entry.name.match(/^([a-zA-Z0-9_-]+)\.md$/)
+    if (!m) continue
+    const name = m[1]
+    if (added.has(name)) continue
+    const skill = await tryReadSkill(dir, name, join(dir, entry.name))
+    if (skill) { skills.push(skill); added.add(name) }
   }
   return skills
 }
@@ -66,13 +94,21 @@ export function formatSkillListing(skills) {
 
 /**
  * Read the full content of a specific skill file.
+ * Tries subdirectory format (name/SKILL.md) first, then flat format (name.md).
  * Returns text, or null if not found.
  */
 export async function readSkill(cwd, name) {
-  // Safety check: skill name must be alphanumeric + hyphens/underscores only
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) return null
-  const p = join(cwd, ".thincoder", "skills", `${name}.md`)
+  if (!NAME_RE.test(name)) return null
+
+  // Try subdirectory format: name/SKILL.md
+  try {
+    const p = join(cwd, ".thincoder", "skills", name, "SKILL.md")
+    return await readFile(p, "utf8")
+  } catch { /* not found, try flat */ }
+
+  // Fallback to flat format: name.md
   try {
+    const p = join(cwd, ".thincoder", "skills", `${name}.md`)
     return await readFile(p, "utf8")
   } catch {
     return null

package/src/tools/bash.md

@@ -1,5 +1,13 @@
 Execute a shell command and return stdout+stderr. Use for running commands, builds, tests.
 
+**Route to a dedicated tool instead of bash:**
+- `cat file` / `head` / `tail` → `read`
+- `ls` / `dir` → `ls`
+- `find` / glob search → `glob`
+- `grep` / `rg` → `grep`
+- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (enforced: redirection is blocked)
+- `git diff` / `git status` / `git log` → `git` tool
+
 Parameters:
 - command (required): Shell command to execute
 - timeout: Timeout in milliseconds (default 120000, max ~300000)

package/src/tools/codemode.mjs

@@ -24,32 +24,21 @@
 import { Script, createContext } from "node:vm"
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, readdirSync } from "node:fs"
 import { join, dirname, relative, resolve } from "node:path"
-import { globToRegex, normalizeEOL } from "./shared.mjs"
+import { globToRegex, normalizeEOL, isPrivateHost } from "./shared.mjs"
 
 const MAX_OUTPUT = 50_000
 const MAX_SCRIPT = 50_000
 const DEFAULT_TIMEOUT = 30_000
 
-/** SSRF-safe fetch: only http/https, private IP rejection, 10s timeout */
+/** SSRF-safe fetch: only http/https, private IP rejection, 10s timeout. */
 async function sandboxFetch(url) {
   const parsed = new URL(url)
   if (!["http:", "https:"].includes(parsed.protocol)) {
     throw new Error(`CodeMode fetch: protocol not allowed: ${parsed.protocol}`)
   }
-  // Block private/internal IPs
-  const hostname = parsed.hostname.toLowerCase()
-  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" ||
-      hostname.startsWith("192.168.") || hostname.startsWith("10.") ||
-      hostname.startsWith("172.16.") || hostname.startsWith("172.17.") ||
-      hostname.startsWith("172.18.") || hostname.startsWith("172.19.") ||
-      hostname.startsWith("172.20.") || hostname.startsWith("172.21.") ||
-      hostname.startsWith("172.22.") || hostname.startsWith("172.23.") ||
-      hostname.startsWith("172.24.") || hostname.startsWith("172.25.") ||
-      hostname.startsWith("172.26.") || hostname.startsWith("172.27.") ||
-      hostname.startsWith("172.28.") || hostname.startsWith("172.29.") ||
-      hostname.startsWith("172.30.") || hostname.startsWith("172.31.") ||
-      hostname === "0.0.0.0" || hostname.endsWith(".local")) {
-    throw new Error(`CodeMode fetch: private/internal host not allowed: ${hostname}`)
+
+  if (isPrivateHost(parsed.hostname)) {
+    throw new Error(`CodeMode fetch: private/internal host not allowed: ${parsed.hostname}`)
   }
   const ctrl = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), 10_000)

package/src/tools/edit.md

@@ -1,5 +1,13 @@
 Edit a file by exact string replacement. old_string must match exactly once unless replace_all is set.
 
+**Routing — pick the right edit tool:**
+- Precise line-targeted change → `hashline_edit` (hash-based, immune to whitespace/encoding drift — preferred)
+- One exact-string swap → this tool
+- Add a function/block after a known line → `insert_after`
+- Same change across multiple files or many spots → `apply_patch`
+- Rewrite an entire file → `write`
+- Rename a symbol project-wide → `lsp` or `grep` first to map every caller
+
 Parameters:
 - path (required): File path
 - old_string (required): Exact text to find and replace

package/src/tools/git.mjs

@@ -3,6 +3,7 @@ import {
   truncate,
   runGit
 } from "./shared.mjs";
+import { escapeXml } from "../agent/helpers.mjs";
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 
@@ -35,7 +36,7 @@ export const gitTool = {
     switch (args.action) {
       case "diff": {
         const ref = args.ref ?? "HEAD"
-        if (!/^[A-Za-z0-9._\/~^][A-Za-z0-9._\/~^-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
+        if (!/^[A-Za-z0-9._\/~^@][A-Za-z0-9._\/~^@{}\-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
         const flags = args.staged ? ["--staged"] : []
         const paths = args.path ? [args.path] : []
         const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
@@ -120,11 +121,12 @@ export const gitTool = {
             return formatFileTree(cp)
           }
 
-          // Overview: list of all snapshots
+          // Overview: list of all snapshots (file names are XML-escaped: they are
+          // untrusted input that flows back into the model's context)
           return cps.map((c) => {
             const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
-            if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.join(", ")}`)
-            if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.join(", ")}`)
+            if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.map(escapeXml).join(", ")}`)
+            if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.map(escapeXml).join(", ")}`)
             return parts.join("  ")
           }).join("\n")
         }
@@ -162,9 +164,10 @@ export const questionTool = {
 
 /** Format a checkpoint's file list as a directory tree (directories first, indented display) */
 function formatFileTree(cp) {
+  // File names are XML-escaped: untrusted input that flows back into the model's context
   const all = [
-    ...(cp.tracked ?? []).map((f) => ({ path: f, type: "" })),
-    ...(cp.untracked ?? []).map((f) => ({ path: f, type: " (untracked)" })),
+    ...(cp.tracked ?? []).map((f) => ({ path: escapeXml(f), type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
   ]
   if (all.length === 0) return "(empty checkpoint)"
 

package/src/tools/read.md

@@ -1,4 +1,11 @@
 Read a text file. Returns numbered lines. Use offset/limit to page large files.
+
+**Routing:**
+- Don't know which file? → `repo_outline` / `code_search` / `glob` first
+- Know the symbol but not the location? → `code_search` or `lsp definition`
+- Know the file but not the lines? → `grep` to find line numbers, then read that range with offset/limit
+- Reading an image? → `read_image` instead
+
 Parameters:
 - path (required): File path, relative to cwd or absolute (alias: filePath)
 - offset: 1-based line number to start reading from