@hncode/hncode 0.4.1 → 0.5.0

package/src/term.js

@@ -167,6 +167,113 @@ function isWideByDefault(c) {
     || (c >= 0x2B1B && c <= 0x2B1C) || c === 0x2B50 || c === 0x2B55;
 }
 
+// ---------------------------------------------------------------------------
+// East Asian AMBIGUOUS width
+// ---------------------------------------------------------------------------
+// Unicode gives every character an East Asian Width class. `A` (Ambiguous) means
+// ONE column on a Western terminal and TWO on a CJK one — the terminal decides, the
+// character does not say. hncode's chrome leans on these heavily, which is why they
+// had to be handled rather than avoided:
+//
+//   box rules   ─ │ ╭ ╮ ╰ ╯ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼
+//   separators  ·  …  —  –
+//   markers     ↑ ↓ ← → ❯ ● ○ ✓ ✗
+//   math        ± × ÷ ≠ ≤ ≥ ∞
+//
+// Measuring them as 1 column on a CJK terminal made every row containing one N columns
+// short, so the row's right edge landed N columns past the panel it belonged to —
+// "the text pushes the wall right". The panel's own background could not hide it
+// either: the overflow is REAL cells on screen, not a measurement disagreement inside
+// one row.
+//
+// Default: follow the LOCALE. A CJK locale is the standard reason a terminal treats
+// EAW=A as wide, and it is the only signal available before anything is drawn — the
+// code page does not say (a UTF-8 Windows console still renders them wide), and no
+// terminal query reports it.
+let ambiguousWide = null;   // lazily resolved so a test can set the env first
+
+/** EAW=A ranges (Unicode 15), ascending — `inRanges` binary-searches this. */
+const AMBIGUOUS = [
+  [0x00A1, 0x00A1], [0x00A4, 0x00A4], [0x00A7, 0x00A8], [0x00AA, 0x00AA],
+  [0x00AD, 0x00AE], [0x00B0, 0x00B4], [0x00B6, 0x00BA], [0x00BC, 0x00BF],
+  [0x00C6, 0x00C6], [0x00D0, 0x00D0], [0x00D7, 0x00D8], [0x00DE, 0x00E1],
+  [0x00E6, 0x00E6], [0x00E8, 0x00EA], [0x00EC, 0x00ED], [0x00F0, 0x00F0],
+  [0x00F2, 0x00F3], [0x00F7, 0x00FA], [0x00FC, 0x00FC], [0x00FE, 0x00FE],
+  [0x0101, 0x0101], [0x0111, 0x0111], [0x0113, 0x0113], [0x011B, 0x011B],
+  [0x0126, 0x0127], [0x012B, 0x012B], [0x0131, 0x0133], [0x0138, 0x0138],
+  [0x013F, 0x0142], [0x0144, 0x0144], [0x0148, 0x014B], [0x014D, 0x014D],
+  [0x0152, 0x0153], [0x0166, 0x0167], [0x016B, 0x016B], [0x01CE, 0x01CE],
+  [0x01D0, 0x01D0], [0x01D2, 0x01D2], [0x01D4, 0x01D4], [0x01D6, 0x01D6],
+  [0x01D8, 0x01D8], [0x01DA, 0x01DA], [0x01DC, 0x01DC], [0x0251, 0x0251],
+  [0x0261, 0x0261], [0x02C4, 0x02C4], [0x02C7, 0x02C7], [0x02C9, 0x02CB],
+  [0x02CD, 0x02CD], [0x02D0, 0x02D0], [0x02D8, 0x02DB], [0x02DD, 0x02DD],
+  [0x02DF, 0x02DF], [0x0300, 0x036F], [0x0391, 0x03A1], [0x03A3, 0x03A9],
+  [0x03B1, 0x03C1], [0x03C3, 0x03C9], [0x0401, 0x0401], [0x0410, 0x044F],
+  [0x0451, 0x0451], [0x2010, 0x2010], [0x2013, 0x2016], [0x2018, 0x2019],
+  [0x201C, 0x201D], [0x2020, 0x2022], [0x2024, 0x2027], [0x2030, 0x2030],
+  [0x2032, 0x2033], [0x2035, 0x2035], [0x203B, 0x203B], [0x203E, 0x203E],
+  [0x2074, 0x2074], [0x207F, 0x207F], [0x2081, 0x2084], [0x20AC, 0x20AC],
+  [0x2103, 0x2103], [0x2105, 0x2105], [0x2109, 0x2109], [0x2113, 0x2113],
+  [0x2116, 0x2116], [0x2121, 0x2122], [0x2126, 0x2126], [0x212B, 0x212B],
+  [0x2153, 0x2154], [0x215B, 0x215E], [0x2160, 0x216B], [0x2170, 0x2179],
+  [0x2189, 0x2189], [0x2190, 0x2199], [0x21B8, 0x21B9], [0x21D2, 0x21D2],
+  [0x21D4, 0x21D4], [0x21E7, 0x21E7], [0x2200, 0x2200], [0x2202, 0x2203],
+  [0x2207, 0x2208], [0x220B, 0x220B], [0x220F, 0x220F], [0x2211, 0x2211],
+  [0x2215, 0x2215], [0x221A, 0x221A], [0x221D, 0x2220], [0x2223, 0x2223],
+  [0x2225, 0x2225], [0x2227, 0x222C], [0x222E, 0x222E], [0x2234, 0x2237],
+  [0x223C, 0x223D], [0x2248, 0x2248], [0x224C, 0x224C], [0x2252, 0x2252],
+  [0x2260, 0x2261], [0x2264, 0x2267], [0x226A, 0x226B], [0x226E, 0x226F],
+  [0x2282, 0x2283], [0x2286, 0x2287], [0x2295, 0x2295], [0x2299, 0x2299],
+  [0x22A5, 0x22A5], [0x22BF, 0x22BF], [0x2312, 0x2312], [0x2460, 0x24E9],
+  [0x24EB, 0x254B], [0x2550, 0x2573], [0x2580, 0x258F], [0x2592, 0x2595],
+  [0x25A0, 0x25A1], [0x25A3, 0x25A9], [0x25B2, 0x25B3], [0x25B6, 0x25B7],
+  [0x25BC, 0x25BD], [0x25C0, 0x25C1], [0x25C6, 0x25C8], [0x25CB, 0x25CB],
+  [0x25CE, 0x25D1], [0x25E2, 0x25E5], [0x25EF, 0x25EF], [0x2605, 0x2606],
+  [0x2609, 0x2609], [0x260E, 0x260F], [0x261C, 0x261C], [0x261E, 0x261E],
+  [0x2640, 0x2640], [0x2642, 0x2642], [0x2660, 0x2661], [0x2663, 0x2665],
+  [0x2667, 0x266A], [0x266C, 0x266D], [0x266F, 0x266F], [0x269E, 0x269F],
+  [0x26C6, 0x26CD], [0x26CF, 0x26D3], [0x26D5, 0x26E1], [0x26E3, 0x26E3],
+  [0x26E8, 0x26E9], [0x26EB, 0x26F1], [0x26F4, 0x26F4], [0x26F6, 0x26F9],
+  [0x26FB, 0x26FC], [0x26FE, 0x26FF], [0x273D, 0x273D], [0x2761, 0x2761],
+  [0x2776, 0x277F], [0x2B56, 0x2B59], [0x3248, 0x324F], [0xE000, 0xF8FF],
+  [0xFE00, 0xFE0F], [0xFFFD, 0xFFFD], [0x1F100, 0x1F10A],
+  [0x1F110, 0x1F12D], [0x1F130, 0x1F169], [0x1F170, 0x1F19A],
+];
+
+/**
+ * Should EAW=Ambiguous characters measure 2 columns?
+ *
+ * Resolved once, from (in order):
+ *   1. `HNCODE_AMBIGUOUS_WIDTH` — an explicit override, for a terminal whose setting
+ *      does not match its locale;
+ *   2. the locale — `zh`/`ja`/`ko` mean a CJK terminal, which is the standard reason a
+ *      terminal renders these wide.
+ */
+export function detectAmbiguousWide(env = process.env) {
+  const raw = env.HNCODE_AMBIGUOUS_WIDTH;
+  if (raw !== undefined && raw !== '') return /^(1|true|yes|on)$/i.test(raw);
+  let loc = '';
+  try { loc = (Intl.DateTimeFormat().resolvedOptions().locale) || ''; } catch { /* no Intl */ }
+  const tag = loc || env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+  return /^(zh|ja|ko)\b/i.test(tag) || /^(zh|ja|ko)[-_]/i.test(tag);
+}
+
+export function isAmbiguousWide() {
+  if (ambiguousWide === null) ambiguousWide = detectAmbiguousWide();
+  return ambiguousWide;
+}
+
+/**
+ * Turn the ambiguous-as-wide rule on or off. Clears the width cache, which is keyed by
+ * string alone and would otherwise hand back widths measured under the other rule.
+ */
+export function setAmbiguousWide(on) {
+  const next = !!on;
+  if (next === ambiguousWide) return;
+  ambiguousWide = next;
+  widthCache.clear();
+}
+
 const inRanges = (c, ranges) => {
   let lo = 0, hi = ranges.length - 1;
   while (lo <= hi) {
@@ -255,9 +362,46 @@ function clusterGlyphWidth(cluster) {
 //   tokens = ceil(ASCII chars / 4) + non-ASCII chars
 // ASCII characters average ~4 per token; CJK and other non-ASCII are ~1 token
 // each. This is far more accurate than a uniform chars/4 ratio.
+// Token estimate. The character walk is O(len), and the context gauge re-prices
+// whole message bodies (a Read result can be hundreds of KB) every turn.
+//
+// A value cache only helps COMPLETED messages: they are immutable, so the same
+// string is measured again and again. It actively HURTS streaming text, where the
+// string grows every frame — every call is a miss, so the cache pays hashing and an
+// insert each time and (once full) an O(n) eviction sweep, measuring 1ms/call vs
+// ~0.001ms for a plain walk (30k growing-text calls: 31s cached vs 30ms uncached).
+//
+// So the cache is limited to SHORT strings: completed metadata and role names hit
+// it, while a long or growing body is just walked directly. At most 4 KB was chosen
+// because a token estimate is only ever re-asked for values that are cheap to hold
+// and genuinely stable; anything larger is better re-walked than hashed + stored.
+const tokCache = new Map();
+const TOK_CACHE_MAX = 20000;
+const TOK_CACHE_MAX_LEN = 4096;   // only memoise strings this short
+
 export function estimateTokens(text) {
+  const s = String(text ?? '');
+  if (s.length <= TOK_CACHE_MAX_LEN) {
+    const hit = tokCache.get(s);
+    if (hit !== undefined) return hit;
+    let ascii = 0, nonAscii = 0;
+    for (const ch of s) {
+      if (ch.codePointAt(0) <= 127) ascii++;
+      else nonAscii++;
+    }
+    const out = Math.ceil(ascii / 4) + nonAscii;
+    if (tokCache.size >= TOK_CACHE_MAX) {
+      // Drop the oldest half in one go: cheaper than one-at-a-time and keeps the
+      // recently measured entries that a per-entry eviction would churn.
+      let i = 0;
+      for (const k of tokCache.keys()) { tokCache.delete(k); if (++i >= TOK_CACHE_MAX / 2) break; }
+    }
+    tokCache.set(s, out);
+    return out;
+  }
+  // Long body: walk it. No memoise, no map churn.
   let ascii = 0, nonAscii = 0;
-  for (const ch of String(text ?? '')) {
+  for (const ch of s) {
     if (ch.codePointAt(0) <= 127) ascii++;
     else nonAscii++;
   }
@@ -273,17 +417,148 @@ export function estimateTokens(text) {
 // estimateRequestOverhead().
 export function estimateMessagesTokens(messages, cfg) {
   let total = 0;
-  for (const m of messages || []) {
-    total += estimateTokens(m.role || '');
-    const c = m.content;
-    total += typeof c === 'string' ? estimateTokens(c) : estimateTokens(JSON.stringify(c || ''));
-    if (m.toolCalls) for (const tc of m.toolCalls) {
-      total += estimateTokens(tc.name || '') + estimateTokens(JSON.stringify(tc.args || ''));
-    }
+  for (const m of messages || []) total += estimateMessageTokens(m, cfg);
+  return total;
+}
+
+/**
+ * Tokens for ONE message. Split out so callers that walk the history (e.g.
+ * planCompaction) can price each message ONCE instead of re-summing the whole
+ * array per message — that was O(n²) over the transcript.
+ */
+export function estimateMessageTokens(m, cfg) {
+  if (!m) return 0;
+  let total = estimateTokens(m.role || '');
+  const c = m.content;
+  total += typeof c === 'string' ? estimateTokens(c) : estimateTokens(JSON.stringify(c || ''));
+  if (m.toolCalls) for (const tc of m.toolCalls) {
+    total += estimateTokens(tc.name || '') + estimateTokens(JSON.stringify(tc.args || ''));
   }
   return total;
 }
 
+// ---- per-message token memo -----------------------------------------------
+//
+// Message objects -> { sig, tok }. WeakMap, so a message dropped from the history
+// takes its estimate with it: no unbounded growth, and no manual eviction policy.
+const msgTokMemo = new WeakMap();
+//
+// `estimateMessageTokens` above re-measures an immutable message every time it is
+// asked, and the askers are frequent: the context gauge runs at every step, and
+// compaction walks the whole history to find its cut point. A Read result can be
+// hundreds of KB, so re-walking one costs milliseconds (measured: a 300 KB body is
+// ~5.3 ms to price). Completed messages never change, so their estimate never has
+// to be recomputed.
+//
+// The memo is a WeakMap keyed on the MESSAGE OBJECT, which gives two properties for
+// free: it cannot leak (a dropped message takes its entry with it) and it cannot
+// collide (two equal messages are still two objects).
+//
+// Correctness — the one place a stored message changes underneath us —
+// --------------------------------------------------------------------
+// `trimToolResults` rewrites `m.content` IN PLACE, replacing a large body with a
+// short pointer. A memo that trusted object identity alone would keep serving the
+// pre-trim count, and the gauge would claim the context was still full right after
+// the very operation meant to shrink it — the trim would appear to do nothing and
+// the next request would compact again for no reason.
+//
+// So every entry stores a cheap SIGNATURE of the content alongside the number, and
+// a mismatch recomputes. `.length` on a string is O(1), which is what makes this
+// affordable: streaming text (which grows every frame) misses on the signature and
+// is re-walked, exactly as `estimateTokens`' own short-string cache already
+// established. Content that is neither a string nor an array gets a weaker
+// signature and is simply re-measured each time rather than risk a stale answer.
+function msgSignature(m) {
+  const c = m.content;
+  let s;
+  if (typeof c === 'string') s = 's' + c.length;
+  else if (c == null) s = 'n';
+  else if (Array.isArray(c)) s = 'a' + c.length;
+  else s = '';                       // unknown shape: never trust a memo
+  if (m.toolCalls) s += 't' + m.toolCalls.length;
+  return s;
+}
+
+/** Drop any memoised estimate for a message whose content was rewritten in place. */
+export function forgetMessageTokens(m) {
+  if (m && typeof m === 'object') msgTokMemo.delete(m);
+}
+
+/**
+ * `estimateMessageTokens`, memoised per message object.
+ *
+ * Safe to call on STREAMING messages too: the signature check misses on every
+ * frame, so a growing body is simply re-measured and never served stale.
+ */
+export function messageTokens(m, cfg) {
+  if (!m || typeof m !== 'object') return estimateMessageTokens(m, cfg);
+  const sig = msgSignature(m);
+  if (sig !== '') {
+    const hit = msgTokMemo.get(m);
+    if (hit !== undefined && hit.sig === sig) return hit.tok;
+  }
+  const tok = estimateMessageTokens(m, cfg);
+  if (sig !== '') msgTokMemo.set(m, { sig, tok });
+  return tok;
+}
+
+/**
+ * A rolling total over a message list that grows by appending.
+ *
+ * This is the idea borrowed from jcode's `ActiveCharEstimate`
+ * (`crates/jcode-base/src/compaction.rs`): keep a running count of the messages
+ * already priced, so the common append-only case never rescans history. jcode also
+ * notes why the cached value and its staleness flag are bundled into one type
+ * rather than two independent fields — a path that updated one without the other
+ * silently corrupted token accounting. Here the two are a single number,
+ * `_counted`: it is meaningless on its own and is only ever read together with the
+ * length it was computed against.
+ *
+ * `sync()` is O(new messages) when the list was only appended to, and O(n) after a
+ * compaction (which REPLACES the array, so the old count describes messages that no
+ * longer exist). Correctness does not depend on detecting appends perfectly: the
+ * boundary identities are spot-checked and any doubt falls back to a full recount,
+ * which is still cheap because the per-message memo makes each step a WeakMap hit.
+ */
+export class TokenLedger {
+  constructor() {
+    this.tokens = 0;
+    this._counted = 0;
+    this._first = null;
+    this._last = null;
+  }
+
+  /** Total tokens for `messages`, reusing the previous count where it is still valid. */
+  sync(messages, cfg) {
+    const msgs = Array.isArray(messages) ? messages : [];
+    const n = msgs.length;
+    const canExtend = this._counted > 0 && this._counted <= n
+      && this._first === msgs[0]
+      && this._last === msgs[this._counted - 1];
+    if (canExtend) {
+      for (let i = this._counted; i < n; i++) this.tokens += messageTokens(msgs[i], cfg);
+    } else {
+      // Full recount. Still O(n) WEAK-MAP LOOKUPS rather than O(n) string walks,
+      // which is the difference between milliseconds and microseconds.
+      let total = 0;
+      for (let i = 0; i < n; i++) total += messageTokens(msgs[i], cfg);
+      this.tokens = total;
+    }
+    this._counted = n;
+    this._first = n ? msgs[0] : null;
+    this._last = n ? msgs[n - 1] : null;
+    return this.tokens;
+  }
+
+  /** Forget everything — call after an in-place edit of an already-counted message. */
+  reset() {
+    this.tokens = 0;
+    this._counted = 0;
+    this._first = null;
+    this._last = null;
+  }
+}
+
 // The overhead a request carries BEYOND its messages: the system prompt plus the
 // tool definitions. Passed the assembled system text so the number matches what is
 // actually sent.

package/src/tools/agent-control.js

@@ -0,0 +1,98 @@
+// Tools for controlling a RUNNING subagent: list, message, interrupt, close.
+//
+// WHY THESE ARE SEPARATE FROM TaskList / TaskStop
+// ----------------------------------------------
+// `TaskStop` cancels a background task by task_id, and for an agent that means aborting
+// its controller — the whole run dies. There was no way to do the thing a person actually
+// asks for while watching a subagent work: tell it something, and let it continue. And
+// there was no way to stop ONE subagent of a swarm without stopping the turn that started
+// them, because `TaskStop` needs a task id that only the background path creates.
+//
+// These tools address agents by AGENT id (or run id, or task id — whichever the caller
+// has), which is the identifier `Agent` prints and `AgentSwarm` reports, so the model can
+// act on what it just started without a lookup table.
+//
+// `AgentMessage` uses the same `steer` path as the TUI's Ctrl+S: the message lands when
+// the subagent's in-flight tool calls finish. That is the only safe moment to change a
+// run's instructions, and it is what makes "keep going, but also do X" meaningful.
+
+import { listRuns, sendToRun, interruptRun, interruptAll, closeRun, describeRuns } from '../subagent-control.js';
+
+export const AgentListSpec = {
+  name: 'AgentList',
+  description: `List the subagents that are running RIGHT NOW, with the id to address each one.
+
+Use this before AgentMessage / AgentInterrupt / AgentClose when you do not already hold the id. A subagent that has finished is not listed — it is no longer controllable, and its result is already in this conversation (or in TaskOutput for a background run).`,
+  parameters: { type: 'object', properties: {} },
+  async execute() {
+    const runs = listRuns();
+    if (!runs.length) return 'No subagent is running.';
+    return describeRuns().join('\n');
+  },
+};
+
+export const AgentMessageSpec = {
+  name: 'AgentMessage',
+  description: `Send a message to a RUNNING subagent without stopping it.
+
+The text is injected when the subagent's in-flight tool calls finish — the same point the user's own steering messages land — so it changes the run's instructions rather than interrupting them. Use it to redirect work ("skip the tests for now"), to add a constraint, or to correct a wrong assumption you can see in its stream.
+
+Identify the subagent by its agent_id (what \`Agent\` returned, or what AgentSwarm reported), its run id, or its task id. Use AgentList if you have none of them.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      agent_id: { type: 'string', description: 'The subagent to message: agent_id, run id, or task_id.' },
+      message: { type: 'string', description: 'What to tell it. Delivered as a steering message.' },
+    },
+    required: ['agent_id', 'message'],
+  },
+  async execute(args) {
+    const r = sendToRun(args.agent_id, args.message);
+    return r.ok ? r.message : `Error: ${r.message}`;
+  },
+};
+
+export const AgentInterruptSpec = {
+  name: 'AgentInterrupt',
+  description: `Stop ONE running subagent, leaving everything else alone.
+
+Prefer this over TaskStop for a subagent: TaskStop works on a background task id and cancels the whole run, while this reaches the subagent directly and needs only the agent id. Omit \`agent_id\` to stop EVERY running subagent, which is the way out when a swarm has gone wrong.
+
+Brief the model on what the agent had established before stopping it: a subagent's partial work is not written anywhere you can read afterwards.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      agent_id: { type: 'string', description: 'The subagent to stop. Omit to stop all of them.' },
+      reason: { type: 'string', description: 'Short reason, for the transcript.' },
+    },
+  },
+  async execute(args) {
+    const ref = args && args.agent_id ? String(args.agent_id).trim() : '';
+    if (!ref) {
+      const all = interruptAll();
+      return all.ok
+        ? `Interrupted ${all.count} subagent(s): ${all.agents.join(', ')}`
+        : 'No subagent is running.';
+    }
+    const r = interruptRun(ref);
+    return r.ok ? r.message : `Error: ${r.message}`;
+  },
+};
+
+export const AgentCloseSpec = {
+  name: 'AgentClose',
+  description: `Interrupt a subagent AND remove it from the running list immediately.
+
+Use this when you stopped a subagent and no longer want it in AgentList. An interrupted run is removed when its await unwinds, which is asynchronous, so a listing right afterwards can still show it; close removes it at once. The subagent's CONVERSATION is kept, so a later \`Agent\` call can still \`resume\` it.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      agent_id: { type: 'string', description: 'The subagent to close.' },
+    },
+    required: ['agent_id'],
+  },
+  async execute(args) {
+    const r = closeRun(args.agent_id);
+    return r.ok ? r.message : `Error: ${r.message}`;
+  },
+};

package/src/tools/agent-swarm.js

@@ -71,6 +71,7 @@ Each of these is enforced — a violation is rejected before any subagent starts
 Use enough subagents to keep the work focused and parallel. AgentSwarm supports up to ${MAX_AGENT_SWARM_SUBAGENTS} subagents, and launches are queued automatically, so it is safe to split large tasks into many clear, independent items.
 
 When NOT to use AgentSwarm:
+- It only exists while swarm mode is ON (\`/swarm\`). With the mode off the tool is not offered at all and calling it is refused. If a fan-out would genuinely help, say so and ask the user to turn the mode on.
 - Never call this on your own initiative. It requires the same explicit permission as \`Agent\`: the user, or the applicable AGENTS.md / project instructions, must have asked for sub-agents, delegation, or parallel agent work. Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do NOT count as permission.
 - Do not use it for two or three differently-shaped tasks: use separate \`Agent\` calls instead, which can run in parallel in one message.
 - Do not use it to fan out work you could finish yourself in a few steps.
@@ -151,9 +152,17 @@ If \`AgentSwarm\` is called, that call must be the only tool call in the respons
         } catch (e) {
           results[i] = `--- #${i + 1} ---\n[error: ${e.message}]`;
         }
-        // Stream progress into the task output so a long swarm is inspectable.
+        // Report progress down BOTH channels, and they are not interchangeable:
+        //   * the task buffer feeds TaskOutput and survives a detach;
+        //   * `ctx.onOutput` is the LIVE sink. The progress block in the transcript
+        //     reads the cells off it (see the tool_output handler's `[n/m] finished`
+        //     match), so writing only to the task buffer left every cell but the first
+        //     stuck on "Queued…" for the whole run — the TUI was told to expect these
+        //     lines on this channel and never received one.
         const done = results.filter((r) => r !== null).length;
-        appendTaskOutput(task, `[${done}/${jobs.length}] finished\n`);
+        const line = `[${done}/${jobs.length}] finished\n`;
+        appendTaskOutput(task, line);
+        if (typeof ctx.onOutput === 'function') ctx.onOutput(line);
       }
     };
     const runAll = Promise.all(Array.from({ length: Math.min(SWARM_CONCURRENCY, jobs.length) }, worker));

package/src/tools/agent.js

@@ -17,6 +17,7 @@
 // summarise it.
 
 import { createTask, appendTaskOutput, settleTask } from '../agent-task.js';
+import { registerRun, endRun } from '../subagent-control.js';
 import { SUBAGENT_TYPES, DEFAULT_SUBAGENT_TYPE, availableTypes, toolsForSubagent } from '../subagent-types.js';
 import { runShellHooks } from '../hooks.js';
 
@@ -53,7 +54,7 @@ function systemPromptFor(type, cfg, systemPrompt) {
 // stream, and each tool it runs) so the TUI can show it under the `Using Agent`
 // row the way Bash's output is shown. `agentId` labels the lines when several
 // subagents run at once (AgentSwarm), so the reader can tell them apart.
-async function runSubagent({ cfg, type, prompt, history, signal, onEvent, onProgress, agentId }) {
+async function runSubagent({ cfg, type, prompt, history, signal, onEvent, onProgress, agentId, onAgent }) {
   const { Agent, SYSTEM_PROMPT } = await import('../agent.js');
   const subCfg = {
     ...cfg,
@@ -105,6 +106,10 @@ async function runSubagent({ cfg, type, prompt, history, signal, onEvent, onProg
     if (signal.aborted) throw new Error('Interrupted by user');
     signal.addEventListener('abort', () => agent.interrupt(), { once: true });
   }
+  // Hand the LIVE agent back to the caller so a control tool can steer or interrupt it
+  // while it runs. `subagents` only learns about this run when it finishes, so without
+  // this the only way to reach a running subagent would be to interrupt the whole turn.
+  if (typeof onAgent === 'function') onAgent(agent);
   await agent.run();
   // SHELL HOOK: SubagentStop. The subagent finished (or was interrupted); the
   // parent-side hook can log/archive it. Never blocks.
@@ -237,12 +242,20 @@ ${availableTypes()}`,
       const agentId = existing ? existing.id : newAgentId();
       task.agentId = agentId;
 
+      // Register the run so a control tool can reach it while it is in flight. The handle
+      // is created BEFORE the run so both `run_in_background` and the detached-foreground
+      // path behave the same, and cleared in `finally` so a settled run can never be
+      // listed as controllable.
+      let runId = '';
+      const early = { agent: null };
+
       // Fire and forget: the task record carries the result when it lands.
       void (async () => {
         try {
           const run = await runSubagent({
             cfg: subCfg, type, prompt, history,
             signal: controller.signal,
+            onAgent: (agent) => { early.agent = agent; },
             // No live streaming into the task output: that should read as the
             // subagent's CONCLUSION. `run.text` below is the cleaned final message.
           });
@@ -258,8 +271,15 @@ ${availableTypes()}`,
           settleTask(task, stopped ? 'killed' : 'failed', { stopReason: stopped ? 'Stopped by user' : e.message });
           appendTaskOutput(task, `\n[error: ${e.message}]`);
           if (typeof ctx._onBackgroundTaskDone === 'function') ctx._onBackgroundTaskDone(task);
+        } finally {
+          if (runId) endRun(runId);
         }
       })();
+      runId = registerRun({
+        agentId, taskId: task.taskId, type, description,
+        steer: (text) => { if (early.agent) early.agent.steer(text); },
+        interrupt: () => controller.abort(),
+      });
 
       return `agent_id: ${agentId}\ntask_id: ${task.taskId}\nstatus: running\nnext_step: Continue your work; the result arrives in a later message. Use TaskOutput {task_id: "${task.taskId}"} for a non-blocking check or TaskStop to cancel.`;
     }
@@ -286,8 +306,13 @@ ${availableTypes()}`,
     // `onProgress` feeds the parent's live-output sink (ctx.onOutput), which the
     // agent tags with THIS tool call's id — the same path Bash uses, so the TUI
     // renders the subagent's stream under the `Using Agent` row and Ctrl+O folds it.
+    // The live Agent is captured as soon as `runSubagent` builds it, which is what makes
+    // this run controllable from another tool call (or the TUI) without waiting for it to
+    // finish. `live` is a box because the handle arrives asynchronously.
+    const live = { agent: null };
     const runPromise = runSubagent({
       cfg: subCfg, type, prompt, history, signal: bgController.signal,
+      onAgent: (agent) => { live.agent = agent; },
       // `_progressTag` is set by AgentSwarm to the item index, so a swarm's
       // concurrently-running subagents are distinguishable in the live stream.
       // A plain Agent call has no tag and prints its stream unlabelled.
@@ -297,6 +322,15 @@ ${availableTypes()}`,
         ctx.onOutput(tag ? text.split('\n').map((l) => (l ? tag + l : l)).join('\n') : text);
       },
     });
+    // Registered here so a foreground subagent is reachable by AgentMessage / AgentInterrupt
+    // too — that is precisely the case where a user wants to redirect one: it is the run
+    // they are watching. Cleared when the run settles, however it settles.
+    let runId = registerRun({
+      agentId, type, description,
+      steer: (text) => { if (live.agent) live.agent.steer(text); },
+      interrupt: () => bgController.abort(),
+    });
+    void runPromise.catch(() => {}).finally(() => { if (runId) { endRun(runId); runId = ''; } });
     if (ctx) {
       ctx._foreground = {
         kind: 'Agent',

package/src/tools/bash.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import cp from 'node:child_process';
 import { resolvePath, truncateBuf } from './utils.js';
 import { createTask, appendTaskOutput, settleTask } from '../agent-task.js';
+import { shellSpawnArgs } from './shell.js';
 
 // kimi-code's timeout policy (agent-core-v2/agent/tools/os/bash/bash.ts).
 export const DEFAULT_TIMEOUT_S = 60;
@@ -137,10 +138,19 @@ export const spec = {
     const cap = bg ? MAX_BACKGROUND_TIMEOUT_S : MAX_TIMEOUT_S;
     const def = bg ? DEFAULT_BACKGROUND_TIMEOUT_S : DEFAULT_TIMEOUT_S;
     const timeoutMs = args.disable_timeout ? undefined : Math.min(args.timeout ?? def, cap) * 1000;
-    const command = args.command;
+const command = args.command;
     // stdin is 'ignore' (NUL / /dev/null): leaving it as an open pipe made any
     // command that reads stdin (`cat`, `npm init`, …) block until the timeout.
-    const child = cp.spawn('pwsh', ['-Command', command], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    //
+    // The shell is RESOLVED, not hardcoded: `spawn('pwsh', …)` failed outright on a
+    // box with only the built-in Windows PowerShell (see tools/shell.js). `env` is
+    // passed explicitly rather than relying on Node's implicit inheritance, which is
+    // what made the tool depend on pwsh having been added to PATH by hand.
+    let shell;
+    try { shell = shellSpawnArgs(command); } catch (e) { return `Error: ${e.message}`; }
+    const child = cp.spawn(shell.bin, shell.args, {
+      cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env },
+    });
 
     const chunks = [];
     let settled = false;
@@ -288,7 +298,11 @@ function spawnBackground(args, cwd, ctx) {
   // task's output file instead, so the process survives and TaskOutput can
   // still read it. (In the TUI the parent rarely exits, but headless -p mode
   // does, and a background job should outlive the prompt.)
-  const child = cp.spawn('pwsh', ['-Command', command], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+let shell;
+  try { shell = shellSpawnArgs(command); } catch (e) { return `Error: ${e.message}`; }
+  const child = cp.spawn(shell.bin, shell.args, {
+    cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env },
+  });
   const task = createTask(ctx, 'process', {
     description: args.description || args.command,
     command: args.command,