subagents

1import { atom, read, update } from 'claude-code';
2import type { Register, Timer } from 'claude-code';
3import type { AgentLogLine, TrackedAgent } from '../types';
4import {
5  LOG_LINES,
6  TICK_MS,
7  agentDone,
8  agentHeading,
9  applyListed,
10  hydrate,
11  isIdle,
12  isSettled,
13  noteSpawn,
14  planTick,
15  requestPaneCheck,
16  setPaneShown,
17  snapshot,
18  stepChunk,
19  stepEnded,
20  stepStarted,
21  toolEnded,
22  toolStarted,
23  track,
24} from './agent-board';
25
26const AGENTS_PANE = 'agents';
27const AGENTS_TITLE = 'Subagents';
28
29const board = atom({ plugin: 'subagents', key: 'board' } as const, {
30  agents: [],
31  at: 0,
32  isBatchClosed: false,
33  isPaneShown: false,
34});
35const tab = atom({ plugin: 'subagents', key: 'tab' } as const, 'all');
36
37const STATUS_COLOR: Readonly<Record<string, string>> = {
38  pending: 'inactive',
39  running: 'warning',
40  waiting: 'warning',
41  idle: 'inactive',
42  completed: 'success',
43  failed: 'error',
44  killed: 'error',
45};
46
47/** 0 is All; agents 1-9 take digits, 10-35 lowercase letters (no letter is bound inside a pane). */
48const TAB_KEYS = [...'123456789abcdefghijklmnopqrstuvwxyz'];
49
50const LINE_MARK = { run: '·', ok: '✓', err: '✗' } as const satisfies Record<NonNullable<AgentLogLine['state']>, string>;
51
52let ticker: Timer | undefined;
53let isTicking = false;
54
55/**
56 * Starts the ticker that writes the board and opens/closes the pane. Set by
57 * `session.start`, the one hook whose `$` the ticker uses, since the engine
58 * refuses a module that passes `$` around.
59 */
60let wake: () => void = () => undefined;
61
62function safe(fn: () => void) {
63  try {
64    fn();
65  } catch {
66    // An observer never lets its own bookkeeping fail the call it watches.
67  }
68}
69
70function observe(fn: () => void) {
71  safe(fn);
72  safe(wake);
73}
74
75const lineText = (line: AgentLogLine) =>
76  line.kind === 'tool' ? `  ${LINE_MARK[line.state ?? 'run']} ${line.text}` : line.kind === 'text' ? `  » ${line.text}` : `  ${line.text}`;
77
78const elapsed = (agent: TrackedAgent, at: number) =>
79  `${Math.max(0, Math.round(((agent.endedAt ?? at) - agent.startedAt) / 1000))}s`;
80
81export const register: Register = (on) => {
82  on('session.start', async ($, e, next) => {
83    const tick = async () => {
84      if (isTicking) return;
85
86      isTicking = true;
87      try {
88        const plan = planTick();
89        if (plan.shouldOpen && !(await $.ui.panes()).some((pane) => pane.id === AGENTS_PANE)) {
90          const opened = await $.ui.open({ id: AGENTS_PANE, title: AGENTS_TITLE, closeOnEscape: true });
91          if (!opened.isPlaced) $.ui.toast('Subagents pane waits for a 144-column terminal. Run /agents-pane to show it now.');
92        }
93        if (plan.shouldSync) applyListed(await $.agent.list());
94        if (plan.shouldCheckPanes || plan.shouldOpen) {
95          setPaneShown((await $.ui.panes()).some((pane) => pane.id === AGENTS_PANE && pane.isPlaced && pane.isShown));
96        }
97        if (plan.shouldClose) await $.ui.close({ id: AGENTS_PANE });
98        if (plan.shouldFlush) await update($, board, () => snapshot());
99      } catch (error) {
100        $.ui.log(`subagents: tick failed: ${String(error)}`, { to: 'debug' });
101      } finally {
102        isTicking = false;
103      }
104      if (isIdle()) {
105        ticker?.cancel();
106        ticker = undefined;
107      }
108    };
109    wake = () => {
110      if (ticker === undefined) ticker = $.clock.every(TICK_MS, tick);
111    };
112
113    try {
114      await $.command.register({ name: 'agents-pane', description: 'Show the live subagents pane', immediate: true });
115      hydrate(await read($, board));
116      wake();
117    } catch (error) {
118      $.ui.log(`subagents: setup failed: ${String(error)}`, { to: 'debug' });
119    }
120    return next(e);
121  });
122
123  on('agent.spawn', async ($, e, next) => {
124    const spawned = await next(e);
125    const { agentId } = spawned;
126    if (agentId !== undefined) {
127      observe(() =>
128        noteSpawn(agentId, {
129          type: e.subagentType,
130          description: e.description,
131          model: spawned.model,
132          detail: `started${e.background ? ' in background' : ''}`,
133        }),
134      );
135    }
136    return spawned;
137  }).catch(($, e, next) => next(e));
138  on('tool.call', async ($, e, next) => {
139    const { agentId } = e;
140    if (agentId === undefined) return next(e);
141
142    observe(() => toolStarted(agentId, e, e.tool, e.tool_use_id));
143    const result = await next(e);
144    observe(() => toolEnded(agentId, e.tool_use_id, result));
145    return result;
146  }).catch(($, e, next) => next(e));
147  on('turn.step', async function* ($, e, next) {
148    const { agentId } = e;
149    if (agentId === undefined) return yield* next(e);
150
151    observe(() => stepStarted(agentId, e.model, e.effort));
152    try {
153      for await (const chunk of next(e)) {
154        observe(() => stepChunk(agentId, chunk));
155        yield chunk;
156      }
157    } finally {
158      observe(() => stepEnded(agentId));
159    }
160  });
161  on('turn.complete', ($, e, next) => {
162    const { agentId } = e;
163    if (agentId !== undefined) observe(() => agentDone(agentId, e));
164    return next(e);
165  }).catch(($, e, next) => next(e));
166  on('ui.close', { id: AGENTS_PANE }, ($, e, next) => {
167    observe(requestPaneCheck);
168    return next(e);
169  }).catch(($, e, next) => next(e));
170  on('command.run', { command: 'agents-pane' }, async ($) => {
171    const opened = await $.ui.open({ id: AGENTS_PANE, title: AGENTS_TITLE, focus: true, closeOnEscape: true });
172    observe(requestPaneCheck);
173    return opened.isPlaced ? {} : { text: `Subagents pane is waiting: ${opened.reason}` };
174  }).catch(() => ({ text: 'agents-pane: could not open the pane (see claude --debug)' }));
175  on('ui.render', { component: 'Pane', requestId: AGENTS_PANE }, async ($, e) => {
176    const { Box, Text, Button } = $.ui.resolve(e);
177    try {
178      const { agents: list, at } = await read($, board);
179      const picked = await read($, tab);
180
181      const selected = list.find((agent) => agent.id === picked);
182      const running = list.filter((agent) => !isSettled(agent.status)).length;
183      const perAgent =
184        selected !== undefined
185          ? LOG_LINES
186          : Math.max(2, Math.floor((Math.max(8, e.props.scroll.bodyRows) - 3) / Math.max(1, list.length)) - 1);
187
188      return (
189        <Box flexDirection="column">
190          <Text bold>{`${AGENTS_TITLE}: ${running} running, ${list.length - running} done`}</Text>
191          <Box flexDirection="row" flexWrap="wrap" columnGap={2}>
192            <Button key="tab-all" label="All" hotkey="0" plain dimColor={selected !== undefined} onPress={() => update($, tab, () => 'all')} />
193            {list.slice(0, TAB_KEYS.length).map((agent, index) => (
194              <Button
195                key={`tab-${TAB_KEYS[index] ?? index}`}
196                label={agent.type}
197                hotkey={TAB_KEYS[index]}
198                plain
199                dimColor={selected?.id !== agent.id}
200                onPress={() => update($, tab, () => agent.id)}
201              />
202            ))}
203          </Box>
204          {list.length === 0 && <Text dimColor>No subagents yet. They show here once Claude starts one.</Text>}
205          {(selected === undefined ? list : [selected]).map((agent) => (
206            <Box flexDirection="column" marginTop={1}>
207              <Box flexDirection="row" columnGap={1}>
208                <Text color={STATUS_COLOR[agent.status] ?? 'text'}>●</Text>
209                <Text bold>{agentHeading(agent)}</Text>
210                <Text wrap="truncate-end">{agent.description}</Text>
211                <Text dimColor wrap="truncate-end">
212                  {`${agent.status} ${elapsed(agent, at)} · ${agent.tools} tools`}
213                </Text>
214              </Box>
215              {agent.lines.slice(-perAgent).map((line) => (
216                <Text
217                  wrap="truncate-end"
218                  dimColor={line.kind === 'note' || line.state === 'ok'}
219                  {...(line.state === 'err' && { color: 'error' })}
220                  {...(line.kind === 'text' && { italic: true })}
221                >
222                  {lineText(line)}
223                </Text>
224              ))}
225              {agent.live !== undefined && (
226                <Text wrap="truncate-start" color="claude">
227                  {`  ▸ ${agent.live}`}
228                </Text>
229              )}
230            </Box>
231          ))}
232          <Text dimColor wrap="truncate-end">
233            {`0-9, a-z tabs · ctrl+x x or Esc closes${running === 0 && list.length > 0 ? ' · closes itself 15s after the last agent ends' : ''}`}
234          </Text>
235        </Box>
236      );
237    } catch (error) {
238      return <Text color="error">{`subagents: ${String(error)}`}</Text>;
239    }
240  });
241  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
242    if (e.props.hasSurvey) return next(e);
243
244    try {
245      const shown = await read($, board);
246      if (shown.agents.length === 0 || shown.isBatchClosed === true || shown.isPaneShown === true) return next(e);
247
248      const running = shown.agents.filter((agent) => !isSettled(agent.status)).length;
249      const { Text } = $.ui.resolve(e);
250      return (
251        <Text wrap="truncate-end">
252          {`${AGENTS_TITLE}: ${running} running · ${shown.agents.length - running} done — /agents-pane`}
253        </Text>
254      );
255    } catch {
256      return next(e);
257    }
258  });
259};
260

