kronk-cli 0.3.1 → 0.4.0

package/README.md

@@ -595,6 +595,7 @@ same way this run did.
 | `-a`, `--auto` | off | Autonomous: auto-approve tools **and** run until the task is done. Implies `--yes` |
 | `-y`, `--yes` | off | Auto-approve `write_file` and `bash` without the autonomous prompt |
 | `--no-think` | off | Disable the model's reasoning pass server-side. Much faster |
+| `--no-subagents` | off | Remove the `task` tool, so the model cannot delegate — see [Sub-agents](#sub-agents) |
 | `--steps <n>` | unlimited | Cap tool calls per task. `0`, `off`, `none`, `inf`, `unlimited` all mean no cap |
 | `-h`, `--help` | — | Print all options and exit |
 | `--` | — | End option parsing; everything after it is prompt text, dashes and all |
@@ -633,12 +634,13 @@ The per-turn usage line still prints after each response; this one is the runnin
 |---|---|
 | `/help` | list these commands |
 | `/models` | what Kronk is serving, with sizes and what is resident |
-| `/model <id>` | switch model — substring match, `/AGENT` preferred |
+| `/model <id>` | switch model — substring match, `/AGENT` preferred; re-reads that model's window and caps |
 | `/file <path>` | add a file to the conversation as context |
 | `/auto` | toggle autonomous mode (auto-approve + run to completion) |
 | `/steps [n\|off]` | show or set the tool-call cap |
 | `/thinking` | show or hide the model's reasoning |
 | `/think` | turn reasoning off entirely — much faster |
+| `/agents` | the sub-agents `task` can delegate to, and what each may touch |
 | `/mcp` | list attached MCP servers and their tools |
 | `/context` | how much of the context window is used |
 | `/compact` | replace the conversation with a summary of itself |
@@ -655,7 +657,7 @@ The per-turn usage line still prints after each response; this one is the runnin
 | `KRONK_TOKEN` | `kronk` | Any non-empty value while Kronk runs open; a real JWT when protected |
 | `KRONK_MODEL` | `unsloth/Qwen3.6-35B-A3B-UD-Q4_K_M/AGENT` | Model id |
 | `KRONK_MODEL_CONFIG` | `~/.kronk/models/model_config.yaml` | Kronk's per-model config, the file `kronk-cli setup` writes |
-| `KRONK_MAX_TOKENS` | `8192` | Output cap per response |
+| `KRONK_MAX_TOKENS` | the model's profile | Output cap per response. Unset, the selected model's own `max_tokens` decides — `8192` only when its profile sets none |
 | `KRONK_MAX_STEPS` | unlimited | Cap on tool calls per task |
 | `KRONK_THINKING` | `true` | `false` hides reasoning but still generates it |
 | `KRONK_NO_THINK` | — | `1` disables reasoning server-side |
@@ -668,6 +670,9 @@ The per-turn usage line still prints after each response; this one is the runnin
 | `KRONK_CONFIG` | `~/.kronk-cli.json` | Path to the config file, so tests and throwaway runs stay off the real one |
 | `KRONK_DISTILL` | `true` | `false` disables tool-output distillation |
 | `KRONK_DISTILL_AT` | `8000` | Characters of output that trigger distillation |
+| `KRONK_SUBAGENTS` | `true` | `false` removes the `task` tool |
+| `KRONK_SUBAGENT_MODEL` | the main model | Model sub-agents run on — substring match, same as `KRONK_MODEL` |
+| `KRONK_SUBAGENT_STEPS` | `40` | Tool-call cap for one delegated task |
 | `KRONK_WARM` | `true` | `false` skips the boot-time model preload |
 | `KRONK_AUTO_COMPACT` | `true` | `false` disables automatic compaction |
 | `KRONK_COMPACT_AT` | `0.85` | Fraction of the window that triggers compaction |
@@ -690,6 +695,8 @@ The per-turn usage line still prints after each response; this one is the runnin
   "noThink": true,
   "preserveThinking": true,
   "replayReasoning": true,
+  "subagentModel": "Qwen3.6-4B",
+  "subagentSteps": 40,
   "sandboxReadable": ["~/Library/Keychains"]
 }
 ```
@@ -851,6 +858,13 @@ not read `reasoning_content` either and would discard the blocks.
 Kronk reports the **effective** window for whichever model id you selected — that comes from
 `context-window` in `model_config.yaml`, so a `/AGENT` profile and its base model can differ.
 
+Every limit is read from the selected model's profile, and re-read when the selection changes:
+the window, the output cap (`sampling-parameters.max_tokens`), whether the chat template
+understands `preserve_thinking`, and the model's native maximum. `/model` mid-session moves all
+of them, and a sub-agent running on `KRONK_SUBAGENT_MODEL` compacts against *its* window rather
+than the main model's. The one number that is not taken from the profile is a `KRONK_MAX_TOKENS`
+you set yourself — yours always wins.
+
 Three places surface it:
 
 **The banner**
@@ -962,10 +976,15 @@ Disable with `--no-compact` or `KRONK_AUTO_COMPACT=false` if you would rather se
 | `write_file` | ✋ | Create or overwrite; shows a diff preview first |
 | `bash` | ✋ | Run a command; shows it first |
 | `set_plan` | — | Record the task checklist; replaces the stored one |
+| `task` | — | Delegate one job to a [sub-agent](#sub-agents) with its own context |
 
 `set_plan` writes nothing and runs nothing — it hands the harness a list, which is why it is
 never gated. See [Autonomous mode](#autonomous-mode) for what the harness then does with it.
 
+`task` is not gated either, because it cannot do anything by itself: every write and every
+command a sub-agent asks for comes back to the same prompt you would have seen had the main
+agent asked for it.
+
 `--yes` and `--auto` skip the prompts. Paths resolve against the session directory and cannot
 escape the launch root — including through a symlink. `bash` additionally runs under an OS
 sandbox where one is available; see [Scope](#scope) for exactly what that covers. `bash` keeps its working directory **between calls**, so a bare `cd`
@@ -1166,6 +1185,127 @@ same way.
 
 ---
 
+## Sub-agents
+
+The model can hand one job to a **sub-agent**: a fresh agent with its own context window, its
+own tool loop, and no memory of your conversation. It runs the task, and the only thing that
+ever comes back is its report.
+
+```console
+› which tools in this repo need approval, and where is that decided?
+
+  1 ⚙ task explore: list every tool definition in src/, say which are gated and where
+   │   1/40 ⚙ search /def\(/ in src
+   │   ✓ 9 lines
+   │   2/40 ⚙ read src/tools.js
+   │   ✓ 587 lines
+   │   3/40 ⚙ read src/subagent.js
+   │   ✓ 211 lines
+   │   2104→380 tok · 58.1 tok/s · 1980 cached
+   Six built-in tools. write_file and bash are gated, by NEEDS_APPROVAL at
+   src/tools.js:261. MCP tools are gated by name, mcpNeedsApproval at :270.
+   read_file, list_dir, search, set_plan and task are not gated.
+  ✓ 3 lines
+
+  `write_file` and `bash`, from the `NEEDS_APPROVAL` set in src/tools.js:246…
+```
+
+`│` marks the sub-agent's own loop; the unprefixed lines are its report, which is what the main
+agent receives as the tool result.
+
+Three files were read. None of them is in your conversation: the 800-odd lines they cost were
+spent in a context that no longer exists, and all that is left in your window is the four-line
+answer. That is the whole point, and it is the trade [distillation](#distillation) makes for
+command output, one level up.
+
+Both agents run against the same Kronk server, so nothing leaves the machine that was not
+already leaving it.
+
+### It is not parallelism
+
+Kronk holds one resident copy of the model, so two sub-agents at once queue behind each other
+and finish no sooner than two in sequence. Delegation here buys **context**, not wall-clock:
+give away the work that is expensive to read and cheap to conclude.
+
+### What it costs, measured
+
+The same survey of `src/` — one table row per module, its responsibility and the gotcha its own
+comments call out, plus three facts quoted with `file:line` — run twice per model on this
+machine, once with `--no-subagents` and once told to orchestrate. `main ctx peak` is the largest
+prompt the *main* conversation ever sent, which is the number the feature exists to move:
+
+| model | mode | wall | main ctx peak | tokens generated | answer |
+|---|---|---|---|---|---|
+| Qwen3.6-35B-A3B `/AGENT` | plain | 143s | 30.8k | 5.5k | 23/23 |
+| Qwen3.6-35B-A3B `/AGENT` | orchestrated, 5 sub-agents | 352s | **12.9k** | 16.2k | 22/23 |
+| Ornith-1.5-35B `/AGENT` | plain | 154s | 34.4k | 5.8k | 23/23 |
+| Ornith-1.5-35B `/AGENT` | orchestrated, 5 sub-agents | 357s | **5.9k** | 16.5k | 23/23 |
+
+Delegation cut the main conversation's high-water mark by 58% and 83%, and cost roughly 2.4×
+the wall clock and 3× the generated tokens to do it. That is the trade in one line: **you are
+buying window, and paying for it in time and tokens.** It is worth it when the conversation has
+to keep going afterwards, and not worth it for a question you were going to ask once.
+
+The one answer that got worse is worth reading too. Qwen's orchestrated run scored 22/23 because
+the sub-agent it asked for "the constant that caps a tool result" came back with a plausible
+wrong one from a different module, and the orchestrator had no way to know: it never read the
+file. The plain run made the same mistake, spent three rounds re-reading `tools.js`, and caught
+it. **A sub-agent's report is evidence you cannot cross-examine** — ask for `file:line` and
+verbatim quotes in the prompt, and check the ones that matter.
+
+### The two agents
+
+| Agent | Tools | For |
+|---|---|---|
+| `explore` | `read_file`, `list_dir`, `search` | Reading, searching, tracing how something works |
+| `code` | those plus `write_file`, `bash` | Making a change, running a build, reproducing a failure |
+
+`/agents` prints this in the REPL, with the model and step cap in force.
+
+Two roles rather than a directory of them, because every extra one is a line the model has to
+read and choose between on each call, and a local model asked to pick between eight
+near-synonyms picks badly. The split that changes what can actually happen is whether it may
+touch anything, so that is the split.
+
+### What it cannot do
+
+- **Ask you anything.** There is nobody in its loop. It is told to take the most reasonable
+  reading of the task, act, and say what it assumed.
+- **Delegate further.** The `task` tool is only ever offered at the top level, which is the
+  entire recursion guard.
+- **Get a command past you.** Its `write_file` and `bash` calls arrive at the same prompt the
+  main agent's do, nested under the call that started them. `--yes` and `--auto` skip them
+  exactly as they always did.
+- **Touch the checklist.** `set_plan` belongs to the task you asked for; a sub-agent has no
+  access to it.
+- **Reach MCP servers.** Its tool list is deliberately the short one.
+
+It also runs under a step cap — 40 by default, where the main agent's is unlimited — because
+nobody is watching it, and a report is worth less than the window a runaway loop would spend
+earning it.
+
+### Knobs
+
+```bash
+kronk-cli --no-subagents             # remove the task tool entirely
+KRONK_SUBAGENT_MODEL=<id> kronk-cli  # run the grunt work on a different model
+KRONK_SUBAGENT_STEPS=80 kronk-cli    # a longer leash per task
+```
+
+A sub-agent gets the same startup scan of your project the main agent got, so it starts knowing
+what the repo is instead of spending its first two steps finding out.
+
+`KRONK_SUBAGENT_MODEL` needs a model that can actually drive a tool loop, and "smaller" is not
+the same thing as "cheaper" here. Measured on the survey task below with `qwen2.5-coder-1.5b`
+as the sub-agent model: every sub-agent returned prose without calling a single tool, the main
+agent noticed, read all eighteen modules itself, and finished with **47.1k** of context against
+the 30.8k it uses when you never delegate at all. A sub-agent that cannot do the work costs you
+the delegation *and* the work.
+
+> A small model will not delegate unprompted as often as a frontier one does. Asking for it
+> works — *"use a sub-agent to survey the test suite first"* — and is usually how you will
+> drive this.
+
 ## Autonomous mode
 
 `--auto`, or `/auto` in the REPL, swaps in a system prompt that tells the model to finish the
@@ -1245,6 +1385,7 @@ previous prompt prefix — watch `cached` climb in the usage line.
 | `src/context.js` | startup scan: git, layout, `AGENTS.md` |
 | `src/compact.js` | summarizing the conversation when the window fills |
 | `src/plan.js` | the task checklist and the snapshot the model sees |
+| `src/subagent.js` | delegation: agent roles, their tools, the report that comes back |
 | `src/mcp.js` | MCP client: stdio + HTTP transports, tool routing |
 | `src/distill.js` | summarizing large tool output in a throwaway context |
 | `src/config.js` | precedence of flags, env, config file |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kronk-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A Claude-Code-style terminal agent for local models served by Kronk.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent.js

@@ -11,6 +11,7 @@ import { maybeDistill } from './distill.js';
 import {
   carryChecklist, clearPlan, openItems, outstandingLines, planLines, pushNudge,
 } from './plan.js';
+import { runTask, taskTools, TASK_TOOL } from './subagent.js';
 
 export const SYSTEM = `You are kronk-cli, a terse coding assistant running fully offline on the user's machine.
 
@@ -50,11 +51,11 @@ const thought = (reasoning) => (reasoning ? { reasoning_content: reasoning } : {
  * view as the wire request that just overflowed — see `compact` in
  * src/compact.js.
  */
-async function compactInto(messages, model, signal, auto) {
-  const res = await compact(messages, { model, signal, auto });
-  if (res.failed || res.skipped) { console.log(report(res)); return false; }
+async function compactInto(messages, { out = console.log, ...opts }) {
+  const res = await compact(messages, opts);
+  if (res.failed || res.skipped) { out(report(res)); return false; }
   messages.splice(0, messages.length, ...res.messages);
-  console.log(report(res));
+  out(report(res));
   return true;
 }
 
@@ -68,8 +69,8 @@ const MAX_NUDGES = 2;
  * message — the reply, or the step-cap note — so a nudge is never left sitting
  * directly before the next typed prompt.
  */
-function endTurn(messages) {
-  outstandingLines().forEach((l) => console.log(l));
+function endTurn(messages, { out = console.log, plan = true } = {}) {
+  if (plan) outstandingLines().forEach((l) => out(l));
   return messages;
 }
 
@@ -86,8 +87,14 @@ function endTurn(messages) {
  */
 export async function runTurn({
   messages, model, signal, approve, grant, mcp, auto = false, maxSteps = config.maxSteps,
+  tools: toolset = TOOLS, plan: usePlan = true, out = console.log, stream = true, depth = 0,
+  // The window and the output cap belong to `model`, not to the session: a
+  // sub-agent may be running on a different model with a different profile.
+  window = config.contextWindow, maxTokens = config.maxTokens,
 }) {
-  const tools = mcp ? [...TOOLS, ...mcp.toolDefs()] : TOOLS;
+  // `taskTools` is empty below the top level, which is the whole recursion
+  // guard: a sub-agent is never handed the tool that spawns one.
+  const tools = [...toolset, ...taskTools(depth), ...(mcp ? mcp.toolDefs() : [])];
   let totalUsage = null;
   let step = 0;
   let compacted = false;
@@ -97,17 +104,22 @@ export async function runTurn({
   // a checklist the previous turn left in the transcript is history, it is
   // already in the prompt prefix, and rewriting history is what evicts the
   // prompt cache — see `carryChecklist`.
-  clearPlan();
+  if (usePlan) clearPlan();
 
   for (;;) {
     step += 1;
     if (Number.isFinite(maxSteps) && step > maxSteps) {
-      console.log(c.yellow(`  ⛔ step cap reached (${maxSteps}). Stopping.`));
-      console.log(c.grey('     raise it with --steps N, or /steps N in the REPL'));
-      messages.push({ role: 'assistant', content: '(stopped: step cap reached)' });
-      return endTurn(messages);
+      out(c.yellow(`  ⛔ step cap reached (${maxSteps}). Stopping.`));
+      out(c.grey(depth
+        ? '     raise it with KRONK_SUBAGENT_STEPS'
+        : '     raise it with --steps N, or /steps N in the REPL'));
+      messages.push({ role: 'assistant',
+        content: depth
+          ? `(stopped: the sub-agent reached its step cap of ${maxSteps} before finishing)`
+          : '(stopped: step cap reached)' });
+      return endTurn(messages, { out, plan: usePlan });
     }
-    let sp = spinner('thinking');
+    let sp = spinner(depth ? 'sub-agent' : 'thinking');
     let text = '';
     let reasoning = '';
     let calls = [];
@@ -122,7 +134,7 @@ export async function runTurn({
         messages: forRequest(messages, auto),
         tools,
         signal,
-        maxTokens: config.maxTokens,
+        maxTokens,
         noThink: config.noThink,
         // Re-read every step: this has to hold for the tool-loop follow-ups too,
         // and `/think` can flip the answer between one turn and the next.
@@ -132,7 +144,9 @@ export async function runTurn({
           // Accumulated before the display check: whether the user watches the
           // model think has nothing to do with whether the model gets it back.
           reasoning += ev.value;
-          if (!config.showThinking) continue;
+          // A sub-agent's reasoning is not the answer, and a second stream
+          // interleaved with the caller's is unreadable. See runTask.
+          if (!stream || !config.showThinking) continue;
           if (sp) { sp.stop(); sp = null; }
           if (!inReasoning) { process.stdout.write(c.grey('\n  ┄ thinking ┄\n  ')); inReasoning = true; }
           process.stdout.write(c.grey(ev.value.replace(/\n/g, '\n  ')));
@@ -140,9 +154,10 @@ export async function runTurn({
         }
 
         else if (ev.type === 'text') {
+          text += ev.value;
+          if (!stream) continue;
           if (sp) { sp.stop(); sp = null; }
           if (inReasoning) { process.stdout.write(c.grey('\n  ┄─────────┄\n\n')); inReasoning = false; }
-          text += ev.value;
           process.stdout.write(ev.value);
           wroteAnything = true;
         }
@@ -159,13 +174,13 @@ export async function runTurn({
       if (sp) { sp.stop(); sp = null; }
       if (isOverflow(e) && !compacted) {
         compacted = true;
-        console.log(c.yellow('\n  context full — compacting and retrying'));
+        out(c.yellow('\n  context full — compacting and retrying'));
         // The plan itself is module state, so compaction cannot reach it. The
         // snapshot it just summarised away is not put back: there is no tool
         // result left to carry one, and inserting a message here would be the
         // rewrite `carryChecklist` exists to avoid. The next round's tool
         // results carry the plan again.
-        if (await compactInto(messages, model, signal, auto)) {
+        if (await compactInto(messages, { model, signal, auto, out, window, maxTokens })) {
           step -= 1;
           continue;
         }
@@ -178,15 +193,21 @@ export async function runTurn({
     if (inReasoning) process.stdout.write(c.grey('\n  ┄─────────┄\n'));
     if (wroteAnything) process.stdout.write('\n');
     if (totalUsage) {
-      console.log(fmtUsage(totalUsage, config.contextWindow));
-      config.lastUsed = (totalUsage.prompt_tokens ?? 0) + (totalUsage.completion_tokens ?? 0);
+      out(fmtUsage(totalUsage, window));
+      // The status line reports the conversation the user is typing into. A
+      // sub-agent's window is its own and is thrown away with it.
+      if (!depth) {
+        config.lastUsed = (totalUsage.prompt_tokens ?? 0) + (totalUsage.completion_tokens ?? 0);
+      }
     }
 
-    if (config.autoCompact && config.contextWindow && totalUsage) {
+    if (config.autoCompact && window && totalUsage) {
       const used = (totalUsage.prompt_tokens ?? 0) + (totalUsage.completion_tokens ?? 0);
-      if (used / config.contextWindow >= config.compactAt) {
-        console.log(c.yellow(`  context ${Math.round((used / config.contextWindow) * 100)}% full — compacting`));
-        if (!await compactInto(messages, model, signal, auto)) config.autoCompact = false;
+      if (used / window >= config.compactAt) {
+        out(c.yellow(`  context ${Math.round((used / window) * 100)}% full — compacting`));
+        if (!await compactInto(messages, { model, signal, auto, out, window, maxTokens })) {
+          config.autoCompact = false;
+        }
       }
     }
 
@@ -195,7 +216,7 @@ export async function runTurn({
       if (!text.trim()) {
         // Reasoning models sometimes spend the whole budget thinking and emit no
         // answer. Say so rather than returning silence.
-        console.log(c.yellow('  (model produced no answer — raise KRONK_MAX_TOKENS or /thinking off)'));
+        out(c.yellow('  (model produced no answer — raise KRONK_MAX_TOKENS or /thinking off)'));
         messages.push({ role: 'assistant', content: '(no answer produced)', ...thought(reasoning) });
       } else {
         messages.push({ role: 'assistant', content: text, ...thought(reasoning) });
@@ -205,13 +226,13 @@ export async function runTurn({
       // keep going — but only when nobody is watching, and only twice: past
       // that the model is not going to finish, and looping is worse than
       // reporting what is left.
-      if (auto && openItems().length && nudges < MAX_NUDGES) {
+      if (usePlan && auto && openItems().length && nudges < MAX_NUDGES) {
         nudges += 1;
         pushNudge(messages);
-        console.log(c.yellow(`  ⚠ ${openItems().length} checklist items still open — continuing`));
+        out(c.yellow(`  ⚠ ${openItems().length} checklist items still open — continuing`));
         continue;
       }
-      return endTurn(messages);
+      return endTurn(messages, { out, plan: usePlan });
     }
 
     messages.push({
@@ -239,17 +260,21 @@ export async function runTurn({
 
       const at = Number.isFinite(maxSteps) ? `${step}/${maxSteps}` : `${step}`;
       const isMcp = Boolean(mcp?.has(call.name));
+      // The same list the model was offered, not just the name it used: with
+      // delegation off, or below the top level, a `task` call is a call to a
+      // tool that does not exist and falls through to runTool saying so.
+      const isTask = !isMcp && call.name === 'task' && tools.includes(TASK_TOOL);
       const label = isMcp
         ? `${c.magenta('⚙')} ${call.name} ${c.grey(JSON.stringify(args).slice(0, 120))}`
         : `${c.blue(`⚙ ${describe(call.name, args)}`)}`;
-      console.log(`${c.grey(`  ${at}`)} ${label}`);
+      out(`${c.grey(`  ${at}`)} ${label}`);
 
       if (isMcp ? mcpNeedsApproval(call.name) : NEEDS_APPROVAL.has(call.name)) {
         const body = preview(call.name, args);
-        if (body) console.log(body.split('\n').map((l) => `    ${l}`).join('\n'));
+        if (body) out(body.split('\n').map((l) => `    ${l}`).join('\n'));
         const ok = await approve(call.name, args);
         if (!ok) {
-          console.log(c.red('  ✗ denied'));
+          out(c.red('  ✗ denied'));
           messages.push({ role: 'tool', tool_call_id: call.id,
             content: 'error: the user denied this action. Ask what to do instead.' });
           continue;
@@ -276,11 +301,11 @@ export async function runTurn({
           if (answer === 'yes' || answer === 'always') {
             try {
               const wrote = rememberGrants(needed, { persist: answer === 'always' });
-              if (wrote) console.log(c.grey(`  remembered in ${wrote}`));
+              if (wrote) out(c.grey(`  remembered in ${wrote}`));
             } catch (e) {
               // Failing to persist must not fail the command. The grant is
               // already in force for this session either way.
-              console.log(c.yellow(`  ${e.message}`));
+              out(c.yellow(`  ${e.message}`));
             }
           } else {
             declineGrants(needed);
@@ -288,35 +313,51 @@ export async function runTurn({
         }
       }
 
-      const live = liveLine();
       let result;
-      try {
-        result = isMcp
-          ? await mcp.call(call.name, args)
-          : await runTool(call.name, args, {
-              onProgress: (info) => live.update({ ...info, window: config.contextWindow }),
-            });
-      } finally {
-        live.done();
+      if (isTask) {
+        // No `liveLine` around this one. It rewrites the current line every
+        // 120 ms, which would erase the sub-agent's own output as fast as it
+        // is printed.
+        try {
+          result = await runTask(args, { run: runTurn, model, signal, approve, grant, out });
+        } catch (e) {
+          // Errors are data here exactly as they are in `runTool`: a
+          // sub-agent that died does not take the turn that delegated to it
+          // down with it.
+          result = `error: the sub-agent failed — ${e.message}`;
+        }
+      } else {
+        const live = liveLine();
+        try {
+          result = isMcp
+            ? await mcp.call(call.name, args)
+            : await runTool(call.name, args, {
+                onProgress: (info) => live.update({ ...info, window }),
+              });
+        } finally {
+          live.done();
+        }
       }
 
       // set_plan hands back a rendering of what the harness just stored; paying a
       // second model call to paraphrase our own text would be pure waste.
-      if (call.name !== 'set_plan') {
+      // A sub-agent's report is already the distillation of everything it
+      // read; paying a second model call to summarise a summary is waste.
+      if (call.name !== 'set_plan' && !isTask) {
         result = await maybeDistill(result, {
-          model, signal, command: args.cmd ?? describe(call.name, args),
+          model, signal, out, command: args.cmd ?? describe(call.name, args),
         });
       }
       const failed = result.startsWith('error:');
-      if (failed) toolResultLines(result).forEach((l) => console.log(l));
-      else if (call.name === 'set_plan') planLines().forEach((l) => console.log(l));
-      else console.log(c.grey(`  ✓ ${result.split('\n').length} lines`));
+      if (failed) toolResultLines(result).forEach((l) => out(l));
+      else if (call.name === 'set_plan') planLines().forEach((l) => out(l));
+      else out(c.grey(`  ✓ ${result.split('\n').length} lines`));
       messages.push({ role: 'tool', tool_call_id: call.id, content: result });
     }
 
     // On the last tool result rather than in a message of its own, so the
     // round only ever adds to the prompt. Nothing already sent is touched.
-    carryChecklist(messages);
+    if (usePlan) carryChecklist(messages);
     // loop: the model now sees the tool output
   }
 }

package/src/argv.js

@@ -24,6 +24,7 @@ const SPECS = [
   { names: ['--no-compact'], kind: 'flag', key: 'noCompact' },
   { names: ['--no-warm'], kind: 'flag', key: 'noWarm' },
   { names: ['--no-think'], kind: 'flag', key: 'noThink' },
+  { names: ['--no-subagents'], kind: 'flag', key: 'noSubagents' },
   { names: ['-a', '--auto'], kind: 'flag', key: 'auto' },
   { names: ['-y', '--yes'], kind: 'flag', key: 'yes' },
   { names: ['--dry-run'], kind: 'flag', key: 'dryRun' },
@@ -102,6 +103,7 @@ export function parseArgv(argv) {
     error: null,
     help: false, models: false, mcpList: false,
     noContext: false, noCompact: false, noWarm: false, noThink: false,
+    noSubagents: false,
     auto: false, yes: false, dryRun: false,
     model: null,
     context: null,

package/src/client.js

@@ -75,10 +75,41 @@ export function samplingOverride(metadata, sampling) {
   return diffs.length ? diffs : null;
 }
 
+export const NO_LIMITS = {
+  configured: null, native: null, preserveThinking: false, samplingDiff: null, maxTokens: null,
+};
+
+/**
+ * Everything about one model that the rest of the program is allowed to
+ * assume, read out of that model's own profile — pure, so the whole surface
+ * is testable without a server.
+ *
+ * `maxTokens` is the profile's own output cap. Kronk reports 0 for a model
+ * whose profile does not set one, which is "no opinion" and not a limit of
+ * zero, so it comes back null and the caller keeps its default. Anything else
+ * is what the person who wrote the profile decided this model may generate,
+ * and it is not ours to halve.
+ */
+export function parseLimits(d) {
+  if (!d) return NO_LIMITS;
+  const sampling = d.model_config?.['sampling-parameters'];
+  const profileMax = num(sampling?.max_tokens);
+  const nativeKey = Object.keys(d.metadata ?? {}).find((k) => k.endsWith('.context_length'));
+  const template = d.metadata?.['tokenizer.chat_template'];
+  return {
+    configured: d.model_config?.['context-window'] ?? null,
+    native: nativeKey ? Number(d.metadata[nativeKey]) : null,
+    preserveThinking: typeof template === 'string' && template.includes('preserve_thinking'),
+    samplingDiff: samplingOverride(d.metadata, sampling),
+    maxTokens: profileMax && profileMax > 0 ? profileMax : null,
+  };
+}
+
 /**
- * Effective context window for a model id, the model's native maximum,
- * whether its chat template understands `preserve_thinking`, and whether the
- * profile is overriding the model's own sampling values.
+ * Effective context window for a model id, the model's native maximum, the
+ * output cap its profile sets, whether its chat template understands
+ * `preserve_thinking`, and whether the profile is overriding the model's own
+ * sampling values.
  * The id contains slashes, so it must be percent-encoded — Kronk's route takes
  * one path segment and 404s on a raw id.
  *
@@ -93,20 +124,9 @@ export function samplingOverride(metadata, sampling) {
  */
 export async function modelLimits(id) {
   try {
-    const d = await (await req(`/kronk/models/${encodeURIComponent(id)}`)).json();
-    const configured = d.model_config?.['context-window'] ?? null;
-    const nativeKey = Object.keys(d.metadata ?? {}).find((k) => k.endsWith('.context_length'));
-    const native = nativeKey ? Number(d.metadata[nativeKey]) : null;
-    const template = d.metadata?.['tokenizer.chat_template'];
-    const preserveThinking = typeof template === 'string' && template.includes('preserve_thinking');
-    const samplingDiff = samplingOverride(d.metadata, d.model_config?.['sampling-parameters']);
-    return {
-      configured, native, preserveThinking, samplingDiff,
-    };
+    return parseLimits(await (await req(`/kronk/models/${encodeURIComponent(id)}`)).json());
   } catch {
-    return {
-      configured: null, native: null, preserveThinking: false, samplingDiff: null,
-    };
+    return NO_LIMITS;
   }
 }
 

package/src/compact.js

@@ -73,16 +73,19 @@ function transcript(messages) {
  * reasoning-replay view of the current task as the wire request that
  * triggered it, not a second, independently-computed answer.
  */
-export async function compact(messages, { model, signal, auto = false } = {}) {
+export async function compact(messages, {
+  model, signal, auto = false, window = config.contextWindow, maxTokens = config.maxTokens,
+} = {}) {
   const system = messages[0];
   const raw = transcript(forRequest(messages, auto));
   if (!raw.trim()) return { messages, before: 0, after: 0 };
 
   const before = await tokenize(model, [system.content, raw].join('\n'));
 
-  // Leave room for the instruction and the summary itself.
-  const window = config.contextWindow ?? 32768;
-  const { text: body, elided } = fit(raw, Math.floor(window * 0.6));
+  // Leave room for the instruction and the summary itself. The window belongs
+  // to the model this compaction runs on, which is not always the one the
+  // session started with — see applyLimits in src/config.js.
+  const { text: body, elided } = fit(raw, Math.floor((window ?? 32768) * 0.6));
   if (elided) console.log(c.grey(`  transcript too large for one pass — elided ${elided.toLocaleString()} chars from the middle`));
 
   let summary = '';
@@ -92,7 +95,7 @@ export async function compact(messages, { model, signal, auto = false } = {}) {
       { role: 'user', content: `${body}\n\n---\n\n${PROMPT}` },
     ],
     signal,
-    maxTokens: Math.min(4096, config.maxTokens),
+    maxTokens: Math.min(4096, maxTokens),
     noThink: true,
   })) {
     if (ev.type === 'text') summary += ev.value;

package/src/config.js

@@ -14,6 +14,11 @@ function fileConfig() {
 
 const file = fileConfig();
 
+/** Only ever used when neither the user nor the model's profile has a number. */
+export const DEFAULT_MAX_TOKENS = 8192;
+
+const maxTokensRaw = process.env.KRONK_MAX_TOKENS ?? file.maxTokens;
+
 /** Used when nothing is passed on the command line or in the environment. */
 export const DEFAULT_MODEL = 'unsloth/Qwen3.6-35B-A3B-UD-Q4_K_M/AGENT';
 
@@ -28,7 +33,13 @@ export const config = {
   baseUrl: process.env.KRONK_URL   ?? file.baseUrl ?? 'http://localhost:11435/v1',
   token:   process.env.KRONK_TOKEN ?? file.token   ?? 'kronk',
   model:   process.env.KRONK_MODEL ?? file.model   ?? null,   // null → DEFAULT_MODEL, then auto-pick
-  maxTokens: Number(process.env.KRONK_MAX_TOKENS ?? file.maxTokens ?? 8192),
+  maxTokens: Number(maxTokensRaw ?? DEFAULT_MAX_TOKENS),
+  // Whether the number above is the user's answer or ours. When it is ours,
+  // boot replaces it with whatever the chosen model's own /AGENT profile
+  // allows — see applyLimits. Without this flag there is no way to tell a
+  // deliberate 8192 from the default one, and the profile would silently
+  // overrule a number the user typed.
+  maxTokensExplicit: maxTokensRaw !== undefined,
   // Unlimited by default — a run stops when the model is done or you press Ctrl-C.
   // Set --steps / KRONK_MAX_STEPS to opt into a cap.
   maxSteps: Number(process.env.KRONK_MAX_STEPS ?? file.maxSteps ?? Infinity),
@@ -56,6 +67,14 @@ export const config = {
   // never enters the conversation. Set KRONK_DISTILL=false to keep it whole.
   distill: (process.env.KRONK_DISTILL ?? String(file.distill ?? 'true')) !== 'false',
   distillAt: Number(process.env.KRONK_DISTILL_AT ?? file.distillAt ?? 8000),
+  // Delegation. A sub-agent runs one task in a context of its own and hands
+  // back only its report, so what it read never enters this conversation —
+  // src/subagent.js has the argument. The step cap is finite where the main
+  // one is not: nobody is watching a sub-agent, and its report is worth less
+  // than the window it would spend earning it.
+  subagents: (process.env.KRONK_SUBAGENTS ?? String(file.subagents ?? 'true')) !== 'false',
+  subagentModel: process.env.KRONK_SUBAGENT_MODEL ?? file.subagentModel ?? null,
+  subagentSteps: Number(process.env.KRONK_SUBAGENT_STEPS ?? file.subagentSteps ?? 40),
   // Kronk's per-model runtime settings. `setup` is the only thing that writes
   // it; the override exists so tests never go near the real one.
   modelConfigPath: process.env.KRONK_MODEL_CONFIG ?? file.modelConfigPath ?? MODEL_CONFIG,
@@ -66,13 +85,39 @@ export const config = {
     .filter((p) => typeof p === 'string' && p.trim())
     .map((p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p)),
   lastUsed: 0,
-  contextWindow: null,   // filled in at boot from Kronk
+  // The startup scan of the working directory, kept so a sub-agent starts
+  // knowing what the project is instead of spending its first two steps on it.
+  projectPrimer: null,
+  contextWindow: null,   // filled in at boot from the chosen model's profile
   nativeContext: null,
+  // The sub-agent model's own limits, when one is configured. A sub-agent on
+  // a 32k model must not compact against the main model's 131k window.
+  subagentLimits: null,
   templatePreservesThinking: false,   // filled in at boot from the model's template
   samplingOverride: null,   // filled in at boot: params where the profile overrides the model's own
   rcPath: RC,
 };
 
+/**
+ * Point the session's limits at one model's profile.
+ *
+ * Every one of these was resolved once at boot and then treated as a property
+ * of the program rather than of the model, so `/model` could move the session
+ * to a 32k model while compaction still aimed at 131k and `preserve_thinking`
+ * was still sent to a template that does not declare it. They are properties
+ * of whichever model is selected now.
+ */
+export function applyLimits({
+  configured, native, preserveThinking, samplingDiff, maxTokens,
+} = {}) {
+  config.contextWindow = configured ?? null;
+  config.nativeContext = native ?? null;
+  config.templatePreservesThinking = Boolean(preserveThinking);
+  config.samplingOverride = samplingDiff ?? null;
+  if (!config.maxTokensExplicit) config.maxTokens = maxTokens ?? DEFAULT_MAX_TOKENS;
+  return config;
+}
+
 /**
  * Whether this request should pin the earlier think blocks: the user wants it,
  * the model's template declares the parameter, and reasoning is on at all —

package/src/distill.js

@@ -103,10 +103,13 @@ export function shouldDistill(result) {
 
 export async function maybeDistill(result, opts) {
   if (!shouldDistill(result)) return result;
+  // `out` so a sub-agent's distillation prints inside its own indented block
+  // rather than at the caller's margin. See runTask in src/subagent.js.
+  const out = opts.out ?? console.log;
   const before = await tokenize(opts.model, result);
   const digest = await distill(result, opts);
   if (!digest || digest.length >= result.length) return result;
   const after = await tokenize(opts.model, digest);
-  console.log(c.grey(`    distilled ${before.toLocaleString()} → ${after.toLocaleString()} tokens (separate context)`));
+  out(c.grey(`    distilled ${before.toLocaleString()} → ${after.toLocaleString()} tokens (separate context)`));
   return digest;
 }

package/src/index.js

@@ -3,7 +3,7 @@ import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
-import { config, DEFAULT_MODEL, warnIfInsecure } from './config.js';
+import { config, DEFAULT_MODEL, applyLimits, warnIfInsecure } from './config.js';
 import { listModels, listModelDetails, listLoaded, modelLimits, tokenize } from './client.js';
 import { pickDefault, ensureLoaded } from './boot.js';
 import { runTurn, SYSTEM, SYSTEM_AUTO } from './agent.js';
@@ -14,6 +14,7 @@ import { compact, report } from './compact.js';
 import { loadServers, McpHub, reportFailures } from './mcp.js';
 import { resolveSandbox, sandbox } from './tools.js';
 import { parseArgv } from './argv.js';
+import { AGENTS } from './subagent.js';
 import { runSetup } from './setup.js';
 
 // ---- argv -------------------------------------------------------------
@@ -50,6 +51,7 @@ if (args.help) {
     -a, --auto          autonomous: approve tools automatically, finish the task
     -y, --yes           approve tools automatically (no autonomous prompt)
         --no-think      disable the model's reasoning pass (faster)
+        --no-subagents  remove the task tool; no delegation
         --steps <n>     cap tool calls per task (default: unlimited)
     -h, --help          this message
         --              end option parsing; everything after is the prompt
@@ -59,7 +61,8 @@ if (args.help) {
     KRONK_TOKEN         any non-empty value when Kronk runs open
     KRONK_MODEL         overrides the default model
     KRONK_MODEL_CONFIG  path to Kronk's model_config.yaml, used by setup
-    KRONK_MAX_TOKENS    output cap per response (default 8192)
+    KRONK_MAX_TOKENS    output cap per response; overrides the cap the
+                        chosen model's own profile sets (8192 if it sets none)
     KRONK_MAX_STEPS     cap on tool calls per task (default unlimited)
     KRONK_NO_THINK      set to 1 to disable reasoning
     KRONK_PRESERVE_THINKING
@@ -68,6 +71,11 @@ if (args.help) {
     KRONK_WARM          false to skip the boot-time model preload
     KRONK_AUTO_COMPACT  false to disable automatic compaction
     KRONK_COMPACT_AT    fraction of the window that triggers it (default 0.85)
+    KRONK_SUBAGENTS     false to remove the task tool
+    KRONK_SUBAGENT_MODEL
+                        model sub-agents run on (default: the main model)
+    KRONK_SUBAGENT_STEPS
+                        tool-call cap for one delegated task (default 40)
 
   Config file: ~/.kronk-cli.json
 `);
@@ -88,6 +96,7 @@ const MCP_ON = args.mcp;
 const MCP_WANTED = args.mcpNames;
 
 if (args.noThink) config.noThink = true;
+if (args.noSubagents) config.subagents = false;
 if (args.noCompact) config.autoCompact = false;
 if (args.noWarm) config.warm = false;
 if (args.model) config.model = args.model;
@@ -128,18 +137,51 @@ async function boot() {
   }
   if (!config.model) config.model = pickDefault(ids);
 
+  // Resolved against what Kronk is actually serving, exactly like the main
+  // model: a substring in the config file that matches nothing would otherwise
+  // only surface as a 404 in the middle of somebody's first delegated task.
+  if (config.subagentModel) {
+    const subs = ids.filter((id) => id.includes(config.subagentModel));
+    const hit = ids.find((id) => id === config.subagentModel)
+             ?? subs.find((id) => id.endsWith('/AGENT'))
+             ?? subs[0];
+    if (hit) config.subagentModel = hit;
+    else {
+      console.error(c.yellow(`  no model matching "${config.subagentModel}" for sub-agents`
+        + ' — they will use the main model'));
+      config.subagentModel = null;
+    }
+  }
+
   if (config.warm) await ensureLoaded(ids);
 
-  const {
-    configured, native, preserveThinking, samplingDiff,
-  } = await modelLimits(config.model);
-  config.contextWindow = configured;
-  config.nativeContext = native;
-  config.templatePreservesThinking = preserveThinking;
-  config.samplingOverride = samplingDiff;
+  // After `ensureLoaded`, which may have fallen back to a different model
+  // than the one asked for. Reading the profile before that point would
+  // describe a model this session is not using.
+  applyLimits(await modelLimits(config.model));
+
+  // The sub-agent model's profile is its own. Resolved once here rather than
+  // on the first delegation, where the wait would land mid-task.
+  config.subagentLimits = config.subagentModel
+    ? await modelLimits(config.subagentModel)
+    : null;
   return ids;
 }
 
+/**
+ * Move the session onto another model, limits and all.
+ *
+ * `/model` used to assign `config.model` and stop there, so a switch to a 32k
+ * model kept compacting against the previous model's 131k window and kept
+ * sending `preserve_thinking` to a template that never declared it. Every
+ * limit is a property of the selected model, so every limit is re-read here.
+ */
+async function switchModel(id) {
+  config.model = id;
+  applyLimits(await modelLimits(id));
+  return id;
+}
+
 const gb = (n) => `${(n / 1e9).toFixed(1)} GB`;
 
 /** Connect the MCP servers the user asked for. Never fatal. */
@@ -244,6 +286,7 @@ const HELP = `
   ${c.bold('/think')}           turn reasoning off entirely (much faster)
   ${c.bold('/auto')}            autonomous mode: auto-approve tools, run to completion
   ${c.bold('/steps [n|off]')}   cap tool calls per task (default: unlimited)
+  ${c.bold('/agents')}          sub-agents you can delegate to with the task tool
   ${c.bold('/mcp')}             list attached MCP servers and their tools
   ${c.bold('/context')}         how much of the context window is used
   ${c.bold('/compact')}         replace the conversation with a summary of itself
@@ -260,6 +303,9 @@ async function systemMessage(auto) {
   const base = auto ? SYSTEM_AUTO : SYSTEM;
   if (NO_CONTEXT) return { content: base, ctx: null };
   const ctx = await projectContext(process.cwd());
+  // Kept for the sub-agents, which get the same primer without paying for the
+  // scan again — see systemFor in src/subagent.js.
+  config.projectPrimer = ctx.text;
   const budget = config.contextWindow
     ? `\n\nYour context window is ${config.contextWindow.toLocaleString()} tokens, shared by `
       + `everything in this conversation: these instructions, file contents you read, command `
@@ -500,6 +546,21 @@ async function main() {
       console.log(c.grey(`  thinking display ${config.showThinking ? 'on' : 'off'}`));
       continue;
     }
+    if (input === '/agents') {
+      if (!config.subagents) {
+        console.log(c.grey('  delegation is off — drop --no-subagents / KRONK_SUBAGENTS=false'));
+        continue;
+      }
+      console.log(c.grey('\n  the model delegates with the task tool — one task, its own context,'));
+      console.log(c.grey('  and only its report comes back. You still approve its writes and commands.'));
+      for (const [name, a] of Object.entries(AGENTS)) {
+        console.log(`  ${c.green('●')} ${c.bold(name)} ${c.grey(`· ${a.tools.join(', ')}`)}`);
+        console.log(c.grey(`      for ${a.use}`));
+      }
+      console.log(c.grey(`  model: ${config.subagentModel ?? config.model} · `
+        + `cap ${config.subagentSteps} steps per task\n`));
+      continue;
+    }
     if (input === '/models') { await showModels(); continue; }
     if (input === '/mcp') {
       if (!mcp || !mcp.routes.size) { console.log(c.grey('  no MCP servers attached — start with --mcp')); continue; }
@@ -538,8 +599,11 @@ async function main() {
                ?? subs.find((m) => m.endsWith('/AGENT'))
                ?? subs[0];
       if (!hit) { console.log(c.red(`  no model matching "${want}"`)); continue; }
-      config.model = hit;
+      await switchModel(hit);
       console.log(c.green(`  switched to ${hit}`));
+      console.log(c.grey(`  window ${config.contextWindow?.toLocaleString() ?? 'unknown'}`
+        + ` · output cap ${config.maxTokens.toLocaleString()}`
+        + `${config.maxTokensExplicit ? ' (yours)' : ' (from its profile)'}`));
       continue;
     }
     if (input.startsWith('/file ')) {

package/src/subagent.js

@@ -0,0 +1,218 @@
+import { def, TOOLS } from './tools.js';
+import { config } from './config.js';
+import { c } from './ui.js';
+
+/**
+ * Sub-agents: one delegated task, one throwaway context.
+ *
+ * The point is the same one src/distill.js makes about command output, moved
+ * up a level. A survey that reads thirty files to answer one question costs
+ * the main conversation thirty files' worth of window, permanently, and it is
+ * still paying for them ten turns later. Handing that survey to a sub-agent
+ * costs the conversation exactly one tool result: the report. Everything the
+ * sub-agent read is discarded with its context.
+ *
+ * So this is not parallelism — a local Kronk server has one resident copy of
+ * the model and calls queue behind each other, so two sub-agents at once is
+ * slower than two in sequence, not faster. It is context economy. Delegate
+ * what is expensive to read and cheap to conclude.
+ */
+
+/** Look, never touch. Every sub-agent gets at least these. */
+const READ_ONLY = ['read_file', 'list_dir', 'search'];
+
+/**
+ * Rules every sub-agent is held to, whatever it is allowed to touch.
+ *
+ * The first two carry the whole contract. A sub-agent that reports "I found
+ * the bug" without saying where is a sub-agent whose entire context was spent
+ * for nothing — the caller cannot go and look, because the files it read are
+ * gone.
+ */
+const CONTRACT = `You are a sub-agent of kronk-cli, running fully offline on the user's machine.
+
+You have been given one self-contained task and a context of your own.
+
+- Nobody sees your work. The agent that delegated this cannot see the files you read, the commands you ran, or your reasoning — your final reply is the only thing it ever receives.
+- So the reply has to stand alone: the answer, the exact paths and line numbers behind it, whatever failed, and whatever you had to assume. Quote the few lines that matter verbatim; never paste whole files, because not having to hold them is the reason you were given this task.
+- Do not ask questions. There is nobody to answer one. Take the most reasonable reading of the task, act on it, and say what you assumed.
+- Do not stop half way and report progress. Finish the task, then report.
+- Keep the reply under about 30 lines.
+- The working directory is the user's project root. Paths are relative to it. You are already inside it. Do not \`cd\` above it.`;
+
+/**
+ * The roles a sub-agent can be given.
+ *
+ * Two, not ten. Each one is a line the delegating model has to read and choose
+ * between on every call, and a local model asked to pick between eight
+ * near-synonyms picks badly — the split that actually changes what can happen
+ * is "can it touch anything", so that is the split.
+ */
+export const AGENTS = {
+  explore: {
+    use: 'reading, searching, tracing how something works, answering a question about the code',
+    tools: READ_ONLY,
+    rules: '- You can only read: read_file, list_dir and search. You cannot run commands and you cannot change anything. If the task needs a command run or a file written, say so in your reply rather than trying.',
+  },
+  code: {
+    use: 'making a change, running a build or a test suite, reproducing a failure',
+    tools: [...READ_ONLY, 'write_file', 'bash'],
+    rules: '- You can also write files and run commands. The user is still asked before each one, and a refusal is an answer: report it, do not look for a way around it.\n'
+      + '- After you write code, RUN it and fix what breaks. Never report that something works unless you have executed it and seen the output.',
+  },
+};
+
+const agentList = () => Object.entries(AGENTS)
+  .map(([name, a]) => `"${name}" — ${a.use}`).join('; ');
+
+/**
+ * The instruction the delegating model actually reads.
+ *
+ * Same reasoning as set_plan's description in src/tools.js: a description is
+ * the one place a small model reliably looks, so the whole protocol lives
+ * here — what it is for, that the sub-agent starts blank, and that a vague
+ * prompt is the failure mode.
+ */
+export const TASK_TOOL = def('task',
+  'Delegate one self-contained piece of work to a sub-agent that runs in its own context. '
+  + 'Use it when getting the answer means reading or running a lot but the answer itself is '
+  + 'small — surveys, searches across many files, reproducing a failure. What the sub-agent '
+  + 'reads never enters this conversation; only its report does. The sub-agent cannot see this '
+  + 'conversation and cannot ask you anything, so the prompt must carry everything it needs and '
+  + 'must say exactly what to report back. It cannot delegate further. Prefer one well-scoped '
+  + 'task over several vague ones.',
+  {
+    agent: {
+      type: 'string',
+      enum: Object.keys(AGENTS),
+      description: `Which sub-agent to run: ${agentList()}.`,
+    },
+    prompt: {
+      type: 'string',
+      description: 'The whole task, written for someone who knows nothing about this '
+        + 'conversation: what to do, where to look, and exactly what to report back.',
+    },
+  },
+  ['agent', 'prompt']);
+
+/**
+ * The delegation tool, when it is allowed at all.
+ *
+ * Empty below the top level, and that is the recursion guard: a sub-agent is
+ * never handed the tool that would let it spawn one. Nothing else enforces
+ * depth, and nothing else needs to.
+ */
+export function taskTools(depth = 0) {
+  return depth === 0 && config.subagents ? [TASK_TOOL] : [];
+}
+
+/** The built-ins this role is allowed, in the order src/tools.js defines them. */
+export function subagentTools(agent) {
+  const allowed = new Set(AGENTS[agent]?.tools ?? READ_ONLY);
+  return TOOLS.filter((t) => allowed.has(t.function.name));
+}
+
+/**
+ * The sub-agent's system prompt: the contract, its role's rules, and the same
+ * project primer the main agent was given at startup.
+ *
+ * The primer is worth its tokens — without it every sub-agent spends its first
+ * two steps working out what the project is, in a context it only gets one of.
+ */
+export function systemFor(agent) {
+  const spec = AGENTS[agent];
+  const primer = config.projectPrimer ? `\n\n---\n\n${config.projectPrimer}` : '';
+  return `${CONTRACT}\n${spec.rules}${primer}`;
+}
+
+/** Nest one line of a sub-agent's output under the call that started it. */
+const nest = (line) => String(line).split('\n')
+  .map((l) => `${c.grey('   │')} ${l}`).join('\n');
+
+const MAX_REPORT_LINES = 14;
+
+/** The report on screen, dimmed and bounded — the caller received all of it. */
+function reportLines(text) {
+  const lines = text.split('\n');
+  const shown = lines.slice(0, MAX_REPORT_LINES).map((l) => c.grey(`   ${l}`));
+  const hidden = lines.length - shown.length;
+  if (hidden > 0) {
+    shown.push(c.grey(`   …${hidden} more line${hidden === 1 ? '' : 's'} (the agent received all of it)`));
+  }
+  return shown;
+}
+
+/**
+ * The sub-agent's last word, which is the entire value of the call.
+ *
+ * A turn always ends on an assistant message — see `endTurn` in src/agent.js —
+ * so the tail is the report. An empty one is reported as the error it is
+ * rather than handed back as a blank tool result the caller would have to
+ * interpret.
+ */
+function reportFrom(messages) {
+  const last = [...messages].reverse().find((m) => m.role === 'assistant');
+  const text = String(last?.content ?? '').trim();
+  if (!text) return 'error: the sub-agent finished without reporting anything. Do the work here, or delegate again with a more specific prompt.';
+  return text;
+}
+
+/**
+ * Run one delegated task to completion and hand back only its report.
+ *
+ * `run` is `runTurn` from src/agent.js, passed in rather than imported: the
+ * dispatch for this tool lives in that loop, so importing it back would be a
+ * cycle for nothing. `approve` and `grant` are the caller's own, unchanged —
+ * delegation is not a way to get a command past the user.
+ */
+export async function runTask(args, {
+  run, model, signal, approve, grant, out = console.log, maxSteps = config.subagentSteps,
+}) {
+  const agent = args?.agent ?? 'explore';
+  const prompt = String(args?.prompt ?? '').trim();
+  if (!AGENTS[agent]) {
+    return `error: unknown agent "${agent}" — use one of: ${Object.keys(AGENTS).join(', ')}`;
+  }
+  if (!prompt) return 'error: task needs a prompt saying what to do and what to report back';
+
+  const messages = [
+    { role: 'system', content: systemFor(agent) },
+    { role: 'user', content: prompt },
+  ];
+
+  // A sub-agent on another model gets that model's window and output cap, not
+  // the session's. Compacting a 32k sub-agent at 85% of the main model's 131k
+  // means never compacting it at all.
+  const own = config.subagentModel ? config.subagentLimits : null;
+
+  const done = await run({
+    messages,
+    // A smaller model for the grunt work is the whole reason this is a knob:
+    // the survey is reading and grepping, the synthesis is not.
+    model: config.subagentModel ?? model,
+    window: own ? own.contextWindow : config.contextWindow,
+    maxTokens: own?.maxTokens ?? config.maxTokens,
+    signal,
+    approve,
+    grant,
+    // No MCP: a local model already struggles past ~25 tools, and the
+    // sub-agent's list is meant to be the short one.
+    mcp: null,
+    tools: subagentTools(agent),
+    // The checklist is module state belonging to the task the user asked for.
+    // A sub-agent that called set_plan would clear it out from under the agent
+    // that delegated to it.
+    plan: false,
+    // Its reasoning and prose are not printed: they are not the answer, and a
+    // second stream interleaved with the caller's is unreadable. Tool calls
+    // still show, indented, so the run is not a black box.
+    stream: false,
+    out: (line) => out(nest(line)),
+    maxSteps,
+    depth: 1,
+  });
+
+  const report = reportFrom(done);
+  reportLines(report).forEach((l) => out(l));
+  return report;
+}

package/src/tools.js

@@ -206,7 +206,13 @@ export function safe(p) {
   return abs;
 }
 
-const def = (name, description, properties, required) => ({
+/**
+ * A tool definition in the shape the OpenAI-compatible API wants.
+ *
+ * Exported because src/subagent.js defines a tool too — one that is only
+ * offered at the top level, so it cannot live in TOOLS below.
+ */
+export const def = (name, description, properties, required) => ({
   type: 'function',
   function: { name, description, parameters: { type: 'object', properties, required } },
 });
@@ -284,6 +290,7 @@ export function describe(name, args) {
     case 'search':     return `search /${args.pattern}/ in ${args.path ?? '.'}`;
     case 'bash':       return `bash: ${args.cmd}`;
     case 'set_plan':   return `plan: ${args.items?.length ?? 0} items`;
+    case 'task':       return `task ${args.agent ?? 'explore'}: ${String(args.prompt ?? '').split('\n')[0]}`;
     default:           return `${name}(${JSON.stringify(args)})`;
   }
 }