heartcode 0.1.3 → 0.1.6

package/SKILL.md

@@ -132,10 +132,12 @@ 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. Their tokens are in `usage`, and each model's in
+`modelUsage`.
 
 ## Setting up a model
 
@@ -177,6 +179,12 @@ Stdout: one JSON event per line, `system`/`init` (its `tools` include the MCP se
 `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), and `message.model` says which model it is (`provider/model`). The helper's last
+reply is that `agent` call's `tool_result`.
+
 ## 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

@@ -253,10 +253,18 @@ class App {
       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)
+    let 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)
+    // Another model in the list is asked from now on: its own abilities (sees images? its window…)
+    // and profile, not the first one's (whose profile was once saved under the next one's name).
+    client.onUse = (t) => {
+      profile = loadProfile(client) || profileFrom(client, limitsOf(t.provider, client.baseUrl, t.model))
+      Object.assign(strat, strategy(profile, cfg))
+      Object.assign(client, { tokenRatio: profile.tokenRatio ?? 1, knownGood: profile.largestAccepted ?? 0 })
+      log('rotate', `${t.provider} · ${t.model}: ${strat.actions}${strat.vision ? ', images' : ''}, ~${strat.context} tokens`)
+    }
     // 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)))
@@ -267,7 +275,7 @@ class App {
     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 +285,12 @@ 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 ? `${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(() => {
       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 +517,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' : ''}`, 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)
   }
 
@@ -626,11 +634,26 @@ class App {
     const now = this.s?.client.rotation?.list[this.s.client.rotation.at] ?? this.myModels()[0]
     return this.myModels()
       .filter((t) => !(t.provider === now?.provider && t.model === now?.model))
-      .map((t) => {
-        const cl = this.client(t.provider, t.model)
-        const st = strategy(loadProfile(cl) || profileFrom(cl, limitsOf(t.provider, cl.baseUrl, t.model)))
-        return { ...t, tools: st.actions === 'tools', images: st.vision, thinking: st.thinking, context: st.context }
-      })
+      .map((t) => ({ ...t, ...this.abilities(t) }))
+  }
+
+  // What a model can do, from its saved profile or models.dev (guessed: neither knows it).
+  abilities(t) {
+    const cl = this.client(t.provider, t.model)
+    const p = loadProfile(cl) || profileFrom(cl, limitsOf(t.provider, cl.baseUrl, t.model))
+    const st = strategy(p)
+    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)
+    return [a.tools ? 'tools' : 'no tools', a.images && 'images', a.thinking && 'thinking', kTokens(a.context) + (a.guessed ? '?' : '')].filter(Boolean).join(' · ')
   }
 
   // Your models, in order: this one (#1), then the fallbacks (chosen on /settings, where every
@@ -658,7 +681,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`, loadProfile(this.client(t.provider, t.model)) && '✓ tested'].filter(Boolean).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)
   }
@@ -1258,6 +1281,7 @@ async function repl(app, f = {}) {
   ui.onEscape = () => ctl?.abort()
   ui.onBtw = (q) => app.btw(q, true) // /btw typed while it works
   ui.isCommand = (l) => app.isCommand(l)
+  loadPrices().then(() => ui.render?.()) // models.dev: what each model can do, for the model lists
   ui.voiceConfig = () => ({ voice: cfg.voice, providers: cfg.providers })
   // Ctrl+C: stops what's running; clears the input if there's text; otherwise asks before quitting
   // (a second Ctrl+C within 2s quits, also when something is stuck).

package/package.json

@@ -1,7 +1,33 @@
 {
   "name": "heartcode",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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

@@ -170,20 +170,47 @@ The user didn't answer. Decide yourself, carry on, and say in your reply what yo
 <!-- Starts a helper agent (only in the main conversation, not in helpers). -->
 Hand a side job to a helper agent with its own fresh context, so the details stay out of this conversation: searching or reading a lot of code to answer a question, researching on the web, reviewing changes. It has the same tools (no helpers of its own) and sees only your prompt, so say exactly what to do and what to report. Its final reply comes back as the result. description: 3-5 words for the user.
 
+Several agent calls in one reply run at the same time. Use that to split independent work (one helper per part), or to ask several helpers the same thing (different models, or the same one more than once) and combine their answers: compare them, keep what they agree on, check where they differ.
+
 ## 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. Leave out to do it with yourself.
+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". 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: never two helpers on the same browser or 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.
+- Check what a helper reports before acting on it.
+
+## 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
 

package/src/acp.js

@@ -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,

package/src/agent.js

@@ -6,13 +6,38 @@ import { newChat } from './sessions.js'
 import path from 'node:path'
 import { est, Client } from './client.js'
 import { runGuided } from './guided.js'
-import { TOOL_DEFS, PLAN_HIDDEN, extraTools, runTool, listFiles, namedFiles, readFileTool, clip, allowed, loadMcpTools, saveOutput } from './tools.js'
+import { TOOL_DEFS, PLAN_HIDDEN, extraTools, runTool, listFiles, namedFiles, readFileTool, clip, allowed, loadMcpTools, saveOutput, OUTPUTS } from './tools.js'
 import { loadHooks, runHooks } from './hooks.js'
 import { takeConfigErrors } from './config.js'
 import { c } from './ui.js'
 
 const MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' }
 
+// Images for a helper (the agent tool's "images"), as data: URLs: image URLs (fetched), data: URLs,
+// or files: in the project, saved screenshots (OUTPUTS), or a path the user gave in a message.
+async function loadImages(list, s, signal) {
+  const out = []
+  for (const x of [].concat(list ?? []).map((v) => String(v).trim()).filter(Boolean)) {
+    if (x.startsWith('data:image/')) {
+      out.push(x)
+    } else if (/^https?:\/\//i.test(x)) {
+      const res = await fetch(x, { signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]) })
+      const type = res.headers.get('content-type')?.split(';')[0].trim() ?? ''
+      if (!res.ok || !type.startsWith('image/')) throw new Error(`${x} is not an image (${res.status}${type ? `, ${type}` : ''})`)
+      out.push(`data:${type};base64,${Buffer.from(await res.arrayBuffer()).toString('base64')}`)
+    } else {
+      const abs = path.resolve(s.root, x.replace(/^~(?=\/)/, os.homedir()))
+      const ext = path.extname(abs).slice(1).toLowerCase()
+      if (!MIME[ext]) throw new Error(`${x} is not an image file (png, jpg, gif, webp)`)
+      if (!fs.existsSync(abs)) throw new Error(`${x} does not exist`)
+      const inside = (dir) => abs.startsWith(dir + path.sep)
+      if (!inside(s.root) && !inside(OUTPUTS) && !s.toolImages?.has(abs) && !s.chat.turns.some((t) => t.task.includes(x) || t.task.includes(abs))) throw new Error(`${x} is outside the project; only images in it, saved screenshots and ones the user named can be sent`)
+      out.push(`data:${MIME[ext]};base64,${fs.readFileSync(abs).toString('base64')}`)
+    }
+  }
+  return out
+}
+
 // An image the message names is attached: "@shot.png", or a path anywhere (/Users/me/Downloads/a.png,
 // ~/a.png; dragged in: quoted, or with "\ " for spaces), when the file is there. The path stays in the text.
 const IMAGE_PATH = /(^|\s)@?(?:(["'])([^"'\n]+?\.(?:png|jpe?g|gif|webp))\2|((?:\\ |[^\s"'])+?\.(?:png|jpe?g|gif|webp)))(?=$|[\s,;:!?).])/gi
@@ -157,27 +182,63 @@ export class Session {
   // The agent tool: a helper with a fresh conversation and the same tools (but no helpers of its
   // own, no memory, no director) does one job; its final reply is the tool's result. Its steps show
   // under the main conversation's, its file changes count for /rewind like the main agent's.
-  // ponytail: helpers run one after another; run several at once if waiting on them gets long.
-  // model: another of your models (team) does it, for what this one can't do (see images, call tools…).
-  async subagent(args, signal) {
+  // model: one of your models (this one when left out); images: for it to look at (it must see).
+  // A helper that fails or replies with nothing: the job goes to the next of your models that can
+  // do it, until one does. id: the agent tool call's; the helper's steps go to onEvent (headless,
+  // ACP) as that call's.
+  async subagent(args, signal, id) {
     const task = String(args.prompt ?? args.task ?? '').trim()
     if (!task) return 'error: give the helper its job in "prompt"'
-    let { client, profile, strat } = this
+    let images
+    try {
+      images = await loadImages(args.images, this, signal)
+    } catch (e) {
+      if (e.name === 'AbortError') throw e
+      return `error: ${e.message}`
+    }
+    const name = (t) => `${t.provider} ${t.model}`
+    const self = { provider: this.client.provider, model: this.client.model, images: this.strat.vision, self: true }
+    const all = [self, ...(this.team?.() ?? [])]
     const want = String(args.model ?? '').trim()
-    if (want) {
-      const team = this.team?.() ?? []
-      const t = team.find((x) => `${x.provider} ${x.model}` === want) ?? team.find((x) => x.model === want || want.endsWith(` ${x.model}`))
-      if (!t) return `error: no model "${want}". Yours: ${team.map((x) => `${x.provider} ${x.model}`).join(', ') || 'none besides this one'}`
+    const first = !want ? self : (all.find((t) => name(t) === want) ?? all.find((t) => t.model === want || want.endsWith(` ${t.model}`)))
+    if (!first) return `error: no model "${want}". Yours: ${all.map(name).join(', ')}`
+    const able = (t) => !images.length || t.images
+    const order = [first, ...all.filter((t) => t !== first)].filter(able)
+    if (!order.length) return 'error: none of your models can see images'
+    const failed = []
+    for (const [i, t] of order.entries()) {
+      let answer = ''
+      try {
+        answer = (await this.#helper(t, task, images, args.description, id, signal))?.trim()
+      } catch (e) {
+        if (e.name === 'AbortError' || signal?.aborted) throw e
+        failed.push(`${t.model}: ${clip(e.message, 150)}`)
+      }
+      if (answer) return t === first ? answer : `(${name(t)} did it${failed.length ? `; before it: ${failed.join('; ')}` : ''})\n\n${answer}`
+      if (failed.length < i + 1) failed.push(`${t.model}: no reply`)
+      this.failures = { ...this.failures, [name(t)]: (this.failures?.[name(t)] ?? 0) + 1 } // shown to the model (Your other models)
+      if (order[i + 1]) this.ui.warn(`${t.model} couldn't do it (${failed.at(-1).slice(t.model.length + 2)}); handing it to ${order[i + 1].model}`)
+    }
+    return `error: none of your models that can do it managed: ${failed.join('; ')}`
+  }
+
+  // One helper on one model (t: this one, or another of yours).
+  async #helper(t, task, images, description, id, signal) {
+    let { client, profile, strat } = this
+    if (!t.self) {
       ;({ client, profile, strat } = await this.engineFor(t))
+      const was = client.retryIf
+      client.retryIf = (e, attempt) => attempt < 3 && (!was || was(e, attempt)) // then the next model gets the job
     }