1import type { AgentInfo, ToolCallResult, TurnCompleteInput, TurnStepChunk } from 'claude-code';
2import type { AgentBoard, AgentLogLine, TrackedAgent } from '../types';
3import { oneLine, summarizeToolInput, tail } from './tool-input-summary';
4
5export const LOG_LINES = 30;
6export const TICK_MS = 300;
7const MAX_AGENTS = 40;
8const SYNC_TICKS = 7;
9const CLOSE_TICKS = Math.ceil(15_000 / TICK_MS);
10const STREAM_KEEP = 400;
11
12/**
13 * The subagents the pane shows, held in module memory: hooks mutate it with no
14 * `$` call, and the ticker `session.start` owns writes it to `$.state`.
15 */
16const agents = new Map<string, TrackedAgent>();
17const streams = new Map<string, { head: string; tail: string }>();
18
19const flags = {
20  isDirty: false,
21  wantsOpen: false,
22  isBatchClosed: false,
23  isPaneShown: false,
24  wantsPaneCheck: false,
25  closeIn: undefined as number | undefined,
26  ticks: 0,
27};
28
29export const isSettled = (status: string) =>
30  status === 'completed' || status === 'failed' || status === 'killed' || status === 'idle';
31
32const allSettled = () => [...agents.values()].every((agent) => isSettled(agent.status));
33
34function pushLine(agent: TrackedAgent, line: AgentLogLine) {
35  agent.lines.push(line);
36  if (agent.lines.length > LOG_LINES) agent.lines.splice(0, agent.lines.length - LOG_LINES);
37}
38
39export function snapshot(): AgentBoard {
40  return {
41    agents: [...agents.values()].map((agent) => ({ ...agent, lines: agent.lines.map((line) => ({ ...line })) })),
42    at: Date.now(),
43    isBatchClosed: flags.isBatchClosed,
44    isPaneShown: flags.isPaneShown,
45  };
46}
47
48export function hydrate(saved: AgentBoard) {
49  if (agents.size > 0) return;
50
51  for (const agent of saved.agents) agents.set(agent.id, { ...agent, lines: agent.lines.map((line) => ({ ...line })) });
52  flags.isBatchClosed = saved.isBatchClosed ?? false;
53  flags.isPaneShown = saved.isPaneShown ?? false;
54  flags.isDirty = saved.agents.length > 0;
55  flags.wantsPaneCheck = saved.agents.length > 0;
56}
57
58/**
59 * `claude-sonnet-5-20261001` → `sonnet-5`; Bedrock (`us.anthropic.…-v1:0`),
60 * Vertex (`…@20261001`) and gateway (`org/…`) spellings alike.
61 */
62export const shortModel = (model: string) =>
63  model
64    .slice(model.lastIndexOf('/') + 1)
65    .replace(/^([a-z]+\.)?anthropic\./, '')
66    .replace(/^claude-/, '')
67    .replace(/-v\d+:\d+$/, '')
68    .replace(/[-@]\d{8}$/, '');
69
70export const agentHeading = (agent: Pick<TrackedAgent, 'type' | 'model' | 'effort'>) =>
71  [agent.type, agent.model, agent.effort].filter((part) => part !== undefined && part !== '').join(' · ');
72
73export function requestPaneCheck() {
74  flags.wantsPaneCheck = true;
75}
76
77export function setPaneShown(isShown: boolean) {
78  if (flags.isPaneShown === isShown) return;
79
80  flags.isPaneShown = isShown;
81  flags.isDirty = true;
82}
83
84export function reset() {
85  agents.clear();
86  streams.clear();
87  Object.assign(flags, {
88    isDirty: false,
89    wantsOpen: false,
90    isBatchClosed: false,
91    isPaneShown: false,
92    wantsPaneCheck: false,
93    closeIn: undefined,
94    ticks: 0,
95  });
96}
97
98/** Starts tracking an agent; true when it is new, which asks for the pane. */
99export function track(id: string, type?: string, description?: string) {
100  const known = agents.get(id);
101  if (known !== undefined) {
102    if (type !== undefined && type !== '' && known.type === 'agent') known.type = type;
103    if (description !== undefined && description !== '' && known.description === '') known.description = description;
104    return false;
105  }
106
107  if (flags.isBatchClosed) {
108    for (const [key, agent] of agents) if (isSettled(agent.status)) agents.delete(key);
109    flags.isBatchClosed = false;
110  }
111
112  agents.set(id, {
113    id,
114    type: type !== undefined && type !== '' ? type : 'agent',
115    description: description ?? '',
116    status: 'running',
117    startedAt: Date.now(),
118    tools: 0,
119    lines: [],
120  });
121  for (const [key, agent] of agents) {
122    if (agents.size <= MAX_AGENTS) break;
123    if (isSettled(agent.status)) agents.delete(key);
124  }
125
126  flags.closeIn = undefined;
127  flags.wantsOpen = true;
128  flags.isDirty = true;
129  return true;
130}
131
132function revive(agent: TrackedAgent) {
133  if (!isSettled(agent.status)) return;
134
135  agent.status = 'running';
136  agent.endedAt = undefined;
137  flags.closeIn = undefined;
138}
139
140export function noteSpawn(agentId: string, spawn: { type: string; description: string; model: string; detail: string }) {
141  track(agentId, spawn.type, spawn.description);
142  const agent = agents.get(agentId);
143  if (agent === undefined) return;
144
145  if (agent.model === undefined && spawn.model !== '') agent.model = shortModel(spawn.model);
146  if (agent.lines.length === 0) pushLine(agent, { kind: 'note', text: spawn.detail });
147}
148
149/** A model request of the agent's loop: the model and effort it is about to be sent with. */
150export function stepStarted(agentId: string, model: string, effort: string | number | undefined) {
151  track(agentId);
152  const agent = agents.get(agentId);
153  if (agent === undefined) return;
154
155  agent.model = shortModel(model);
156  agent.effort = effort === undefined ? undefined : String(effort);
157  flags.isDirty = true;
158}
159
160export function toolStarted(agentId: string, input: Readonly<Record<string, unknown>>, tool: string, toolUseId: string) {
161  track(agentId);
162  const agent = agents.get(agentId);
163  if (agent === undefined) return;
164
165  revive(agent);
166  agent.tools += 1;
167  const summary = summarizeToolInput(input);
168  pushLine(agent, { id: toolUseId, kind: 'tool', state: 'run', text: summary === '' ? tool : `${tool}: ${summary}` });
169  flags.isDirty = true;
170}
171
172export function toolEnded(agentId: string, toolUseId: string, result: ToolCallResult) {
173  const line = agents.get(agentId)?.lines.find((one) => one.id === toolUseId);
174  if (line === undefined) return;
175
176  line.state = result.deny !== undefined || result.isError === true ? 'err' : 'ok';
177  if (result.deny !== undefined) line.text = `${line.text}  (denied)`;
178  flags.isDirty = true;
179}
180
181export function stepChunk(agentId: string, chunk: TurnStepChunk) {
182  const agent = agents.get(agentId);
183  if (agent === undefined) return;
184
185  const stream = streams.get(agentId) ?? { head: '', tail: '' };
186  if (chunk.kind === 'thinking' && stream.head === '') {
187    agent.live = 'thinking…';
188    flags.isDirty = true;
189    return;
190  }
191  if (chunk.kind !== 'text') return;
192
193  const next = { head: `${stream.head}${chunk.text}`.slice(0, STREAM_KEEP), tail: `${stream.tail}${chunk.text}`.slice(-STREAM_KEEP) };
194  streams.set(agentId, next);
195  agent.live = tail(next.tail, 160);
196  flags.isDirty = true;
197}
198
199export function stepEnded(agentId: string) {
200  const agent = agents.get(agentId);
201  const text = streams.get(agentId)?.head ?? '';
202  streams.delete(agentId);
203  if (agent === undefined) return;
204
205  agent.live = undefined;
206  if (text.trim() !== '') pushLine(agent, { kind: 'text', text: oneLine(text, 200) });
207  flags.isDirty = true;
208}
209
210export function agentDone(agentId: string, e: TurnCompleteInput) {
211  track(agentId);
212  const agent = agents.get(agentId);
213  if (agent === undefined) return;
214
215  agent.status = e.isAborted ? 'killed' : e.reason === 'answer' ? 'completed' : 'failed';
216  agent.endedAt = Date.now();
217  agent.live = undefined;
218  pushLine(agent, { kind: 'note', text: `${agent.status} after ${Math.round(e.durationMs / 100) / 10}s` });
219  flags.isDirty = true;
220}
221
222/** Refreshes type, description and status from `$.agent.list()`, and adopts running agents no hook saw start. */
223export function applyListed(listed: readonly AgentInfo[]) {
224  for (const info of listed) {
225    const agent = agents.get(info.id);
226    if (agent === undefined) {
227      if (info.status === 'running' || info.status === 'pending') track(info.id, info.type, info.description);
228      continue;
229    }
230
231    const before = `${agent.type}|${agent.description}|${agent.status}`;
232    if (agent.type === 'agent' && info.type !== '') agent.type = info.type;
233    if (agent.description === '' && info.description !== '') agent.description = info.description;
234    if (agent.status !== info.status && (isSettled(info.status) || !isSettled(agent.status))) {
235      agent.status = info.status;
236      if (isSettled(info.status)) agent.endedAt ??= Date.now();
237    }
238    if (`${agent.type}|${agent.description}|${agent.status}` !== before) flags.isDirty = true;
239  }
240}
241
242/** What one tick of the ticker owes: which effects to run, and whether it may stop. */
243export function planTick() {
244  flags.ticks += 1;
245
246  const shouldOpen = flags.wantsOpen;
247  flags.wantsOpen = false;
248
249  const shouldSync = !allSettled() && flags.ticks % SYNC_TICKS === 0;
250
251  const shouldCheckPanes =
252    flags.wantsPaneCheck || (agents.size > 0 && !flags.isBatchClosed && flags.ticks % SYNC_TICKS === 0);
253  flags.wantsPaneCheck = false;
254
255  let shouldClose = false;
256  if (agents.size === 0 || !allSettled() || flags.isBatchClosed) flags.closeIn = undefined;
257  else if (flags.closeIn === undefined) flags.closeIn = CLOSE_TICKS;
258  else if (--flags.closeIn <= 0) {
259    flags.closeIn = undefined;
260    flags.isBatchClosed = true;
261    flags.isPaneShown = false;
262    flags.isDirty = true;
263    shouldClose = true;
264  }
265
266  const shouldFlush = flags.isDirty;
267  flags.isDirty = false;
268
269  return { shouldOpen, shouldSync, shouldCheckPanes, shouldFlush, shouldClose };
270}
271
272export const isIdle = () =>
273  !flags.isDirty &&
274  !flags.wantsOpen &&
275  !flags.wantsPaneCheck &&
276  flags.closeIn === undefined &&
277  allSettled() &&
278  (agents.size === 0 || flags.isBatchClosed);
279

