thincoder 0.11.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/advisor.mjs

@@ -1,105 +1,393 @@
 /**
- * advisor.mjs — automated code review after each turn.
+ * advisor.mjs — Code review engine.
+ * Called by the advisor tool (agent-tools/advisor.mjs) when the agent
+ * explicitly requests a review at the end of a coding task.
  *
- * After every agent turn with tool execution, a second chat completion reviews
- * the turn's transcript and injects observations as a system reminder.
+ * The advisor runs as a read-only exploration sub-agent with tools
+ * (read, glob, grep, ls, git, lsp, code_search). It discovers changes
+ * via git diff, reads files for context, and traces callers via grep/lsp.
  *
  * Config:
  *   { advisor: { enabled: true, provider: "deepseek", model: "deepseek-chat" } }
  *   provider + model are optional — defaults to the main agent's provider/model.
+ *
+ * Convergence protocol:
+ *   Round 1: full review → produces a numbered issue table.
+ *   Agent responds with a response table per issue.
+ *   Round 2: semi-convergence — verifies table + can flag obvious new issues.
+ *   Round 3+: strict convergence — only checks the prior issue table.
+ *   No hard round cap — the convergence protocol naturally limits divergence.
+ *
+ *
+ * Project customisation: .thincoder/advisor.md in the project root.
  */
 import { chat } from "./provider/core.mjs"
 import { findProvider } from "./config.mjs"