-    const label = clip((want ? `${client.model}: ` : '') + (String(args.description ?? '').trim() || task.split('\n')[0]), 60)
+    const label = clip(`${client.model}: ${String(description ?? '').trim() || task.split('\n')[0]}`, 60)
     const helper = new Session({ client, profile, strat, root: this.root, ui: helperUI(this.ui, label), chat: newChat(this.root) })
     Object.assign(helper, { isSub: true, mcp: this.mcp, skills: this.skills, hooks: this.hooks, allowTools: this.allowTools, denyTools: this.denyTools, maxTurns: this.maxTurns, autoCompact: this.autoCompact, appendSystem: this.appendSystem, fileCache: this.fileCache, noFormat: this.noFormat, noLsp: this.noLsp })
     helper.track = (rel, before) => this.track(rel, before)
-    log('agent', `helper "${label}": ${task}`)
-    const answer = await (strat.actions === 'tools' ? runNative : runGuided)(helper, task, [], signal)
+    if (this.onEvent) helper.onEvent = (e) => this.onEvent({ ...e, parent: id, helper: label })
+    log('agent', `helper "${label}" (${images.length} image(s)): ${task}`)
+    const answer = await (strat.actions === 'tools' ? runNative : runGuided)(helper, task, images, signal)
     log('agent', `helper "${label}" done`, answer)