1const PRIMARY_KEYS = [
2  'command',
3  'file_path',
4  'notebook_path',
5  'pattern',
6  'path',
7  'url',
8  'query',
9  'skill',
10  'description',
11  'subject',
12  'prompt',
13];
14
15const ENVELOPE_KEYS = ['tool', 'tool_use_id', 'agentId'];
16
17export function oneLine(text: string, max: number) {
18  const flat = text.replace(/\s+/g, ' ').trim();
19
20  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
21}
22
23export function tail(text: string, max: number) {
24  const flat = text.replace(/\s+/g, ' ').trim();
25
26  return flat.length > max ? `…${flat.slice(flat.length - max + 1)}` : flat;
27}
28
29/** One short line for a tool call's input: the Bash command, the file path, the pattern, ... */
30export function summarizeToolInput(input: Readonly<Record<string, unknown>>, max = 140) {
31  for (const key of PRIMARY_KEYS) {
32    const value = input[key];
33    if (typeof value !== 'string' || value.trim() === '') continue;
34
35    const where = input.path;
36    if (key === 'pattern' && typeof where === 'string' && where !== '') return oneLine(`${value} in ${where}`, max);
37
38    return oneLine(value, max);
39  }
40
41  const rest = Object.fromEntries(Object.entries(input).filter(([key]) => !ENVELOPE_KEYS.includes(key)));
42  return Object.keys(rest).length === 0 ? '' : oneLine(JSON.stringify(rest), max);
43}
44

