zames_pro 2.69.0 → 2.71.0

package/dist/deepseek-ui.js

@@ -0,0 +1,225 @@
+// DeepSeek UI constants — the SINGLE place where chat.deepseek.com specifics live.
+//
+// WHY this module exists: the agent drives the DeepSeek web UI through
+// Playwright, so every selector, button label and protocol marker is a
+// hardcoded assumption about a page we do not control. Keeping them scattered
+// across browser.ts made a DeepSeek redesign a diffuse, easy-to-miss breakage
+// (a renamed class here, a relabeled button there). Concentrating them here
+// turns "DeepSeek changed the UI" into ONE file to audit, and lets the health
+// check (probeUiHealth) report the exact broken capability to the operator
+// BEFORE a task hangs on it.
+//
+// Priority order everywhere: prefer SEMANTIC anchors (role / aria-label /
+// accessible name / input type) over DeepSeek's `ds-*` class names, which
+// drift between builds. The `ds-*` selectors stay in the chains as a
+// high-precision FIRST hit, with semantic fallbacks after them.
+// ---------- endpoints ----------
+export const CHAT_URL = 'https://chat.deepseek.com/';
+export const CHAT_ID_RE = /\/chat\/s\/([a-zA-Z0-9_-]+)/;
+// DeepSeek's chat URL shape. A direct navigation always yields the requested
+// chat (the sidebar link click is tried first, this is the fallback).
+export const CHAT_PATH_PREFIX = 'a/chat/s/';
+export function chatUrl(id) {
+    return CHAT_URL + CHAT_PATH_PREFIX + id;
+}
+// The history endpoint returns EVERY message of a chat as JSON (the rendered
+// page virtualizes long chats). Requested from INSIDE the page so the auth
+// cookie and PoW handling are the browser's; see browser.fetchChatMessages.
+export const HISTORY_MESSAGES_URL = 'https://chat.deepseek.com/api/v0/chat/history_messages';
+// ---------- input ----------
+export const INPUT_SELECTORS = [
+    'textarea',
+    'div[contenteditable="true"]',
+    '[role="textbox"]',
+];
+// ---------- send ----------
+// IMPORTANT: you MUST NOT add the generic
+// 'div[role="button"][class*="ds-button--primary"]' here — it matches the
+// STOP button too, and then _isGenerating() always returns true, so an answer
+// is never considered ready.
+export const SEND_SELECTORS = [
+    'div[role="button"].ds-button--primary.ds-button--circle',
+    'div[role="button"].ds-button--primary.ds-button--filled',
+    'button[type="submit"]',
+    'button[aria-label*="send" i]',
+    'button[aria-label*="отправ" i]',
+];
+// DeepSeek's own button classes. Used as a coarse "is this a DeepSeek button?"
+// filter in the raw-DOM fallbacks for Stop and for the send/stop icon
+// detection. Kept as a source string because the fallback runs INSIDE
+// page.evaluate, which cannot receive a RegExp object.
+export const BUTTON_CLASS_RE = /ds-button--(circle|primary|filled)/i;
+// ---------- stop ----------
+export const STOP_SELECTORS = [
+    'div[role="button"][aria-label*="stop" i]',
+    'div[role="button"][aria-label*="останов" i]',
+    'button:has-text("Stop")',
+    'button:has-text("Остановить")',
+    'button[aria-label*="Stop" i]',
+];
+// Accessible name of the Stop button, for a TRUSTED Playwright click. A bare
+// stop word (optionally with a short suffix), anchored and length-limited so a
+// "Stop" inside rendered prose is never clicked.
+export const STOP_NAME_RE = /^(?:stop|остановить)(?:\s+\S{0,20})?\s*[.!…]?$/i;
+// ---------- continue ----------
+// DeepSeek's "Continue" button. With the reasoning ("Deep thinking") toggle on
+// the server caps the THINK phase: the reasoning stops mid-way and the UI
+// offers a Continue button (NOT the same as a truncated turn with
+// generation_err — there the answer FAILED; here the model paused). The agent
+// must click it so the reasoning/answer keeps flowing.
+//
+// Reasoning mode uses a LONGER label («Продолжить размышление» / «Continue
+// thinking»), not a bare «Continue», so the match is a regex: a bare continue
+// word OR the word plus a short reasoning/answer suffix. It is anchored and
+// length-limited, so a "Continue" inside rendered prose is never clicked.
+export const CONTINUE_NAME_RE = /^(?:continue|продолжить|продолжение)(?:\s+(?:think(?:ing)?|reason(?:ing)?|размышлени[ея]|генераци[юя]|ответ))?\s*[.!…]?$/i;
+// ---------- messages / answers ----------
+// The rendered assistant answer. The FIRST hit is preferred (most specific),
+// so `ds-markdown` stays ahead of the generic `markdown` catch-all.
+export const ANSWER_SELECTORS = [
+    'div.ds-assistant-message-main-content',
+    'div[class*="ds-assistant-message-main-content"]',
+    'div[class*="ds-markdown"]',
+    'div[class*="markdown"]',
+];
+// Reasoning blocks. They are NOT the answer and must never be picked up as
+// one, otherwise the terminal would show the model's long reasoning.
+export const THINK_CLASS_RE = /ds-think-content|thinking-content/i;
+// Last-resort answer-only selectors for the restored-dialogue scraper. The
+// generic `markdown` catch-all is deliberately absent here: without a message
+// container it would also match a user bubble that happens to render markdown.
+export const RESTORE_ANSWER_SELECTORS = [
+    'div.ds-assistant-message-main-content',
+    'div[class*="ds-assistant-message-main-content"]',
+    'div[class*="ds-markdown"]',
+];
+// Message-level containers for the restored dialogue (broad first).
+export const MESSAGE_CONTAINER_SELECTORS = [
+    '[data-message-id]',
+    '[class*="ds-message"]',
+    '[class*="chat-message"]',
+    '[class*="message-item"]',
+    '[class*="_message"]',
+];
+// A message block is "assistant" when it carries the assistant class OR a
+// rendered markdown wrapper (a user bubble has no rendered markdown). Used by
+// the restored-dialogue scraper; the class names drift between builds, so the
+// detection is content-based rather than class-prefix-only.
+export const ASSISTANT_CLASS_RE = /ds-assistant-message|assistant-message/i;
+export const ASSISTANT_SELECTOR = '[class*="ds-assistant-message"]';
+export const ANSWER_MARKDOWN_SELECTOR = '[class*="ds-markdown"]';
+// A cheap "did the page grow?" signal (_chatSignal): count message nodes and
+// measure the LAST answer node's text length. The old code read
+// document.body.innerText.length every tick, which serializes the WHOLE page
+// (sidebar, history, menus) and forces a layout — expensive on a long chat.
+export const CHAT_SIGNAL_NODES_SELECTOR = '[class*="ds-message"], [class*="chat-message"], .ds-markdown';
+export const MARKDOWN_SELECTOR = '.ds-markdown';
+// ---------- new chat ----------
+// The "New chat" control is NOT a <button>/<a> on the current DeepSeek build
+// (it is a <div>), so matching only button/a missed it. Match any
+// clickable-ish element whose text is EXACTLY the new-chat label (an anchored
+// regex keeps a big outer container from matching its long descendant text).
+export const NEW_CHAT_SELECTOR = 'button, a, [role="button"], div, span';
+export const NEW_CHAT_TEXT_RE = /^\s*(new chat|новый чат|новый диалог)\s*$/i;
+// ---------- login ----------
+// The login page is served on the same origin and swaps in a password field;
+// the exact classes change, so we match loosely on input types and the known
+// placeholder/autocomplete attributes.
+export const PASSWORD_SELECTORS = [
+    'input[type="password"]',
+    'input[autocomplete="current-password"]',
+    'input[autocomplete="new-password"]',
+];
+export const LOGIN_SELECTORS = [
+    'input[type="email"]',
+    'input[type="tel"]',
+    'input[name="email"]',
+    'input[name="phone"]',
+    'input[name="username"]',
+    'input[placeholder*="email" i]',
+    'input[placeholder*="phone" i]',
+    'input[placeholder*="телефон" i]',
+    'input[placeholder*="почт" i]',
+    'input[autocomplete="username"]',
+    'input[autocomplete="email"]',
+];
+// Any login-ish button: a primary DeepSeek button or a plain <button>. The
+// visible label is filtered by LOGIN_NAME_RE so "Log in with Google" is not
+// hit by mistake.
+export const LOGIN_BUTTON_SELECTOR = 'div[role="button"].ds-button--primary, button';
+export const LOGIN_NAME_RE = /^\s*(log ?in|sign ?in|войти)\s*$/i;
+// A looser label test used inside the form fallback: a Continue button can also
+// submit the login step on some builds.
+export const LOGIN_FORM_SUBMIT_RE = /log ?in|sign ?in|войти|continue|продолж/i;
+export const LOGIN_SUBMIT_SELECTORS = [
+    // DeepSeek's real button: a div[role=button] with these classes and a
+    // <span class="ds-button__content">Log in</span> inside.
+    'div[role="button"].ds-button--primary.ds-button--filled',
+    'div[role="button"].ds-button--primary',
+    'button[type="submit"]',
+    'button:has-text("Log in")',
+    'button:has-text("Sign in")',
+    'button:has-text("Войти")',
+    'div[role="button"]:has-text("Log in")',
+    'div[role="button"]:has-text("Sign in")',
+    'div[role="button"]:has-text("Войти")',
+];
+// ---------- sidebar / chats ----------
+export const SIDEBAR_TOGGLE_SELECTORS = [
+    'button[aria-label*="sidebar" i]',
+    'button[aria-label*="история" i]',
+    'button[aria-label*="history" i]',
+    'button[class*="sidebar-toggle"]',
+    'button[class*="sidebarToggle"]',
+];
+// ---------- toggles (deep thinking / web search) ----------
+// DeepSeek exposes two toggle buttons above the input. Their labels are
+// localized, so we match by a loose regex on the visible text and read the
+// state from aria-pressed. `.ds-toggle-button` is the class anchor; the
+// semantic fallback ([aria-pressed] or [role=switch]) is tried when the class
+// is renamed, so a redesign does not silently disable the toggles.
+export const TOGGLE_SELECTORS = [
+    '.ds-toggle-button',
+    '[role="switch"]',
+    'div[role="button"][aria-pressed]',
+    'button[aria-pressed]',
+];
+export const DEEP_THINKING_RE = /глубок|deep\s*think/i;
+export const WEB_SEARCH_RE = /поиск|search/i;
+// ---------- attachments ----------
+export const ATTACH_SELECTORS = [
+    'div[role="button"][aria-label*="attach" i]',
+    'div[role="button"][aria-label*="влож" i]',
+    'button[aria-label*="attach" i]',
+    'button[aria-label*="влож" i]',
+    '[class*="upload"]',
+    '[class*="attach"]',
+];
+// ---------- service statuses / errors ----------
+// DeepSeek UI service statuses that are NOT the model's answer. Otherwise the
+// agent takes a status (Reading...) for an answer and breaks parsing.
+export const STATUS_RE = /^(reading|thinking|searching|analyzing|generating|stop|остановить|читаю|думаю|поиск|анализ)[\s.…]*$/i;
+// DeepSeek's answer when the rate limit is exceeded.
+//
+// IMPORTANT: the generic "try again later" / "повторите позже" tail is NOT
+// part of this pattern. DeepSeek appends it to MANY toasts ("Server busy.
+// Try again later.", "Service unavailable. Try again later."), so matching it
+// here classified every server hiccup as a RATE LIMIT and sent the agent into
+// a 5-minute wait. The rate limit is recognized by its specific wording only.
+export const RATE_LIMIT_RE = /(messages? too frequent|too many requests|rate limit|слишком часто|сообщени[яе] слишком част)/i;
+// Transient server-side hiccups (DeepSeek overloaded / hiccup). Unlike the
+// rate limit, these usually clear in seconds, so we retry quickly instead of
+// waiting minutes.
+export const SERVER_BUSY_RE = /(server (is )?busy|server error|service (is )?unavailable|temporarily unavailable|internal server error|502|503|504|server overloaded|сервер занят|сервер перегружен|сервис недоступен|внутренняя ошибка|попробуйте позже)/i;
+// ---------- network protocol (SSE) ----------
+export const GENERATION_ERR_RE = /"finish_reason":\s*"generation_err"/i;
+export const INCOMPLETE_STATUS_RE = /"quasi_status","v":"INCOMPLETE"/i;
+// A turn that ENDED (`quasi_status: FINISHED`) but produced NO answer text —
+// the reasoning was generated and the model stopped WITHOUT a RESPONSE
+// fragment. The UI shows Stopped + Continue.
+export const FINISHED_STATUS_RE = /"quasi_status","v":"FINISHED"/i;
+export const RESPONSE_CONTENT_RE = /"type":"RESPONSE","content":"[^"]/;
+// Only a completion/continue turn carries a real answer. Gating the capture
+// assignment to these URLs keeps a future endpoint (which happens to return a
+// `content`/`text` field) from clobbering the answer and looking fresh.
+export const ANSWER_URL_RE = /chat\/(completion|continue)/i;

