@davait/aipictury 1.9.2

package/ext/agent.js

@@ -0,0 +1,1929 @@
+'use strict'
+// The agent loop: ask the server for the model's next move, carry it out, ask again.
+//
+// The server never sees the workspace. It is given the conversation and the shape of
+// the tools, and answers with text and tool calls; everything those calls do happens
+// here, under the approval rules the user set.
+
+const os = require('os')
+const vscode = require('vscode')
+const { toolSchema, normalizeQuestions, normalizeFindings, IMPLEMENTATIONS, WRITES, RUNS, resolve } = require('./tools')
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+const files = require('./files')
+const shell = require('./shell')
+const mcp = require('./mcp')
+const context = require('./context')
+const { safeSlice } = require('./text')
+const { runCommand, stopBackground, plain, commandEnv } = shell
+const { summarize, hunks, applyHunks } = require('./diff')
+const mediagen = require('./mediagen')
+const memory = require('./memory')
+const deps = require('./deps')
+const workbench = require('./workbench')
+const permissions = require('./permissions')
+const userHooks = require('./hooks')
+const sandboxing = require('./sandbox')
+const tasklist = require('./tasklist')
+const workflows = require('./workflow')
+const browserTool = require('./browser')
+const scheduler = require('./scheduler')
+const worktrees = require('./worktree')
+const notebooks = require('./notebook')
+const prefs = require('./prefs')
+const log = require('./log')
+const { root: workspaceRoot } = require('./paths')
+
+// A local model answers slowly but steadily. What must never happen is waiting for
+// ever: the connection is given a while to open, and then the stream has its own
+// deadline. The server sends a "still waiting" event every 10s while the model is quiet
+// (reading a long prompt, or composing a tool call, which Ollama holds back until it is
+// whole — five silent minutes for a large file). So silence on the wire means the link
+// is gone, never that the model is slow, and it can be short.
+const OPEN_TIMEOUT = 90_000
+const STALL_TIMEOUT = 90_000
+// A server that sends "still waiting" without saying for how long (an older one) is held
+// to this, in seconds.
+const QUIET_LIMIT = 30 * 60
+
+/** An error the run can recover from by asking again: a dropped link, a busy GPU. */
+function failure(message, { transient = false, busy = false } = {}) {
+  const error = new Error(message)
+  error.transient = transient || busy
+  error.busy = busy
+  return error
+}
+
+/** Rejects if the promise has not settled in time, naming what was being waited for. */
+function withDeadline(promise, ms, what) {
+  let timer
+  const limit = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(failure(
+      `the connection to the server was lost while ${what} (nothing for ${Math.round(ms / 1000)}s)`,
+      { transient: true })), ms)
+  })
+  return Promise.race([promise, limit]).finally(() => clearTimeout(timer))
+}
+
+// The permission modes shown beside Send. Stored in aipictury.approval.
+const MODES = {
+  ask:   { label: 'Manual', icon: '\u270B',
+           hint: 'Asks before every file change and command.' },
+  edits: { label: 'Edit Automatically', icon: '\u270E',
+           hint: 'Applies file edits without asking; still asks before running commands.' },
+  plan:  { label: 'Plan', icon: '\u25F4',
+           hint: 'Read-only: investigates and proposes a plan, changes nothing.' },
+  never: { label: 'Auto', icon: '\u26A1',
+           hint: 'Goes ahead with routine work; asks before anything risky — judged by fixed rules and the model.' },
+  bypass: { label: 'Bypass permissions', icon: '\u26A0',
+            hint: 'Does everything without asking, with no checks at all. Only with aipictury.allowDangerouslySkipPermissions.' },
+}
+
+/** The mode in force. Bypass needs its own setting: without it, it is Auto. */
+function modeNow() {
+  const config = vscode.workspace.getConfiguration('aipictury')
+  const mode = config.get('approval', 'ask')
+  return mode === 'bypass' && !config.get('allowDangerouslySkipPermissions', false) ? 'never' : mode
+}
+const unattended = (mode) => mode === 'never' || mode === 'bypass'
+
+const PLAN_NOTE = `
+
+You are in PLAN mode. You may only read and search the workspace — files cannot be
+changed, and only read-only commands run (ls, cat, git status/log/diff, grep…).
+Investigate what the user asked about, then write a concise plan: the goal, which files
+change and how, the order, and anything you are unsure about. Describe the code, do not
+write it out in full. When the plan is ready, present it with exit_plan_mode: the user
+approves it (and you may then make the changes) or asks for changes to it.`
+
+const AUTO_NOTE = `
+
+You are in AUTO mode: the user is not approving each step. Still call ask_user whenever
+you choose between real options — it keeps a record of the choice. Unless you mark the
+call important, your recommended (first) option is taken at once, you carry on without
+waiting, and the user can change it when you finish. Mark important only a decision that
+would be costly to undo.`
+
+const SYSTEM = `You are AIPictury's coding agent, working inside the user's editor on
+their own machine. You can read and change the workspace with the tools provided.
+
+How to work:
+- Look before you act. Find things with grep (contents) and glob (file names); ask
+  code_intel where a symbol is defined or used; read the file you are about to change;
+  check the reported problems when fixing a bug. For a broad search across the codebase,
+  hand it to a helper with task (subagent_type "explore") so your context stays small.
+- Make the change with edit_file when the file already exists, quoting enough context
+  that old_text appears exactly once (or replace_all). Use write_file for a new file, or
+  a rewrite. After a change, the editor's new errors in that file come back with the
+  result: fix them.
+- Use the file tools for files — never cat, sed, awk or echo in run_command to read,
+  search or edit them. run_command is for tests, builds, git, installs and servers
+  (run_in_background for servers and watchers).
+- Change what was asked for and what that change requires — nothing else.
+- For a task of three or more steps, keep a to-do list with todo_write.
+- Make pictures and video with generate_media when the user wants an image, photo,
+  illustration, icon, background or clip. To replace one the code uses, find it first
+  (search, read the component), then save_to that same path: it keeps the size and
+  format. To change an existing picture, pass it as source. Describe what to draw in
+  full — subject, setting, light, style, composition — never a bare label.
+- Research online when the task needs current or external facts: web_search to find
+  pages, fetch_url to read one. Bring what you learn back into your answer, and cite the
+  page you took it from inline, as a Markdown link: [Node.js releases](https://nodejs.org/…).
+- When you are done, say in a few lines what you changed and what the user should check.
+  Do not paste the whole file back: they can see the diff in their editor.
+
+When a decision belongs to the user — which library or stack, the scope, naming or
+structure they will live with, a real trade-off between options, anything costly to
+undo — do not settle it in your reasoning: ask with ask_user. Give 2 to 4 concrete
+options, your recommended one first with " (Recommended)" at the end of its label, each
+with a one-line description of what it means. The user can always write their own
+answer. Ask related decisions together (up to 4 in one call), before you start the work
+they shape. Do not ask about what you can find out by reading the code, or small choices
+with an obvious answer.
+In particular: before you install a package, or pick a library, framework, database,
+provider, service or platform the user did not name and the project does not already
+use, ask — look at the project first (package.json, the code), then ask with what you
+found in mind. Installing something they did not choose is costly to undo. Where data is
+kept (in memory, a file, a database) and which platform or provider to deploy to, store
+files with or pay through are theirs to choose too. Look first — a few reads at most —
+then ask; do not keep exploring for an answer that only they can give.
+
+When the user states something to keep — a rule, a preference, a convention, anything
+said with "remember", "always", "never", "from now on", "recordá", "regla", "siempre",
+"nunca", "de ahora en más" — save it with the remember tool before carrying on: scope
+"project" for this codebase, "user" for how they like to work everywhere. The rules
+already saved are listed at the end of these instructions; follow them.
+
+Put code in the tool call, not in your reply and not in your reasoning. Showing the
+user a block of code is not the same as changing their file, and only the tool call
+changes anything.
+
+Your answers are rendered as Markdown: fenced code blocks tagged with their language,
+tables where they help, and \`backticks\` for paths and identifiers. Keep prose short —
+this is a side panel, not an essay.`
+
+/** One streamed turn from the server. Returns what the model said and wants done. */
+async function turn(server, messages, { role = 'agent', tools, model, think = true, effort, signal, onDelta, onThinking,
+                                          onWaiting, onSpeed, watchReasoning = false, watchLoops = false, steer,
+                                          thinkBudget = 0 } = {}) {
+  const sent = compact(messages)
+  // Our own switch for cutting the reasoning short, tied to the caller's Stop as well.
+  const cut = new AbortController()
+  const onStop = () => cut.abort()
+  signal?.addEventListener('abort', onStop, { once: true })
+  // The user said something mid-generation: this answer is cut so the next one hears it.
+  let interrupted = false
+  const onSteer = () => { interrupted = true; cut.abort() }
+  if (steer?.aborted) onSteer()
+  steer?.addEventListener('abort', onSteer, { once: true })
+  const body = { messages: sent, tools: tools || toolSchema(), role, think }
+  if (effort) body.effort = effort
+  if (model) body.model = model            // the picker's choice overrides the role default
+  const stopped = () => { const stop = new Error('stopped'); stop.name = 'AbortError'; return stop }
+  let response
+  try {
+    response = await withDeadline(
+      fetch(`${server}/api/agent/turn`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: cut.signal,
+      }), OPEN_TIMEOUT, 'opening the connection')
+  } catch (error) {
+    cut.abort()
+    signal?.removeEventListener('abort', onStop)
+    steer?.removeEventListener('abort', onSteer)
+    if (signal?.aborted) throw stopped()
+    if (interrupted) return { text: '', thinking: '', calls: [], meta: {}, interrupted: true }
+    if (error.transient) throw error
+    // fetch itself failed: the server is restarting, or the Wi-Fi link blinked.
+    throw failure(`the server could not be reached (${error.cause?.code || error.message})`,
+      { transient: true })
+  }
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    signal?.removeEventListener('abort', onStop)
+    // 409 is the one the user meets in practice: a render already holds the GPU.
+    if (response.status === 409) {
+      throw failure('a generation is using the GPU right now, so the agent waits for it '
+        + 'to finish', { busy: true })
+    }
+    throw failure(`the server answered ${response.status}: ${detail.slice(0, 300)}`,
+      { transient: response.status >= 500 || response.status === 429 })
+  }
+
+  const reader = response.body.getReader()
+  const decode = new TextDecoder()
+  let buffer = ''
+  let text = ''
+  let thinking = ''
+  let calls = []
+  let meta = {}
+
+  let overthought = false
+  let looped = false
+  let checkedAt = 0                          // reasoning length at the last loop check
+  for (;;) {
+    let chunk
+    try {
+      chunk = await withDeadline(reader.read(), STALL_TIMEOUT, 'answering')
+    } catch (error) {
+      if (overthought || looped || interrupted) break       // we cut it ourselves
+      // Close our end, so the server stops the generation instead of finishing a
+      // turn nobody will read while the retry waits behind it for the GPU.
+      cut.abort()
+      signal?.removeEventListener('abort', onStop)
+      if (signal?.aborted) throw stopped()
+      if (error.transient) throw error
+      throw failure(`the connection to the server broke while answering (${error.message})`,
+        { transient: true })
+    }
+    const { done, value } = chunk
+    if (done) break
+    buffer += decode.decode(value, { stream: true })
+    const lines = buffer.split('\n')
+    buffer = lines.pop()
+    for (const line of lines) {
+      if (!line.trim()) continue
+      let event
+      try { event = JSON.parse(line) } catch { continue }
+      if (event.delta) { text += event.delta; onDelta?.(event.delta) }
+      if (event.thinking) { thinking += event.thinking; onThinking?.(event.thinking) }
+      if (event.tool_calls) calls = event.tool_calls
+      if (event.waiting) {
+        onWaiting?.(event)
+        // The server says how long it will wait before giving up; its "still waiting" events
+        // keep the stream alive, so this is what stops a wait that outlives that promise.
+        if ((event.silent ?? event.waiting) > (event.limit || QUIET_LIMIT) + 30) {
+          cut.abort()
+          signal?.removeEventListener('abort', onStop)
+          throw failure(`the model made no progress for ${Math.round(event.waiting / 60)} minutes`, { transient: true })
+        }
+      }
+      if (event.speed) onSpeed?.(event.speed)
+      if (event.done || event.error) meta = event
+      // The effort chosen caps the reasoning: past its budget, the reasoning is cut and the
+      // model acts on what it worked out, as with a loop.
+      if (thinkBudget && !looped && !overthought && !text && !calls.length && thinking.length > thinkBudget) {
+        looped = true
+        cut.abort()
+      }
+      if (watchReasoning && !overthought && !text && !calls.length && overthinking(thinking)) {
+        overthought = true
+        cut.abort()                          // stop spending minutes on a draft
+      }
+      // Checked every ~1,500 characters rather than per token: the check reads the
+      // whole reasoning, and a loop is only visible after a few paragraphs anyway.
+      if (watchLoops && !overthought && !looped && !text && !calls.length
+          && thinking.length - checkedAt >= 1_500) {
+        checkedAt = thinking.length
+        if (thinkingLoops(thinking)) {
+          // Going round in circles. When what repeats is a code draft, the fitting
+          // instruction is the draft one — write the files — not "act on your notes".
+          if (watchReasoning && (CODE_BLOCK.test(thinking) || looksLikeCode(thinking))) overthought = true
+          else looped = true
+          cut.abort()
+        }
+      }
+    }
+    if (overthought || looped || interrupted) break
+  }
+  signal?.removeEventListener('abort', onStop)
+  steer?.removeEventListener('abort', onSteer)
+  if (signal?.aborted) throw stopped()
+  if (overthought) return { text: '', thinking, calls: [], meta: {}, overthought: true }
+  if (looped) return { text: '', thinking, calls: [], meta: {}, looped: true, budget: thinkBudget && thinking.length > thinkBudget }
+  if (interrupted) return { text, thinking, calls: [], meta: {}, interrupted: true }
+  // An error the server reported mid-stream (the model stopped early, Ollama failed):
+  // the turn is incomplete, and asking again is the fix.
+  if (meta.error) throw failure(meta.error, { transient: true })
+  calibrate(size(sent), meta.context_used)
+  if (meta.context_window) setWindow(meta.context_window)
+  return { text, thinking, calls, meta }
+}
+
+/** Asks the user about a change or a command, unless their settings already answered.
+ *  Asked in the panel — the change shown hunk by hunk, each accepted or rejected, or the
+ *  whole of it; "no" can say what to do instead — as Claude Code asks in its chat, not in
+ *  a dialog that hides the editor. Without a panel (tests, a closed view) a dialog asks.
+ *  Returns { ok, all, feedback, content } — content when only part of a change was kept
+ *  or the user edited the proposal. */
+async function approve(call, session, signal, hooks = {}, preview = null, { force = false, because = null, server = '' } = {}) {
+  const mode = modeNow()
+  const name = call.function.name
+  const args = call.function.arguments || {}
+  const isRun = RUNS.has(name) || mcp.isMcp(name) || name === 'browser'
+  if (mode === 'plan' && WRITES.has(name)) return { ok: false }     // plan mode changes nothing
+  // An "ask" rule asks whatever the mode and any earlier yes: that is what it is for.
+  if (!force) {
+    if (mode === 'bypass') return { ok: true }
+    if (mode === 'never') {
+      // Auto: edits inside the workspace go ahead (a checkpoint can undo them); anything else
+      // is judged — fixed rules, routine work, then the model — and asked when it is risky.
+      if (WRITES.has(name)) return { ok: true }
+      const verdict = await judge(call, session, signal, hooks, server)
+      if (verdict.verdict === 'allow') return { ok: true, judged: verdict }
+      because = `Auto mode asks: ${verdict.reason || 'it could not tell whether this is safe'}`
+    }
+    if (mode === 'edits' && !isRun) return { ok: true }
+    if (session.allowAll) return { ok: true }
+    if (RUNS.has(name) && session.allowCommands?.some((p) => String(args.command || '').trim().startsWith(p))) return { ok: true }
+  }
+
+  if (hooks.approve) {
+    const prefix = RUNS.has(name) ? commandPrefix(args.command) : undefined
+    const request = RUNS.has(name)
+      ? { kind: 'command', command: String(args.command || ''), description: args.description || '', prefix }
+      : mcp.isMcp(name) ? { kind: 'mcp', tool: name, args }
+        : WRITES.has(name) ? { kind: 'edit', path: args.path, tool: name, before: preview?.before ?? null, after: preview?.after ?? null,
+          hunks: preview ? hunks(preview.before ?? '', preview.after ?? '') : [] }
+          : { kind: 'tool', tool: name, args }
+    // A standing yes for a command, an MCP tool or another tool can be kept beyond this
+    // conversation: the rule it would save is shown, and where to save it is chosen.
+    if (request.kind !== 'edit') { request.rule = permissions.ruleFor(name, args, prefix); request.destinations = permissions.DESTINATIONS }
+    if (name === 'browser') {
+      request.site = browserTool.hostOf(args.page || '')
+      if (!because) because = `the browser would ${browserTool.describe(args)} on ${request.site || 'a page'}`
+    }
+    if (because) request.because = because
+    const answer = await Promise.race([hooks.approve(request, signal), stopped(signal)])
+    if (answer === STOPPED || !answer) return { ok: false }
+    if (answer.decision === 'allow_all') {
+      const where = answer.destination || 'conversation'
+      if (where !== 'conversation' && request.rule) {
+        // Not saved is said, not swallowed: the yes still counts for this conversation.
+        try { permissions.remember(folderPath(), where, request.rule) } catch (error) {
+          log.warn(`could not save the rule ${request.rule}`, error)
+          vscode.window.showWarningMessage(`AIPictury could not save the rule ${request.rule}: ${error.message}. It applies to this conversation only.`)
+          if (RUNS.has(name) && answer.prefix) (session.allowCommands ||= []).push(answer.prefix)
+          else if (name === 'browser') (session.allowSites ||= []).push(request.site)
+          else (session.allowTools ||= []).push(name)
+        }
+      } else if (name === 'browser') (session.allowSites ||= []).push(request.site)
+      else if (RUNS.has(name) && answer.prefix) (session.allowCommands ||= []).push(answer.prefix)
+      else if (mcp.isMcp(name) || request.kind === 'tool') (session.allowTools ||= []).push(name)
+      else session.allowAll = true
+    }
+    if (answer.decision === 'deny') return { ok: false, feedback: answer.feedback || '' }
+    let content
+    if (preview && Array.isArray(answer.keep) && answer.keep.length < request.hunks.length) {
+      content = applyHunks(preview.before ?? '', preview.after ?? '', new Set(answer.keep))
+    }
+    if (typeof answer.edited === 'string' && answer.edited !== preview?.after) content = answer.edited
+    return { ok: true, content, partial: Array.isArray(answer.keep) && answer.keep.length < request.hunks.length,
+             edited: typeof answer.edited === 'string' && answer.edited !== preview?.after }
+  }
+
+  const what = RUNS.has(name) ? `Run this command?\n\n${args.command}`
+    : mcp.isMcp(name) ? `Use ${name}?\n\n${JSON.stringify(args).slice(0, 400)}`
+      : `${name === 'write_file' ? 'Write' : 'Edit'} ${args.path}?`
+  // Stop has to work while a question is on screen, or the only way out is to answer it.
+  const asked = vscode.window.showWarningMessage(what, { modal: true },
+    'Allow', 'Allow for this conversation', ...(isRun ? [] : ['Show diff first']))
+  const choice = await Promise.race([asked, stopped(signal)])
+  if (choice === STOPPED) return { ok: false }
+  if (choice === 'Show diff first') {
+    await showDiff(args.path, preview)
+    const second = await Promise.race([vscode.window.showWarningMessage(`Apply the change to ${args.path}?`,
+      { modal: true }, 'Allow', 'Allow for this conversation'), stopped(signal)])
+    if (second === STOPPED) return { ok: false }
+    if (second === 'Allow for this conversation') { session.allowAll = true; return { ok: true } }
+    return { ok: second === 'Allow' }
+  }
+  if (choice === 'Allow for this conversation') { session.allowAll = true; return { ok: true } }
+  return { ok: choice === 'Allow' }
+}
+
+/** Auto mode's judgement of one call, from the server — remembered for the conversation, so
+ *  the same command is judged once. Anything that goes wrong is an "ask". */
+async function judge(call, session, signal, hooks, server) {
+  const name = call.function.name
+  const args = call.function.arguments || {}
+  const key = JSON.stringify([name, args])
+  const cache = (session.judged ||= new Map())
+  if (cache.has(key)) return cache.get(key)
+  if (!server) return { verdict: 'ask', reason: 'no server to judge it' }
+  const controller = new AbortController()
+  const stop = () => controller.abort()
+  signal?.addEventListener('abort', stop, { once: true })
+  const timer = setTimeout(stop, 45_000)
+  try {
+    const response = await fetch(`${server}/api/agent/classify`, { method: 'POST', signal: controller.signal,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ tool: name, args, request: String(hooks.userSaid?.() || '').slice(-1500),
+        root: folderPath(), model: hooks.model || undefined }) })
+    if (!response.ok) return { verdict: 'ask', reason: `the judge answered ${response.status}` }
+    const verdict = await response.json()
+    log.info(`Auto mode: ${verdict.verdict} ${name} (${verdict.by}: ${verdict.reason})`)
+    if (verdict.by !== 'error') cache.set(key, verdict)
+    return verdict
+  } catch (error) {
+    return { verdict: 'ask', reason: signal?.aborted ? 'stopped' : `it could not be judged (${error.message})` }
+  } finally {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', stop)
+  }
+}
+
+/** How a command runs with the sandbox settings: { run } sandboxed, { outside } left out of it
+ *  (excluded, or asked for), { unavailable } on a machine without one, or null with it off.
+ *  A setting made in VS Code wins over the settings files' "sandbox". */
+function sandboxFor(args, folder) {
+  const config = vscode.workspace.getConfiguration('aipictury')
+  const set = (key) => { const i = config.inspect(`sandbox.${key}`); return i?.workspaceValue ?? i?.globalValue }
+  const s = sandboxing.settings(prefs.load(folder).merged.sandbox, { enabled: set('enabled'), allowNetwork: set('allowNetwork'),
+    autoAllow: set('autoAllow'), excludedCommands: set('excludedCommands'), writablePaths: set('writablePaths') })
+  if (!s.enabled) return null
+  if (args.outside_sandbox || sandboxing.excluded(args.command, s.excluded)) return { s, outside: true, asked: !!args.outside_sandbox }
+  if (!sandboxing.available()) return { s, unavailable: true }
+  return { s, run: { root: folder, writable: s.writable, network: s.allowNetwork } }
+}
+
+/** The workspace folder, for rules written relative to it — or none, with no folder open. */
+function folderPath() { try { return workspaceRoot().fsPath } catch { return undefined } }
+
+// Tools that steer the conversation itself: no rule applies to them.
+const CONTROL = new Set(['ask_user', 'exit_plan_mode', 'enter_plan_mode', 'todo_write'])
+
+/** The part of a command a standing yes covers: its program and, for tools with verbs
+ *  (git, npm, cargo…), the verb — "npm test", "git status" — never the arguments. */
+function commandPrefix(command) {
+  const words = String(command || '').trim().split(/\s+/)
+  const verbs = /^(git|npm|pnpm|yarn|bun|npx|cargo|go|pip|pip3|python|python3|node|docker|make|uv|poetry|dotnet|mvn|gradle|kubectl)$/
+  return words.slice(0, verbs.test(words[0]) && words[1] && !words[1].startsWith('-') ? 2 : 1).join(' ')
+}
+
+// A sentinel for "the user pressed stop while this was being asked".
+const STOPPED = Symbol('stopped')
+
+/** Resolves if and when the run is aborted. */
+function stopped(signal) {
+  if (!signal) return new Promise(() => {})
+  if (signal.aborted) return Promise.resolve(STOPPED)
+  return new Promise((resolve) =>
+    signal.addEventListener('abort', () => resolve(STOPPED), { once: true }))
+}
+
+/** What a write or an edit would make of a file, without making it. */
+async function previewChange(call, session) {
+  const name = call.function.name
+  const args = call.function.arguments || {}
+  if (!['write_file', 'edit_file'].includes(name)) return null
+  const uri = resolve(args.path)
+  let raw = null
+  try { raw = decoder.decode(await vscode.workspace.fs.readFile(uri)) } catch { /* a new file */ }
+  const before = raw === null ? null : files.parseText(raw).text
+  if (name === 'write_file') return { before, after: String(args.content ?? '').replace(/\r\n/g, '\n') }
+  if (before === null) return null
+  await files.checkFresh(session, uri, args.path)
+  const edits = Array.isArray(args.edits) && args.edits.length ? args.edits
+    : [{ old_text: args.old_text, new_text: args.new_text, replace_all: args.replace_all }]
+  let text = before
+  for (const [i, e] of edits.entries()) {
+    text = files.replaceOnce(text, e.old_text, e.new_text, !!e.replace_all, edits.length > 1 ? `edit ${i + 1}: ` : '').text
+  }
+  return { before, after: text }
+}
+
+/** Shows what a write would do, against what is on disk, in VS Code's diff. */
+async function showDiff(relPath, preview) {
+  if (!preview) return
+  const uri = resolve(relPath)
+  const proposed = uri.with({ scheme: 'aipictury-proposed', query: String(Date.now()) })
+  proposedContents.set(proposed.toString(), preview.after)
+  await vscode.commands.executeCommand('vscode.diff', uri, proposed, `${relPath} — proposed by AIPictury`, { preview: true })
+}
+
+// What a file held before the agent changed it, for VS Code's side-by-side diff. In
+// memory only, and only the most recent few — it is a convenience, not a history.
+const befores = new Map()
+function rememberBefore(path, text) {
+  const key = `${Date.now().toString(36)}-${befores.size}`
+  befores.set(key, { path, text })
+  while (befores.size > 50) befores.delete(befores.keys().next().value)
+  return key
+}
+
+/** Opens VS Code's own side-by-side diff: what the file was, against what it is now. */
+async function openSideBySide(key) {
+  const entry = befores.get(key)
+  if (!entry) {
+    vscode.window.showInformationMessage('That earlier version is no longer in memory; '
+      + 'the change is still shown in the panel.')
+    return
+  }
+  const current = resolve(entry.path)
+  const was = current.with({ scheme: 'aipictury-proposed', query: `before-${key}` })
+  proposedContents.set(was.toString(), entry.text)
+  await vscode.commands.executeCommand('vscode.diff', was, current,
+    `${entry.path} — before ↔ after`, { preview: true })
+}
+
+// Backing store for the proposed side of a diff.
+const proposedContents = new Map()
+const proposedProvider = {
+  provideTextDocumentContent(uri) { return proposedContents.get(uri.toString()) ?? '' },
+}
+
+/** The model's question, answered. Blocks on the panel's chooser — except in Auto mode,
+ *  where a question not marked important takes the recommended options at once and is
+ *  kept as a decision the user can change when the run ends. */
+async function askUser(args, report, signal, hooks) {
+  let questions
+  try {
+    questions = normalizeQuestions(args)
+  } catch (error) {
+    report({ tool: 'ask_user', args, status: 'failed', result: error.message })
+    return `error: ${error.message}`
+  }
+  const mode = modeNow()
+  const recommended = (q) => q.options[0].label.replace(/\s*\(recommended\)\s*$/i, '')
+  if ((unattended(mode) && !args.important) || !hooks.askUser) {
+    const picks = questions.map((q) => ({ ...q, picked: [q.options[0].label], other: '' }))
+    hooks.onDecision?.(picks)
+    report({ tool: 'ask_user', args: { questions }, status: 'decided', result: picks })
+    return 'Auto mode: the user is not asked now. Proceed with your recommended option'
+      + `${picks.length > 1 ? 's' : ''}: ${questions.map((q) => `${q.header} → ${recommended(q)}`).join('; ')}. `
+      + 'The user can change these when you finish.'
+  }
+  report({ tool: 'ask_user', args: { questions }, status: 'asking-user' })
+  const answer = await hooks.askUser(questions, signal)
+  if (!answer) {                                          // Stop, while the question was open
+    report({ tool: 'ask_user', args: { questions }, status: 'refused' })
+    return 'stopped by the user before answering'
+  }
+  if (answer.dismissed) {
+    report({ tool: 'ask_user', args: { questions }, status: 'dismissed' })
+    return 'The user closed the question without answering. Use your best judgement, and say '
+      + 'in your answer what you chose so they can change it.'
+  }
+  report({ tool: 'ask_user', args: { questions }, status: 'answered', result: answer.answers })
+  const lines = answer.answers.map((a) => {
+    const chosen = [...(a.picked || []), ...(a.other ? [`their own answer: "${a.other}"`] : [])]
+    return `- ${a.header} (${a.question}): ${chosen.join(', ') || 'no answer'}`
+  })
+  return `The user answered:\n${lines.join('\n')}\nCarry on with these.`
+}
+
+/** A picture or clip made on the server and written into the workspace. */
+async function makeMedia(call, session, report, signal, server, hooks = {}) {
+  const args = call.function.arguments || {}
+  const mode = modeNow()
+  if (mode === 'plan') {
+    report({ tool: 'generate_media', args, status: 'plan' })
+    return 'Plan mode: nothing was generated. Describe the picture in your plan instead.'
+  }
+  // Writing a file needs the same yes as any write: asked for in Manual only.
+  const ask = async (question) => {
+    if (unattended(mode) || mode === 'edits' || session.allowAll) return true
+    report({ tool: 'generate_media', args, status: 'asking' })
+    if (hooks.approve) {
+      const answer = await Promise.race([hooks.approve({ kind: 'media', question, path: args.save_to }, signal), stopped(signal)])
+      if (answer === STOPPED || !answer || answer.decision === 'deny') return false
+      if (answer.decision === 'allow_all') session.allowAll = true
+      return true
+    }
+    const choice = await Promise.race([
+      vscode.window.showWarningMessage(question, { modal: true }, 'Allow', 'Allow for this conversation'),
+      stopped(signal)])
+    if (choice === 'Allow for this conversation') { session.allowAll = true; return true }
+    return choice === 'Allow'
+  }
+  try {
+    const result = await mediagen.generate(server, args, {
+      ask, signal, report: (update) => report({ tool: 'generate_media', args, ...update }) })
+    if (result.refused) report({ tool: 'generate_media', args, status: 'refused' })
+    return result.text
+  } catch (error) {
+    if (error.name === 'AbortError' || signal?.aborted) return 'stopped by the user'
+    report({ tool: 'generate_media', args, status: 'failed', result: error.message })
+    return `error: ${error.message}`
+  }
+}
+
+/** The to-do list the model keeps, cleaned: at most 30 items, a known status each. */
+function normalizeTodos(todos) {
+  let list = todos
+  if (typeof list === 'string') { try { list = JSON.parse(list) } catch { list = [] } }
+  if (!Array.isArray(list)) throw new Error('todos must be a list of { content, status }')
+  const out = list.slice(0, 30).map((t) => ({
+    content: String(t?.content || t?.task || '').trim(),
+    status: ['pending', 'in_progress', 'completed'].includes(t?.status) ? t.status : 'pending',
+    activeForm: String(t?.activeForm || t?.active_form || '').trim(),
+  })).filter((t) => t.content)
+  if (!out.length) throw new Error('todos is empty — give at least one item')
+  return out
+}
+
+/** Carries out one tool call and returns what goes back to the model: text, or
+ *  { text, images } when there is a picture for it to see. */
+/** The hooks' context for this conversation: where, who, and how to ask for trust. */
+const hookContext = (session, signal, hooks, subject) => ({ folder: folderPath(), subject, sessionId: session?.id || '',
+  trust: hooks.trustHooks, signal, log: (line) => log.warn(line) })
+
+/** One tool call, with the user's PreToolUse and PostToolUse hooks around it. */
+async function execute(call, session, report, signal, server, hooks = {}) {
+  const name = call.function.name
+  let args = call.function.arguments || {}
+  if (typeof args === 'string') { try { args = JSON.parse(args) } catch { args = {} } }
+  const folder = folderPath()
+  const ctx = hookContext(session, signal, hooks, name)
+  const asClaude = { tool_name: userHooks.claudeName(name), tool_input: userHooks.toolInput(name, args, folder) }
+  const pre = await userHooks.fire('PreToolUse', asClaude, ctx)
+  if (pre.stop) {
+    session.hookStop = pre.stopReason || 'a hook stopped the run'
+    report({ tool: name, args, status: 'refused', result: `stopped by a hook: ${session.hookStop}` })
+    return `Stopped by a hook: ${session.hookStop}`
+  }
+  if (pre.block || pre.permission === 'deny') {
+    const why = [...pre.reasons, ...pre.permissionReasons].filter(Boolean).join('; ') || 'no reason given'
+    report({ tool: name, args, status: 'refused', result: `blocked by a hook: ${why}` })
+    return `A PreToolUse hook blocked this: ${why}. Do not try to reach the same result another way; `
+      + 'if it matters, say in your reply what you could not do and why.'
+  }
+  const result = await executeTool(call, session, report, signal, server,
+    pre.permission ? { ...hooks, hookPermission: pre.permission, hookReason: pre.permissionReasons.filter(Boolean).join('; ') } : hooks)
+  const text = typeof result === 'object' ? result.text : result
+  const post = await userHooks.fire('PostToolUse', { ...asClaude, tool_response: String(text ?? '').slice(0, 20_000) }, ctx)
+  if (post.stop) session.hookStop = post.stopReason || 'a hook stopped the run'
+  const notes = [...(post.block ? post.reasons : []), ...post.context]
+  if (!notes.length) return result
+  const added = `\n\n[A PostToolUse hook says: ${notes.join('\n')}]`
+  return typeof result === 'object' ? { ...result, text: `${result.text}${added}` } : `${result}${added}`
+}
+
+// The tools that take a path: in a worktree, their paths are the worktree's.
+const PATH_TOOLS = new Set(['read_file', 'write_file', 'edit_file', 'notebook_edit', 'list_files', 'grep', 'glob', 'code_intel', 'search'])
+
+async function executeTool(call, session, report, signal, server, hooks = {}) {
+  const name = call.function.name
+  let args = call.function.arguments || {}
+  if (typeof args === 'string') { try { args = JSON.parse(args) } catch { args = {} } }
+  if (session.worktree && PATH_TOOLS.has(name)) args = { ...args, path: worktrees.inside(session.worktree, args.path) }
+  // The browser: the site a call goes to or acts on — for the rules, the question and the judge.
+  if (name === 'browser') args = { ...args, page: browserTool.targetUrl(args) || undefined }
+  const mode = modeNow()
+  const planning = mode === 'plan'
+  const ctx = { session, signal, readSpecial: hooks.readSpecial }
+  const fail = (error) => {
+    report({ tool: name, args, status: 'failed', result: error.message })
+    return `error: ${error.message}`
+  }
+  // The permission rules of the settings files: a deny stops the call here, whatever the mode.
+  const rule = CONTROL.has(name) ? { decision: null } : permissions.decide(name, args, { folder: folderPath(), extraAllow: session.commandAllow, extraDeny: session.commandDeny })
+  if (rule.decision === 'deny') {
+    const where = rule.file ? ` (${rule.level} settings, ${rule.file.replace(os.homedir(), '~')})` : ''
+    report({ tool: name, args, status: 'refused', result: `denied by ${rule.rule}` })
+    return `Denied by the permission rule ${rule.rule}${where}. Do not try to reach the same result another way; `
+      + 'if it matters, say in your reply what you could not do and why.'
+  }
+  if (name === 'ask_user') return askUser(args, report, signal, hooks)
+  if (name === 'generate_media') return makeMedia(call, session, report, signal, server, hooks)
+
+  if (name === 'remember') {
+    report({ tool: name, args, status: 'running' })
+    try {
+      const rule = String(args.rule || '').trim()
+      if (!rule) throw new Error('rule is required')
+      const result = args.scope === 'user' ? await memory.addUserRule(server, rule) : await memory.addProjectRule(rule)
+      report({ tool: name, args, status: 'done', result })
+      return result
+    } catch (error) { return fail(error) }
+  }
+
+  if (name === 'todo_write') {
+    try {
+      const todos = normalizeTodos(args.todos)
+      session.todos = todos
+      hooks.onTodos?.(todos)
+      report({ tool: name, args: { todos }, status: 'done', todos })
+      const doing = todos.find((t) => t.status === 'in_progress')
+      return `To-do list saved (${todos.filter((t) => t.status === 'completed').length}/${todos.length} done`
+        + `${doing ? `; now: ${doing.content}` : ''}). Keep it up to date as you go.`
+    } catch (error) { return fail(error) }
+  }
+
+  // A git worktree for this conversation: changes away from the user's checkout.
+  if (name === 'enter_worktree' || name === 'exit_worktree') {
+    try {
+      const base = folderPath()
+      let text
+      if (name === 'enter_worktree') {
+        if (session.worktree) throw new Error(`already in the worktree ${session.worktree.name} — exit_worktree first`)
+        session.worktree = await worktrees.enter(base, args.name)
+        session.cwd = session.worktree.path
+        text = `Working in the worktree ${session.worktree.relative} on the branch ${session.worktree.branch}. Paths are now relative to it, and commands run in it.`
+      } else {
+        if (!session.worktree) throw new Error('not in a worktree')
+        const wt = session.worktree
+        const done = await worktrees.exit(base, wt, { action: args.action === 'remove' ? 'remove' : 'keep', discard: !!args.discard_changes })
+        delete session.worktree
+        session.cwd = base
+        text = done.kept ? `Left the worktree. It is kept at ${wt.relative} on ${wt.branch} (${done.commits} commit(s), ${done.dirty.length} uncommitted change(s)) — tell the user, so they can merge it.`
+          : 'Left the worktree and removed it.'
+      }
+      report({ tool: name, args, status: 'done', result: text })
+      return text
+    } catch (error) { return fail(error) }
+  }
+
+  // This conversation's schedule: cron prompts and wake-ups.
+  if (['cron_create', 'cron_list', 'cron_delete', 'schedule_wakeup'].includes(name)) {
+    try {
+      if (!hooks.schedule) throw new Error('scheduling is not available here')
+      const jobs = hooks.schedule.get()
+      let text
+      if (name === 'cron_list') text = jobs.length ? jobs.map((j) => scheduler.describe(j)).join('\n') : 'Nothing is scheduled.'
+      else if (name === 'cron_delete') {
+        if (!jobs.some((j) => j.id === args.id)) throw new Error(`no scheduled prompt ${args.id}`)
+        hooks.schedule.set(jobs.filter((j) => j.id !== args.id))
+        text = `${args.id} removed.`
+      } else {
+        const minutes = Number(args.delay_minutes)
+        if (name === 'schedule_wakeup' && !(minutes >= 1 && minutes <= 1440)) throw new Error('delay_minutes is 1 to 1440')
+        const j = name === 'schedule_wakeup'
+          ? scheduler.job(jobs, { schedule: `${Math.round(minutes)}m`, prompt: args.prompt, recurring: false, kind: 'wakeup' })
+          : scheduler.job(jobs, { schedule: args.schedule, prompt: args.prompt, recurring: args.recurring !== false })
+        hooks.schedule.set([...jobs, j])
+        text = `Scheduled as ${j.id}: ${scheduler.describe(j)}`
+      }
+      report({ tool: name, args, status: 'done', result: text })
+      return text
+    } catch (error) { return fail(error) }
+  }
+
+  // The task list with dependencies — the same list todo_write keeps.
+  if (['task_create', 'task_update', 'task_list', 'task_get'].includes(name)) {
+    try {
+      const list = tasklist.fromTodos(session.todos || [])
+      let text
+      if (name === 'task_list') text = tasklist.summary(list)
+      else if (name === 'task_get') text = tasklist.detail(list, args.taskId)
+      else {
+        const done = name === 'task_create' ? tasklist.create(list, args) : tasklist.update(list, args)
+        session.todos = done.list
+        hooks.onTodos?.(done.list)
+        text = name === 'task_create' ? `Task #${done.task.id} added${done.task.blockedBy.length ? `, waiting for ${done.task.blockedBy.map((i) => `#${i}`).join(', ')}` : ''}.`
+          : args.status === 'deleted' ? `Task #${done.task.id} deleted.`
+            : `Task #${done.task.id} is ${done.task.status}.${done.freed?.length ? ` Now free to start: ${done.freed.map((t) => `#${t.id} ${t.content}`).join(', ')}.` : ''}`
+      }
+      report({ tool: name, args, status: 'done', result: text, todos: session.todos })
+      return text
+    } catch (error) { return fail(error) }
+  }
+
+  if (name === 'exit_plan_mode') {
+    if (!planning) return 'You are not in plan mode — carry on with the task.'
+    const plan = String(args.plan || '').trim()
+    if (!plan) return fail(new Error('plan is required'))
+    report({ tool: name, args: { plan }, status: 'asking-user' })
+    const answer = hooks.approvePlan ? await Promise.race([hooks.approvePlan(plan, signal), stopped(signal)]) : null
+    if (answer === STOPPED || !answer) {
+      report({ tool: name, args: { plan }, status: 'refused' })
+      return 'The plan was not approved yet. Stop here: the user will reply.'
+    }
+    if (!answer.approved) {
+      report({ tool: name, args: { plan }, status: 'revise', result: answer.feedback || '' })
+      return `The user wants the plan changed${answer.feedback ? `: ${answer.feedback}` : ''}. Revise it and present it again with exit_plan_mode.`
+    }
+    await vscode.workspace.getConfiguration('aipictury').update('approval', answer.mode || 'edits', vscode.ConfigurationTarget.Global)
+    report({ tool: name, args: { plan }, status: 'approved', result: answer.mode })
+    const edited = answer.plan && answer.plan.trim() !== plan
+    return `The user approved the plan and switched you to ${MODES[answer.mode || 'edits']?.label || answer.mode} mode. `
+      + 'Carry it out now, step by step: you can change files and run commands.'
+      + (edited ? `\n\nThey edited the plan first — follow their version:\n\n${answer.plan.trim()}` : '')
+  }
+
+  if (name === 'enter_plan_mode') {
+    if (planning) return 'You are already in Plan mode: investigate, then present the plan with exit_plan_mode.'
+    const reason = String(args.reason || '').trim()
+    // Auto mode does not stop for this: the plan itself is still put to the user.
+    if (!unattended(mode)) {
+      report({ tool: name, args, status: 'asking' })
+      const answer = hooks.approve
+        ? await Promise.race([hooks.approve({ kind: 'plan-mode', reason }, signal), stopped(signal)]) : null
+      if (answer === STOPPED || !answer || answer.decision === 'deny') {
+        report({ tool: name, args, status: 'refused', result: answer?.feedback })
+        return answer?.feedback ? `The user does not want a plan first and said: ${answer.feedback}`
+          : 'The user does not want a plan first: go ahead with the task directly.'
+      }
+    }
+    await vscode.workspace.getConfiguration('aipictury').update('approval', 'plan', vscode.ConfigurationTarget.Global)
+    report({ tool: name, args, status: 'approved', result: 'plan' })
+    return 'You are in Plan mode now. Investigate with the read-only tools, then present your plan with '
+      + 'exit_plan_mode; nothing can be changed until the user approves it.'
+  }
+
+  if (name === 'push_notification') {
+    const message = String(args.message || '').trim()
+    if (!message) return fail(new Error('message is required'))
+    const title = String(args.title || '').trim().slice(0, 60) || 'AIPictury'
+    const sent = workbench.notify(title, message)
+    report({ tool: name, args: { title, message }, status: 'done', result: sent ? 'sent' : 'not sent' })
+    return sent ? 'The user was notified.' : 'Not sent: the user is looking at VS Code right now, or notifications are off — say it in your reply.'
+  }
+
+  if (name === 'report_findings') {
+    const findings = normalizeFindings(args)
+    report({ tool: name, args: { count: findings.length }, status: 'done', findings })
+    if (!findings.length) return 'Reported: no findings. Tell the user in a sentence what you checked.'
+    const counts = ['high', 'medium', 'low'].map((s) => [s, findings.filter((f) => f.severity === s).length])
+      .filter(([, n]) => n).map(([s, n]) => `${n} ${s}`).join(', ')
+    return `The user sees ${findings.length} finding${findings.length === 1 ? '' : 's'} (${counts}) as a list they can open. `
+      + 'Summarize in a sentence or two; do not repeat the list.'
+  }
+
+  if (name === 'tool_search') {
+    const found = mcp.search(args, (session.loadedMcp ||= new Set()))
+    report({ tool: name, args, status: 'done', result: found.split('\n')[0] })
+    return found
+  }
+  if (name === 'list_mcp_resources' || name === 'read_mcp_resource') {
+    report({ tool: name, args, status: 'running' })
+    try {
+      const text = name === 'list_mcp_resources' ? await mcp.listResources(args) : await mcp.readResource(args)
+      report({ tool: name, args, status: 'done', result: text })
+      return text
+    } catch (error) { return fail(error) }
+  }
+
+  // A notebook cell runs code: the user is asked (a native Execute / Cancel), unless in Bypass.
+  if (name === 'notebook_run_cell') {
+    if (planning) { report({ tool: name, args, status: 'plan' }); return 'Plan mode: no cell was run. Describe it in your plan instead.' }
+    report({ tool: name, args, status: 'running' })
+    try {
+      const ask = hooks.askRun || (async (question, code) => (await Promise.race([vscode.window.showQuickPick(
+        [{ label: 'Execute', description: 'run the cell' }, { label: 'Cancel' }], { title: question, placeHolder: code.split('\n').slice(0, 3).join(' ⏎ ').slice(0, 200) }),
+      stopped(signal)]))?.label === 'Execute')
+      const text = await notebooks.runCell(args, { ask, skipAsk: mode === 'bypass', signal })
+      report({ tool: name, args, status: 'done', result: text })
+      return text
+    } catch (error) { return fail(error) }
+  }
+  if (name === 'publish_page') {
+    try {
+      if (!String(args.markdown || args.html || '').trim()) throw new Error('give the page markdown or html')
+      const response = await fetch(`${server}/api/pages`, { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: String(args.title || 'Page').slice(0, 200), markdown: args.markdown, html: args.html }), signal })
+      const data = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(data.detail || `the server answered ${response.status}`)
+      const url = `${server}${data.path}`
+      report({ tool: name, args: { title: args.title }, status: 'done', result: url, url })
+      return `Published at ${url} — give the user this link.`
+    } catch (error) { return fail(error) }
+  }
+  if (name === 'send_user_file') {
+    try {
+      const uri = resolve(args.path)
+      const stat = await vscode.workspace.fs.stat(uri)
+      if (stat.type & vscode.FileType.Directory) throw new Error(`${args.path} is a folder — send a file`)
+      report({ tool: name, args, status: 'done', result: args.message || '', file: { path: args.path, size: stat.size, message: args.message || '' } })
+      return `The user has ${args.path} as a card in the conversation, to open or save.`
+    } catch (error) { return fail(error) }
+  }
+
+  if (name === 'task') return runHelper(args, { server, session, signal, report, hooks, model: hooks.model })
+  if (name === 'workflow') return runWorkflow(args, { server, session, signal, report, hooks, model: hooks.model })
+  if (name === 'send_message') return sendToHelper(args, { server, session, signal, report, hooks, model: hooks.model })
+  if (name === 'list_agents') { const text = listHelpers(session); report({ tool: name, args, status: 'done', result: text }); return text }
+  if (name === 'task_stop') {
+    const h = findHelper(session, args.id)
+    if (h) {
+      if (h.status !== 'running') return `${h.id} is not running (${h.status}).`
+      h.controller?.abort()
+      report({ tool: name, args, status: 'done', result: `${h.id} stopped` })
+      return `${h.id} stopped.`
+    }
+    try { const text = shell.killShell({ shell_id: args.id }); report({ tool: name, args, status: 'done', result: text }); return text } catch (error) { return fail(error) }
+  }
+
+  const isMcp = mcp.isMcp(name)
+  const isRun = RUNS.has(name)
+  // PowerShell is never taken as read-only: the read-only check knows bash, not PowerShell.
+  const readOnlyRun = isRun && name !== 'powershell' && shell.isReadOnly(args.command)
+  // Read-only, but of somewhere outside the workspace (and the added folders): asked first.
+  const readsOutside = readOnlyRun && shell.readsOutside(args.command)
+  if (planning && (WRITES.has(name) || (isRun && !readOnlyRun) || (isMcp && !mcp.readOnly(name)))) {
+    report({ tool: name, args, status: 'plan' })
+    return isRun ? 'Plan mode: only read-only commands (ls, cat, git status/log/diff, grep…) run here. '
+      + 'Describe this one in your plan instead.' : 'Plan mode: this change was not applied. Describe it in your plan instead.'
+  }
+
+  // The browser in Plan mode looks — opens and reads pages — but does not act on them.
+  if (name === 'browser' && planning && !['navigate', 'back', 'close', ...browserTool.LOOKS].includes(args.action)) {
+    report({ tool: name, args, status: 'plan' })
+    return 'Plan mode: the browser only opens and reads pages here. Describe this step in your plan instead.'
+  }
+
+  let preview
+  let approval = { ok: true }
+  // The browser acts on a site once the user has said yes to it (localhost needs no yes); a
+  // password, card or similar field is asked about every time, whatever the mode.
+  const site = name === 'browser' ? browserTool.hostOf(args.page || '') : ''
+  const browserAsks = name === 'browser' && browserTool.ACTS.has(args.action) && args.action !== 'close'
+    && !browserTool.isLocal(args.page || '') && !session.allowSites?.includes(site)
+  const tender = name === 'browser' && browserTool.sensitive(args)
+  if (tender) Object.assign(rule, { decision: 'ask', rule: null, hook: null, why: `the browser always asks: ${tender}` })
+  // A PreToolUse hook's say: allow skips the question (a deny rule has already stopped the
+  // call), ask asks whatever the mode.
+  if (hooks.hookPermission === 'allow' && rule.decision !== 'ask') rule.decision = 'allow'
+  // The sandbox: a command kept in it (no network) needs no question; one leaving it is asked.
+  const box = isRun ? sandboxFor(args, folderPath()) : null
+  if (box?.run && box.s.autoAllow && !box.s.allowNetwork && rule.decision !== 'ask' && hooks.hookPermission !== 'ask') rule.decision = 'allow'
+  if (box?.asked || box?.unavailable) {
+    Object.assign(rule, { decision: 'ask', rule: null, hook: null,
+      sandbox: box.asked ? 'the agent asks to run this outside the sandbox' : 'the sandbox is on, but this machine has none (sandbox-exec / bubblewrap)' })
+  }
+  if (hooks.hookPermission === 'ask') Object.assign(rule, { decision: 'ask', rule: null, hook: hooks.hookReason || 'a hook' })
+  const standing = session.allowTools?.includes(name)
+  const needsYes = rule.decision === 'ask'
+    || (rule.decision !== 'allow' && !standing && (WRITES.has(name) || (isRun && (!readOnlyRun || readsOutside)) || (isMcp && !mcp.readOnly(name)) || browserAsks))
+  if (needsYes) {
+    if (WRITES.has(name)) { try { preview = await previewChange(call, session) } catch (error) { return fail(error) } }
+    // Say in the panel that a question is waiting: a silent pause reads as a hang.
+    report({ tool: name, args, status: 'asking' })
+    approval = await approve({ ...call, function: { ...call.function, arguments: args } }, session, signal, hooks, preview,
+      rule.decision === 'ask' ? { force: true, server, because: rule.why || rule.sandbox || (rule.hook ? `asked by a hook: ${rule.hook}` : `asked by the rule ${rule.rule}`) } : { server })
+    if (!approval.ok) {
+      report({ tool: name, args, status: 'refused', result: approval.feedback })
+      return approval.feedback
+        ? `The user declined this and said: ${approval.feedback}`
+        : 'The user declined this. Do not try it again in another way; ask what they want, or carry on without it.'
+    }
+  }
+  report({ tool: name, args, status: 'running' })
+  let before
+  if (WRITES.has(name)) {
+    try { before = files.parseText(decoder.decode(await vscode.workspace.fs.readFile(resolve(args.path)))).text } catch { before = null }
+    hooks.onFileChange?.(args.path, before)             // for checkpoints: what to restore
+  }
+  try {
+    let result
+    if (name === 'monitor') {
+      const task = shell.startMonitor(String(args.command || ''), { session, sandbox: box?.run, description: String(args.description || ''),
+        limitMs: Math.max(1, Math.min(120, Number(args.timeout_minutes) || 30)) * 60_000,
+        onLines: (t, lines, info) => hooks.onMonitor?.(t, lines, info) })
+      hooks.onTasks?.(shell.taskList())
+      result = `Watching as ${task.id}: each new output line will reach you as an event — between your steps, or as a new turn `
+        + `once you have finished. Stop it with kill_shell (shell_id "${task.id}").`
+    } else if (isRun) {
+      result = await runCommand(String(args.command || ''), { signal, session, timeout: args.timeout, sandbox: name === 'powershell' ? null : box?.run, powershell: name === 'powershell',
+        background: !!args.run_in_background, onTasks: () => hooks.onTasks?.(shell.taskList()) })
+    } else if (isMcp) {
+      result = await mcp.call(name, args)
+    } else if (approval.content !== undefined && WRITES.has(name)) {
+      // Only part of the change was kept, or the user edited it: write what they approved.
+      result = await files.writeFile({ path: args.path, content: approval.content }, { ...ctx, session: null })
+      files.remember(session, resolve(args.path), await files.stat(resolve(args.path)))
+      result = `${approval.edited ? 'The user edited your change before accepting it' : 'The user accepted only part of your change'}; `
+        + `${args.path} now holds what they approved — read it before changing it further.`
+    } else if (IMPLEMENTATIONS[name]) {
+      result = await IMPLEMENTATIONS[name](args, ctx)
+    } else {
+      throw new Error(`there is no tool called ${name}`)
+    }
+    // A web tool hands back what the model reads and, beside it, what the panel shows.
+    let web
+    let images
+    let text = result
+    if (result && typeof result === 'object' && 'text' in result) ({ text, web, images } = result)
+    let diff
+    if (WRITES.has(name)) {
+      try {
+        const uri = resolve(args.path)
+        const after = files.parseText(decoder.decode(await vscode.workspace.fs.readFile(uri))).text
+        diff = summarize(before, after)
+        diff.key = rememberBefore(args.path, before ?? '')
+        if (!/\.ipynb$/.test(args.path)) text += await files.diagnosticsAfter(uri)
+      } catch { /* the file could not be read back; the row still says it was written */ }
+    }
+    report({ tool: name, args, status: 'done', result: text, diff, web, tasks: isRun ? shell.taskList() : undefined })
+    return images?.length ? { text, images } : text
+  } catch (error) {
+    // A failed tool is information for the model, not the end of the conversation.
+    return fail(error)
+  }
+}
+
+// ---- helper agents (the task tool) ----
+// A piece of work handed to a fresh agent, as Claude Code's subagents are: its own
+// context, so the files it reads and the searches it runs never fill the main one; only
+// its final report comes back. "explore" only looks; "general" may change things, asking
+// as the main agent would. The panel shows one row for it, with its latest activity.
+const HELPER_STEPS = 40
+
+const HELPER_SYSTEM = (type) => `You are a helper agent working for AIPictury's coding agent, inside the
+user's workspace. You were given one task; do it with the tools and then reply with your
+final report — that report is all the main agent will see, so make it complete and
+specific: file paths with line numbers, the facts found, what you changed. Be efficient:
+search (grep, glob, code_intel) before reading whole files, and read only what you need.
+${type === 'explore' ? 'You are read-only: find and explain, do not change anything.' : 'You may change files and run commands when the task needs it.'}`
+
+// Claude Code's tool names, in an agent's "tools:", as ours.
+const AGENT_TOOLS = { Read: ['read_file', 'list_files'], LS: ['list_files'], Grep: ['grep'], Glob: ['glob'], Bash: ['run_command', 'bash_output', 'kill_shell'],
+  Edit: ['edit_file'], MultiEdit: ['edit_file'], Write: ['write_file'], NotebookEdit: ['notebook_edit'], WebFetch: ['fetch_url'],
+  WebSearch: ['web_search'], TodoWrite: [] }
+
+/** The helpers of a conversation: id or name → their record (messages, state, status). */
+function helpersOf(session) { return (session.helpers ||= new Map()) }
+
+/** A helper by its id or its name. */
+function findHelper(session, key) {
+  const all = helpersOf(session)
+  return all.get(String(key)) || [...all.values()].find((h) => h.name && h.name === String(key))
+}
+
+async function runHelper(args, { server, session, signal, report, hooks, model }) {
+  // A helper with a role (an agent file: .aipictury/agents, .claude/agents, a plugin's agents/):
+  // its instructions, and only the tools it lists.
+  const role = !['explore', 'general', undefined, ''].includes(args.subagent_type)
+    ? context.agents().find((a) => a.name === args.subagent_type) : null
+  if (!role && !['explore', 'general', undefined, ''].includes(args.subagent_type)) {
+    return `error: no helper called ${args.subagent_type} — use "explore", "general" or one of: ${context.agents().map((a) => a.name).join(', ') || '(none)'}`
+  }
+  const name = String(args.name || '').trim().replace(/[^\w.-]+/g, '-').slice(0, 40) || null
+  if (name && findHelper(session, name)) return `error: there is already a helper called ${name} — send_message to it, or choose another name`
+  const allowedTools = role?.tools.length ? new Set(role.tools.flatMap((t) => AGENT_TOOLS[t] || [t])) : null
+  const writes = !allowedTools || [...allowedTools].some((t) => WRITES.has(t) || t === 'run_command')
+  const type = role ? (writes ? 'general' : 'explore') : args.subagent_type === 'general' ? 'general' : 'explore'
+  const sub = { allowAll: session.allowAll, allowCommands: session.allowCommands, allowSites: session.allowSites, seen: new Map(), cwd: session.cwd, worktree: session.worktree }
+  // isolation: "worktree" — the helper works in a checkout of its own.
+  let ownTree = null
+  if (args.isolation === 'worktree') {
+    try { ownTree = await worktrees.enter(folderPath(), `helper-${Date.now().toString(36)}`) } catch (error) { return `error: no worktree for the helper: ${error.message}` }
+    sub.worktree = ownTree
+    sub.cwd = ownTree.path
+  }
+  const readOnly = type === 'explore' || modeNow() === 'plan'
+  const tools = toolSchema({ readOnly, helper: true, extra: [...mcp.schema({ readOnly, loaded: (session.loadedMcp ||= new Set()) }), ...mcp.resourceSchema()] })
+    .filter((t) => !allowedTools || allowedTools.has(t.function.name) || (t.function.name.startsWith('mcp__') && allowedTools.has(t.function.name)))
+  const id = `agent_${helpersOf(session).size + 1}`
+  const h = {
+    id, name, type, role: role?.name || null, description: String(args.description || '').slice(0, 80), tools, readOnly, sub, ownTree,
+    messages: [{ role: 'system', content: HELPER_SYSTEM(type) + (role ? `\n\n## Your role: ${role.name}\n${role.body}` : '') + context.instructionsBlock() },
+      { role: 'user', content: String(args.prompt || args.description || '') }],
+    state: { steps: 0, tokens: 0, last: '' }, status: 'running', started: Date.now(), inbox: [], background: !!args.run_in_background,
+  }
+  helpersOf(session).set(id, h)
+  const run = () => helperLoop(h, { args, server, session, signal: h.background ? null : signal, report, hooks, model })
+  if (!h.background) return run()
+  // In the background: the main agent carries on; the report arrives as an event.
+  run().then((text) => hooks?.onHelperDone?.(h, text)).catch(() => {})
+  return `Started ${id}${name ? ` (${name})` : ''} in the background. Its report will reach you as an event when it is done; `
+    + `send_message to it meanwhile, list_agents to see it, task_stop to stop it.`
+}
+
+/** A helper's work, until its report — started, or resumed by send_message. */
+async function helperLoop(h, { args, server, session, signal, report, hooks, model }) {
+  const { state, sub, tools, readOnly, type, ownTree } = h
+  h.status = 'running'
+  h.controller = new AbortController()
+  const stopAll = () => h.controller.abort()
+  signal?.addEventListener('abort', stopAll, { once: true })
+  const halt = h.controller.signal
+  const started = Date.now()
+  const show = (status, extra = {}) => report({ tool: 'task', args: { ...args, subagent_type: h.role || type }, status,
+    progress: { steps: state.steps, tokens: state.tokens, seconds: Math.round((Date.now() - h.started) / 1000), last: state.last }, ...extra })
+  show('running')
+  const { messages } = h
+  const recent = []
+  let known = null
+  const holds = new Map()
+  try {
+    for (;;) {
+      if (halt.aborted) throw Object.assign(new Error('stopped'), { name: 'AbortError' })
+      // Messages sent to it meanwhile (send_message) join between its steps.
+      if (h.inbox.length) messages.push(...h.inbox.splice(0).map((text) => ({ role: 'user', content: `[A message from the main agent:]\n${text}` })))
+      const result = await steadyTurn(server, messages, { tools, model, signal: halt, think: false })
+      state.tokens += (result.meta?.tokens || 0)
+      const { text, calls } = result
+      messages.push({ role: 'assistant', content: text, tool_calls: calls })
+      if (!calls.length && state.steps < HELPER_STEPS && (state.stopBlocks || 0) < 3) {
+        const held = await userHooks.fire('SubagentStop', { stop_hook_active: (state.stopBlocks || 0) > 0 }, hookContext(session, halt, hooks || {}))
+        if (held.block) {
+          state.stopBlocks = (state.stopBlocks || 0) + 1
+          messages.push({ role: 'user', content: `A SubagentStop hook says this is not finished yet: ${held.reasons.join('\n')}\nCarry on, then report.` })
+          continue
+        }
+      }
+      if (!calls.length && h.inbox.length) continue
+      if (!calls.length || state.steps >= HELPER_STEPS) {
+        const final = String(text || '').trim() || '(the helper finished without a report)'
+        let where = ''
+        if (ownTree) {
+          const left = await worktrees.changes(ownTree)
+          if (left.commits || left.dirty.length) where = `\n\nIts changes are in the worktree ${ownTree.relative} (branch ${ownTree.branch}): ${left.commits} commit(s), ${left.dirty.length} uncommitted change(s).`
+          else if (!h.name) await worktrees.exit(folderPath(), ownTree, { action: 'remove' })
+        }
+        h.status = 'done'
+        h.report = final
+        show('done', { result: final })
+        return `Report from ${h.id}${h.name ? ` (${h.name})` : ''} (${type}, ${state.steps} steps, ${Math.round((Date.now() - started) / 1000)}s):\n\n${final}${where}`
+      }
+      for (const call of calls) {
+        state.steps += 1
+        state.last = `${call.function.name} ${String(call.function.arguments?.path || call.function.arguments?.pattern
+          || call.function.arguments?.command || call.function.arguments?.query || '').slice(0, 80)}`.trim()
+        show('running')
+        recent.push(signature(call))
+        if (isSpinning(recent)) {
+          messages.push({ role: 'tool', tool_name: call.function.name, content: 'You are repeating yourself. Write your final report now.' })
+          break
+        }
+        // A helper cannot ask the user: a package they have not chosen goes back as a question.
+        const brought = deps.brings(call.function.name, parsedArgs(call))
+        if (brought.length && hooks?.userSaid) {
+          known ??= await deps.declared()
+          const open = deps.unchosen(brought, hooks.userSaid(), known, holds)
+          if (open.length) {
+            messages.push({ role: 'tool', tool_name: call.function.name, content: deps.holdNote(open, { helper: true }) })
+            continue
+          }
+        }
+        // Its steps are not drawn one by one: the row shows the latest, as Claude Code's does.
+        const out = await execute(call, readOnly && type === 'general' ? { ...sub } : sub, () => {}, halt, server,
+          { ...hooks, askUser: null, onTodos: null, approvePlan: null })
+        const content = typeof out === 'object' ? out.text : out
+        messages.push({ role: 'tool', tool_name: call.function.name, content: capResult(content) })
+      }
+      const fitted = compact(messages)
+      if (fitted !== messages) messages.splice(0, messages.length, ...fitted)
+    }
+  } catch (error) {
+    if (error.name === 'AbortError') { h.status = 'stopped'; show('refused'); return `${h.id} was stopped` }
+    h.status = 'failed'
+    show('failed', { result: error.message })
+    return `error: the helper failed: ${error.message}`
+  } finally {
+    signal?.removeEventListener('abort', stopAll)
+  }
+}
+
+/** workflow: steps run as helpers in the order their dependencies give — one at a time (one GPU) —
+ *  each told what the steps it depends on found; one report of all of them. */
+async function runWorkflow(args, ctx) {
+  let order
+  try { order = workflows.plan(args.steps) } catch (error) { return `error: ${error.message}` }
+  const results = new Map()
+  const show = (status, extra = {}) => ctx.report({ tool: 'workflow', args: { goal: args.goal, steps: order.length }, status,
+    progress: { done: results.size, total: order.length, current: extra.current }, ...extra })
+  for (const s of order) {
+    if (ctx.signal?.aborted) break
+    show('running', { current: s.name })
+    const out = await runHelper({ description: s.name, prompt: workflows.stepPrompt(s, args.goal, results), subagent_type: s.subagent_type || 'general' },
+      { ...ctx, report: () => {} })
+    results.set(s.name, String(out).replace(/^Report from [^\n]*\n\n/, ''))
+  }
+  show('done', { result: `${results.size}/${order.length} steps` })
+  return workflows.combine(order, results, { goal: args.goal, stopped: !!ctx.signal?.aborted })
+}
+
+/** send_message: a message to a named (or numbered) helper — between its steps while it works,
+ *  or it carries on from where it was when it has reported. */
+async function sendToHelper(args, ctx) {
+  const h = findHelper(ctx.session, args.to)
+  if (!h) return `error: no helper ${args.to} — list_agents shows them`
+  const text = String(args.message || '').trim()
+  if (!text) return 'error: an empty message'
+  if (h.status === 'running') { h.inbox.push(text); return `Sent to ${h.id}: it reads it before its next step.` }
+  h.inbox.push(text)
+  const run = () => helperLoop(h, { args: { description: h.description, subagent_type: h.role || h.type }, ...ctx, signal: h.background ? null : ctx.signal })
+  if (!h.background) return run()
+  run().then((out) => ctx.hooks?.onHelperDone?.(h, out)).catch(() => {})
+  return `Sent to ${h.id}: it carries on in the background; its report will reach you as an event.`
+}
+
+function listHelpers(session) {
+  const all = [...helpersOf(session).values()]
+  if (!all.length) return 'No helpers in this conversation yet.'
+  return all.map((h) => `${h.id}${h.name ? ` (${h.name})` : ''} — ${h.role || h.type}, ${h.status}${h.background ? ', in the background' : ''}`
+    + ` · ${h.state.steps} steps, ${h.state.tokens} tokens, ${Math.round((Date.now() - h.started) / 1000)} s · ${h.description}`).join('\n')
+}
+
+// A fenced block with a few lines in it: enough to be a change the model meant to make
+// rather than an inline example.
+const CODE_BLOCK = /```[\w-]*\n(?:[^\n]*\n){3,}?```/
+
+// A request that asks for something to be made or changed, in English or Spanish.
+const ASKS_CHANGE = /\b(add|change|fix|implement|rename|refactor|update|write|create|remove|delete|replace|modify|edit|convert|move|make|build|set ?up|install|apply|insert|append|generate|go ahead|do it|agreg|añad|cambi|arregl|corrig|renombr|actualiz|escrib|cre[aá]|elimin|borr|reemplaz|modific|mov[eé]|hacé|hacelo|hazlo|haz |gener|instal|aplic|insert|dale)/i
+
+/** A tool call's arguments as an object, whether they came parsed or as JSON text. */
+function parsedArgs(call) {
+  const args = call.function.arguments || {}
+  if (typeof args !== 'string') return args
+  try { return JSON.parse(args) } catch { return {} }
+}
+
+/** Whether the user's latest message asks for a change (not only to find or explain). */
+function askedForChange(messages, fromUser) {
+  const last = [...messages].reverse().find((m) => fromUser.has(m))
+  if (!last) return true                 // no record of what was asked: keep the safety net
+  const text = typeof last.content === 'string' ? last.content
+    : (last.content || []).map((p) => p.text || '').join(' ')
+  return ASKS_CHANGE.test(text)
+}
+
+/**
+ * True when every fenced block in the text only quotes what the tools returned — code the
+ * model read and is showing back, as in "where is route defined?", not a change it drafted.
+ * Line numbers from read_file ("12\t…") are ignored, as is indentation.
+ */
+function onlyQuotes(text, messages) {
+  const blocks = [...String(text || '').matchAll(/```[\w-]*\n([\s\S]*?)```/g)].map((m) => m[1])
+  if (!blocks.length) return false
+  const seen = new Set()
+  for (const m of messages) {
+    if (m.role !== 'tool') continue
+    for (const line of String(m.content || '').split('\n')) seen.add(line.replace(/^\s*\d+\t/, '').trim())
+  }
+  return blocks.every((block) => block.split('\n').map((l) => l.trim()).filter(Boolean).every((l) => seen.has(l)))
+}
+
+// ---- keeping the conversation inside the model's window ----
+// The model sees a 32k-token window. The agent used to resend its whole history every
+// turn — every file read, every page fetched — so a long task eventually filled the
+// window and Ollama failed with a 500 (or spent minutes re-reading 32k tokens). This
+// keeps what is sent under budget the way Claude Code's auto-compact does: recent steps
+// stay whole, older tool output is replaced by a note saying it can be fetched again.
+// The budget is in tokens, and the character count that fits is *measured*: code and
+// repetitive text tokenize far denser than prose, so a fixed chars-per-token guess
+// either wastes the window or overflows it. Every turn Ollama reports how many tokens
+// the prompt really took; the ratio is learned from that, starting conservative.
+// Of the 128k window (config: agent_num_ctx). Compaction keeps what is sent under this;
+// the rest is headroom for the answer, the tools and the reasoning. Far larger than the
+// old 18k, so summaries are rare and, when they happen, the model has room to work.
+// 112k of the 131k window (measured: a larger window no longer fits the GPU and the 27B
+// model drops from 40 to 11 tok/s at 196k): the rest is room for the tools (~6k) and the answer.
+const TARGET_TOKENS = 112_000
+let charsPerToken = 2.5           // conservative start; replaced by measurement
+// The window the model in use is loaded with — 131k, or less for a model measured not to
+// fit the GPU at that (the server says which). A smaller window gets a smaller budget.
+const FULL_WINDOW = 131_072
+let windowTokens = FULL_WINDOW
+const targetTokens = () => (windowTokens >= FULL_WINDOW ? TARGET_TOKENS : Math.round(windowTokens * 0.75))
+const setWindow = (tokens) => { windowTokens = Number(tokens) > 0 ? Number(tokens) : FULL_WINDOW }
+const budget = () => Math.round(targetTokens() * charsPerToken)
+const TOOL_RESULT_CAP = 16_000    // one tool result may not take more than this
+
+/** Roughly how many tokens these messages take, at the density measured so far. */
+function estimateTokens(messages) { return Math.round(size(messages) / charsPerToken) }
+
+/** Learns the real density from what a turn cost. The prompt count also includes the
+ *  tool list and the chat template, so the ratio errs small — i.e. safe. */
+function calibrate(sentChars, promptTokens) {
+  if (!promptTokens || promptTokens < 500 || !sentChars) return
+  const measured = sentChars / promptTokens
+  charsPerToken = Math.min(4, Math.max(1.5, measured))
+}
+const KEEP_RECENT = 6             // the newest messages are never shortened
+
+/** Caps one tool result as it enters the conversation. */
+function capResult(text) {
+  const t = String(text)
+  if (t.length <= TOOL_RESULT_CAP) return t
+  return `${safeSlice(t, 0, TOOL_RESULT_CAP)}\n… [${t.length - TOOL_RESULT_CAP} more characters not shown — `
+    + 'read a narrower range, or search, if you need them]'
+}
+
+// A picture costs the model roughly a thousand tokens; counted as characters here.
+const IMAGE_COST = 4_000
+const size = (messages) => messages.reduce((n, m) => n + String(m.content || '').length
+  + (m.tool_calls ? JSON.stringify(m.tool_calls).length : 0)
+  + (m.images ? m.images.length * IMAGE_COST : 0), 0)
+
+/** What is actually sent: the same conversation, shortened from the oldest end until
+ *  it fits. The system prompt and the first question are always kept. */
+function compact(messages, limit = budget()) {
+  if (size(messages) <= limit) return messages
+  const out = messages.map((m) => ({ ...m }))
+  const firstUser = out.findIndex((m) => m.role === 'user')
+  const protectedIdx = new Set([0, firstUser])
+  const middle = []
+  for (let i = 1; i < out.length - KEEP_RECENT; i += 1) if (!protectedIdx.has(i)) middle.push(i)
+
+  // 1. Old tool output becomes a one-line note.
+  for (const i of middle) {
+    if (size(out) <= limit) return out
+    if (out[i].role === 'tool' && String(out[i].content).length > 200) {
+      out[i].content = `[earlier output of ${out[i].tool_name || 'a tool'} omitted to fit the `
+        + 'context window — call it again if you still need it]'
+    }
+  }
+  // 2. Old reasoning-out-loud from the assistant is shortened.
+  for (const i of middle) {
+    if (size(out) <= limit) return out
+    if (out[i].role === 'assistant' && String(out[i].content || '').length > 400) {
+      out[i].content = `${safeSlice(out[i].content, 0, 400)} …`
+    }
+  }
+  // 3. Still too big: drop whole old steps (an assistant turn and its tool results
+  //    together, so every tool result still follows the call that asked for it).
+  let dropped = 0
+  while (size(out) > limit) {
+    const at = out.findIndex((m, i) => i > firstUser && i < out.length - KEEP_RECENT
+      && m.role === 'assistant')
+    if (at === -1) break
+    let end = at + 1
+    while (end < out.length - KEEP_RECENT && out[end].role === 'tool') end += 1
+    out.splice(at, end - at)
+    dropped += 1
+  }
+  if (dropped) {
+    out.splice(firstUser + 1, 0, { role: 'user',
+      content: `[${dropped} earlier step(s) omitted to fit the context window.]` })
+  }
+  // 4. Last resort: the recent steps alone are too big (a few large files in a row).
+  //    Shorten their tool output too, oldest first, keeping the newest result whole.
+  for (let i = firstUser + 1; i < out.length - 1 && size(out) > limit; i += 1) {
+    if (out[i].role === 'tool' && String(out[i].content).length > 3000) {
+      out[i].content = `${safeSlice(out[i].content, 0, 3000)}\n… [shortened to fit the `
+        + 'context window — read it again if you need the rest]'
+    }
+  }
+  return out
+}
+
+// A line that reads as source code, for spotting a file written out in the reasoning.
+const CODE_LINE = /^\s*(def |class |import |from \S+ import|function |const |let |var |export |return |async |public |private |#include|<\/?[a-zA-Z][\w-]*[ >]|[}\])];?\s*$|.*[{(]\s*$|.*=>)/
+
+/** True when the reasoning contains a real block of code rather than a passing mention. */
+function looksLikeCode(text) {
+  return String(text || '').split('\n').filter((line) => CODE_LINE.test(line)).length >= 5
+}
+
+// ---- summarizing the older part of a long conversation ----
+// Dropping old steps loses them — including an instruction the user gave halfway
+// through. When the conversation nears the window, the older part is summarized
+// instead: the user's goals and instructions, decisions, what was changed, what is left.
+// The summary replaces those messages in what is kept, and is itself folded into the
+// next summary, so a long session keeps its thread. Rules saved with `remember` sit in
+// the system prompt and never depend on this.
+const SUMMARY_AT = 0.9           // share of the budget that triggers a summary (~100k tokens)
+const SUMMARY_MARK = '[Summary of the earlier part of this conversation'
+
+function asDialogue(messages) {
+  return messages.map((m) => {
+    if (m.role === 'tool') return `TOOL RESULT (${m.tool_name || 'tool'}): ${safeSlice(m.content || '', 0, 1500)}`
+    if (m.role === 'assistant') {
+      const calls = (m.tool_calls || []).map((c) => `${c.function.name}(${safeSlice(JSON.stringify(c.function.arguments || {}), 0, 300)})`)
+      return `ASSISTANT: ${safeSlice(m.content || '', 0, 3000)}${calls.length ? `\n  called: ${calls.join('; ')}` : ''}`
+    }
+    return `USER: ${safeSlice(m.content || '', 0, 6000)}`
+  }).join('\n\n')
+}
+
+/** Replaces the older part of `messages` with a summary written by the model. Returns
+ *  the new list, or null when there is too little to summarize or the model failed. */
+const READ_TPS = 1000          // prompt tokens/s this GPU reads uncached (measured)
+
+/** How far a summary has got, as a percentage the panel can show. Reading the
+ *  conversation is the first 40% — timed against how long a prompt that size takes to
+ *  read — and writing the summary the rest, by its length against the length expected.
+ *  It stops at 95%: only the end says 100. */
+function summaryProgress(dialogueChars, onProgress) {
+  const started = Date.now()
+  const readFor = Math.max(3, dialogueChars / charsPerToken / READ_TPS)
+  const expected = Math.min(5000, Math.max(1500, dialogueChars * 0.08))
+  let written = 0
+  let reading = true
+  const tick = () => {
+    const seconds = (Date.now() - started) / 1000
+    const percent = reading
+      ? Math.min(40, (seconds / readFor) * 40)
+      : 40 + Math.min(55, (written / expected) * 55)
+    // `stage`, not `phase`: the caller sends this inside a message whose `phase` says what
+    // kind of message it is — the same name overwrote it, and every tick read as the end.
+    onProgress?.({ percent: Math.round(percent), stage: reading ? 'reading' : 'writing', seconds: Math.round(seconds) })
+  }
+  const timer = setInterval(tick, 500)
+  tick()
+  return {
+    wrote: (chars) => { reading = false; written += chars },
+    stop: () => clearInterval(timer),
+  }
+}
+
+/** What a summary would cover — the messages between the first question and the recent
+ *  ones kept whole — or null when there is nothing worth summarizing. One plan for both
+ *  deciding to summarize and summarizing: they disagreed, and a run announced a summary on
+ *  every step that then had nothing to do (the conversation was large, but in its recent
+ *  messages, which are never summarized). */
+function summaryPlan(messages, force = false) {
+  if (!force && size(messages) < budget() * SUMMARY_AT) return null
+  const firstUser = messages.findIndex((m) => m.role === 'user')
+  let end = messages.length - KEEP_RECENT
+  // Never split an assistant's tool calls from their results.
+  while (end > firstUser + 1 && messages[end] && messages[end].role === 'tool') end -= 1
+  const older = messages.slice(firstUser + 1, end)
+  if (older.length < (force ? 1 : 4)) return null
+  return { firstUser, end, older }
+}
+
+async function summarizeEarlier(server, messages, { model, signal, force = false, onProgress, focus = '' } = {}) {
+  const plan = summaryPlan(messages, force)
+  if (!plan) return null
+  const { firstUser, end, older } = plan
+  const dialogue = safeSlice(asDialogue(older), -Math.round(budget() * 0.9))
+  const progress = summaryProgress(dialogue.length, onProgress)
+  try {
+    const { text } = await turn(server, [
+      { role: 'system', content: 'You write the working notes that let a coding agent carry on '
+        + 'a conversation after its early part is removed from its memory.' },
+      { role: 'user', content: 'Summarize the conversation below so it can be continued without '
+        + 'it. Keep, precisely: the user\'s goals and every instruction, preference or rule they '
+        + 'gave; decisions made and why; files created or changed and what they now contain, in '
+        + 'outline; commands run and how they ended; problems still open and what is left to do. '
+        + 'Be concise, but never drop an instruction. Write in the language the user writes in.'
+        + (focus ? ` Pay particular attention to: ${focus}.` : '')
+        + `\n\n<conversation>\n${dialogue}\n</conversation>` },
+    ], { tools: [], think: false, model, signal, onDelta: (d) => progress.wrote(d.length) })
+    if (!text.trim()) return null
+    return [
+      ...messages.slice(0, firstUser + 1),
+      { role: 'user', content: `${SUMMARY_MARK} — written to keep the context window in bounds]\n${text.trim()}` },
+      ...messages.slice(end),
+    ]
+  } catch (error) {
+    if (error.name === 'AbortError') throw error
+    return null               // mechanical compaction still keeps the turn inside the window
+  } finally {
+    progress.stop()
+  }
+}
+
+// ---- a budget for the reasoning ----
+// Measured on a real session: asked to build a frontend, the model spent 4½ minutes and
+// 9,316 tokens writing every component out in its reasoning, with no tool call — and it
+// could never have finished, since writing it all again in the tool calls would have
+// overflowed the window. Reasoning is kept (it is useful to watch), but once it has
+// turned into a long draft of code with nothing applied, that generation is stopped and
+// the model is told to write the files, with reasoning off for that one step.
+const THINK_BUDGET = 6_000        // characters of reasoning (~1.5k tokens) before a code draft is cut
+
+/** True when the reasoning has become a draft of the code rather than a plan. */
+function overthinking(thinking) {
+  return thinking.length > THINK_BUDGET && (CODE_BLOCK.test(thinking) || looksLikeCode(thinking))
+}
+
+// ---- reasoning that goes round in circles ----
+// A model that loses its thread starts restating what it already thought — the same
+// paragraphs, back and forth, for minutes. Measured by word 8-grams: in ordinary
+// reasoning almost every 8-word run is new, while in a loop most of the latest
+// stretch has already been said. When it has, the reasoning is stopped and the model
+// is handed back what it had worked out, with the repeats removed, and told to act.
+const GRAM = 8
+const LOOP_TAIL = 240          // words: the latest stretch of reasoning that is judged
+const LOOP_SHARE = 0.6         // share of that stretch already said before = a loop
+const LOOP_MIN_WORDS = 500     // too short to tell before this
+
+const words = (text) => String(text || '').toLowerCase().match(/[\p{L}\p{N}_]+/gu) || []
+
+/** True when most of the latest reasoning repeats what was already reasoned. */
+function thinkingLoops(thinking) {
+  const w = words(thinking)
+  if (w.length < LOOP_MIN_WORDS) return false
+  const seen = new Set()
+  const tailStart = w.length - LOOP_TAIL
+  let judged = 0
+  let repeated = 0
+  for (let i = 0; i + GRAM <= w.length; i += 1) {
+    const gram = w.slice(i, i + GRAM).join(' ')
+    if (i >= tailStart) {
+      judged += 1
+      if (seen.has(gram)) repeated += 1
+    }
+    seen.add(gram)
+  }
+  return judged > 0 && repeated / judged >= LOOP_SHARE
+}
+
+/** The reasoning with its repeats removed: each sentence kept once, in order. */
+function distill(thinking, limit = 6_000) {
+  const seen = new Set()
+  const lines = []
+  // Line by line, sentence by sentence, so lists and steps keep their shape.
+  for (const line of String(thinking || '').split('\n')) {
+    const kept = []
+    for (const sentence of line.split(/(?<=[.!?])\s+/)) {
+      const w = words(sentence)
+      if (!w.length) continue
+      const grams = []
+      for (let i = 0; i + GRAM <= w.length; i += 1) grams.push(w.slice(i, i + GRAM).join(' '))
+      const keys = grams.length ? grams : [w.join(' ')]
+      const old = keys.filter((g) => seen.has(g)).length
+      keys.forEach((g) => seen.add(g))
+      if (old / keys.length < 0.5) kept.push(sentence.trim())     // not said already
+    }
+    if (kept.length) lines.push(kept.join(' '))
+  }
+  let notes = lines.join('\n')
+  // The latest conclusions matter most: when it is long, keep the start and the end.
+  if (notes.length > limit) {
+    notes = `${safeSlice(notes, 0, limit * 0.3)} […] ${safeSlice(notes, -limit * 0.7)}`
+  }
+  return notes
+}
+
+// ---- a question on the side (/btw) ----
+// Asked about the conversation without adding to it, as Claude Code's /btw. The prompt is
+// the conversation exactly as the next turn would send it — the same system prompt, the
+// same tools — with the question after it, so the model's prompt cache serves all of it
+// and the conversation's next turn still finds its own prefix cached.
+/** The tools of one step — the same for the run and for /btw, so the prompt cache serves both.
+ *  MCP tools past a score of them are given whole only once loaded by tool_search. */
+function stepTools(planning, session = {}) {
+  const all = toolSchema({ readOnly: planning, autoMemory: vscode.workspace.getConfiguration('aipictury').get('autoMemory', true),
+    extra: [...mcp.schema({ readOnly: planning, loaded: (session.loadedMcp ||= new Set()) }), ...mcp.resourceSchema()] })
+  // A tool denied outright for this run (--disallowedTools "Bash") is not offered at all.
+  const off = new Set((session.commandDeny || []).flatMap((rule) => permissions.toolsNamed(rule)))
+  return off.size ? all.filter((t) => !off.has(t.function?.name)) : all
+}
+
+async function sideQuestion(server, history, question, { model, signal, onDelta, session, thread = [], effort } = {}) {
+  const mode = modeNow()
+  const rules = await memory.block(server)
+  // The earlier side questions of the thread come after the conversation, so its prefix stays
+  // cached, and a follow-up ("and what about…?") knows what it follows.
+  const before = thread.flatMap((x) => [{ role: 'user', content: `[A side question:] ${x.question}` }, { role: 'assistant', content: x.answer }])
+  const messages = [{ role: 'system', content: systemPrompt(mode, rules, effortOf(effort || vscode.workspace.getConfiguration('aipictury').get('effort', 'high'))) }, ...history, ...before,
+    { role: 'user', content: '[A side question — answer it briefly from what you already know of this '
+      + 'conversation and the code you have seen. Do not call any tool, and do not continue the task.]\n'
+      + question }]
+  const tools = stepTools(mode === 'plan', session)
+  const { text } = await steadyTurn(server, messages, { tools, model, signal, onDelta, think: false })
+  return String(text || '').trim() || '(no answer — ask again, or ask the agent directly)'
+}
+
+// ---- getting through a lost connection ----
+// The server sits on Wi-Fi and shares its GPU with renders. A blip, a restart or a
+// render in progress must not end the task: the run waits and asks again from exactly
+// where it was — the conversation so far, tool results included, is all still here.
+const RETRY_WAITS = [5, 10, 20, 40, 60, 60, 120, 120]   // seconds, then it gives up
+const BUSY_WAIT = 20                                    // seconds between GPU checks
+const BUSY_LIMIT = 90                                   // 30 minutes of a render
+
+/** Waits `seconds` unless Stop is pressed first. */
+function pause(seconds, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, seconds * 1000)
+    function done() { signal?.removeEventListener('abort', onStop); resolve() }
+    function onStop() {
+      clearTimeout(timer)
+      const stop = new Error('stopped'); stop.name = 'AbortError'; reject(stop)
+    }
+    if (signal?.aborted) return onStop()
+    signal?.addEventListener('abort', onStop, { once: true })
+  })
+}
+
+/** One turn, asked again through transient failures. Non-transient errors pass through. */
+async function steadyTurn(server, messages, options, onRetry) {
+  let failures = 0
+  let busy = 0
+  for (;;) {
+    try {
+      return await turn(server, messages, options)
+    } catch (error) {
+      if (error.name === 'AbortError' || !error.transient) throw error
+      let wait
+      if (error.busy) {
+        busy += 1
+        if (busy > BUSY_LIMIT) throw error
+        wait = BUSY_WAIT
+      } else {
+        if (failures >= RETRY_WAITS.length) throw error
+        wait = RETRY_WAITS[failures]
+        failures += 1
+      }
+      onRetry?.({ error: error.message, wait, attempt: error.busy ? busy : failures,
+                  of: error.busy ? BUSY_LIMIT : RETRY_WAITS.length, busy: !!error.busy })
+      await pause(wait, options.signal)
+    }
+  }
+}
+
+// How Auto mode stops: not by capping work, but by noticing when the agent is spinning
+// — repeating the same call, or a short cycle of calls, without getting anywhere. A
+// weaker local model loops where a stronger one would finish; this catches that.
+const REPEAT_LIMIT = 3       // the same exact call this many times = stuck
+const WINDOW = 8             // over the last this-many calls
+
+/** A stable signature for a call, so "the same call" is recognised regardless of key order. */
+function signature(call) {
+  const args = call.function.arguments || {}
+  const keys = Object.keys(args).sort()
+  return `${call.function.name}(${keys.map((k) => `${k}=${JSON.stringify(args[k])}`).join(',')})`
+}
+
+/** True when the recent calls show the agent is stuck rather than making progress. */
+function isSpinning(recent) {
+  const window = recent.slice(-WINDOW)
+  // The same call, over and over.
+  for (const sig of new Set(window)) {
+    if (window.filter((s) => s === sig).length >= REPEAT_LIMIT) return true
+  }
+  // A short cycle repeated: A,B,A,B,A,B or A,B,C,A,B,C.
+  for (const period of [2, 3]) {
+    if (window.length >= period * 3) {
+      const tail = window.slice(-period * 3)
+      const unit = tail.slice(0, period).join('|')
+      if ([1, 2].every((n) => tail.slice(period * n, period * (n + 1)).join('|') === unit)) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/** Runs the whole exchange: turns and tool calls until the model has nothing left. */
+async function run(options) {
+  // Whatever happens, the work done so far comes back. A thrown error used to discard
+  // every tool call and result of the run, leaving only the user's message — so
+  // "continue" started the task over from nothing. Now the caller always receives the
+  // conversation as far as it got, and the error beside it.
+  const messages = []
+  // One run at a time on the GPU (gpuRun.js): another app holding it, nothing is started.
+  const last = [...(options.history || [])].reverse().find((m) => m.role === 'user')
+  const label = String(last?.content || '').split('\n')[0]
+  try {
+    return await require('./gpuRun').holding({ server: options.server, client: vscode.cli ? 'cli' : 'vscode', label },
+      () => work(options, messages))
+  } catch (error) {
+    const kept = messages.slice(1)
+    if (error.name === 'AbortError') return { messages: kept, stopped: true }
+    if (error.busy) return { messages: kept, error: error.message, busy: true, gpu: error.gpu }
+    return { messages: kept, error: error.message }
+  }
+}
+
+// How hard the model reasons, as Claude Code's effort levels: low answers without
+// reasoning (fastest), medium and high cap the reasoning (about 1.5k and 6k tokens), max
+// lets it reason as long as it needs — a loop or a code draft is still cut.
+const EFFORT = {
+  low: { think: false, budget: 0 },
+  medium: { think: true, budget: 6_000 },
+  high: { think: true, budget: 24_000 },
+  max: { think: true, budget: 0 },
+  // Ultracode: as max, and large tasks are planned as workflows of helpers.
+  ultra: { think: true, budget: 0 },
+}
+const effortOf = (value) => (EFFORT[value] ? value : 'high')
+
+const TODO_NOTE = `
+
+Use todo_write to plan and track a task of three or more steps: the user sees the list.`
+
+/** The system prompt for this step: the mode may change mid-run (a plan approved, the
+ *  user switching), and the project's instruction files are read fresh. */
+const ULTRA_NOTE = `
+
+ULTRACODE: for a substantial task — several parts, several files, research then changes — plan it as a
+workflow: the workflow tool runs its steps as helpers, in order, each given what the earlier ones found,
+and returns one report. Then check the result yourself before you finish.`
+
+// Text added after the system prompt for every run (the CLI's --append-system-prompt).
+let appended = ''
+function appendSystem(text) { appended = String(text || '').trim() }
+
+function systemPrompt(mode, rules, effort) {
+  const dirs = require('./paths').extraRoots()
+  const added = dirs.length ? `\n\nBesides the workspace, you may also work in these folders (name their files by absolute path): ${dirs.join(', ')}.` : ''
+  return SYSTEM + TODO_NOTE + (effort === 'ultra' ? ULTRA_NOTE : '') + (mode === 'plan' ? PLAN_NOTE : unattended(mode) ? AUTO_NOTE : '')
+    + context.instructionsBlock() + rules + context.styleBlock() + added + (appended ? `\n\n${appended}` : '')
+}
+
+async function work({ server, model, history, session, signal,
+                      onDelta, onThinking, onTool, onTurn, onNudge, onWaiting, onSpeed, takeQueued, onSteerable,
+                      askUser: ask, onDecision, approve: approveHook, approvePlan, onTodos, onTasks, onFileChange,
+                      readSpecial, effort: chosenEffort, onMessages, window: modelWindow, trustHooks, trustMcp, onMonitor, schedule, onHelperDone }, messages) {
+  setWindow(modelWindow)
+  // 0 (the default) means no limit: the agent runs until it is done or is stopped.
+  const settings = () => vscode.workspace.getConfiguration('aipictury')
+  const configured = settings().get('maxSteps', 0)
+  const maxSteps = configured > 0 ? configured : Infinity
+  // The rules are read once per request; a rule saved with remember is added as it is saved.
+  const rules = await memory.block(server)
+  await mcp.ensure({ trust: trustMcp }).catch(() => [])
+  messages.push({ role: 'system', content: systemPrompt(modeNow(), rules, effortOf(chosenEffort || settings().get('effort', 'high'))) }, ...history)
+  // What the user wrote, as opposed to the notes the loop adds in their voice.
+  const fromUser = new Set(history.filter((m) => m.role === 'user'))
+  let known = null           // the dependencies the workspace declares, read when first needed
+  const holds = new Map()    // package → times a call bringing it in was held
+  const hooks = { askUser: ask, onDecision, approve: approveHook, approvePlan, onTodos, onTasks, onFileChange, readSpecial, model, trustHooks, onMonitor, schedule, onHelperDone,
+    // For helpers: what the user said, so a package is judged chosen by them, not by a task text.
+    userSaid: () => deps.saidByUser(messages, fromUser) }
+  let steps = 0
+  let changed = false      // has anything actually been written this time round?
+  let nudged = false       // the reminder below is given once, never in a loop
+  const recent = []        // recent call signatures, to notice spinning
+  let spinNudged = false
+  let stopBlocks = 0        // times a Stop hook has kept the run going
+
+  let actNow = false        // the previous turn drafted code in its reasoning: act this time
+  let truncations = 0       // turns in a row cut off at the output limit
+  let retrySummaryAt = 0    // after a summary failed: the size to reach before trying again
+  for (;;) {
+    if (signal?.aborted) return { messages: messages.slice(1), stopped: true }
+    // Messages the user sent while this was running enter here, between steps — never
+    // between a tool call and its result — and the next turn reasons about them.
+    const queued = takeQueued?.() || []
+    for (const m of queued) fromUser.add(m)
+    messages.push(...queued)
+    // A summary the run needs — only when there is something to summarize — shown as it
+    // happens (the input held), then what it saved. One that failed is not tried again on
+    // every step: only once the conversation has grown by a fifth since.
+    if (summaryPlan(messages) && size(messages) > retrySummaryAt) {
+      const before = estimateTokens(messages)
+      const started = Date.now()
+      onNudge?.('summarizing', { phase: 'start', tokens: before })
+      await userHooks.fire('PreCompact', { trigger: 'auto', custom_instructions: '' }, hookContext(session, signal, hooks))
+      const summarized = await summarizeEarlier(server, messages, { model, signal,
+        onProgress: (p) => onNudge?.('summarizing', { phase: 'progress', ...p }) })
+      if (summarized) {
+        messages.splice(0, messages.length, ...summarized)
+        retrySummaryAt = 0
+      } else {
+        retrySummaryAt = size(messages) * 1.2
+      }
+      onNudge?.('summarizing', { phase: 'done', ok: !!summarized, before,
+        after: estimateTokens(messages), seconds: Math.round((Date.now() - started) / 1000) })
+    }
+    const mode = modeNow()
+    const planning = mode === 'plan'
+    const think = settings().get('showThinking', true)
+    const effort = EFFORT[effortOf(chosenEffort || settings().get('effort', 'high'))]
+    messages[0].content = systemPrompt(mode, rules, effortOf(chosenEffort || settings().get('effort', 'high')))
+    const tools = stepTools(planning, session)
+    const thinking = think && effort.think && !actNow
+    // A fresh switch per turn: a message queued while the model generates cuts this
+    // generation, so the correction is heard now rather than after it finishes.
+    const steer = new AbortController()
+    onSteerable?.(steer)
+    const result = await steadyTurn(server, messages, { tools, model, signal, onDelta, onThinking,
+      onWaiting, onSpeed, think: thinking, effort: effortOf(chosenEffort || settings().get('effort', 'high')),
+      thinkBudget: thinking ? effort.budget : 0,
+      watchReasoning: thinking && !planning, watchLoops: thinking, steer: steer.signal },
+    (retry) => onNudge?.('retry', retry))
+    onSteerable?.(null)
+    actNow = false
+    if (result.interrupted) {
+      onNudge?.('steered')
+      // What it had already said stays in the conversation; it continues from there.
+      if (String(result.text || '').trim()) {
+        messages.push({ role: 'assistant', content: `${result.text}\n[interrupted by the user's next message]` })
+      }
+      continue            // the queued message is taken at the top of the loop
+    }
+    if (result.looped) {
+      // Keep what it worked out, drop the circles, and have it act on it — with the
+      // reasoning off for that one step, so it cannot start the same circle again.
+      actNow = true
+      onNudge?.(result.budget ? 'budget' : 'looped')
+      const notes = distill(result.thinking)
+      messages.push({ role: 'user', content:
+        (result.budget
+          ? 'Your reasoning reached the length the chosen effort allows, so it was stopped. '
+            + 'This is what you had worked out:\n\n'
+          : 'Your reasoning started repeating itself — the same points, round and round — so it '
+            + 'was stopped. This is what you had worked out, with the repeats removed:\n\n')
+        + `<your-reasoning>\n${notes}\n</your-reasoning>\n\n`
+        + 'Do not work through it again. Decide from it and act now: make the next tool call, '
+        + 'or give your answer if the task is done. Where you were torn between options, '
+        + 'pick the simplest one that works.' })
+      continue
+    }
+    if (result.overthought) {
+      actNow = true
+      onNudge?.('overthought')
+      messages.push({ role: 'user', content:
+        'You have planned enough and started writing the code in your reasoning, where it '
+        + 'changes nothing. Stop planning. Write the files now with write_file (or change '
+        + 'existing ones with edit_file), one call per file, then continue until the task '
+        + 'is done.' })
+      continue
+    }
+    const { text, calls, meta } = result
+    truncations = meta.truncated ? truncations + 1 : 0
+    // Cut off three times running despite being told to write in parts: that is a loop
+    // too, and each round costs minutes of GPU. Stop, keeping everything done.
+    if (truncations >= 3) return { messages: messages.slice(1), meta, stuck: true }
+    if (meta.truncated) {
+      // It ran into the output cap mid-answer. A tool call that long is either a file
+      // too big for one call or the model repeating itself inside one — either way,
+      // writing it in parts is the way through. Nothing half-written is applied.
+      onNudge?.('truncated')
+      messages.push({ role: 'assistant', content: text || '(the answer was cut off at the output limit)' })
+      messages.push({ role: 'user', content:
+        'Your last answer hit the output limit (about 32k tokens) and was cut off, so nothing '
+        + 'in it was applied. If you were writing a large file, write it in parts: create it '
+        + 'with the first part using write_file, then add each further part with edit_file '
+        + '(quote the last lines as old_text and repeat them followed by the new part). Keep '
+        + 'each call well under the limit. If you were repeating yourself, stop and take the '
+        + 'next concrete step.' })
+      onTurn?.({ text, thinking: result.thinking, meta, calls: [] })
+      continue
+    }
+    messages.push({ role: 'assistant', content: text, tool_calls: calls })
+    onTurn?.({ text, thinking: result.thinking, meta, calls })
+    onMessages?.(messages.slice(1))
+
+    if (!calls.length) {
+      // A model that has written out the code but called nothing has described the
+      // change instead of making it. That is worth one reminder — from the code it
+      // just produced, applying it is a small step, and the alternative is a user who
+      // believes their file was edited when it was not.
+      // With reasoning shown, a model sometimes writes the file out in its thinking and
+      // stops there. A substantial answer means it was explaining, not editing, so the
+      // unfenced-code check only applies when the answer itself is thin.
+      const narrated = looksLikeCode(result.thinking) && String(text || '').trim().length < 200
+      // Code that only quotes what the tools returned is an answer, not an unapplied change.
+      const drafted = (CODE_BLOCK.test(text) && !onlyQuotes(text, messages))
+        || (CODE_BLOCK.test(result.thinking || '') && !onlyQuotes(result.thinking, messages))
+        || narrated
+      // Only when the user asked for a change: to "find and tell me" the reminder would
+      // push the agent into editing something nobody asked it to touch.
+      if (!planning && !changed && !nudged && drafted && askedForChange(messages, fromUser)) {
+        nudged = true
+        onNudge?.()
+        messages.push({ role: 'user', content:
+          'You wrote the code but did not apply it — showing it is not the same as '
+          + 'changing the file. Make the change now with write_file or edit_file, then '
+          + 'confirm in one line. If nothing actually needs changing, say why.' })
+        continue
+      }
+      // About to finish, but the user has said more meanwhile: carry on with it.
+      const late = takeQueued?.() || []
+      if (late.length) { for (const m of late) fromUser.add(m); messages.push(...late); continue }
+      // The user's Stop hooks may say the work is not finished (tests not run…): the agent
+      // carries on with their reason — at most three times, so a hook cannot keep it going for ever.
+      const stopHook = await userHooks.fire('Stop', { stop_hook_active: stopBlocks > 0 }, hookContext(session, signal, hooks))
+      if (stopHook.block && stopBlocks < 3 && !signal?.aborted) {
+        stopBlocks += 1
+        const why = stopHook.reasons.join('\n')
+        onNudge?.('hook', { text: `a Stop hook: ${why}` })
+        messages.push({ role: 'user', content: `A Stop hook says the work is not finished yet: ${why}\nCarry on, then finish.` })
+        continue
+      }
+      return { messages: messages.slice(1), meta, nudged }
+    }
+
+    for (const call of calls) {
+      if (signal?.aborted) return { messages: messages.slice(1), meta, stopped: true }
+      steps += 1
+      if (steps > maxSteps) {
+        messages.push({ role: 'tool', tool_name: call.function.name,
+                        content: `stopped: this request has already taken ${maxSteps} steps` })
+        return { messages: messages.slice(1), meta, exhausted: true }
+      }
+
+      recent.push(signature(call))
+      if (isSpinning(recent)) {
+        if (!spinNudged) {
+          // One chance to break out of it on its own: tell the model plainly.
+          spinNudged = true
+          recent.length = 0
+          onNudge?.()
+          messages.push({ role: 'tool', tool_name: call.function.name, content:
+            'You are repeating the same action without making progress. Stop repeating '
+            + 'it. Either finish now with a short summary of what you have done, or take a '
+            + 'clearly different approach.' })
+          break            // skip the rest of this batch, get a fresh turn
+        }
+        // Still spinning after the reminder — end it. This is what makes Auto stop.
+        return { messages: messages.slice(1), meta, stuck: true }
+      }
+
+      // Each call its own row in the panel, even when it repeats an earlier one exactly.
+      const callId = `c${Date.now().toString(36)}-${steps}`
+      // A package the user has not chosen is not installed or imported: the model asks first.
+      const brought = deps.brings(call.function.name, parsedArgs(call))
+      if (brought.length) {
+        known ??= await deps.declared()
+        const open = deps.unchosen(brought, deps.saidByUser(messages, fromUser), known, holds)
+        if (open.length) {
+          const note = deps.holdNote(open)
+          onTool?.({ tool: call.function.name, args: parsedArgs(call), status: 'failed', result: note, id: callId })
+          messages.push({ role: 'tool', tool_name: call.function.name, content: note })
+          continue
+        }
+      }
+      const result = await execute(call, session, (event) => onTool?.({ ...event, id: callId }), signal, server, hooks)
+      if (WRITES.has(call.function.name) || call.function.name === 'generate_media') changed = true
+      const content = typeof result === 'object' ? result.text : result
+      const toolMessage = { role: 'tool', tool_name: call.function.name, content: capResult(content) }
+      if (typeof result === 'object' && result.images?.length) toolMessage.images = result.images
+      messages.push(toolMessage)
+      onMessages?.(messages.slice(1))
+      if (session.hookStop) {
+        onNudge?.('hook', { text: `a hook stopped the run: ${session.hookStop}` })
+        delete session.hookStop
+        return { messages: messages.slice(1), meta, stopped: true }
+      }
+      // Approving a plan switches the mode: the next step gets the tools that go with it.
+      if (call.function.name === 'exit_plan_mode' && modeNow() !== 'plan') break
+    }
+  }
+}
+
+module.exports = { appendSystem, helpersOf, findHelper, listHelpers, modeNow, setWindow, targetTokens, sideQuestion, run, turn, steadyTurn, execute, runHelper, normalizeTodos, commandPrefix, previewChange, approve, EFFORT, effortOf, systemPrompt, estimateTokens, summaryPlan, plain, commandEnv, AUTO_NOTE, thinkingLoops, distill, summarizeEarlier, runCommand, openSideBySide, stopBackground, compact, capResult, looksLikeCode, onlyQuotes, askedForChange, overthinking, calibrate, budget, SYSTEM, MODES,
+  TARGET_TOKENS, proposedProvider, proposedContents }