@hncode/hncode 0.5.6 → 0.6.0

package/src/screen.js

@@ -0,0 +1,277 @@
+/**
+ * A screen buffer of individual cells, and the diff that turns two of them into terminal bytes.
+ *
+ * WHY CELLS AND NOT LINES
+ * -----------------------
+ * A frame used to be an array of strings, and the painter compared those strings. That worked while every row
+ * was text and every change was coarse, but it cannot express two things a terminal actually has: a bitmap,
+ * which occupies a RECTANGLE and no row of characters, and a style change, which alters what is drawn without
+ * altering which characters are drawn.
+ *
+ * Comparing whole rows also means a one-character change rewrites the entire row, and any consumer that
+ * wants to know "did anything under this rectangle change" has to re-derive it from string offsets.
+ *
+ * So a frame is a grid. Each cell is two integers — a pooled character id and a pooled style id — which makes
+ * a comparison an integer compare and makes a rectangle an index range. That is the same shape dsh-tui uses,
+ * and it is what lets an image be handled as a region rather than as a special row.
+ */
+
+/** Cell width markers, matching the terminal's own notion. */
+export const CELL_WIDTH = { narrow: 1, wide: 2, spacer: 0 };
+
+/**
+ * Character pool: interned strings so a cell comparison is an integer comparison.
+ *
+ * Index 0 is a space and index 1 is the empty "spacer" that follows a wide character, so both have stable ids
+ * that no ordinary character can take.
+ */
+export class CharPool {
+  constructor() {
+    this.strings = [' ', ''];
+    this.ids = new Map([[' ', 0], ['', 1]]);
+    this.ascii = new Int32Array(128).fill(-1);
+    this.ascii[32] = 0;
+  }
+
+  intern(ch) {
+    if (ch.length === 1) {
+      const code = ch.charCodeAt(0);
+      if (code < 128) {
+        const hit = this.ascii[code];
+        if (hit !== -1) return hit;
+        const id = this.strings.length;
+        this.strings.push(ch);
+        this.ascii[code] = id;
+        return id;
+      }
+    }
+    const hit = this.ids.get(ch);
+    if (hit !== undefined) return hit;
+    const id = this.strings.length;
+    this.strings.push(ch);
+    this.ids.set(ch, id);
+    return id;
+  }
+
+  get(id) {
+    return this.strings[id] ?? ' ';
+  }
+}
+
+/**
+ * Style pool: an SGR prefix per distinct style, so a cell stores an id rather than a string.
+ *
+ * The value is the SGR sequence that ENTERS the style; the diff writes `ESC[0m` plus the next cell's prefix
+ * when the style changes, which is simpler than a minimal-diff of two SGR strings and cannot be wrong.
+ */
+export class StylePool {
+  constructor() {
+    this.strings = [''];
+    this.ids = new Map([['', 0]]);
+  }
+
+  intern(sgr) {
+    const s = sgr || '';
+    const hit = this.ids.get(s);
+    if (hit !== undefined) return hit;
+    const id = this.strings.length;
+    this.strings.push(s);
+    this.ids.set(s, id);
+    return id;
+  }
+
+  get(id) {
+    return this.strings[id] ?? '';
+  }
+}
+
+/** A rectangle in cell coordinates. */
+export const rect = (x, y, width, height) => ({ x, y, width, height });
+
+/** The union of two rectangles, or whichever is non-null. */
+export function unionRect(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  const right = Math.max(a.x + a.width, b.x + b.width);
+  const bottom = Math.max(a.y + a.height, b.y + b.height);
+  return { x, y, width: right - x, height: bottom - y };
+}
+
+/** True when the two rectangles share any cell. */
+export function rectsOverlap(a, b) {
+  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+/**
+ * A frame's painted surface.
+ *
+ * `cells` holds two Int32 per cell: `[charId, styleId]`. A wide character's second column holds the SPACER
+ * id so that a later write cannot split it, and the diff skips those columns when emitting.
+ */
+export class Screen {
+  constructor(width, height, charPool, stylePool) {
+    this.width = Math.max(0, width | 0);
+    this.height = Math.max(0, height | 0);
+    this.charPool = charPool;
+    this.stylePool = stylePool;
+    this.cells = new Int32Array(this.width * this.height * 2);
+    /** Bounding box of everything written since the last reset, or null when nothing was. */
+    this.damage = null;
+  }
+
+  /** Fill the buffer with spaces in the given style and clear the damage. */
+  reset(styleId = 0) {
+    this.cells.fill(0);
+    for (let i = 1; i < this.cells.length; i += 2) this.cells[i] = styleId;
+    this.damage = null;
+  }
+
+  inBounds(x, y) {
+    return x >= 0 && y >= 0 && x < this.width && y < this.height;
+  }
+
+  /**
+   * Write one character.
+   * @param {number} x
+   * @param {number} y
+   * @param {string} ch
+   * @param {number} styleId
+   * @param {number} [width] 1 for narrow, 2 for wide.
+   */
+  set(x, y, ch, styleId, width = 1) {
+    if (!this.inBounds(x, y)) return;
+    const at = (y * this.width + x) * 2;
+    this.cells[at] = this.charPool.intern(ch);
+    this.cells[at + 1] = styleId;
+
+    if (width === 2) {
+      // The second column is a spacer, never a character of its own.
+      if (this.inBounds(x + 1, y)) {
+        const next = (y * this.width + x + 1) * 2;
+        this.cells[next] = 1;
+        this.cells[next + 1] = styleId;
+      }
+    }
+    this._mark(x, y, width);
+  }
+
+  /** Write a run of characters starting at x, returning the column after the last one. */
+  write(x, y, text, styleId) {
+    let col = x;
+    for (const ch of text) {
+      const w = charWidth(ch);
+      if (col + w > this.width) break;
+      this.set(col, y, ch, styleId, w);
+      col += w;
+    }
+    return col;
+  }
+
+  /** Blank a rectangle in the given style. */
+  clear(x, y, width, height, styleId = 0) {
+    for (let row = y; row < Math.min(y + height, this.height); row++) {
+      for (let col = x; col < Math.min(x + width, this.width); col++) {
+        if (col < 0 || row < 0) continue;
+        const at = (row * this.width + col) * 2;
+        this.cells[at] = 0;
+        this.cells[at + 1] = styleId;
+      }
+    }
+    this._mark(x, y, Math.max(0, width), Math.max(0, height));
+  }
+
+  /** Rows this screen claims to have painted, so a later diff can tell a moved layout from an edited one. */
+  get rowCount() {
+    return this._rowCount === undefined ? -1 : this._rowCount;
+  }
+
+  _mark(x, y, width, height = 1) {
+    const r = rect(Math.max(0, x), Math.max(0, y), Math.max(1, width), Math.max(1, height));
+    this.damage = unionRect(this.damage, r);
+  }
+
+  /** The character at a cell, and its style. */
+  at(x, y) {
+    const at = (y * this.width + x) * 2;
+    return { ch: this.charPool.get(this.cells[at]), styleId: this.cells[at + 1] };
+  }
+
+  /** True when this cell is the second half of a wide character. */
+  isSpacer(x, y) {
+    return this.cells[(y * this.width + x) * 2] === 1;
+  }
+
+  /**
+   * Every cell that differs from `other`, row by row.
+   *
+   * @param {Screen|null} other The previous frame, or null for a full paint.
+   * @param {(x:number, y:number, rowEnd:number)=>void} onRow Called once per row that has any change, with the
+   *   first differing column and the column after the last one.
+   * @returns {boolean} Whether anything differed.
+   */
+  diffRows(other, onRow) {
+    if (!other || other.width !== this.width || other.height !== this.height) {
+      for (let y = 0; y < this.height; y++) onRow(0, y, this.width);
+      return this.height > 0;
+    }
+
+    // `damage` may only narrow the scan when it already covers the whole grid: a row that lost its text is
+    // not written by anyone, so it never enters damage, and bounding by damage would skip exactly the rows
+    // that changed.
+    const covered = this.damage && this.damage.y <= 0 && this.damage.y + this.damage.height >= this.height;
+    const from = covered ? 0 : 0;
+    const to = this.height;
+
+    let any = false;
+    const a = other.cells;
+    const b = this.cells;
+    for (let y = from; y < to; y++) {
+      const base = y * this.width * 2;
+      let first = -1;
+      let last = -1;
+      for (let i = 0; i < this.width; i++) {
+        const at = base + i * 2;
+        if (a[at] !== b[at] || a[at + 1] !== b[at + 1]) {
+          if (first < 0) first = i;
+          last = i;
+        }
+      }
+      if (first >= 0) {
+        any = true;
+        onRow(first, y, last + 1);
+      }
+    }
+    return any;
+  }
+}
+
+/** Terminal columns a code point occupies. Narrow unless it is East Asian wide or an emoji. */
+export function charWidth(ch) {
+  const cp = ch.codePointAt(0);
+  if (cp === undefined) return 1;
+  // Combining marks attach to the previous cell and take no column of their own.
+  if (cp >= 0x300 && cp <= 0x36f) return 0;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f)      // Hangul Jamo
+    || (cp >= 0x2e80 && cp <= 0xa4cf)   // CJK radicals … Yi
+    || (cp >= 0xac00 && cp <= 0xd7a3)   // Hangul syllables
+    || (cp >= 0xf900 && cp <= 0xfaff)   // CJK compatibility ideographs
+    || (cp >= 0xfe30 && cp <= 0xfe6f)   // CJK compatibility forms
+    || (cp >= 0xff00 && cp <= 0xff60)   // Fullwidth forms
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f64f) // emoji
+    || (cp >= 0x1f900 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) return 2;
+  return 1;
+}
+
+/** A shareable pool pair, so screens in one session can be compared cheaply. */
+export const pools = () => ({ charPool: new CharPool(), stylePool: new StylePool() });
+
+/** Create a screen over the given pools. */
+export function createScreen(width, height, charPool, stylePool) {
+  return new Screen(width, height, charPool, stylePool);
+}