package/dist/i18n/config.js

@@ -119,6 +119,14 @@ export const configMessages = {
         ru: 'Пересылать системный промпт при возобновлении чата',
         en: 'Resend the system prompt on chat resume',
     },
+    'cfg.f.browser_subagents': {
+        ru: 'Субагенты: инструмент Task (отдельный чат)',
+        en: 'Subagents: the Task tool (separate chat)',
+    },
+    'cfg.f.browser_maxSubagents': {
+        ru: 'Максимум субагентов на задачу',
+        en: 'Max subagents per task',
+    },
     'cfg.f.browser_deepThinking': {
         ru: 'Глубокое мышление (долго; размышления не выводятся)',
         en: 'Deep thinking (slow; reasoning is hidden)',

package/dist/i18n/doctor.js

@@ -38,6 +38,26 @@ export const doctorMessages = {
         ru: 'UA ещё не закэширован (первый запуск перезапустится один раз)',
         en: 'no cached UA yet (first start relaunches once)',
     },
+    'doctor.ui_ok': {
+        ru: 'все ключевые элементы найдены',
+        en: 'all key elements found',
+    },
+    'doctor.ui_degraded': {
+        ru: 'часть элементов не найдена: {v} (агент может работать некорректно)',
+        en: 'some elements not found: {v} (the agent may misbehave)',
+    },
+    'doctor.ui_broken': {
+        ru: 'НЕ найдено критичное: {v} — DeepSeek сменил вёрстку, задачи не будут отправляться. Запусти /debug-dom.',
+        en: 'MISSING critical: {v} — DeepSeek changed the markup, tasks will not send. Run /debug-dom.',
+    },
+    'ui.probe_failed': {
+        ru: '⚠ DeepSeek UI: не найдено критичное ({v}) — возможно, сменилась вёрстка chat.deepseek.com. Задачи могут не отправляться; проверь /doctor и /debug-dom.',
+        en: '⚠ DeepSeek UI: missing critical element(s) ({v}) — chat.deepseek.com markup may have changed. Tasks may not send; check /doctor and /debug-dom.',
+    },
+    'ui.probe_degraded': {
+        ru: '⚠ DeepSeek UI: не найдено ({v}) — часть возможностей (тумблеры/новый чат) может не работать.',
+        en: '⚠ DeepSeek UI: not found ({v}) — some features (toggles/new chat) may not work.',
+    },
     'adddir.usage': {
         ru: 'Использование: /add-dir <path>',
         en: 'Usage: /add-dir <path>',

package/dist/index.js

@@ -6,9 +6,10 @@ import { existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { theme } from './theme.js';
 import { DeepSeekBrowser, headlessUACacheReady } from './browser.js';
-import { createTools, mergeTools } from './tools.js';
+import { createTools, mergeTools, filterToolsForReadOnly } from './tools.js';
 import { createTodoStore, getTodos, setTodos, resetTodos, renderTodos, } from './extraTools.js';
 import { runAgentLoop } from './agent-loop.js';
+import { createSubagentRunner } from './subagent.js';
 import { createSpinner } from './spinner.js';
 import { LineEditor } from './input.js';
 import { parseImagePaste, extForMime, saveToTemp, guessMime, formatSize, readClipboardImageDetailed, sniffMime, readWindowsClipboardFiles, hasClipboardTool, writeClipboardText, contentHash, } from './attachments.js';
@@ -997,6 +998,23 @@ async function main() {
         await transcript.close();
         process.exit(1);
     }
+    // DeepSeek UI health probe. The agent drives a page we do not control, so a
+    // redesign silently breaks selectors and the FIRST symptom is a task hanging
+    // on "input field not found". Probe the always-present controls right after
+    // login and warn the operator up front. Best-effort: a probe failure must
+    // never block startup.
+    const warnUiHealth = (h) => {
+        if (h.missingCritical.length) {
+            console.error(theme.warn(t('ui.probe_failed', { v: h.missingCritical.join(', ') })));
+        }
+        else if (h.missing.length) {
+            console.error(theme.warn(t('ui.probe_degraded', { v: h.missing.join(', ') })));
+        }
+    };
+    try {
+        warnUiHealth(await browser.probeUiHealth());
+    }
+    catch { }
     // One-shot mode
     if (task) {
         const baseTools = mod.createTools(currentWorkdir, {
@@ -1104,6 +1122,33 @@ async function main() {
     // Write the checklist whenever the agent changes it, so a restart/resume
     // brings the tasks back (they used to be in-memory only).
     todoStore.onChange = () => persistTodos();
+    // Subagents (BACKLOG N36): the `Task` tool delegates a self-contained
+    // sub-task to a nested agent loop in its OWN chat (context isolation — in
+    // zames "context" IS the chat), then restores this chat and returns only
+    // the report. Sequential by design (one browser, one send slot). On by
+    // default via browser.subagents (its own budget caps the extra sends).
+    const makeSubagentRunner = () => config.browser.subagents
+        ? createSubagentRunner({
+            browser,
+            workdir: currentWorkdir,
+            locale: currentLocale,
+            runAgentLoop: mod.runAgentLoop,
+            buildTools: (readOnly) => {
+                const base = mod.createTools(currentWorkdir, {
+                    undo,
+                    todos: todoStore,
+                    readOnly: false,
+                    subagents: false,
+                });
+                return readOnly ? filterToolsForReadOnly(base) : base;
+            },
+            transcript,
+            maxSubagents: config.browser.maxSubagents,
+            askDeadlineMs: config.browser.askDeadlineMs,
+            maxAfterToolRetries: config.browser.maxAfterToolRetries,
+            selfImprovement: devMode,
+        })
+        : null;
     // A compact "tasks: 2/5" summary for the status line. Empty when the list
     // is empty, so an idle status is not cluttered.
     const todosSummary = () => {
@@ -2940,6 +2985,9 @@ async function main() {
             const mcpStatus = mcpPool
                 ? mcpPool.status()
                 : { servers: [], toolCount: 0 };
+            // Probe the DeepSeek UI so a redesign shows up as a /doctor row instead
+            // of a task that hangs on a missing input. Best-effort.
+            const uiHealth = await browser.probeUiHealth().catch(() => null);
             console.log(theme.system(mod.commands.renderDoctor({
                 nodeVersion: process.version,
                 platform: process.platform,
@@ -2961,6 +3009,9 @@ async function main() {
                 sshRemote: !!(process.env.SSH_CONNECTION || process.env.SSH_TTY),
                 headless: !!headless,
                 headlessUaCached: await headlessUACacheReady().catch(() => false),
+                uiPresent: uiHealth?.present,
+                uiMissing: uiHealth?.missing,
+                uiMissingCritical: uiHealth?.missingCritical,
             }, t)));
             continue;
         }
@@ -3372,6 +3423,9 @@ async function main() {
             undo,
             todos: todoStore,
             readOnly: planMode,
+            // `Task` is only offered when subagents are enabled AND we are not in
+            // plan (read-only) mode — a `general` subagent could write otherwise.
+            subagents: config.browser.subagents && !planMode,
         });
         const tools = mergeTools(baseTools, mcpPool?.tools, planMode);
         if (editor)
@@ -3429,6 +3483,7 @@ async function main() {
                 goal: sessionGoal,
                 todosQuery: () => todosSummary(),
                 selfImprovement: devMode,
+                onSubagent: makeSubagentRunner(),
             }, inputAttachments);
         }
         finally {

package/dist/net-capture.js

@@ -1,6 +1,7 @@
 import fs from 'fs/promises';
 import os from 'os';
 import path from 'path';
+import { FINISHED_STATUS_RE, RESPONSE_CONTENT_RE } from './deepseek-ui.js';
 // Extraction of the RAW model answer text from DeepSeek's network data.
 //
 // Why: the answer is read from the RENDERED DOM, and DeepSeek's rendering
@@ -175,11 +176,11 @@ export function isFinishedWithoutAnswer(body) {
     const b = String(body || '');
     if (!b)
         return false;
-    const finished = /"quasi_status","v":"FINISHED"/i.test(b);
+    const finished = FINISHED_STATUS_RE.test(b);
     if (!finished)
         return false;
     // A RESPONSE fragment with actual content means the model DID answer.
-    if (/"type":"RESPONSE","content":"[^"]/.test(b))
+    if (RESPONSE_CONTENT_RE.test(b))
         return false;
     // The turn carried reasoning (THINK) or was truncated mid-way; treat the
     // absence of response content as "no answer produced".

package/dist/run-task.js

@@ -237,7 +237,7 @@ export function watchInput({ onEscape, onChange, onQueue, } = {}) {
 }
 export async function runTask(deps, browser, tools, taskText, workdir, opts, attachments = []) {
     const { t, locale, debug, maxIter, config, runAgentLoop, createSpinner } = deps;
-    const { transcript, freshChat, sendSystemPrompt, queue = [], ui: editor, onChatReady, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, goal = null, todosQuery = null, selfImprovement = false, } = opts;
+    const { transcript, freshChat, sendSystemPrompt, queue = [], ui: editor, onChatReady, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, goal = null, todosQuery = null, selfImprovement = false, onSubagent = null, } = opts;
     // In TTY mode the UI is a LineEditor: it owns the input (queue, Esc,
     // Ctrl+C) and draws the status ABOVE the permanent input line. In non-TTY
     // mode (pipes) - a regular spinner + watchInput.
@@ -358,6 +358,7 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
                 contextLimit,
                 getTokenUsage,
                 selfImprovement,
+                onSubagent,
             });
             // The loop may end WITHOUT a model answer: an exhausted iteration limit
             // or an ask() watchdog. Surface it instead of a silent stop.

package/dist/subagent.js

@@ -0,0 +1,119 @@
+// Subagent runner (BACKLOG N36). A `Task` tool call from the model is handled
+// by the agent loop as a SEAM (like onAutoCompact): it calls back into the
+// caller, which owns the whole lifecycle. This module builds that callback.
+//
+// Why a SEPARATE chat: in zames "context" IS the DeepSeek chat, so context
+// isolation can only be achieved by opening a new chat, running a nested
+// agent loop there, and restoring the parent chat afterwards. The nested loop
+// returns ONLY the subagent's final `respond` report; the parent never sees
+// the subagent's raw turns, which is the whole point.
+//
+// This is deliberately SEQUENTIAL: one browser, one send slot. Parallel
+// subagents would need a second page and a shared send scheduler (a change to
+// browser.ts, which owns the live Playwright context) — out of scope here.
+/** Hard cap on iterations for one subagent run. */
+export const SUBAGENT_MAX_ITER = 30;
+/**
+ * The subagent persona, prepended to the task message. It is deliberately NOT
+ * injected as a replacement system prompt: the nested runAgentLoop builds the
+ * standard system prompt itself (tool list + call format), and the model needs
+ * exactly that to work. The persona only adds role + output contract.
+ */
+export function subagentPersona(type) {
+    const base = 'You are a SUBAGENT launched by a main coding agent to complete ONE ' +
+        'self-contained sub-task in an ISOLATED chat. You do NOT see the main ' +
+        "conversation's history, so rely only on the instructions below and on " +
+        'the files/tools available. You cannot talk to the operator, so do not ' +
+        'ask questions. When the sub-task is done, call respond with a concise, ' +
+        'information-dense report: findings, exact file paths, relevant code ' +
+        'snippets and a clear conclusion. Do NOT call respond until the work is ' +
+        'complete.';
+    if (type === 'explore') {
+        return (base +
+            '\n\nYou are in EXPLORE (read-only) mode: you may search and read files ' +
+            'but you CANNOT modify anything or run mutating commands. Investigate ' +
+            'and report your findings.');
+    }
+    return base;
+}
+/**
+ * Build the `onSubagent` callback for runAgentLoop. It enforces the per-task
+ * budget, opens a fresh chat, runs a nested loop (with the subagent's own
+ * task text and a restricted or full tool set), restores the parent chat and
+ * returns only the report.
+ */
+export function createSubagentRunner(opts) {
+    const { browser, workdir, locale, runAgentLoop, buildTools, transcript = null, maxSubagents, askDeadlineMs, maxAfterToolRetries, selfImprovement = false, onAskPermission, } = opts;
+    let used = 0;
+    return async (req) => {
+        if (used >= maxSubagents) {
+            return {
+                ok: false,
+                text: 'Subagent budget exhausted (' +
+                    maxSubagents +
+                    ' per task). Do the remaining work yourself with the other tools.',
+            };
+        }
+        used++;
+        const parentChatId = await browser.getCurrentChatId().catch(() => null);
+        const subTools = buildTools(req.type === 'explore');
+        const taskText = subagentPersona(req.type) + '\n\n--- SUB-TASK ---\n' + req.prompt;
+        // Save the parent's send hooks: the nested loop OVERWRITES them on
+        // browser, and leaving the nested (no-op) callbacks in place would kill
+        // the parent's spinner/status for the rest of the task.
+        const savedHooks = {
+            onSendStart: browser.onSendStart ?? null,
+            onSendPause: browser.onSendPause ?? null,
+            onSendState: browser.onSendState ?? null,
+            onNotice: browser.onNotice ?? null,
+        };
+        let report = '';
+        let failed = '';
+        try {
+            report = await runAgentLoop({
+                browser,
+                tools: subTools,
+                task: taskText,
+                workdir,
+                maxIterations: SUBAGENT_MAX_ITER,
+                // A fresh chat gives the subagent an isolated context; the nested loop
+                // opens it AND sends the standard system prompt itself.
+                freshChat: true,
+                sendSystemPrompt: true,
+                transcript,
+                locale,
+                askDeadlineMs,
+                maxAfterToolRetries,
+                selfImprovement,
+                // No recursion: the subagent cannot spawn its own subagents.
+                onSubagent: null,
+                // Do not persist the subagent chat as a session.
+                onChatReady: () => { },
+                onAskPermission: onAskPermission
+                    ? (info) => onAskPermission({
+                        tool: info.tool,
+                        reason: info.reason,
+                        action: info.action,
+                    })
+                    : undefined,
+            });
+        }
+        catch (e) {
+            failed = e.message;
+        }
+        finally {
+            // Restore the parent chat, then the hooks, so a failure in openChat
+            // still leaves the hooks correct.
+            if (parentChatId) {
+                await browser.openChat(parentChatId).catch(() => false);
+            }
+            browser.onSendStart = savedHooks.onSendStart;
+            browser.onSendPause = savedHooks.onSendPause;
+            browser.onSendState = savedHooks.onSendState;
+            browser.onNotice = savedHooks.onNotice;
+        }
+        if (failed)
+            return { ok: false, text: failed };
+        return { ok: true, text: report };
+    };
+}

package/dist/system-prompt.js

@@ -21,6 +21,35 @@ Rules for that note:
 - this is the ONE exception to "do not touch unrelated files". If nothing
   worth noting, add nothing.
 `;
+// Guidance for the `Task` tool (subagents), injected only when that tool is in
+// the model's set. Without it the model under-uses subagents (it does every
+// broad search itself and floods the main context) or misuses them (delegates
+// work that needs THIS conversation's history, which the isolated subagent
+// cannot see). Kept short: it competes with the tool list for space.
+const SUBAGENT_SECTION = `
+## Task tool (subagents)
+
+The Task tool delegates a self-contained sub-task to a subagent that works in
+its OWN separate chat with an ISOLATED context and returns ONLY a final
+report. The subagent does NOT see this conversation, so the prompt you pass
+must be fully self-contained (goal, exact questions, file paths, context).
+
+Use it to PROTECT this chat's context and to parallelize independent work:
+
+- Broad exploration whose raw hits would flood this chat ("find every use of
+  X", "map how module Y works end to end"): delegate it with
+  subagent_type "explore" (read-only) and keep only the report.
+- A self-contained research or verification sub-task you can specify in a
+  paragraph: delegate it and continue the main line meanwhile.
+- Several INDEPENDENT investigations: emit several Task calls in ONE batch.
+
+Do NOT use it for:
+- work that depends on this conversation's history (the subagent cannot see
+  it) - pass everything needed in the prompt, or do the work yourself;
+- a trivial single read/edit you can do directly (a subagent costs a full
+  extra chat with its own system prompt and sends);
+- edits that must run strictly in order with the rest of this chat.
+`;
 /** Render the AGENTS.md / MEMORY / skills / commands blocks of the prompt. */
 export function renderContextSection(context) {
     if (!context)
@@ -112,6 +141,12 @@ export function renderToolSection(tools) {
 export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, selfImprovement = false, }) {
     const t = translate(locale);
     const toolDescriptions = renderToolSection(tools);
+    // Emit the subagent guidance ONLY when the Task tool is actually in the set
+    // (subagents enabled and not in plan mode), so the prompt never tells the
+    // model about a tool it does not have.
+    const subagentSection = tools.some((x) => x.name === 'Task')
+        ? SUBAGENT_SECTION
+        : '';
     const gitSection = gitContext
         ? `\n## Git context\n\n${gitContext}\n`
         : '\n## Git context\n\nNot a git repository (or git is not installed).\n';
@@ -186,7 +221,9 @@ Prefer the most specific tool; a wrong choice wastes a turn:
   directory -> LS.
 - Git operations -> the Git* tools, not Bash.
 - Reading a file whose path you already know -> Read, not Bash cat.
-
+- A broad search/exploration that would flood this chat -> the Task tool
+  (a subagent in its own chat) if it is available, then work from its report.
+${subagentSection}
 ## MCP tools
 
 Some tools are provided by external MCP servers and their names look

package/dist/tools.js

@@ -9,7 +9,7 @@ import { createExtraTools } from './extraTools.js';
 // user-facing. They must be in ENGLISH (like Claude Code / Codex). Only the
 // strings the OPERATOR sees (help, spinner, service messages) are localized —
 // those live in src/i18n.ts (CATALOG) and are picked by the locale setting.
-export function createTools(workdir, { undo, todos, readOnly = false, } = {}) {
+export function createTools(workdir, { undo, todos, readOnly = false, subagents = false, } = {}) {
     const root = path.resolve(workdir);
     const safe = (p) => safePath(root, p);
     // Extracts text from content/content_base64. base64 is needed because the
@@ -200,11 +200,34 @@ export function createTools(workdir, { undo, todos, readOnly = false, } = {}) {
         parameters: { message: 'string' },
         fn: async ({ message }) => message,
     };
+    // `Task` is a SEAM handled by the agent loop (onSubagent), not an ordinary
+    // fn. Its body here is only a fallback for a direct unit-test call; the live
+    // path never reaches it because agent-loop intercepts the name first.
+    const taskTool = {
+        name: 'Task',
+        description: 'Delegate a self-contained sub-task to a SUBAGENT that works in its own ' +
+            'separate chat with an isolated context, then returns ONLY a final ' +
+            'report. Use it to keep heavy research out of the main context. ' +
+            'subagent_type: "explore" (read-only: search/read, cannot modify) or ' +
+            '"general" (full tools). The subagent does NOT see this conversation, so ' +
+            '`prompt` must be fully self-contained: state the goal, the exact ' +
+            'questions, and any file paths/context it needs. Returns the subagent ' +
+            'report as text.',
+        parameters: {
+            description: 'string',
+            prompt: 'string',
+            subagent_type: 'string?',
+        },
+        fn: async () => 'Subagents are not available in this run. Do the work yourself.',
+    };
+    // In plan (read-only) mode `Task` is dropped too: a `general` subagent could
+    // otherwise write through it and defeat the read-only promise.
     const all = [
         ...baseTools,
         ...extraTools,
         ...gitTools,
         ...webTools,
+        ...(subagents && !readOnly ? [taskTool] : []),
         respondTool,
     ];
     return readOnly ? filterToolsForReadOnly(all) : all;