-    return answer?.trim() || '(the helper finished without a reply)'
+    return answer
   }
 
   // Images for a model that can't see them: another of yours (seer) describes each, for the task.
@@ -309,6 +370,7 @@ const SYSTEM = (s) => {
     prompt('agent/system', { root: s.root, files: '', more: '', caller: Boolean(s.appendSystem) }),
     instructions && prompt('agent/instructions', { instructions }),
     s.memory && prompt('agent/memory', { tags: s.memory.tagSummary() || '(none yet)' }),
+    s.strat.vision && prompt('agent/you-see'), // models that can see often say they can't
     s.mcpInstructions && prompt('agent/mcp-instructions', { instructions: s.mcpInstructions }), // what the MCP servers say about their tools
     s.director && !s.appendSystem && s.director.app.cfg.director !== false && prompt('agent/director'),
     !s.isSub && teamPrompt(s),
@@ -324,7 +386,8 @@ const SYSTEM = (s) => {
 const teamPrompt = (s) => {
   const team = s.team?.() ?? []
   if (!team.length) return ''
-  const can = (t) => [t.tools ? 'tool calls' : 'no tool calls', t.images && 'images', t.thinking && 'thinking', `${Math.round(t.context / 1000)}k context`].filter(Boolean).join(', ')
+  const fails = (t) => s.failures?.[`${t.provider} ${t.model}`] && `failed ${s.failures[`${t.provider} ${t.model}`]}× this session`
+  const can = (t) => [t.tools ? 'tool calls' : 'no tool calls', t.images && 'images', t.thinking && 'thinking', `${Math.round(t.context / 1000)}k context`, fails(t)].filter(Boolean).join(', ')
   const you = [s.strat.vision ? 'images' : 'no images', s.strat.thinking && 'thinking'].filter(Boolean).join(', ')
   return prompt('agent/team', { models: team.map((t) => `- ${t.provider} ${t.model}: ${can(t)}`).join('\n'), you })
 }
@@ -542,10 +605,13 @@ async function runNative(s, task, images, signal) {
       log('task', 'the user added while working:', added)
       s.messages.push({ role: 'user', content: prompt('agent/user-added', { text: added.join('\n\n') }) })
     }
+    // the model answering can change mid-message (your model list): the system prompt follows it
+    const now = SYSTEM(s)
+    if (s.messages[0]?.content !== now && (s.messages[0]?.role === 'system' || strat.mergeSystem)) s.messages[0] = { ...s.messages[0], content: now }
     fitMessages(s.messages, budget())
     pairTools(s.messages)
     ui.spinner('thinking')
-    const out = ui.response()
+    const out = ui.response(client.model) // named: helpers think too (theirs are named in helperUI)
     const stream = strat.toolsStream
     let res
     try {
@@ -575,7 +641,7 @@ async function runNative(s, task, images, signal) {
       res.content = ''
       s.messages[s.messages.length - 1] = { role: 'assistant', content: '', tool_calls: res.toolCalls }
     }
-    s.onEvent?.({ type: 'assistant', content: res.content, reasoning: res.reasoning, toolCalls: res.toolCalls }) // headless output
+    s.onEvent?.({ type: 'assistant', model: `${client.provider}/${client.model}`, content: res.content, reasoning: res.reasoning, toolCalls: res.toolCalls }) // headless output
     if (!res.toolCalls.length && !res.content?.trim()) {
       // Nothing at all (seen after a failed tool call): not an answer. The same request again
       // first (often fine the second time), then asked to go on; three in a row ends the task.
@@ -604,12 +670,25 @@ async function runNative(s, task, images, signal) {
       continue
     }
 
+    // Helpers (agent) asked for in one reply work at the same time: the same model or several.
+    // ponytail: no cap on how many at once; add one if a provider's rate limit makes them crawl.
+    const argsOf = (call) => {
+      try {
+        return JSON.parse(call.function.arguments || '{}')
+      } catch {
+        return null
+      }
+    }
+    const together = new Map()
+    for (const call of res.toolCalls) {
+      const args = argsOf(call)
+      if (call.function.name !== 'agent' || !args || !allowed(s, 'agent') || res.toolCalls.filter((x) => x.function.name === 'agent').length < 2) continue
+      ui.step('agent', clip([args.model && `${args.model}:`, args.description].filter(Boolean).join(' '), 80))
+      together.set(call.id, runTool('agent', args, s, signal, call.id))
+    }
     for (const call of res.toolCalls) {
       const name = call.function.name
-      let args = null
-      try {
-        args = JSON.parse(call.function.arguments || '{}')
-      } catch {}
+      const args = argsOf(call)
       const detail = !args
         ? ''
         : args.server
@@ -619,12 +698,12 @@ async function runNative(s, task, images, signal) {
             : name === 'manage'
               ? [args.action, args.kind, args.name].filter(Boolean).join(' ')
               : name === 'agent'
-                ? (args.description ?? '')
+                ? [args.model && `${args.model}:`, args.description].filter(Boolean).join(' ')
                 : name === 'todo' || name === 'ask_user'
                   ? ''
                   : (args.path ?? args.url ?? args.query ?? args.filter ?? args.name ?? '')
-      if (name !== 'run_command') ui.step(name, clip(detail, 80))
-      const out = !allowed(s, name) ? `error: the tool ${name} is not allowed here` : args ? await runTool(name, args, s, signal) : 'error: the tool arguments were not valid JSON'
+      if (name !== 'run_command' && !together.has(call.id)) ui.step(name, clip(detail, 80))
+      const out = together.has(call.id) ? await together.get(call.id) : !allowed(s, name) ? `error: the tool ${name} is not allowed here` : args ? await runTool(name, args, s, signal, call.id) : 'error: the tool arguments were not valid JSON'
       if (name === 'read_file' || name === 'search' || name === 'list_files' || name === 'web_fetch' || name === 'web_search') ui.result(`${out.split('\n').length} lines`)
       else if (name === 'agent' && !out.startsWith('error')) ui.result(`${s.ui.permission === 'plan' ? 'planned' : 'done'}: ${clip(out.split('\n').find((l) => l.trim()) ?? '', 100)}`)
       else if (out.startsWith('error')) ui.result(clip(out, 120))
@@ -657,13 +736,36 @@ async function notDone(s, signal, again) {
 
 // A helper agent's view of the screen: its steps are labelled, and its replies (which go to the
 // main agent) aren't shown as answers. Everything else is the main UI's.
+// Its thinking is shown whole when its reply is in (helpers working at once don't mix), named.
+// Questions to the user (confirm, pick, ask) wait their turn: helpers working at once ask one by one.
+const asking = new WeakMap() // ui → the question being asked
 function helperUI(ui, label) {
-  const quiet = { think() {}, text() {}, end() {} }
+  const response = () => {
+    const t0 = Date.now()
+    let thought = ''
+    return {
+      think: (t) => (thought += t ?? ''),
+      text() {},
+      end() {
+        if (!thought.trim()) return
+        const secs = ((Date.now() - t0) / 1000).toFixed(1)
+        ui.print(c.faint(c.italic(`  ✻ ${label} thought for ${secs}s`)) + (ui.showThinking ? `\n${c.think(c.italic(thought.trim().replace(/^/gm, '    ')))}` : ''))
+      },
+    }
+  }
+  const inTurn = (k) => (...a) => {
+    const next = (asking.get(ui) ?? Promise.resolve()).then(() => ui[k](...a))
+    asking.set(ui, next.catch(() => {}))
+    return next
+  }
   const own = {
     step: (name, detail) => ui.step(`  ${label} › ${name}`, detail),
     result: (text) => ui.result(`  ${text}`),
-    response: () => quiet,
+    response,
     spinner: (text) => ui.spinner(`${label} · ${text}`),
+    confirm: inTurn('confirm'),
+    pick: inTurn('pick'),
+    ask: inTurn('ask'),
   }
   return new Proxy(ui, { get: (t, k) => (k in own ? own[k] : typeof t[k] === 'function' ? t[k].bind(t) : t[k]), set: (t, k, v) => ((t[k] = v), true) })
 }

package/src/client.js

@@ -161,9 +161,12 @@ export class Client {
     const r = this.rotation
     if (r && r.next === 'first' && r.at) this.#use(r.list[(r.at = 0)])
   }
+  // onUse(target): the model the next request goes to changed (its abilities and profile follow)
   #use(t) {
+    const changed = this.model !== t.model || this.baseUrl !== normalizeBaseUrl(t.baseUrl)
     Object.assign(this, { baseUrl: normalizeBaseUrl(t.baseUrl), apiKey: t.apiKey, model: t.model, provider: t.provider })
     this.quirks = t.quirks ?? (t.quirks = {})
+    if (changed) this.onUse?.(t)
   }
   // After a failure: go on to the next model? (then it's tried at once)
   #rotate(e, tries) {

package/src/headless.js

@@ -127,10 +127,11 @@ export async function runHeadless(app, opts) {
           ...(e.content ? [{ type: 'text', text: e.content }] : []),
           ...e.toolCalls.map((t) => ({ type: 'tool_use', id: t.id, name: t.function.name, input: parseArgs(t.function.arguments) })),
         ]
-        if (e.content) said = true
-        if (content.length) emit({ type: 'assistant', message: { role: 'assistant', model, content }, session_id })
+        if (e.content && !e.parent) said = true
+        // a helper's (agent) steps too, as Claude Code sends a subagent's: parent_tool_use_id is its agent call
+        if (content.length) emit({ type: 'assistant', message: { role: 'assistant', model: e.parent ? e.model : model, content }, parent_tool_use_id: e.parent ?? null, session_id })
       } else if (e.type === 'tool') {
-        emit({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: e.id, content: e.output, is_error: e.output.startsWith('error') }] }, session_id })
+        emit({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: e.id, content: e.output, is_error: e.output.startsWith('error') }] }, parent_tool_use_id: e.parent ?? null, session_id })
       }
     }
     if (s.strat.actions === 'tools' && s.mcp?.names.length) await loadMcpTools(s) // their tools are in the list, as in Claude Code's