package/src/subagent-types.js

@@ -1,147 +1,136 @@
-// Subagent type catalog, shared by the Agent tool and AgentSwarm.
-//
-// Mirrors kimi-code's builtin agent profiles (session/agentLifecycle/profile/profiles.ts):
-//   coder    - general software engineering; the only type with editing tools
-//   explore  - fast read-only codebase exploration (kimi calls it "explore")
-//   plan     - read-only implementation planning; no shell, no editing
-//
-// Kept in its own module so agent.js and agent-swarm.js can both import it
-// without a cycle (agent-swarm used to import it from agent.js, which then
-// imported agent-swarm back — the constant was read before it was initialised).
-
-export const DEFAULT_SUBAGENT_TYPE = 'coder';
-
-// Shared prefix kimi puts on every task-agent role prompt. It is what stops a
-// subagent from addressing the end user directly or assuming the parent can see
-// its context.
-const TASK_AGENT_ROLE_PREFIX =
-  'You are now running as a subagent. All the `user` messages are sent by the main agent. '
-  + 'The main agent cannot see your context, it can only see your last message when you finish the task. '
-  + 'You must treat the parent agent as your caller. Do not directly ask the end user questions. '
-  + 'If something is unclear, explain the ambiguity in your final summary to the parent agent. '
-  // A subagent has no Agent/AgentSwarm in its toolbelt (see DELEGATION_TOOLS), so it
-  // must not try: a delegated delegation would have nobody to report to and would
-  // nest without bound.
-  + 'You cannot delegate: you have no Agent or AgentSwarm tool. Do all of the work yourself.';
-
-// Tools that let an agent hand work to ANOTHER agent. Subagents never get these:
-// delegation belongs to the top-level turn the user is watching. kimi expresses
-// this through each profile's explicit `tools` allowlist; we enforce it the same
-// way plus a hard block, so a future profile that forgets to list its tools
-// cannot silently re-enable nesting.
-export const DELEGATION_TOOLS = ['Agent', 'AgentSwarm'];
-
-export const SUBAGENT_TYPES = {
-  coder: {
-    label: 'Coder',
-    description: 'General software engineering agent — the only subagent type with file-editing tools; use it for any delegated task that must modify code.',
-    whenToUse:
-      'Use this agent for non-trivial software engineering work that may require reading files, editing code, '
-      + 'running commands, and returning a compact but technically complete summary to the parent agent.',
-    // An explicit allowlist (not `null` = everything) so Agent/AgentSwarm are
-    // excluded. Mirrors kimi's CODER_TOOLS.
-    tools: [
-      'Read', 'Write', 'Edit', 'Glob', 'Grep', 'FileLines', 'Bash', 'Git',
-      'TodoList', 'FetchURL', 'WebSearch', 'ReadMediaFile',
-      'TaskList', 'TaskOutput', 'TaskStop', 'TaskWait',
-    ],
-    prompt:
-      `${TASK_AGENT_ROLE_PREFIX}\n\n`
-      + 'Your final message is the entire handoff — the parent sees nothing else from your run. '
-      + 'Make it technically complete: what you changed and why, the path of every file you touched, '
-      + 'how you verified the change (tests or commands run, with results), and anything left undone '
-      + 'or worth follow-up. If you are stopped before finishing, the parent receives only what '
-      + 'you have written so far, so keep the handoff current.',
-  },
-  explore: {
-    label: 'Explore',
-    description: 'Fast codebase exploration with prompt-enforced read-only behavior.',
-    whenToUse:
-      'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns '
-      + '(e.g. "src/**/*.yaml"), search code for keywords (e.g. "database connection"), or answer questions about '
-      + 'the codebase (e.g. "how does the auth module work?"). When calling this agent, specify the desired '
-      + 'thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "thorough" for '
-      + 'comprehensive analysis across multiple locations and naming conventions. Use this agent for any read-only '
-      + 'exploration that will clearly require more than 3 search queries. Prefer launching multiple explore agents '
-      + 'concurrently when investigating independent questions.',
-    // Bash is allowed for READ-ONLY commands (git log, ls, find) — the prompt
-    // forbids using it to create or modify anything, exactly as kimi does.
-    tools: ['Read', 'ReadMediaFile', 'Glob', 'Grep', 'Bash', 'WebSearch', 'FetchURL'],
-    prompt:
-      `${TASK_AGENT_ROLE_PREFIX}\n\n`
-      + 'You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing '
-      + 'code and resources. You do NOT have access to file editing tools.\n\n'
-      + 'Your strengths:\n'
-      + '- Rapidly finding files using glob patterns\n'
-      + '- Searching code and text with powerful regex patterns\n'
-      + '- Reading and analyzing file contents\n'
-      + '- Running read-only shell commands (git log, git diff, ls, find, etc.)\n\n'
-      + 'Guidelines:\n'
-      + '- Use Glob for broad file pattern matching. Prefer patterns with a literal anchor (extension or subdirectory); '
-      + 'pure wildcards like `*` or `**/*` are allowed but usually truncate at the match cap.\n'
-      + '- Use Grep for searching file contents with regex\n'
-      + '- Use Read when you know the specific file path\n'
-      + '- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find)\n'
-      + '- NEVER use Bash for any file creation or modification commands\n'
-      + '- Use WebSearch or FetchURL when a question needs external context; the local codebase remains your primary domain\n'
-      + '- Adapt your search depth based on the thoroughness level specified by the caller\n'
-      + '- Wherever possible, spawn multiple parallel tool calls for grepping and reading files to maximize speed\n\n'
-      + 'You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly '
-      + 'in a structured format.',
-  },
-  plan: {
-    label: 'Plan',
-    description: 'Read-only implementation planning and architecture design.',
-    whenToUse:
-      'Use this agent when the parent agent needs a step-by-step implementation plan, key file identification, '
-      + 'and architectural trade-off analysis before code changes are made.',
-    // No Bash at all — a planning agent has no shell.
-    tools: ['Read', 'ReadMediaFile', 'Glob', 'Grep', 'WebSearch', 'FetchURL'],
-    prompt:
-      `${TASK_AGENT_ROLE_PREFIX}\n\n`
-      + 'Before designing your implementation plan, consider whether you fully understand the codebase areas '
-      + 'relevant to the task. If not, recommend the parent agent to use the explore agent '
-      + '(subagent_type="explore") to investigate key questions first. In your response, clearly state:\n'
-      + '1. What you already know from the information provided\n'
-      + '2. What questions remain unanswered that would benefit from explore agent investigation\n'
-      + '3. Your implementation plan (either preliminary if questions remain, or final if sufficient context exists)\n\n'
-      + 'You are a read-only planning agent: you can read and search files and consult the web, but you have no '
-      + 'shell and no file-editing tools. Where the general instructions tell you to make changes with tools, that '
-      + 'does not apply to you — do not attempt to run commands or modify files. Your deliverable is the plan '
-      + 'itself, returned as your final message.',
-  },
-  researcher: {
-    label: 'Researcher',
-    description: 'Read-only investigation; reports findings, changes nothing.',
-    whenToUse:
-      'Use this agent for read-only investigation on the web or in the repository when you want findings '
-      + 'reported back without any chance of local modification.',
-    tools: ['Read', 'ReadMediaFile', 'Grep', 'Glob', 'WebSearch', 'FetchURL'],
-    prompt:
-      `${TASK_AGENT_ROLE_PREFIX}\n\n`
-      + 'You are a research subagent. Investigate with the read-only tools and report findings. '
-      + 'Do NOT modify anything.',
-  },
-};
-
-// The catalog as the Agent tool describes it: one line per type, description and
-// the "when to use" guidance the model needs to pick correctly.
-export function availableTypes() {
-  return Object.entries(SUBAGENT_TYPES)
-    .map(([id, t]) => `- ${id}: ${t.description}${t.whenToUse ? `\n  ${t.whenToUse}` : ''}`)
-    .join('\n');
-}
-
-// The tool allowlist a subagent of `type` may run. Always excludes the delegation
-// tools, whatever the profile declares, so nesting is impossible.
-export function toolsForSubagent(type, parentFilter) {
-  const profile = SUBAGENT_TYPES[type] || SUBAGENT_TYPES[DEFAULT_SUBAGENT_TYPE];
-  const base = Array.isArray(profile.tools) ? profile.tools : null;
-  if (base) return base.filter((t) => !DELEGATION_TOOLS.includes(t));
-  // No explicit list: derive it from the parent's filter so a narrowed parent
-  // (Plan / Focus mode) stays narrowed in the child, minus delegation.
-  if (Array.isArray(parentFilter) && parentFilter.length) {
-    return parentFilter.filter((t) => !DELEGATION_TOOLS.includes(t));
-  }
-  return null;   // null = agent.js exposes everything except DELEGATION_TOOLS
-}
+// Subagent type catalog, shared by the Agent tool and AgentSwarm.
+//
+// Mirrors kimi-code's builtin agent profiles (session/agentLifecycle/profile/profiles.ts):
+//   coder    - general software engineering; the only type with editing tools
+//   explore  - fast read-only codebase exploration (kimi calls it "explore")
+//   plan     - read-only implementation planning; no shell, no editing
+//
+// Kept in its own module so agent.js and agent-swarm.js can both import it
+// without a cycle (agent-swarm used to import it from agent.js, which then
+// imported agent-swarm back — the constant was read before it was initialised).
+
+export const DEFAULT_SUBAGENT_TYPE = 'coder';
+
+// Shared prefix kimi puts on every task-agent role prompt. It is what stops a
+// subagent from addressing the end user directly or assuming the parent can see
+// its context.
+const TASK_AGENT_ROLE_PREFIX =
+  'You are now running as a subagent. All the `user` messages are sent by the main agent. '
+  + 'The main agent cannot see your context, it can only see your last message when you finish the task. '
+  + 'You must treat the parent agent as your caller. Do not directly ask the end user questions. '
+  + 'If something is unclear, explain the ambiguity in your final summary to the parent agent. '
+  // A subagent has no Agent/AgentSwarm in its toolbelt (see DELEGATION_TOOLS), so it
+  // must not try: a delegated delegation would have nobody to report to and would
+  // nest without bound.
+  + 'You cannot delegate: you have no Agent or AgentSwarm tool. Do all of the work yourself.';
+
+// Tools that let an agent hand work to ANOTHER agent. Subagents never get these:
+// delegation belongs to the top-level turn the user is watching. kimi expresses
+// this through each profile's explicit `tools` allowlist; we enforce it the same
+// way plus a hard block, so a future profile that forgets to list its tools
+// cannot silently re-enable nesting.
+export const DELEGATION_TOOLS = ['Agent', 'AgentSwarm'];
+
+export const SUBAGENT_TYPES = {
+  coder: {
+    label: 'Coder',
+    description: 'The only type that may edit files. For delegated work that changes code.',
+    whenToUse: 'Use for non-trivial engineering work: read, edit, run commands, report a compact but complete summary.',
+    // An explicit allowlist (not `null` = everything) so Agent/AgentSwarm are
+    // excluded. Mirrors kimi's CODER_TOOLS.
+    tools: [
+      'Read', 'Write', 'Edit', 'Glob', 'Grep', 'FileLines', 'Bash', 'Git',
+      'TodoList', 'FetchURL', 'WebSearch', 'ReadMediaFile',
+      'TaskList', 'TaskOutput', 'TaskStop', 'TaskWait',
+    ],
+    prompt:
+      `${TASK_AGENT_ROLE_PREFIX}\n\n`
+      + 'Your final message is the entire handoff — the parent sees nothing else from your run. '
+      + 'Make it technically complete: what you changed and why, the path of every file you touched, '
+      + 'how you verified the change (tests or commands run, with results), and anything left undone '
+      + 'or worth follow-up. If you are stopped before finishing, the parent receives only what '
+      + 'you have written so far, so keep the handoff current.',
+  },
+  explore: {
+    label: 'Explore',
+    description: 'Read-only codebase exploration.',
+    whenToUse: 'Use for read-only search that needs more than about three queries: find files, grep for a symbol, '
+      + 'answer how a module works. Say "quick", "medium" or "thorough". Launch several in parallel when the '
+      + 'questions are independent.',
+    // Bash is allowed for READ-ONLY commands (git log, ls, find) — the prompt
+    // forbids using it to create or modify anything, exactly as kimi does.
+    tools: ['Read', 'ReadMediaFile', 'Glob', 'Grep', 'Bash', 'WebSearch', 'FetchURL'],
+    prompt:
+      `${TASK_AGENT_ROLE_PREFIX}\n\n`
+      + 'You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing '
+      + 'code and resources. You do NOT have access to file editing tools.\n\n'
+      + 'Your strengths:\n'
+      + '- Rapidly finding files using glob patterns\n'
+      + '- Searching code and text with powerful regex patterns\n'
+      + '- Reading and analyzing file contents\n'
+      + '- Running read-only shell commands (git log, git diff, ls, find, etc.)\n\n'
+      + 'Guidelines:\n'
+      + '- Use Glob for broad file pattern matching. Prefer patterns with a literal anchor (extension or subdirectory); '
+      + 'pure wildcards like `*` or `**/*` are allowed but usually truncate at the match cap.\n'
+      + '- Use Grep for searching file contents with regex\n'
+      + '- Use Read when you know the specific file path\n'
+      + '- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find)\n'
+      + '- NEVER use Bash for any file creation or modification commands\n'
+      + '- Use WebSearch or FetchURL when a question needs external context; the local codebase remains your primary domain\n'
+      + '- Adapt your search depth based on the thoroughness level specified by the caller\n'
+      + '- Wherever possible, spawn multiple parallel tool calls for grepping and reading files to maximize speed\n\n'
+      + 'You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly '
+      + 'in a structured format.',
+  },
+  plan: {
+    label: 'Plan',
+    description: 'Read-only implementation planning.',
+    whenToUse: 'Use when you need a step-by-step plan, the files involved, and the trade-offs, before editing.',
+    // No Bash at all — a planning agent has no shell.
+    tools: ['Read', 'ReadMediaFile', 'Glob', 'Grep', 'WebSearch', 'FetchURL'],
+    prompt:
+      `${TASK_AGENT_ROLE_PREFIX}\n\n`
+      + 'Before designing your implementation plan, consider whether you fully understand the codebase areas '
+      + 'relevant to the task. If not, recommend the parent agent to use the explore agent '
+      + '(subagent_type="explore") to investigate key questions first. In your response, clearly state:\n'
+      + '1. What you already know from the information provided\n'
+      + '2. What questions remain unanswered that would benefit from explore agent investigation\n'
+      + '3. Your implementation plan (either preliminary if questions remain, or final if sufficient context exists)\n\n'
+      + 'You are a read-only planning agent: you can read and search files and consult the web, but you have no '
+      + 'shell and no file-editing tools. Where the general instructions tell you to make changes with tools, that '
+      + 'does not apply to you — do not attempt to run commands or modify files. Your deliverable is the plan '
+      + 'itself, returned as your final message.',
+  },
+  researcher: {
+    label: 'Researcher',
+    description: 'Read-only investigation; reports findings, changes nothing.',
+    whenToUse: 'Use for read-only investigation on the web or in the repo when nothing local may be modified.',
+    tools: ['Read', 'ReadMediaFile', 'Grep', 'Glob', 'WebSearch', 'FetchURL'],
+    prompt:
+      `${TASK_AGENT_ROLE_PREFIX}\n\n`
+      + 'You are a research subagent. Investigate with the read-only tools and report findings. '
+      + 'Do NOT modify anything.',
+  },
+};
+
+// The catalog as the Agent tool describes it: one line per type, description and
+// the "when to use" guidance the model needs to pick correctly.
+export function availableTypes() {
+  return Object.entries(SUBAGENT_TYPES)
+    .map(([id, t]) => `- ${id}: ${t.description}${t.whenToUse ? `\n  ${t.whenToUse}` : ''}`)
+    .join('\n');
+}
+
+// The tool allowlist a subagent of `type` may run. Always excludes the delegation
+// tools, whatever the profile declares, so nesting is impossible.
+export function toolsForSubagent(type, parentFilter) {
+  const profile = SUBAGENT_TYPES[type] || SUBAGENT_TYPES[DEFAULT_SUBAGENT_TYPE];
+  const base = Array.isArray(profile.tools) ? profile.tools : null;
+  if (base) return base.filter((t) => !DELEGATION_TOOLS.includes(t));
+  // No explicit list: derive it from the parent's filter so a narrowed parent
+  // (Plan / Focus mode) stays narrowed in the child, minus delegation.
+  if (Array.isArray(parentFilter) && parentFilter.length) {
+    return parentFilter.filter((t) => !DELEGATION_TOOLS.includes(t));
+  }
+  return null;   // null = agent.js exposes everything except DELEGATION_TOOLS
+}