+import { existsSync, readFileSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import { execFileSync } from "node:child_process"
+import { toOpenAISchema } from "./tools/index.mjs"
 
-const ADVISOR_PROMPT = `你是代码审查顾问。审查编程助手最近一轮操作并提供简短的观察。
+const __dirname = dirname(fileURLToPath(import.meta.url))
 
-规则：
-- 用中文回答，2-4 行，分条目
-- 关注：遗漏的边界情况、错误的假设、低效的模式、安全隐患
-- 如果一切正常，说"未发现问题"
-- 不要建议或调用工具 — 只做只读审查
-- 不要直接对用户说话 — 用第三人称评价助手的行为`
+const ADVISOR_MD_PATH = ".thincoder/advisor.md"
+const MAX_TASK_SUMMARY = 500
+const GIT_TIMEOUT = 5_000
+
+const DEFAULT_CRITERIA = `Review the code changes, focusing on:
+1. Correctness: logic errors, edge cases, off-by-one, incomplete modifications
+2. Security: unhandled exceptions, null references, resource leaks, race conditions
+3. Consistency: alignment with existing project patterns and conventions
+4. Completeness: missing callers, imports, or follow-up changes
+5. Maintainability: vague naming, missing comments, overly complex logic`
+
+// ────────────────────────────────────────
+// Advisor's read-only tool set
+// ────────────────────────────────────────
 
 /**
- * Run advisor review on the most recent turn.
- * Only fires when the agent executed tool calls (did real work).
- * Returns the advisor's message, or null if advisor is disabled or there's nothing to review.
+ * Restricted git tool: diff / status / log only.
+ * Checkpoint create/rewind are blocked — the advisor must not mutate state.
  */
-export async function runAdvisor(agent) {
-  const cfg = agent.config?.advisor
-  if (!cfg?.enabled) return null
+const { gitTool, readTool, globTool, grepTool, lsTool } = await import("./tools/index.mjs")
+const { lspTool } = await import("./tools/lsp.mjs")
+const { codeModeTool: codeSearchTool } = await import("./tools/codemode.mjs")
+
+const advisorGitTool = {
+  ...gitTool,
+  readonly: true,
+  async execute(args, ctx) {
+    // Block checkpoint create/rewind — advisor is read-only
+    if (args.action === "checkpoint") {
+      if (args.checkpointAction === "create" || args.checkpointAction === "rewind") {
+        return "Error: checkpoint create/rewind is disabled in advisor mode. Use diff/status/log only."
+      }
+    }
+    return gitTool.execute(args, ctx)
+  },
+}
+
+const ADVISOR_TOOLS = [readTool, globTool, grepTool, lsTool, advisorGitTool, lspTool, codeSearchTool]
+const ADVISOR_TOOL_SCHEMAS = ADVISOR_TOOLS.map(toOpenAISchema)
+const ADVISOR_TOOL_BY_NAME = new Map(ADVISOR_TOOLS.map((t) => [t.name, t]))
 
-  // Only review turns where the agent did real work (tool calls executed)
-  const lastAssistant = findLast(agent.history, (m) => m.role === "assistant")
-  const lastTool = findLast(agent.history, (m) => m.role === "tool")
-  if (!lastAssistant || !lastTool) return null
-
-  // Build a clean transcript: last user message + assistant + tool results
-  const lastUser = findLast(agent.history, (m) => m.role === "user")
-  const transcript = buildTranscript(agent.history, lastUser)
-
-  // Resolve provider: explicit provider name → look up from providers list;
-  // only model → reuse main provider with different model; neither → main provider as-is.
-  let provider
-  if (cfg.provider) {
-    provider = findProvider(agent.providers ?? [agent.provider], cfg.provider)
-    if (cfg.model) provider = { ...provider, model: cfg.model }
-  } else {
-    provider = { ...agent.provider }
-    if (cfg.model) provider.model = cfg.model
+// ────────────────────────────────────────
+// Prompt files — loaded at module init
+// ────────────────────────────────────────
+
+const ADVISOR_ROUND1 = readFileSync(join(__dirname, "prompts", "advisor-round1.md"), "utf8")
+const ADVISOR_ROUND2 = readFileSync(join(__dirname, "prompts", "advisor-round2.md"), "utf8")
+const ADVISOR_ROUND3 = readFileSync(join(__dirname, "prompts", "advisor-round3.md"), "utf8")
+
+// ────────────────────────────────────────
+// History extraction — issue/response tables
+// ────────────────────────────────────────
+
+const ADVISOR_TABLE_HEADER = "| # | File | Severity | Issue | Suggestion |"
+const CONVERGENCE_TABLE_HEADER = "| # | Orig# | File | Severity | Status | Notes |"
+const AGENT_RESPONSE_HEADER = "| # | Action | Detail |"
+const LEGACY_ADVISOR_HEADER = "| # | 文件 | 严重程度 | 问题描述 | 建议修复 |"
+const LEGACY_CONVERGENCE_HEADER = "| # | 原# | 文件 | 严重程度 | 当前状态 | 说明 |"
+const LEGACY_RESPONSE_HEADER = "| # | 处理 | 详情 |"
+const ALL_CLEAR_PHRASES = [
+  "No issues found",
+  "All issues resolved",
+  "review passed",
+  "未发现问题",
+  "所有问题已解决",
+  "审查通过",
+]
+
+export function extractPriorIssueTable(history) {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const m = history[i]
+    if (m.role !== "tool") continue
+    const content = typeof m.content === "string" ? m.content : ""
+    if (ALL_CLEAR_PHRASES.some((p) => content.includes(p))) return null
+    if (content.includes(ADVISOR_TABLE_HEADER) || content.includes(CONVERGENCE_TABLE_HEADER) ||
+        content.includes(LEGACY_ADVISOR_HEADER) || content.includes(LEGACY_CONVERGENCE_HEADER)) {
+      const table = extractTableBlock(content)
+      if (table) return { text: table, sinceIdx: i }
+      return null
+    }
   }
+  return null
+}
 
+export function extractAgentResponseTable(history, sinceIdx) {
+  for (let i = sinceIdx + 1; i < history.length; i++) {
+    const m = history[i]
+    if (m.role !== "assistant") continue
+    const content = typeof m.content === "string" ? m.content : ""
+    if (content.includes(AGENT_RESPONSE_HEADER) || content.includes(LEGACY_RESPONSE_HEADER)) {
+      return extractTableBlock(content)
+    }
+  }
+  return null
+}
+
+function extractTableBlock(text) {
+  const lines = text.split("\n")
+  let start = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("|")) { start = i; break }
+  }
+  if (start < 0) return null
+  let end = start
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("|")) end = i
+    else break
+  }
+  return lines.slice(start, end + 1).join("\n")
+}
+
+// ────────────────────────────────────────
+// Review scope — repos to review
+// ────────────────────────────────────────
+
+/**
+ * Find the git repository roots that contain the agent's touched files.
+ * Falls back to cwd if no repos found.
+ */
+function findReviewRepos(agent) {
+  const touched = agent._touchedFiles ?? []
+  const repos = []
+
+  for (const abs of touched) {
+    try {
+      const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: dirname(abs), encoding: "utf8", timeout: GIT_TIMEOUT,
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim()
+      if (root && !repos.includes(root)) repos.push(root)
+    } catch { /* not a git repo */ }
+  }
+
+  if (repos.length > 0) return repos
+
+  // Fallback: cwd itself
   try {
-    const response = await chat(provider, {
-      messages: [
-        { role: "system", content: ADVISOR_PROMPT },
-        { role: "user", content: transcript },
-      ],
-      tools: [],
-      signal: new AbortController().signal,
-    })
-    if (!response.content?.trim()) return null
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: agent.cwd, encoding: "utf8", timeout: GIT_TIMEOUT,
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim()
+    if (root) return [root]
+  } catch { /* not a git repo */ }
 
-    return `[Advisor 审查 — 自动观察，非用户指令。请批判性参考：\n${response.content.trim()}]`
+  return []
+}
+
+// ────────────────────────────────────────
+
+export function loadAdvisorMd(cwd) {
+  const path = join(cwd, ADVISOR_MD_PATH)
+  if (!existsSync(path)) return DEFAULT_CRITERIA
+  try {
+    const content = readFileSync(path, "utf8").trim()
+    return content || DEFAULT_CRITERIA
   } catch {
-    // Advisor failure is non-fatal — main loop continues
-    return null
+    return DEFAULT_CRITERIA
   }
 }
 
