heartcode 0.1.5 → 0.1.7

package/SKILL.md

@@ -51,15 +51,19 @@ reached has an `error` and is skipped; the command still exits `0`.
 | `default`, or no `-m` | the user's list: #1, and the next one in order when it fails (rate limits, outages…). Use this unless you need one particular model. |
 | a model from the list: `-m "<provider> <model>"` (`-m "groq openai/gpt-oss-120b"`), or `-m <model>` alone | that model alone: never another one, also when it fails (a rate limit or an outage is tried again, up to `--max-retries`) |
 
-**Failures:** a rate limit, a server error, a timeout or a lost connection is waited out and tried
+**Failures:** a rate limit, a server error, a timeout, a reply that stops coming (nothing for 150s),
+a lost connection, or an error page from a proxy in front of the provider is waited out and tried
 again (or handed to the next model in the list), up to `--max-retries` (10). With the default
 list, a model that can't be used (a wrong key, no access to it, a name the server doesn't know:
 401, 403, 404) also makes way for the next one, and so does one that keeps replying with nothing.
-The run stops with that error and exit code `1` when every model in the list fails that way, when
-a single model (`-m <model>`) does, or at a request the server refuses (400), which is never sent
-again (unless the user set the fallback rule to "at any error"). A provider that refuses a part
+The run stops with that error and exit code `1` when every model in the list fails that way, or
+when a single model (`-m <model>`) does. A request a server refuses (400) is sent as it is to two
+more models of the list at most, then the run stops (unless the user set the fallback rule to "at
+any error"). A provider that refuses a part
 of the request HeartCode can do without (the model's thinking sent back, keys in the tools'
-schemas) gets it again without that part.
+schemas, images) gets it again without that part, and that is remembered for the model for a day.
+Each request is fitted to the model it goes to: one that can't see gets a note in place of each
+image, one that can't call tools gets the tool calls as text.
 
 `--provider <name>` and `-u <url>` (a server for this run) also mean one model, alone.
 
@@ -74,6 +78,9 @@ heart -p --output-format json -C /path/to/project "fix the failing test in math.
 
 - `-C <folder>`: the project to work in (default: the current folder). A folder, not a file.
 - The prompt is the last argument, or stdin: `echo "explain src/agent.js" | heart -p`.
+- An image goes with the task as `@path/to/shot.png` or a full path (`/Users/me/shot.png`) in the
+  prompt, or as an image block in stream-json. A file name only mentioned ("rename logo.png") isn't
+  attached. A model that can't see gets it looked at by one of the user's models that can.
 - Exit code: `0` it finished, `1` it failed (no model, the model kept failing, the server refused
   the request (wrong model name, bad key), `--max-turns` hit). The error is in `result` (JSON) or on stderr.
 
@@ -101,7 +108,9 @@ heart -p --continue "…"          # or: the last session in this folder
 ## Keep it safe
 
 Headless never asks anyone. What the permission mode would ask about is declined, and the
-model is told why. An MCP tool its server marks read-only is never asked about.
+model is told why. An MCP tool its server marks read-only is never asked about. The model can't
+give itself a freer permission mode (its `manage` tool asks the user, so headless refuses it), and
+can't switch the model you chose.
 
 | You want | Flags |
 |---|---|
@@ -132,10 +141,13 @@ nothing is sent to the model to find out. A model models.dev doesn't know works
 assumptions, and the user can set it up on the settings page. Models that can't call tools still
 work, in a slower guided mode.
 
-The model in use knows the user's other models and what each can do, and hands a job it can't do
-(see an image, call tools…) to one that can: an attached image goes to a model that sees images, an
-image's path to one through its `agent` tool, and a model without tool calls can hand the task to one
-with them. Their tokens are in `usage`, and each model's in `modelUsage`.
+The model in use knows the user's other models (what each can do, how often it failed this
+session) and works with them through its `agent` tool: it asks a model that can for what it
+can't do itself (a model that can't see asks one that can about a screenshot: "which tiles show a
+chair?"), several at once when there are many images or parts, and a helper that fails is handed to
+the next capable model until one does the job. A helper takes 25 steps at most, then answers with
+what it has. Their tokens are in `usage`, and each model's in
+`modelUsage`.
 
 ## Setting up a model
 