package/src/term-caps.js

@@ -347,15 +347,21 @@ export function parseProbeReplies(buf) {
   // are needed to place an image in cells rather than guessing — and a guess here is wrong
   // on every display whose font is not square, which is most of them.
   takeMatches(XT_CELL_RE, buf, spans, (m) => {
-    const w = Number(m[1]);
-    const h = Number(m[2]);
+    // THE REPLY PUTS HEIGHT FIRST: `CSI 6 ; height ; width t`.
+    //
+    // Reading it as width-then-height swapped the two on every terminal, which put the cell size at 20x10
+    // instead of 9x20 for a normal font. An image's row count is derived from the CELL height, so the bitmap
+    // claimed twice the rows it needed and pushed the interface down by exactly that much.
+    const h = Number(m[1]);
+    const w = Number(m[2]);
     // A terminal that answers 0x0 has nothing to say — treat it as unknown rather than
     // as a cell of zero width, which would divide by zero downstream.
     if (w > 0 && h > 0) found.cell = { w, h };
   });
   takeMatches(XT_AREA_RE, buf, spans, (m) => {
-    const w = Number(m[1]);
-    const h = Number(m[2]);
+    // The text area reply is `CSI 4 ; height ; width t` — same order.
+    const h = Number(m[1]);
+    const w = Number(m[2]);
     if (w > 0 && h > 0) found.textArea = { w, h };
   });
   let complete = false;