1export type AgentLogLine = {
2  /** The tool_use_id of a tool line, so its result can mark it. */
3  id?: string;
4  kind: 'tool' | 'text' | 'note';
5  text: string;
6  state?: 'run' | 'ok' | 'err';
7};
8
9export type TrackedAgent = {
10  id: string;
11  type: string;
12  description: string;
13  status: string;
14  startedAt: number;
15  endedAt?: number;
16  tools: number;
17  /** Short model id, from the spawn's resolved model, then each model request. */
18  model?: string;
19  /** Effort of the agent's latest model request; absent for a model without effort. */
20  effort?: string;
21  /** Tail of the text the agent is streaming right now. */
22  live?: string;
23  lines: AgentLogLine[];
24};
25
26export type AgentBoard = {
27  agents: TrackedAgent[];
28  /** When the board was last written, for elapsed times of running agents. */
29  at: number;
30  /** The batch's pane was closed by the 15s timer; its agents are no longer "recent". */
31  isBatchClosed?: boolean;
32  /** The agents pane is placed and is the pane shown; the band stays out of its way. */
33  isPaneShown?: boolean;
34};
35
36declare module 'claude-code' {
37  interface PluginState {
38    subagents: {
39      board: AgentBoard;
40      tab: string;
41    };
42  }
43}
44