-/** Find the last history entry matching a predicate. */
-function findLast(arr, fn) {
-  for (let i = arr.length - 1; i >= 0; i--) {
-    if (fn(arr[i])) return i
+function extractTaskSummary(history) {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const m = history[i]
+    if (m.role !== "user") continue
+    const content = typeof m.content === "string" ? m.content : ""
+    if (content.startsWith("[System reminder:") || content.startsWith("[User interrupt:")) continue
+    const firstPara = content.split("\n\n")[0]
+    return firstPara.length > MAX_TASK_SUMMARY ? firstPara.slice(0, MAX_TASK_SUMMARY) + "…" : firstPara
   }
-  return -1
+  return null
 }
 
-/** Build a compact transcript of the last turn for the advisor. */
-function buildTranscript(history, lastUserIdx) {
-  const lines = []
-  lines.push("## Last user message")
-  lines.push(truncate(String(history[lastUserIdx]?.content ?? "")))
-  lines.push("")
-  lines.push("## Assistant response and tool calls")
+// ────────────────────────────────────────
+// System prompt routing
+// ────────────────────────────────────────
 
-  for (let i = lastUserIdx + 1; i < history.length; i++) {
-    const m = history[i]
-    if (m.role === "assistant") {
-      const content = typeof m.content === "string" ? m.content : ""
-      const tools = m.tool_calls?.map((tc) => tc.function?.name).filter(Boolean) ?? []
-      const label = tools.length ? ` (called: ${tools.join(", ")})` : ""
-      lines.push(`[assistant${label}] ${truncate(content, 500)}`)
-    } else if (m.role === "tool") {
-      lines.push(`[tool ${m.tool_call_id}] ${truncate(String(m.content ?? ""), 300)}`)
+export function buildAdvisorSystemPrompt(agent, _prior) {
+  const prior = _prior ?? extractPriorIssueTable(agent.history)
+  if (!prior || (agent._advisorRound || 0) === 0) return ADVISOR_ROUND1
+  const round = (agent._advisorRound || 0) + 1
+  if (round === 2) return ADVISOR_ROUND2
+  return ADVISOR_ROUND3
+}
+
+// ────────────────────────────────────────
+// User message building
+// ────────────────────────────────────────
+
+export function buildAdvisorUserMessage(agent, _prior) {
+  const prior = _prior ?? extractPriorIssueTable(agent.history)
+
+  // Repos to review
+  const repos = findReviewRepos(agent)
+  const repoList = repos.length > 0
+    ? repos.map((r, i) => `${i + 1}. ${r}`).join("\n")
+    : `(no git repository — working directory: ${agent.cwd})`
+
+  const parts = []
+
+  // Convergence data (round 2+)
+  if (prior && (agent._advisorRound || 0) > 0) {
+    const response = extractAgentResponseTable(agent.history, prior.sinceIdx)
+      || "(Agent did not provide a response table — re-evaluate each issue)"
+    const round = (agent._advisorRound || 0) + 1
+    const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
+    parts.push(`## Round ${round} — ${label}`)
+    parts.push("")
+    parts.push("## Prior Issue Table")
+    parts.push(prior.text)
+    parts.push("")
+    parts.push("## Agent Response")
+    parts.push(response)
+    parts.push("")
+    parts.push("---")
+    parts.push("")
+  }
+
+  // Review scope
+  parts.push("## Review Scope")
+  parts.push(`Review the following git repositor${repos.length === 1 ? "y" : "ies"}:`)
+  parts.push(repoList)
+  parts.push("")
+
+  // Task summary
+  const taskSummary = extractTaskSummary(agent.history)
+  if (taskSummary) {
+    parts.push("## Task")
+    parts.push(taskSummary)
+    parts.push("")
+  }
+
+  // Review criteria
+  const criteria = loadAdvisorMd(agent.cwd)
+  parts.push("## Review Criteria")
+  parts.push(criteria)
+  parts.push("")
+
+  // Instructions
+  parts.push("## Instructions")
+  parts.push("1. Read `AGENTS.md` and any design documents first — understand project conventions, version requirements, and architecture decisions before flagging issues.")
+  parts.push("2. Run `git diff HEAD` in each repo to discover uncommitted changes.")
+  parts.push("3. `read` changed files for full context beyond the diff.")
+  parts.push("4. Use `grep` or `lsp` to trace callers, imports, and dependencies.")
+  parts.push("5. Produce your review table based on the review criteria above.")
+  parts.push("Do NOT flag features that are valid under the project's stated platform requirements.")
+
+  return parts.join("\n")
+}
+
+// ────────────────────────────────────────
+// Advisor tool loop
+// ────────────────────────────────────────
+
+/**
+ * Run the advisor's tool loop: chat → execute tools → repeat.
+ * Stops when the model produces text without tool calls.
+ */
+async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd) {
+  while (true) {
+    const response = await chat(provider, {
+      messages,
+      tools: ADVISOR_TOOL_SCHEMAS,
+      signal: (signal && !signal.aborted) ? signal : new AbortController().signal,
+      onToken: onOutput,
+      onReasoning: onOutput,
+    })
+
+    // No tool calls — this is the final review text
+    if (!response.toolCalls?.length) {
+      if (!response.content?.trim()) return "Advisor: (empty response — review was inconclusive)"
+      return response.content.trim()
+    }
+
+    // Push assistant message with tool calls
+    messages.push({
+      role: "assistant",
+      content: response.content || null,
+      tool_calls: response.toolCalls.map((tc) => ({
+        id: tc.id, type: "function",
+        function: { name: tc.name, arguments: tc.arguments },
+      })),
+    })
+
+    // Execute each tool call
+    for (const tc of response.toolCalls) {
+      const tool = ADVISOR_TOOL_BY_NAME.get(tc.name)
+      let result
+      if (!tool) {
+        result = `Error: unknown tool "${tc.name}". Available: ${[...ADVISOR_TOOL_BY_NAME.keys()].join(", ")}`
+      } else {
+        try {
+          const args = JSON.parse(tc.arguments || "{}")
+          result = await tool.execute(args, {
+            cwd,
+            agent,
+            onOutput,
+            signal,
+          })
+        } catch (e) {
+          result = `Error: ${e.message}`
+        }
+      }
+      messages.push({ role: "tool", tool_call_id: tc.id, content: String(result) })
     }
   }
+}
+
+// ────────────────────────────────────────
+// Main entry point
+// ────────────────────────────────────────
 
-  return lines.join("\n")
+export function resolveAdvisorProvider(agent) {
+  const cfg = agent.config?.advisor
+  if (cfg?.provider) {
+    try {
+      const provider = findProvider(agent.providers ?? [agent.provider], cfg.provider)
+      const result = cfg.model ? { ...provider, model: cfg.model } : { ...provider }
+      if (cfg.thinking === null) result.thinking = undefined  // explicitly off
+      else if (cfg.thinking !== undefined) result.thinking = cfg.thinking
+      if (cfg.reasoningEffort !== undefined) result.reasoningEffort = cfg.reasoningEffort
+      return result
+    } catch {
+      // Provider not found — fall back to main provider
+    }
+  }
+  const provider = { ...agent.provider }
+  if (cfg?.model) provider.model = cfg.model
+  if (cfg?.thinking === null) provider.thinking = undefined  // explicitly off
+  else if (cfg?.thinking !== undefined) provider.thinking = cfg.thinking
+  if (cfg?.reasoningEffort !== undefined) provider.reasoningEffort = cfg.reasoningEffort
+  return provider
 }
 
-/** Truncate text to maxLen characters, adding "…" if truncated. */
-function truncate(text, maxLen = 1000) {
-  if (text.length <= maxLen) return text
-  return text.slice(0, maxLen) + "…"
+export async function runAdvisorReview(agent, onOutput, signal) {
+  const cfg = agent.config?.advisor
+  if (!cfg?.enabled) return null
+
+  const repos = findReviewRepos(agent)
+  if ((agent._touchedFiles ?? []).length === 0) return null
+
+  const provider = resolveAdvisorProvider(agent)
+  const priorIssue = extractPriorIssueTable(agent.history)
+  const systemPrompt = buildAdvisorSystemPrompt(agent, priorIssue)
+  const userMessage = buildAdvisorUserMessage(agent, priorIssue)
+
+  // Set the advisor's cwd to the first repo (for tool context)
+  const advisorCwd = repos.length > 0 ? repos[0] : agent.cwd
+
+  const messages = [
+    { role: "system", content: systemPrompt },
+    { role: "user", content: userMessage },
+  ]
+
+  try {
+    return await runAdvisorToolLoop(provider, messages, onOutput, signal, agent, advisorCwd)
+  } catch (e) {
+    if (e.name === "AbortError" && signal?.reason?.interrupt) throw e
+    return `Advisor: review failed — ${e.message || "unknown error"}. You may retry or proceed to verify.`
+  }
 }

package/src/agent/helpers.mjs

@@ -12,8 +12,12 @@ export const DEFAULT_SUBAGENT_TURNS = 100
 export const DEFAULT_GOAL_TURNS = 200
 export const MIN_REPORT_CHARS = 200
 export const REPORT_CONTINUATION =
-  "Your report is too brief to be a complete handoff — the parent agent sees nothing else from your run. " +
-  "Expand it: what you did and why, the path of every file you touched, how you verified (commands/tests run, with results), and anything left undone."
+  "Your report was sent back: too brief to be a complete handoff — the parent agent sees nothing else from your run. " +
+  "Rewrite your final message as a checklist:\n" +
+  "1. What you changed and why\n" +
+  "2. The path of every file you touched\n" +
+  "3. How you verified (tests run, commands executed, with results)\n" +
+  "4. Anything left undone or worth follow-up"
 
 const TOOL_RESULT_OFFLOAD_LIMIT = 16_000
 const TOOL_RESULT_PREVIEW = 2_000
@@ -22,7 +26,7 @@ const GIT_TIMEOUT_MS = 5000
 const MAX_GIT_CHANGES_DISPLAY = 20
 
 export const OUTLINE_INJECT_PREFIX = "[System reminder: project dependency outline:"
-export const FILE_MUTATORS = new Set(["write", "edit", "insert_after", "apply_patch", "delete"])
+export const FILE_MUTATORS = new Set(["write", "edit", "insert_after", "apply_patch", "delete", "hashline_edit"])
 
 /** Escape XML special characters in a string for safe embedding in XML/HTML */
 export function escapeXml(s) {

package/src/agent/setup.mjs

@@ -117,8 +117,8 @@ export async function prepareRun(agent, input, callbacks, {
   }
 
   // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool } = await import("../agent-tools.mjs")
-  const tools = [...agent.tools, taskTool, planTool, timerTool, ...(depth === 0 ? [subagentTool, skillTool, goalTool, verifyTool, recentChangesTool] : [])]
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool } = await import("../agent-tools.mjs")
+  const tools = [...agent.tools, taskTool, planTool, timerTool, ...(depth === 0 ? [subagentTool, skillTool, goalTool, verifyTool, recentChangesTool, advisorTool] : [])]
   const toolSchemas = tools.map(toOpenAISchema)
   const toolByName = new Map(tools.map((t) => [t.name, t]))
   agent._onTaskUpdate = callbacks.onTaskUpdate

package/src/agent-tools/advisor.mjs

@@ -0,0 +1,36 @@
+/**
+ * agent-tools/advisor.mjs — advisor tool wrapper.
+ * The agent calls this explicitly at the end of a coding task to get a code review.
+ */
+import { runAdvisorReview } from "../advisor.mjs"
+
+export const advisorTool = {
+  name: "advisor",
+  description:
+    "Run a code review on your changes (convergence protocol). " +
+    "Call this when you have finished coding and want an independent review before finalising. " +
+    "The advisor is an independent read-only sub-agent that explores the codebase, runs git diff, " +
+    "reads files, and traces callers via grep/lsp. " +
+    "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
+    "Round 1 does a full review and produces a numbered issue table. " +
+    "After the review, you MUST produce a response table (see discipline rules for format). " +
+    "Round 2 verifies the table + can flag obvious new issues. " +
+    "Round 3+ strictly checks only the prior table — convergence, not divergence. " +
+    "If issues are found, fix them, update your response table, then re-run advisor. " +
+    "If advisor says all clear, call verify.",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  readonly: true,
+  sideEffectExempt: true,
+  outputPanel: true,
+  async execute(_args, ctx) {
+    const agent = ctx.agent
+
+    const result = await runAdvisorReview(agent, ctx.onOutput, ctx.signal)
+    if (!result) return "Advisor: review is disabled or no changes to review."
+
+    return result
+  },
+}

package/src/agent-tools/plan.mjs

@@ -2,7 +2,56 @@
  * plan tool: enter/exit plan mode.
  * In plan mode only read-only tools are allowed — explore code, design solutions, no code writing.
  * After the user approves the plan, exit plan mode and start implementing.
+ *
+ * Reminder cadence (kimi-code style): while plan mode is active the agent loop
+ * re-injects reminders — sparse every 2 turns, full every 5 turns or when the
+ * user sends a new message — so the constraint never fades from context.
  */
+
+export const PLAN_FULL_REMINDER =
+  "[System reminder: plan mode is ON. Workflow: (1) explore/read codebase with read-only tools, " +
+  "(2) design a solution considering trade-offs, (3) present your plan by calling plan with action='exit' " +
+  "so the user can approve it. Only read-only tools are allowed — do not write, edit, or run mutation commands. " +
+  "Your turn must end with either a clarifying question to the user or a call to plan with action='exit'.]"
+
+export const PLAN_SPARSE_REMINDER =
+  "[System reminder: plan mode still active — read-only tools only (the current plan file exempt). " +
+  "Design the solution, then call plan with action='exit' for user approval.]"
+
+export const PLAN_EXIT_REMINDER =
+  "[System reminder: plan mode is now OFF. Start implementing your plan — edit files, run commands. " +
+  "No need for a task list (plan already covered that) or further confirmation.]"
+
+/** Turns between reminder re-injections while plan mode is active */
+const SPARSE_INTERVAL = 2
+const FULL_INTERVAL = 5
+
+/**
+ * Decide which plan-mode reminder (if any) to inject this turn.
+ * @param {object} agent — the agent object (mutated: tracks reminder state)
+ * @param {boolean} userMessageSince — whether a user message arrived since the last reminder
+ * @returns {string|null} reminder text or null
+ */
+export function planReminderForTurn(agent, userMessageSince) {
+  if (!agent.planMode) {
+    agent._planTurnsSinceReminder = 0
+    agent._planTurnsSinceSparse = 0
+    return null
+  }
+  agent._planTurnsSinceReminder = (agent._planTurnsSinceReminder ?? 0) + 1
+  agent._planTurnsSinceSparse = (agent._planTurnsSinceSparse ?? 0) + 1
+  if (userMessageSince || agent._planTurnsSinceReminder >= FULL_INTERVAL) {
+    agent._planTurnsSinceReminder = 0
+    agent._planTurnsSinceSparse = 0
+    return PLAN_FULL_REMINDER
+  }
+  if (agent._planTurnsSinceSparse >= SPARSE_INTERVAL) {
+    agent._planTurnsSinceSparse = 0
+    return PLAN_SPARSE_REMINDER
+  }
+  return null
+}
+
 export const planTool = {
   name: "plan",
   description:
@@ -18,13 +67,15 @@ export const planTool = {
   async execute(args, ctx) {
     if (args.action === "exit") {
       ctx.agent.planMode = false
+      ctx.agent._planTurnsSinceReminder = 0
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
-      ctx.agent._pendingReminders.push("[System reminder: plan mode is now OFF. Start implementing your plan — edit files, run commands. No need for a task list (plan already covered that) or further confirmation.]")
+      ctx.agent._pendingReminders.push(PLAN_EXIT_REMINDER)
       return "Plan mode exited. You may now edit files and run commands."
     }
     ctx.agent.planMode = true
+    ctx.agent._planTurnsSinceReminder = 0
     ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
-    ctx.agent._pendingReminders.push("[System reminder: plan mode is now ON. Workflow: (1) explore/read codebase with read-only tools, (2) design a solution considering trade-offs, (3) present your plan by calling plan with action='exit' so the user can approve it. Only read-only tools are allowed — do not write, edit, or run mutation commands.]")
+    ctx.agent._pendingReminders.push(PLAN_FULL_REMINDER)
     return "Plan mode activated. You are now restricted to READ-ONLY tools. Explore the codebase, understand the architecture, design a solution. Present your plan to the user for approval before writing any code."
   },
 }

package/src/agent-tools/subagent.mjs

@@ -16,7 +16,13 @@ import {
 export const subagentTool = {
   name: "subagent",
   description:
-    "Spawn a sub-agent to handle an independent subtask in an isolated context. The sub-agent returns only its final report. Spawn MULTIPLE subagents in the SAME response for parallel work—they run concurrently. Use role='explore' for codebase search/analysis (read-only, fast), role='plan' for read-only implementation planning (returns a step-by-step plan, never edits), role='coder' for self-contained implementation tasks. Do not give parallel subagents tasks that edit the same files.",
+    "Spawn a sub-agent to handle an independent subtask in an isolated context. The sub-agent returns only its final report. Spawn MULTIPLE subagents in the SAME response for parallel work—they run concurrently.\n" +
+    "Use role='explore' for codebase search/analysis (read-only, fast), role='plan' for read-only implementation planning (returns a step-by-step plan, never edits), role='coder' for self-contained implementation tasks. Do not give parallel subagents tasks that edit the same files.\n\n" +
+    "Writing the prompt:\n" +
+    "- The sub-agent starts with zero context — it has not seen this conversation. Brief it like a colleague who just walked into the room: state the goal, list what you already know, hand over the specifics.\n" +
+    "- Put exact paths and commands in the prompt when you know them. The sub-agent should not search for things you already know.\n" +
+    "- Do not delegate understanding: if the task hinges on a file path or line number, find it yourself first and write it into the prompt.\n" +
+    "- Once a sub-agent is running, leave that scope to it: don't redo its searches in parallel, and don't abandon it midway to finish manually.",
   parameters: {
     type: "object",
     properties: {

package/src/agent-tools/timer.mjs

@@ -29,7 +29,7 @@ export const timerTool = {
   readonly: true,
   sideEffectExempt: true,
   execute(args, ctx) {
-    const seconds = args.seconds ?? 30
+    const seconds = args.seconds ?? 180
     const expiresAt = Date.now() + seconds * 1000
     const message = args.message || `⏰ Time's up (${seconds}s). Have you tried running the code, adding a console.log, or checking the output? Thinking more without data is guessing.`