@@ -172,11 +184,21 @@ heart -p --input-format stream-json --output-format stream-json
 ```
 
 Stdin: one message per line, `{"type":"user","message":{"role":"user","content":"…"}}`.
-Stop the running one with `{"type":"control_request","request_id":"1","request":{"subtype":"interrupt"}}`.
+Stop the running one with `{"type":"control_request","request_id":"1","request":{"subtype":"interrupt"}}`;
+any other control request gets a `control_response` with `subtype: "error"` (not supported).
 Stdout: one JSON event per line, `system`/`init` (its `tools` include the MCP servers' tools,
 `mcp_servers` says which are `connected`), then `assistant` (text, thinking, `tool_use`),
 `user` (`tool_result`), and a `result` after each message. It runs until stdin closes.
 
+A helper's steps (the `agent` tool: another of the user's models, or the same one, doing a job;
+several can run at once) come as `assistant` and `user` lines too, as Claude Code sends a
+subagent's: `parent_tool_use_id` is the id of the `agent` call they belong to (`null` for the main
+conversation's). The helper's last reply is that `agent` call's `tool_result`.
+
+Every `assistant` line's `message.model` is the model that wrote it (`provider/model`): after a
+fallback, the one that took over, not the one the run started with (the `init` line's `model`).
+`modelUsage` in the `result` has each model that answered.
+
 ## Don't
 
 - Don't run `heart` without `-p` from an agent: it's a full-screen app and waits for a person.

package/bin/heartcode.js

@@ -4,7 +4,7 @@ import { parseArgs } from 'node:util'
 import { Client } from '../src/client.js'
 import { loadConfig, saveConfig, readJson, writeJson, providerName, CONFIG_FILE, HOME, DEFAULT_MODEL, VERSION } from '../src/config.js'
 import { probe, loadProfile, strategy, describe, profilePath, profileFrom } from '../src/probe.js'
-import { learnFromUsage, RATE_CAP_MS } from '../src/context.js'
+import { learnFromUsage, RATE_CAP_MS, LIMIT_MS } from '../src/context.js'
 import { Session, transcript } from '../src/agent.js'
 import { treeItems, codePlan, move, leaving, leftText, leftFiles } from '../src/tree.js'
 import { UI, c, PERMISSIONS, rank, setTheme, themeCodes, renderDiff, diffLines, DEFAULT_KEYS, loadKeys } from '../src/ui.js'
@@ -160,6 +160,7 @@ class App {
     this.memory = new Memory(root) // .heartcode/memory: notes linked with [[name]]
     this.director = new Director(this) // the manage tool: skills, MCP servers and settings by asking
     this.later = [] // setting changes that wait until the current message is done
+    this.failures = {} // "provider model" → failed requests this session (engine: onFail)
   }
 
   newMcp() {
@@ -209,10 +210,13 @@ class App {
     const bad = (choices) => `error: ${name} must be ${choices}`
     const save = (msg) => (saveConfig(cfg), log('director', `setting ${name} = ${v}`), msg)
     switch (name) {
-      case 'permissions':
+      case 'permissions': {
         if (!PERMISSIONS.some(([p]) => p === v)) return bad('all, commands, ask or plan')
-        ui.setPermission(v)
-        return `permissions: ${v}`
+        // allowing more than now: only if you say yes (the model can't give itself more on its own)
+        const free = (p) => ['plan', 'ask', 'commands', 'all'].indexOf(p)
+        if (free(v) <= free(ui.permission)) return (ui.setPermission(v), `permissions: ${v}`)
+        return ui.confirm(`The model wants to change permissions from "${ui.permission}" to "${v}". Allow?`, 'command').then((ok) => (ok === true ? (ui.setPermission(v), `permissions: ${v}`) : `The user didn't allow it; permissions stay "${ui.permission}".`))
+      }
       case 'effort':
         if (!ARGS.set_effort.some(([o]) => o === v)) return bad('default, low, medium or high')
         cfg.effort = v === 'default' ? undefined : v
@@ -228,6 +232,8 @@ class App {
         let [p, ...m] = v.split(/\s+/)
         if (!cfg.providers[p]) [p, m] = [cfg.provider, [v]]
         if (!cfg.providers[p] || !m.join(' ')) return `error: give "provider model" or a model of the current provider; providers: ${Object.keys(cfg.providers).join(', ')}`
+        // headless (-p) and editors (ACP): the program that started HeartCode chooses the model
+        if (this.ui instanceof HeadlessUI) return 'error: the model can\'t be switched here: the program that started HeartCode chooses it'
         this.later.push(() => this.use(p, m.join(' ')).catch((e) => ui.warn(e.message)))
         return `switching to ${p} · ${m.join(' ')} after this reply`
       }