@@ -165,7 +166,7 @@ export async function runHeadless(app, opts) {
     current = null
     const result = { type: 'result', subtype, is_error: Boolean(error), result: error ?? answer, num_turns: Math.max(1, requests), duration_ms: Date.now() - t0, total_cost_usd: (app.chat.usage?.cost ?? 0) - spent, usage, modelUsage: { [model]: { inputTokens: 0, outputTokens: 0 }, ...byModel }, session_id }
     if (out === 'stream-json') {
-      if (!error && answer && !said) emit({ type: 'assistant', message: { role: 'assistant', model, content: [{ type: 'text', text: answer }] }, session_id }) // guided mode
+      if (!error && answer && !said) emit({ type: 'assistant', message: { role: 'assistant', model, content: [{ type: 'text', text: answer }] }, parent_tool_use_id: null, session_id }) // guided mode
       emit(result)
     } else if (out === 'json') emit(result)
     else if (error) process.stderr.write(`heartcode: ${error}\n`)

package/src/probe.js

@@ -21,7 +21,8 @@ export const profilePath = (client) => {
 const PROBE_VERSION = 2
 export const loadProfile = (client) => {
   const p = readJson(profilePath(client), null)
-  return p?.version === PROBE_VERSION ? p : null
+  // another model's (a model list switch once saved the first model's profile under the next one's name)
+  return p?.version === PROBE_VERSION && (!p.model || p.model === client.model) ? p : null
 }
 
 // --- tiny PNG encoder, for the vision probe ---

package/src/tools.js

@@ -23,12 +23,13 @@ export const tail = (s, n) => (s.length > n ? '…' + s.slice(-n) : s)
 // Tool output too long for the conversation is saved here (one folder per chat), where read_file
 // and search can read it although it's outside the project.
 export const OUTPUTS = path.join(os.tmpdir(), 'heartcode-outputs')
-export function saveOutput(chatId, name, text) {
+// data: text, or an image's bytes (ext: png…)
+export function saveOutput(chatId, name, data, ext = 'txt') {
   try {
     const dir = path.join(OUTPUTS, String(chatId ?? 'chat'))
     fs.mkdirSync(dir, { recursive: true })
-    const file = path.join(dir, `${Date.now().toString(36)}-${String(name).replace(/[^\w-]/g, '_').slice(0, 60)}.txt`)
-    fs.writeFileSync(file, text)
+    const file = path.join(dir, `${Date.now().toString(36)}-${String(name).replace(/[^\w-]/g, '_').slice(0, 60)}.${ext}`)
+    fs.writeFileSync(file, data)
     return file
   } catch (e) {
     log('tool', `could not save the output: ${e.message}`)
@@ -487,7 +488,8 @@ export function extraTools(s) {
   if (!s.isSub && s.subagent) {
     const team = s.team?.() ?? []
     const model = { type: 'string', description: prompt('agent/tool-agent-model') }
-    out.push({ name: 'agent', description: prompt('agent/tool-agent'), parameters: obj({ description: str, prompt: str, ...(team.length && { model }) }, ['description', 'prompt']) })
+    const images = { type: 'array', items: str, description: prompt('agent/tool-agent-images') }
+    out.push({ name: 'agent', description: prompt('agent/tool-agent'), parameters: obj({ description: str, prompt: str, ...(team.length && { model, images }) }, ['description', 'prompt']) })
   }
   return [...out, ...(s.director && !s.appendSystem ? s.director.toolDefs(s) : [])] // manage (director.js); not when a program gives the instructions (--append-system-prompt)
 }
@@ -628,10 +630,21 @@ async function callMcp(s, server, tool, a, signal) {
   const parts = r.content ?? []
   const text = parts.filter((p) => p.type === 'text').map((p) => p.text).join('\n')
   const images = parts.filter((p) => p.type === 'image' && p.data)
+  // image files the tool says it saved ("Saved screenshot to /…/shot.webp"): as if returned
+  const saved = [...new Set([...text.matchAll(/(?:^|[\s"'`(])((?:\/|~\/)[^\s"'`)]+\.(?:png|jpe?g|gif|webp))\b/gi)].map((m) => m[1].replace(/^~(?=\/)/, os.homedir())))].filter((f) => fs.existsSync(f))
+  if (saved.length) {
+    s.toolImages ??= new Set()
+    for (const f of saved) s.toolImages.add(f) // may be sent to a helper (agent images)
+    if (s.strat?.vision) images.push(...saved.map((f) => ({ data: fs.readFileSync(f).toString('base64'), mimeType: `image/${path.extname(f).slice(1).toLowerCase().replace('jpg', 'jpeg')}`, file: f })))
+  }
   let note = ''
   if (images.length && s.strat?.vision) {
     ;(s.pendingImages ??= []).push(...images.map((p) => `data:${p.mimeType ?? 'image/png'};base64,${p.data}`))
     note = `\n(${images.length} image(s) attached in the next message)`
+  } else if ((images.length || saved.length) && s.team?.().some((t) => t.images)) {
+    // saved, for a model that can see to be asked about (the agent tool's images)
+    const files = [...images.map((p, i) => saveOutput(s.chat?.id, `${tool}-${i + 1}`, Buffer.from(p.data, 'base64'), (p.mimeType ?? 'image/png').split('/')[1].replace('jpeg', 'jpg'))).filter(Boolean), ...saved]
+    note = `\n${prompt('agent/images-unseen', { files: files.join('\n') })}`
   } else if (images.length) note = `\n(${images.length} image(s) not shown: this model can't see images)`
   return `${r.isError ? 'error: ' : ''}${text || '(no text)'}${note}`
 }
@@ -782,11 +795,12 @@ async function applyPatch(s, text) {
 }
 
 // Every tool call goes through the user's PreToolUse and PostToolUse hooks (hooks.js).
-export async function runTool(name, args, s, signal) {
+// id: the tool call's (a helper's steps are sent as its, for other apps to show under it)
+export async function runTool(name, args, s, signal, id) {
   log('tool', name, args)
   const pre = await runHooks(s, 'PreToolUse', { tool_name: name, tool_input: args }, signal)
   if (pre.block) return prompt('agent/hook-blocked-tool', { reason: pre.block })
-  let out = await tool(name, args, s, signal)
+  let out = await tool(name, args, s, signal, id)
   const post = await runHooks(s, 'PostToolUse', { tool_name: name, tool_input: args, tool_response: out }, signal)
   if (post.block) out += `\n\n${prompt('agent/hook-after-tool', { reason: post.block })}`
   log('tool', `${name} result:`, clip(out, 4000))
@@ -822,7 +836,7 @@ export function allowed(s, name) {
   return names.some((n) => s.allowTools.has(n)) || (name === 'mcp' && [...s.allowTools].some((n) => n.startsWith('mcp__')))
 }
 
-async function tool(name, args, s, signal) {
+async function tool(name, args, s, signal, id) {
   if (!name.startsWith('mcp__') && !mcpTarget(s, name)) args = normalize(args) // an MCP tool's arguments are its own
   try {
     const { root } = s
@@ -865,7 +879,7 @@ async function tool(name, args, s, signal) {
       case 'web_fetch':
         return await webTool(s, name, args, signal)
       case 'agent':
-        return await s.subagent(args, signal)
+        return await s.subagent(args, signal, id)
       case 'ask_user':
         return await askUser(s, args)
       case 'skill': {

package/src/ui.js

@@ -399,7 +399,8 @@ export class UI {
   }
 
   // One model reply: thinking (dim, its own block) kept apart from the answer.
-  response() {
+  // who: the model thinking, named over its thinking (helpers say their own: helperUI in agent.js)
+  response(who) {
     const t0 = Date.now()
     const secs = () => ((Date.now() - t0) / 1000).toFixed(1)
     const write = (x) => this.write(x)
@@ -407,7 +408,7 @@ export class UI {
     let text = null
     let thought = false
     const summary = () => {
-      if (thought && !this.showThinking) this.print(c.faint(c.italic(`✻ thought for ${secs()}s`)))
+      if (thought && !this.showThinking) this.print(c.faint(c.italic(`✻ ${who ? `${who} ` : ''}thought for ${secs()}s`)))
     }
     return {
       think: (t) => {
@@ -416,7 +417,7 @@ export class UI {
         if (!this.showThinking) return this.spinner(`thinking · ${secs()}s`)
         if (!think) {
           this.gap()
-          this.print(c.faint(c.italic('✻ Thinking…')))
+          this.print(c.faint(c.italic(`✻ ${who ? `${who} is thinking` : 'Thinking'}…`)))
           think = new Block(write, { style: (x) => c.think(c.italic(x)) })
         }
         think.push(t)
@@ -705,7 +706,13 @@ export class UI {
         m.off = rl.line
         return this.refreshMenu()
       }
-      if (m.on && key.name === 'tab') return it && this.#accept(it)
+      // Tab only completes the text: the menu closes (no list of a command's choices pops up); Enter runs it
+      if (m.on && key.name === 'tab') {
+        if (!it) return
+        this.#accept(it)
+        m.off = rl.line
+        return this.refreshMenu()
+      }
       if (it && key.name === 'return' && rl.line.slice(it.start, it.end) !== it.value) {
         this.#accept(it)
         if (it.insertOnly) return