@@ -237,37 +243,73 @@ class App {
   }
 
   // The model, its probe and strategy for a provider and model (probed once, then cached).
-  async engine(provider, model, ui, signal) {
+  // quiet: for a helper (orchestration): nothing printed about the model, the settings left alone.
+  async engine(provider, model, ui, signal, { quiet = false } = {}) {
     const { cfg } = this
     const client = this.client(provider, model)
+    let price = null
     // tokens and cost, into the chat (also a helper's, the probe's, compaction's)
-    let price = priceOf(provider, client.baseUrl, model)
-    loadPrices().then(() => ((price = priceOf(provider, client.baseUrl, model)), ui.render?.()))
     client.price = () => price
     client.onSpend = (u) => addUsage((this.chat.usage ??= {}), u, price)
     client.onRetry = (err, ms, attempt, next) => ui.retrying(err, ms, attempt, next) // keep trying until Esc (also while probing)
-    // the model list (settings page): another model answered; its price from now on
+    // failures per model this session: the main model sees them (Your other models) and helpers
+    // are tried in that order
+    client.onFail = (e, t) => {
+      if (e.name === 'AbortError') return
+      const k = `${t.provider} ${t.model}`
+      this.failures[k] = (this.failures[k] ?? 0) + 1
+    }
+    // the model list (settings page): another model answered
     client.onSwitch = (t) => {
-      price = priceOf(t.provider, t.baseUrl, t.model)
       const i = client.rotation.list.indexOf(t)
       ui.print(c.dim(`↻ ${t.provider} · ${t.model} answered${i ? ` (#${i + 1} in your model list)` : ' (#1 again)'}`))
     }
     if (cfg.maxRetries !== undefined) client.retryIf = (e, attempt) => attempt < cfg.maxRetries // headless: then give up
-    const profile = await getProfile(client, ui, cfg.force, signal)
-    cfg.force = false
-    if (strategy(profile, cfg).thinking) client.effort = cfg.effort
-    const strat = strategy(profile, cfg)
+    let profile = await getProfile(client, ui, !quiet && cfg.force, signal, quiet)
+    if (!quiet) cfg.force = false
+    const strat = {}
+    // The model asked from now on (at first, and when the model list moves on): its own profile,
+    // abilities (sees images? calls tools? its window), thinking effort, price, and what its
+    // provider refuses. client.can: what the conversation is fitted to before each request.
+    const apply = () => {
+      for (const k of Object.keys(strat)) delete strat[k]
+      Object.assign(strat, strategy(profile, cfg))
+      Object.assign(client, { tokenRatio: profile.tokenRatio ?? 1, knownGood: profile.largestAccepted ?? 0, can: strat, effort: strat.thinking ? cfg.effort : undefined })
+      for (const [q, at] of Object.entries(profile.quirks ?? {})) if (Date.now() - at < LIMIT_MS) client.quirks[q] = true
+      price = priceOf(client.provider, client.baseUrl, client.model)
+      if (this.s?.client === client) this.s.profile = profile // /model_info, the settings page
+    }
+    apply()
+    client.onUse = (t) => {
+      profile = loadProfile(client) || profileFrom(client, limitsOf(t.provider, client.baseUrl, t.model))
+      apply()
+      log('rotate', `${t.provider} · ${t.model}: ${strat.actions}${strat.vision ? ', images' : ''}, ~${strat.context} tokens`)
+    }
+    // Saved with what another connection to the same model (a helper on it) learned meanwhile: the
+    // provider's refusals of both are kept (each writes its whole profile).
+    const save = () => {
+      const disk = readJson(profilePath(client), null)
+      if (disk?.model === profile.model) profile.quirks = { ...disk.quirks, ...profile.quirks }
+      writeJson(profilePath(client), profile)
+    }
     // What the window is, learned while working (context.js); kept in the profile for next time.
     const learned = () => {
       Object.assign(strat, (({ context, contextSure, ratio, reply }) => ({ context, contextSure, ratio, reply }))(strategy(profile, cfg)))
       Object.assign(client, { tokenRatio: profile.tokenRatio ?? 1, knownGood: profile.largestAccepted ?? 0 })
-      writeJson(profilePath(client), profile)
+      save()
+    }
+    // A part of the request this model's provider refused and the request worked without: kept for
+    // a day (images: the model is treated as not seeing them).
+    client.onLearn = (quirk) => {
+      profile.quirks = { ...profile.quirks, [quirk]: Date.now() }
+      if (quirk === 'noImages') strat.vision = false
+      save()
+      log('quirk', `${client.model}: ${quirk} (kept for a day)`)
     }
-    Object.assign(client, { tokenRatio: profile.tokenRatio ?? 1, knownGood: profile.largestAccepted ?? 0 })
     client.onUsage = (used, estimate) => {
       const was = profile.largestAccepted
       const change = learnFromUsage(profile, used, estimate)
-      if (change === 'cut') ui.warn(`${model} silently cut a request to ~${profile.inputLimit} tokens: that's its window here; keeping the conversation within it`)
+      if (change === 'cut') ui.warn(`${client.model} silently cut a request to ~${profile.inputLimit} tokens: that's its window here; keeping the conversation within it`)
       if (change) log('context', `${change}: ${used} tokens counted, ~${estimate} estimated; window now ${strategy(profile, cfg).context}`, { was, largestAccepted: profile.largestAccepted, inputLimit: profile.inputLimit, tokenRatio: profile.tokenRatio })
       if (change) learned()
     }
@@ -277,12 +319,13 @@ class App {
       if (rate) profile.rateCap = { tokens: n, until: Date.now() + RATE_CAP_MS }
       else Object.assign(profile, { inputLimit: Math.min(profile.inputLimit ?? Infinity, n), inputLimitAt: Date.now() })
       learned()
-      ui.warn(rate ? `${provider} takes at most ~${n} tokens a minute on your account; shortening the conversation to fit (for today)` : `${model} takes at most ~${n} tokens per request here; shortening the conversation to fit`)
+      ui.warn(rate ? `${client.provider} takes at most ~${n} tokens a minute on your account; shortening the conversation to fit (for today)` : `${client.model} takes at most ~${n} tokens per request here; shortening the conversation to fit`)
     }
     // models.dev's published size for the model (a day old at most): used when the server doesn't say
     loadPrices().then(() => {
+      price = priceOf(client.provider, client.baseUrl, client.model)
       const known = limitsOf(provider, client.baseUrl, model) ?? undefined
-      if (JSON.stringify(known) === JSON.stringify(profile.known)) return
+      if (profile.model !== model || JSON.stringify(known) === JSON.stringify(profile.known)) return // (a switched-to model: its own)
       profile.known = known
       if (known && profile.source === 'assumed') profile.source = 'models.dev' // it's listed now
       learned()
@@ -509,7 +552,7 @@ class App {
   modelChoices(typed, start, end) {
     const mine = this.myModels()
     const twice = (m) => mine.filter((t) => t.model === m).length > 1
-    const items = mine.map((t, i) => ({ value: twice(t.model) ? `${t.provider} ${t.model}` : t.model, desc: `${t.provider} · #${i + 1}${i === 0 ? ' · in use' : ''} · ${this.canText(t)}`, start, end }))
+    const items = mine.map((t, i) => ({ value: twice(t.model) ? `${t.provider} ${t.model}` : t.model, desc: this.modelDesc(t, i), start, end }))
     return rank(items, typed).slice(0, 200)
   }
 
@@ -593,7 +636,8 @@ class App {
     Object.assign(this.s, { noFormat: cfg.format === false, noLsp: cfg.lsp === false })
     Object.assign(this.s, { mcp: this.mcp, memory: this.memory, skills: this.skills, director: this.director })
     this.s.team = () => this.team() // your other models: a job this one can't do goes to one of them
-    this.s.engineFor = (t) => this.engine(t.provider, t.model, ui)
+    this.s.engineFor = (t) => this.engine(t.provider, t.model, ui, undefined, { quiet: true })
+    this.s.failures = this.failures
     if (this.allowTools?.length) this.s.allowTools = toolNames(this.allowTools) // headless --allowedTools
     if (this.denyTools?.length) this.s.denyTools = toolNames(this.denyTools)
     if (this.cfg.maxTurns) this.s.maxTurns = this.cfg.maxTurns
@@ -637,6 +681,11 @@ class App {
     return { tools: st.actions === 'tools', images: st.vision, thinking: st.thinking, context: st.context, guessed: p.source === 'assumed' && !p.set }
   }
 
+  // A row of the model lists (the picker, the /select_model suggestions): "openrouter · #1 · in use · tools · 1M".
+  modelDesc(t, i) {
+    return `${t.provider} · #${i + 1}${i === 0 ? ' · in use' : ''} · ${this.canText(t)}`
+  }
+
   // "tools · images · thinking · 1M", for the model lists.
   canText(t) {
     const a = this.abilities(t)
@@ -668,7 +717,7 @@ class App {
       if (!Object.keys(cfg.providers).length && (await this.detectLocal())) return this.session()
       return ui.print(NO_MODELS)
     }
-    const items = mine.map((t, i) => ({ label: t.model, group: t.provider, t, current: i === 0, desc: [i === 0 ? '#1 · in use' : `#${i + 1} · fallback`, this.canText(t)].join(' · ') }))
+    const items = mine.map((t, i) => ({ label: t.model, t, current: i === 0, desc: this.modelDesc(t, i) }))
     const it = await ui.pick('Choose a model (more on /settings)', items, { filter })
     if (it && !it.current) await this.useMine(it.t)
   }
@@ -989,7 +1038,7 @@ function copyText(text) {
 // A model's profile: the saved one; else what models.dev says (nothing is sent to the model to
 // find out); a model it doesn't know: plain assumptions, until you set it up on the settings page.
 // force (/test_model, heart probe): test it now instead, with real requests.
-async function getProfile(client, ui, force, signal) {
+async function getProfile(client, ui, force, signal, quiet = false) {
   let p = !force && loadProfile(client)
   if (!p && !force) {
     await loadPrices()
@@ -1004,7 +1053,7 @@ async function getProfile(client, ui, force, signal) {
     if (known) writeJson(profilePath(client), (p = { ...p, known, source: 'models.dev' }))
   }
   if (p) {
-    if (p.source === 'assumed') ui.warn(`${client.model} isn't in models.dev: assuming it calls tools and streams, with a ~128k window. Set what it can do on /settings`)
+    if (p.source === 'assumed' && !quiet) ui.warn(`${client.model} isn't in models.dev: assuming it calls tools and streams, with a ~128k window. Set what it can do on /settings`)
     return p
   }
   ui.print(c.dim(`Testing ${client.model}…`))
@@ -1222,7 +1271,6 @@ async function slash(app, line) {
   }
   const s = await app.session()
   if (!s) return
-  const restrat = () => (s.strat = strategy(s.profile, cfg))
   switch (cmd) {
     case 'compact': {
       const done = await s.compact({ signal: app.signal, focus: args.join(' ') })
@@ -1232,11 +1280,13 @@ async function slash(app, line) {
     }
     case 'model_info':
       return ui.print(`${c.cyan(s.client.model)}\n${describe(s.profile, s.strat)}`)
-    case 'test_model':
-      s.profile = await getProfile(s.client, ui, true, app.signal)
-      restrat()
+    case 'test_model': {
+      const tested = await getProfile(app.client(s.client.provider, s.client.model), ui, true, app.signal) // tested on a fresh connection (requests not fitted to what it was thought to do), and saved
       s.reset()
-      return ui.print(describe(s.profile, s.strat))
+      app.s = null // built again from the saved profile (one profile and strategy, kept up to date as the model list moves on)
+      await app.session()
+      return ui.print(`${c.cyan(tested.model)}\n${describe(tested, strategy(tested, cfg))}`)
+    }
   }
 }
 
@@ -1377,7 +1427,9 @@ async function main() {
   const argv = process.argv.slice(2)
   const print = argv.includes('-p') || argv.includes('--print') // headless: an id after --resume is always an id
   for (let i = 0; i < argv.length; i++) if (argv[i] === '-w' || argv[i] === '--worktree') argv[i] = '--worktree=' // a name only as --worktree=name
-  for (let i = 0; i < argv.length; i++) if ((argv[i] === '--resume' || argv[i] === '-r') && /^[\w.-]{6,}$/.test(argv[i + 1] ?? '') && (print || loadChat(argv[i + 1]))) argv[i] = '--resume-id'
+  // an id: a saved session's, or (headless) shaped like one: HeartCode's (20261028091723-f44o) or a UUID
+  const idShaped = (x) => /^\d{14}-[a-z0-9]+$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(x)
+  for (let i = 0; i < argv.length; i++) if ((argv[i] === '--resume' || argv[i] === '-r') && /^[\w.-]{6,}$/.test(argv[i + 1] ?? '') && (loadChat(argv[i + 1]) || (print && idShaped(argv[i + 1])))) argv[i] = '--resume-id'
   const { values: f, positionals } = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -1471,7 +1523,8 @@ async function main() {
   if (f.acp) {
     // each editor session gets its own App, for its folder and its MCP servers
     cfg.maxRetries ??= 10
-    const makeApp = (root, ui, mcp) => new App(mcp ? { ...cfg, mcp: { extra: [mcp] } } : cfg, ui, root)
+    // each editor session its own settings (one choosing a model doesn't change the others')
+    const makeApp = (root, ui, mcp) => new App({ ...structuredClone(cfg), ...(mcp && { mcp: { extra: [mcp] } }) }, ui, root)
     process.exit(await runAcp({ makeApp, version: VERSION, permission: f['permission-mode'] ? PERMISSION_MODES[f['permission-mode']] : (cfg.permissions ?? 'ask') }))
   }
   const headless = f.print || f['output-format'] || f['input-format'] === 'stream-json'

package/package.json

@@ -1,7 +1,33 @@
 {
   "name": "heartcode",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A coding CLI for any local or OpenAI-compatible model, including small models without tool calling.",
+  "keywords": [
+    "ai",
+    "cli",
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "openai-compatible",
+    "openrouter",
+    "groq",
+    "ollama",
+    "lm-studio",
+    "gemini",
+    "mcp",
+    "terminal",
+    "developer-tools",
+    "claude-code-alternative"
+  ],
+  "homepage": "https://github.com/p32929/HeartCode#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/p32929/HeartCode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/p32929/HeartCode/issues"
+  },
+  "author": "p32929",
   "type": "module",
   "bin": {
     "heart": "bin/heart.js",

package/prompts/agent.md

@@ -107,21 +107,6 @@ Change an existing file: replace `search`, copied exactly from the file (includi
 
 Create a file, or overwrite one with its full content. With append: true, add to its end instead (to write a long file in parts).
 
-## tool-apply_patch
-
-Change, add, delete or move files in one go, with a patch in `input`:
-*** Begin Patch
-*** Update File: path/to/file.js
-@@ a line just above the change (optional)
- context line
--old line
-+new line
-*** Add File: new.js
-+its content
-*** Delete File: old.js
-*** End Patch
-(*** Move to: new/path after *** Update File: moves the file.) Give a few unchanged lines around each change so it matches one place.
-
 ## tool-run_command
 
 Run a shell command in the project folder; returns the exit code and output.
@@ -175,17 +160,42 @@ Several agent calls in one reply run at the same time. Use that to split indepen
 ## tool-agent-model
 
 <!-- The agent tool's "model", there when the user has other models. -->
-Another of your models to do the job (from "Your other models" in the system prompt, as "provider model"), when it needs what you can't do or you want its view too. Leave out for a helper on your own model.
+Which of your models does the job (from "Your other models" in the system prompt, as "provider model"): one that can do what it needs. Left out: your own model, or with images and you can't see them, the first of yours that can.
 
 ## team
 
-<!-- In the system prompt when the user set up other models. {{models}}: one per line with what each can do. {{you}}: what this model can do. -->
+<!-- In the system prompt when the user set up other models. {{models}}: one per line with what each can do (and failures this session). {{you}}: what this model can do. -->
 # Your other models
 
-The user set up these models besides you (you: tool calls, {{you}}):
+Besides you (tool calls, {{you}}), the user set up these models:
 {{models}}
 
-You can hand a job to one of them with the agent tool and its "model", and to several at once (several agent calls in one reply), for a second opinion or to compare answers. Never decline a part of the task, or say you can't do it, because it needs something you can't do (see an image, call tools, think longer, read more than fits your context): give that part to a model here that can, with everything it needs in the prompt (file paths, what to look for, what to report), then go on with its answer. Answering yourself is better when you can.
+Work with them through the agent tool: "model" picks one (as "provider model"; left out, a helper on your own model), "images" gives it images to look at (image files, saved screenshots, image URLs). Several agent calls in one reply run at the same time.
+
+- Never decline, guess or work around something because you can't do it (see an image, think it through, read more than fits your context): ask a model that can. Choose by what the job needs: the ability first; a faster one for a simple job, the strongest for a hard one; not one that keeps failing.
+- Ask for what you need in order to act, not for a description. Not "describe this screenshot" but "Which of these 9 tiles (numbered 1-9, left to right, top to bottom) show a chair? Reply with the numbers only." or "Where is the Submit button? Reply with its exact text and its position (top/middle/bottom, left/center/right)." Say what to answer and in what form, and nothing more.
+- Many images, or a job in independent parts: one agent call per image or part, all in the same reply (the same model several times, or different ones). Then put the answers together and decide the next step yourself.
+- A loop that needs the ability at every step (look, act, look again, until done) goes whole to a model that has it: the goal, how to tell it's done, what to report. Better than asking about each step.
+- A helper starts fresh: it knows only your prompt and images. Give it all it needs: the goal, what's known (paths, URLs, the page the browser is on, what was tried), what to reply. It has your tools, the same browser and MCP servers too: helpers that need the same MCP server (a browser) take turns (HeartCode makes the next one wait), so jobs that use it don't gain from running together; and never give two helpers the same files at once.
+- A helper that fails or replies with nothing is handed on to your next model that can do the job, on its own. An answer that doesn't settle it (wrong, unsure, part of it): ask again, a sharper question or another capable model, until it's done.
+- Trust a helper's answer to what you asked; question it only when it looks doubtful (it contradicts what you know, or it's vague) or acting on it can't be undone. Don't redo its work yourself.
+
+## you-see
+
+<!-- In the system prompt of a model that can see images (models that can often say they can't). -->
+You can see images: those in the user's messages, those tools return (a browser screenshot), and image files you open with read_file. To know what's on a page or in a picture, look at it yourself and act on what you see; never say you can't see or interpret images, and never ask for an image as text (base64).
+
+## tool-agent-images
+
+<!-- The agent tool's "images", there when the user has other models. -->
+Images for the helper to look at: image file paths (in the project, saved screenshots, ones the user gave) or image URLs. The model must see images (leave "model" out to get one that can).
+
+## images-unseen
+
+<!-- After a tool's result that had images (a browser screenshot) when this model can't see them. {{files}}: where they were saved. -->
+(You can't see the image(s) this tool returned. Saved as:
+{{files}}
+To act on what's in them, ask a model that can see: the agent tool with these in "images" and a precise question about what you need to do next.)
 
 ## images-described
 
@@ -197,7 +207,7 @@ You can hand a job to one of them with the agent tool and its "model", and to se
 ## subagent
 
 <!-- Added to a helper agent's system prompt. -->
-You are a helper agent: the main agent gave you one job, and your final reply goes back to it (not to the user). Do the job, then reply with what it needs: findings with file paths and line numbers, what you changed, or what failed. Be complete but brief.
+You are a helper agent: the main agent gave you one job, and your final reply goes back to it (not to the user). Do the job, then reply with what it needs: findings with file paths and line numbers, what you changed, or what failed. Be complete but brief. Do no more than the job needs: a question you can answer from what you know or were given gets its answer right away, without searching. You have at most 25 steps.
 
 ## plan-mode
 
@@ -286,10 +296,20 @@ The user added this while you were working:
 
 Take it into account and carry on.
 
+## garbled-call
+
+<!-- Sent when the model's reply had a tool call written out as text (template markup like <tool_call> or <arg_key>) instead of made. -->
+(Your last reply had a tool call written out as text, so nothing was done and it can't be shown as an answer. To use a tool, call it; if you're done, reply in plain words.)
+
+## repeating
+
+<!-- Added to a tool's result when the model made exactly the same call {{n}} times in a row. At five, HeartCode stops. -->
+(You've made exactly this call {{n}} times in a row now. Doing it again won't change anything: try another way, or say what's in the way.)
+
 ## tool-images
 
-<!-- Comes right after tool results that produced images (screenshots), which can only be sent as a message. -->
-(The images from the tool calls above.)
+<!-- Comes right after tool results that produced images (screenshots), which can only be sent as a message. {{files}}: where they're saved. -->
+(The images from the tool calls above: look at them here. They're also saved, only for giving them to a helper with the agent tool's images: {{files}})
 
 ## memory
 
@@ -319,16 +339,6 @@ Tags in use: {{tags}}
 {{#if notes}}Related notes:
 {{notes}}{{/if}}
 
-## memory-exchange
-
-<!-- The exchange to look at for memories. {{task}}: what the user said. {{answer}}: the reply. -->
-Below is an exchange that already happened. Don't do what it asks and don't answer it: only save, with the memory tool, what in it is worth remembering, or reply NONE.
-
-<exchange>
-User: {{task}}
-Assistant: {{answer}}
-</exchange>
-
 ## memory-tidy
 
 <!-- /tidy_memory. {{notes}}: every note, with its scope. {{broken}}: links to notes that don't exist (may be empty). -->

package/prompts/guided.md

@@ -61,7 +61,7 @@ Reply with only yes or no.
 
 ## intent
 
-<!-- Asked only when the wording of the task doesn't say whether it needs changes. -->
+<!-- Asked at the start of each task: does it need changes? -->
 Does the TASK require changing existing code or creating files (not just answering a question)?
 
 ## pick-file
@@ -113,6 +113,11 @@ Here is the current content of {{file}}:
 Rewrite this file with the change needed for the TASK. Reply with the COMPLETE new file content and nothing else. Keep everything that should not change. Never use placeholders like "rest of code here".{{#if extra}}
 {{extra}}{{/if}}
 
+## meant-to-remove
+
+<!-- Asked when an edit still removes definitions after a retry. {{names}}: what it removes. -->
+Your edit removes {{names}}. Does the TASK ask for that to be removed or renamed?
+
 ## keep-names
 
 <!-- An edit deleted definitions the task didn't ask to remove. {{names}}: them. {{them}}: "it" or "them". -->
@@ -187,8 +192,3 @@ There are no files in the project.
 ## note-unknown-file
 
 Could not work out which file was meant.
-
-## note-tests-are-right
-
-<!-- A weak model tried to edit a failing test instead of the code it tests. {{test}}, {{code}}: the files. -->
-The tests in {{test}} are correct; fix {{code}}, the code they test.

package/src/acp.js

@@ -9,7 +9,7 @@ import readline from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 import { log } from './log.js'
-import { clip } from './tools.js'
+import { clip, runningCall, failed as toolFailed } from './tools.js'
 import { HeadlessUI } from './headless.js'
 import { PERMISSIONS } from './ui.js'
 import { loadChat } from './sessions.js'
@@ -36,7 +36,7 @@ class AcpUI extends HeadlessUI {
   }
   async confirm(question, kind = 'edit') {
     if ((this.permission === 'all' || (this.permission === 'commands' && kind === 'edit') || (this.permission === 'plan' && kind === 'read'))) return true
-    const toolCallId = this.calls[0] ?? `ask_${Date.now()}`
+    const toolCallId = runningCall.getStore() ?? this.calls[0] ?? `ask_${Date.now()}` // the call asking
     const r = await this.conn
       .request('session/request_permission', {
         sessionId: this.sessionId,
@@ -197,7 +197,7 @@ function events(ui, s, e) {
       ui.update({
         sessionUpdate: 'tool_call',
         toolCallId: t.id,
-        title: clip(`${name}${what ? ` ${what}` : ''}`, 120),
+        title: clip(`${e.helper ? `${e.helper} › ` : ''}${name}${what ? ` ${what}` : ''}`, 120), // a helper's steps: named
         kind: KIND[name] ?? 'other',
         status: 'pending',
         rawInput: args,
@@ -206,7 +206,7 @@ function events(ui, s, e) {
     }
   } else if (e.type === 'tool') {
     ui.calls = ui.calls.filter((id) => id !== e.id)
-    const failed = /^error/.test(e.output)
+    const failed = toolFailed(e.output)
     ui.update({ sessionUpdate: 'tool_call_update', toolCallId: e.id, status: failed ? 'failed' : 'completed', content: [{ type: 'content', content: { type: 'text', text: clip(plain(e.output), 4000) } }] })
     if (e.name === 'todo') ui.update({ sessionUpdate: 'plan', entries: (s.chat.todos ?? []).map((t) => ({ content: t.content, priority: 'medium', status: t.status })) })
   }