@oddessentials/agent-guild 0.10.0 → 0.11.0

package/src/manager/session.mjs

@@ -3,11 +3,11 @@
 // byte replay), and the sub-agents and model the coding tool has reported.
 
 import { EventEmitter } from 'node:events';
-import { execFile } from 'node:child_process';
 import crypto from 'node:crypto';
 import pty from 'node-pty';
 import headless from '@xterm/headless';
 import serializeAddon from '@xterm/addon-serialize';
+import { killWindowsTree } from './command-resolver.mjs';
 
 const { Terminal } = headless;
 const { SerializeAddon } = serializeAddon;
@@ -19,6 +19,20 @@ const MODEL_SOURCE_RANK = { args: 0, screen: 1, report: 2 };
 const SCREEN_SCAN_DELAY_MS = 400;
 const SCREEN_SCAN_MAX_DELAY_MS = 2000;
 const MAX_TOOL_SESSION_ID = 200;
+const REPORTING_STATES = new Set(['pending', 'active', 'unavailable', 'setup_required', 'unsupported']);
+const SHELL_EVENTS = new Set(['start', 'waiting', 'asked', 'background', 'end', 'running', 'reset']);
+const MAX_SHELLS = 256;
+const MAX_SHELL_PIDS = 16;
+const MAX_ENDED_TASKS = 256;
+
+function processExists(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
 
 /**
  * Colours reported to programs that query them (OSC 10/11/12), matching the
@@ -81,6 +95,15 @@ export class Session extends EventEmitter {
     this.activityIdleMs = opts.activityIdleMs ?? 2500;
     this.doneAgentLingerMs = opts.doneAgentLingerMs ?? 15000;
     this.killGraceMs = opts.killGraceMs ?? 4000;
+    this.reportingTimeoutMs = opts.reportingTimeoutMs ?? 30000;
+    this.reporting = REPORTING_STATES.has(opts.reporting?.state) ? { state: opts.reporting.state, reason: opts.reporting.reason ?? null } : null;
+    this._reportingTimer = null;
+    this.shellDisplayDelayMs = opts.shellDisplayDelayMs ?? 600;
+    this.shellPidCheckMs = opts.shellPidCheckMs ?? 2000;
+    this.shells = new Map();
+    this._shellSeq = 0;
+    this._endedTasks = new Set();
+    this._pidTimer = null;
     this.createdAt = new Date().toISOString();
     this.exitedAt = null;
     this.status = 'running';
@@ -190,7 +213,9 @@ export class Session extends EventEmitter {
     clearTimeout(this._activityTimer);
     clearTimeout(this._killTimer);
     clearTimeout(this._scanTimer);
+    clearTimeout(this._reportingTimer);
     this._clearAgents();
+    this._clearShells();
     // Let the headless terminal finish parsing before announcing the exit so
     // any client attaching afterwards still sees the final screen.
     this.term.write('', () => {
@@ -260,6 +285,21 @@ export class Session extends EventEmitter {
     try { this.pty.write(data); } catch { /* process is exiting */ }
   }
 
+  input(data) {
+    this.write(data);
+    if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && /[\r\n]/.test(data)) {
+      this._reportingTimer = setTimeout(() => {
+        if (this.reporting?.state !== 'pending' || this.status !== 'running') return;
+        this.reporting = {
+          state: 'unavailable',
+          reason: `${this.provider.tool} has not run Agent Guild's reporting hooks yet. That is expected while it signs in or sets up; otherwise its hooks may be turned off, restricted by an administrator, or not trusted for this folder.`,
+        };
+        this._changed();
+      }, this.reportingTimeoutMs);
+      this._reportingTimer.unref?.();
+    }
+  }
+
   _reply(data) {
     this.write(data);
   }
@@ -302,9 +342,7 @@ export class Session extends EventEmitter {
     };
     const pid = this.pty.pid;
     if (!pid) return fallback();
-    execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, (err) => {
-      if (err) fallback();
-    });
+    killWindowsTree(pid, (err) => { if (err) fallback(); });
   }
 
   /**
@@ -317,6 +355,8 @@ export class Session extends EventEmitter {
     this.disposed = true;
     clearTimeout(this._activityTimer);
     clearTimeout(this._scanTimer);
+    clearTimeout(this._reportingTimer);
+    this._clearShells();
     for (const t of this._agentTimers.values()) clearTimeout(t);
     this.subscribers.clear();
     this.term.dispose();
@@ -339,12 +379,14 @@ export class Session extends EventEmitter {
   reportAgent(report, source = 'api') {
     if (!report || typeof report !== 'object') throw badRequest('agent report must be an object');
     if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    if (source === 'api') this._reportingHeard();
     if (report.finishForeground === true && report.agentId === undefined) {
       // The tool is between turns, so no foreground agent can still be
       // running; one that is never got its end event.
       for (const agent of [...this.agents.values()]) {
         if (agent.foreground && agent.status === 'working') this.reportAgent({ agentId: agent.id, status: 'done' }, source);
       }
+      this._endForegroundShells(null);
       return null;
     }
     const id = String(report.agentId ?? report.agent ?? report.id ?? '').trim().slice(0, 128);
@@ -360,6 +402,12 @@ export class Session extends EventEmitter {
     }
     const now = new Date().toISOString();
     const existing = this.agents.get(id);
+    if (!existing && status === 'done' && report.foreground === true) {
+      // Gemini CLI's invoke_agent is paired by its input, which a BeforeTool hook may rewrite before AfterTool.
+      const working = [...this.agents.values()].filter((agent) => agent.foreground && agent.status === 'working');
+      return working.length === 1 ? this.reportAgent({ agentId: working[0].id, status: 'done' }, source) : null;
+    }
+    if (status === 'done') this._endForegroundShells(id);
     // A first report that already says done would only flash an icon:
     // Claude Code's internal helpers (prompt suggestions, side questions)
     // stop without ever having started here.
@@ -425,13 +473,180 @@ export class Session extends EventEmitter {
       const isAgent = report && typeof report === 'object' &&
         ((report.agentId ?? report.agent ?? report.id) !== undefined || report.finishForeground === true);
       if (isAgent) this.reportAgent(report, 'terminal');
-      else if (report?.toolSessionId !== undefined) this.reportToolSession(report);
-      else this.reportModel(report);
+      else if (report?.toolSessionId !== undefined) this.reportToolSession(report, 'terminal');
+      else this.reportModel(report, 'terminal');
     } catch (err) {
       this.emit('warning', `ignored in-band report: ${err.message}`);
     }
   }
 
+  // ---- shells ------------------------------------------------------------
+
+  reportShell(report) {
+    if (!report || typeof report !== 'object') throw badRequest('shell report must be an object');
+    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    if (!SHELL_EVENTS.has(report.shell)) throw badRequest(`shell must be one of ${[...SHELL_EVENTS].join(', ')}`);
+    const id = (value) => (typeof value === 'string' && value ? value.slice(0, 128) : null);
+    const key = id(report.key);
+    const bucket = !key && typeof report.bucket === 'string' && /^[a-f0-9]{1,64}$/.test(report.bucket) ? report.bucket : null;
+    const task = id(report.task);
+    const match = typeof report.match === 'string' && /^[a-f0-9]{32}$/.test(report.match) ? report.match : null;
+    const agentId = id(report.agentId);
+    this._reportingHeard();
+
+    if (report.shell === 'reset') {
+      for (const shell of [...this.shells.values()]) this._endShell(shell);
+      return null;
+    }
+
+    if (report.shell === 'running') {
+      if (!Array.isArray(report.tasks)) throw badRequest('a running report needs a tasks array');
+      const running = new Set(report.tasks.slice(0, MAX_SHELLS).map(id).filter(Boolean));
+      for (const shell of [...this.shells.values()]) if (shell.task && !running.has(shell.task)) this._endShell(shell);
+      const known = new Set([...this.shells.values()].map((shell) => shell.task));
+      for (const each of running) if (!known.has(each) && !this._endedTasks.has(each)) this._addShell({ task: each }, { now: true });
+      return null;
+    }
+
+    if (report.shell === 'waiting' || report.shell === 'asked') {
+      // A permission request carries no call id, and a PreToolUse hook may have rewritten its command: it belongs to the
+      // agent's one foreground command with that command, else to its only one.
+      const candidates = [...this.shells.values()].filter((shell) => shell.agentId === agentId && this._foreground(shell) && !shell.waiting && !shell.asked);
+      const exact = match ? candidates.filter((shell) => shell.match === match) : [];
+      const shell = exact.length === 1 ? exact[0] : exact.length === 0 && candidates.length === 1 ? candidates[0] : null;
+      if (shell && report.shell === 'asked') {
+        shell.asked = true;
+      } else if (shell) {
+        clearTimeout(shell.timer);
+        shell.waiting = true;
+        this._setVisible(shell, false);
+      }
+      return null;
+    }
+
+    if (report.shell === 'end') {
+      if (!key && !bucket && !task) throw badRequest('a shell end needs a key, a bucket or a task');
+      if (task) this._rememberEnded(task);
+      const shell = (key && this._shellBy('key', key)) || (task && this._shellBy('task', task)) || (bucket && this._shellByBucket(bucket));
+      if (shell) this._endShell(shell);
+      return null;
+    }
+
+    if (!key && !bucket) throw badRequest('a shell report needs a key or a bucket');
+    if (report.shell === 'start') {
+      if (!key || !this._shellBy('key', key)) this._addShell({ key, bucket, match, agentId, persist: report.persist === true });
+      return null;
+    }
+
+    const pids = Array.isArray(report.pids) ? report.pids.filter((pid) => Number.isInteger(pid) && pid > 0).slice(0, MAX_SHELL_PIDS) : [];
+    if (!task && pids.length === 0) throw badRequest('a background report needs a task or pids');
+    const shell = key ? this._shellBy('key', key) : this._shellByBucket(bucket);
+    if (!shell) return null;
+    if (task) {
+      Object.assign(shell, { task, endsWithAgent: report.endsWithAgent === true });
+    } else {
+      // Gemini CLI names a pid even for a command that ended at once.
+      shell.pids = pids.filter(processExists);
+      if (shell.pids.length === 0) {
+        this._endShell(shell);
+        return null;
+      }
+      this._checkPids();
+    }
+    if (shell.waiting) {
+      shell.waiting = false;
+      this._showAfterDelay(shell);
+    }
+    return null;
+  }
+
+  _addShell(fields, { now = false } = {}) {
+    if (this.shells.size >= MAX_SHELLS) {
+      this.emit('warning', `ignored a shell command: ${MAX_SHELLS} are already running`);
+      return;
+    }
+    const shell = {
+      id: `shell-${++this._shellSeq}`, key: null, bucket: null, match: null, agentId: null, persist: false, task: null, pids: null,
+      endsWithAgent: false, waiting: false, asked: false, visible: false, timer: null, ...fields,
+    };
+    this.shells.set(shell.id, shell);
+    if (now) this._setVisible(shell, true);
+    else this._showAfterDelay(shell);
+  }
+
+  _showAfterDelay(shell) {
+    clearTimeout(shell.timer);
+    shell.timer = setTimeout(() => this._setVisible(shell, true), this.shellDisplayDelayMs);
+    shell.timer.unref?.();
+  }
+
+  _setVisible(shell, visible) {
+    if (shell.visible === visible) return;
+    shell.visible = visible;
+    this._changed();
+  }
+
+  _foreground(shell) {
+    return shell.task === null && shell.pids === null;
+  }
+
+  _shellBy(field, value) {
+    for (const shell of this.shells.values()) if (shell[field] === value) return shell;
+    return null;
+  }
+
+  // Gemini CLI's calls are paired by their input, which a BeforeTool hook may rewrite before AfterTool.
+  _shellByBucket(bucket) {
+    const open = [...this.shells.values()].filter((shell) => shell.bucket !== null && this._foreground(shell));
+    return open.find((shell) => shell.bucket === bucket) ?? (open.length === 1 ? open[0] : null);
+  }
+
+  _checkPids() {
+    if (this._pidTimer) return;
+    this._pidTimer = setInterval(() => {
+      let watching = false;
+      for (const shell of [...this.shells.values()]) {
+        if (!shell.pids) continue;
+        shell.pids = shell.pids.filter(processExists);
+        if (shell.pids.length) watching = true;
+        else this._endShell(shell);
+      }
+      if (!watching) {
+        clearInterval(this._pidTimer);
+        this._pidTimer = null;
+      }
+    }, this.shellPidCheckMs);
+    this._pidTimer.unref?.();
+  }
+
+  // A turn's foreground commands end with it; a background command, or one Codex CLI keeps running, does not.
+  _endForegroundShells(agentId) {
+    for (const shell of [...this.shells.values()]) {
+      if (shell.agentId !== agentId) continue;
+      const lasting = this._foreground(shell) ? shell.persist && !shell.asked : !(agentId && shell.endsWithAgent);
+      if (!lasting) this._endShell(shell);
+    }
+  }
+
+  _rememberEnded(task) {
+    this._endedTasks.delete(task);
+    this._endedTasks.add(task);
+    if (this._endedTasks.size > MAX_ENDED_TASKS) this._endedTasks.delete(this._endedTasks.values().next().value);
+  }
+
+  _endShell(shell) {
+    clearTimeout(shell.timer);
+    if (shell.task) this._rememberEnded(shell.task);
+    if (this.shells.delete(shell.id) && shell.visible) this._changed();
+  }
+
+  _clearShells() {
+    for (const shell of this.shells.values()) clearTimeout(shell.timer);
+    clearInterval(this._pidTimer);
+    this._pidTimer = null;
+    this.shells.clear();
+  }
+
   // ---- model -------------------------------------------------------------
 
   /**
@@ -446,9 +661,10 @@ export class Session extends EventEmitter {
     this._changed();
   }
 
-  reportModel(report) {
+  reportModel(report, source = 'api') {
     if (!report || typeof report !== 'object') throw badRequest('model report must be an object');
     if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    if (source === 'api') this._reportingHeard();
     const name = String(report.model ?? '').trim().slice(0, 120);
     if (!name) throw badRequest('model is required');
     const displayName = report.displayName === undefined || report.displayName === null ? null : String(report.displayName).trim().slice(0, 80) || null;
@@ -460,9 +676,10 @@ export class Session extends EventEmitter {
     return this.model;
   }
 
-  reportToolSession(report) {
+  reportToolSession(report, source = 'api') {
     if (!report || typeof report !== 'object') throw badRequest('tool session report must be an object');
     if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    if (source === 'api') this._reportingHeard();
     const id = String(report.toolSessionId ?? '').trim();
     if (!id || id.length > MAX_TOOL_SESSION_ID || /\p{Cc}/u.test(id)) throw badRequest(`toolSessionId must be a printable id of at most ${MAX_TOOL_SESSION_ID} characters`);
     if (this.toolSessionId !== id) {
@@ -472,6 +689,19 @@ export class Session extends EventEmitter {
     return this.toolSessionId;
   }
 
+  reportHello() {
+    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    this._reportingHeard();
+    return this.reporting;
+  }
+
+  _reportingHeard() {
+    clearTimeout(this._reportingTimer);
+    if (!this.reporting || this.reporting.state === 'active') return;
+    this.reporting = { state: 'active', reason: null };
+    this._changed();
+  }
+
   _foregroundAgentWorking() {
     for (const agent of this.agents.values()) {
       if (agent.foreground && agent.status === 'working') return true;
@@ -539,7 +769,9 @@ export class Session extends EventEmitter {
       attachedClients: this.subscribers.size,
       model: this.model,
       toolSessionId: this.toolSessionId,
+      reporting: this.reporting,
       agents: [...this.agents.values()],
+      shells: [...this.shells.values()].filter((s) => s.visible).map((s) => ({ id: s.id })),
     };
   }
 }

package/src/report/hooks.mjs

@@ -28,24 +28,71 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 const SUBAGENT_TOOLS = new Set(['Task', 'Agent', 'invoke_agent']);
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell', 'run_shell_command', 'run_terminal_command']);
 const TOOL_START_EVENTS = new Set(['PreToolUse', 'BeforeTool']);
 const TOOL_END_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure', 'AfterTool']);
-const TURN_BOUNDARY_EVENTS = new Set(['BeforeAgent', 'AfterAgent', 'UserPromptSubmit', 'Stop']);
+const TURN_BOUNDARY_EVENTS = new Set(['BeforeAgent', 'AfterAgent', 'UserPromptSubmit', 'Stop', 'Interrupt']);
 const MAX_DETAIL = 200;
 
+const FINISHED_TASKS = new Set(['completed', 'failed', 'killed']);
+const LIVE_TASKS = new Set(['pending', 'running', 'paused']);
+const MAX_RUNNING_TASKS = 256;
+
 const text = (...values) => values.find((v) => typeof v === 'string' && v.trim())?.trim() ?? null;
 
+function commandHash(command) {
+  return crypto.createHash('sha256').update(command.replace(/\s+/g, ' ').trim()).digest('hex').slice(0, 32);
+}
+
+function geminiBackgroundPids(response) {
+  const content = response?.llmContent;
+  const body = typeof content === 'string' ? content
+    : Array.isArray(content) ? content.map((part) => (typeof part === 'string' ? part : part?.text || '')).join('\n') : '';
+  const own = body.match(/Command is running in background\. PID: (\d+)/) || body.match(/moved to background \(PID: (\d+)\)/);
+  if (own) return [Number(own[1])];
+  const left = body.match(/Background PIDs: (\d+(?:, \d+)*)/);
+  return left ? left[1].split(', ').map(Number) : [];
+}
+
+function shellReport(event, input, subagentId) {
+  const toolInput = input.tool_input || input.toolInput || {};
+  const id = text(input.tool_use_id, input.toolUseId);
+  const ref = id ? { key: id.slice(0, 128) } : { bucket: crypto.createHash('sha256').update(JSON.stringify(toolInput)).digest('hex').slice(0, 32) };
+  const agent = subagentId ? { agentId: `hook-${subagentId}` } : {};
+  const match = typeof toolInput.command === 'string' ? { match: commandHash(toolInput.command) } : {};
+  // Codex CLI (its events carry turn_id) keeps a command running past its turn, and reports no end for one it refused.
+  const codex = Boolean(text(input.turn_id));
+  if (event === 'PermissionRequest') return { shell: codex ? 'asked' : 'waiting', ...agent, ...match };
+  if (TOOL_START_EVENTS.has(event)) return { shell: 'start', ...ref, ...agent, ...match, ...(codex ? { persist: true } : {}) };
+  const response = input.tool_response ?? input.toolResponse;
+  const task = text(response?.backgroundTaskId);
+  if (task) return { shell: 'background', ...ref, task: task.slice(0, 128), ...(response.backgroundEndsWithFinalResponse === true ? { endsWithAgent: true } : {}) };
+  const pids = geminiBackgroundPids(response);
+  if (pids.length) return { shell: 'background', ...ref, pids };
+  return { shell: 'end', ...ref };
+}
+
+// Claude Code reports a background task ending as a prompt of <task-notification> blocks.
+function taskNotifications(prompt) {
+  if (typeof prompt !== 'string' || !/^\s*<task-notification>/.test(prompt)) return null;
+  return [...prompt.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)].map(([, body]) => {
+    const tag = (name) => body.match(new RegExp(`<${name}>([^<]*)</${name}>`))?.[1].trim() || null;
+    return { taskId: tag('task-id'), toolUseId: tag('tool-use-id'), status: tag('status') };
+  });
+}
+
+function runningShells(tasks) {
+  const ids = tasks.filter((task) => task?.type === 'shell' && !FINISHED_TASKS.has(task.status)).map((task) => text(task.id)).filter(Boolean);
+  return { shell: 'running', tasks: ids.slice(0, MAX_RUNNING_TASKS).map((id) => id.slice(0, 128)) };
+}
+
 /** "subagent_start", "subagentStart" and "SubagentStart" all become "SubagentStart". */
 function eventName(input) {
   const raw = text(input.hook_event_name, input.hookEventName) || '';
   return raw.replace(/(?:^|[_-])([a-z])/g, (_m, c) => c.toUpperCase());
 }
 
-/**
- * Reports for one hook event: an agent report (has agentId) when a
- * sub-agent starts or stops, and a model report (has model) when the event
- * names the main model. Empty for events that carry neither.
- */
+/** Reports for one hook event: its sub-agents, shell commands, model and the tool's own session id. */
 export function hookToReports(input) {
   if (!input || typeof input !== 'object') return [];
   const event = eventName(input);
@@ -69,6 +116,19 @@ export function hookToReports(input) {
       if (detail) report.detail = detail.slice(0, MAX_DETAIL);
       reports.push(report);
     }
+    if (Array.isArray(input.background_tasks)) reports.push(runningShells(input.background_tasks));
+    return reports;
+  }
+
+  if (event === 'UserPromptSubmit' && !text(input.turn_id)) {
+    // Claude Code (turn_id is Codex's) fires this for a prompt typed while a turn runs, too, so it is no turn boundary.
+    // It also brings each background task's end; a sub-agent's task id is its agent id, and one stopped with TaskStop
+    // gets no SubagentStop.
+    for (const { taskId, toolUseId, status } of taskNotifications(input.prompt) ?? []) {
+      if (!taskId || LIVE_TASKS.has(status)) continue;
+      reports.push({ shell: 'end', task: taskId.slice(0, 128), ...(toolUseId ? { key: toolUseId.slice(0, 128) } : {}) });
+      if (FINISHED_TASKS.has(status)) reports.push({ agentId: `hook-${taskId}`, status: 'done' });
+    }
     return reports;
   }
 
@@ -79,11 +139,19 @@ export function hookToReports(input) {
     const childType = text(input.subagent_type, input.subagentType);
     const childId = text(input.session_id, input.sessionId);
     if (childType && childId) reports.push({ agentId: `hook-${childId}`, name: childType, kind: 'subagent', status: 'done' });
+    else if (event === 'SessionEnd') reports.push({ shell: 'reset' });
     return reports;
   }
 
   const toolName = text(input.tool_name, input.toolName);
-  if ((TOOL_START_EVENTS.has(event) || TOOL_END_EVENTS.has(event)) && SUBAGENT_TOOLS.has(toolName)) {
+  const toolEvent = TOOL_START_EVENTS.has(event) || TOOL_END_EVENTS.has(event);
+  if ((toolEvent || event === 'PermissionRequest') && SHELL_TOOLS.has(toolName)) reports.push(shellReport(event, input, subagentId));
+  if (event === 'PostToolUse' && toolName === 'TaskStop') {
+    const toolInput = input.tool_input || input.toolInput || {};
+    const task = text(toolInput.task_id, toolInput.shell_id);
+    if (task) reports.push({ shell: 'end', task: task.slice(0, 128) }, { agentId: `hook-${task}`, status: 'done' });
+  }
+  if (toolEvent && SUBAGENT_TOOLS.has(toolName)) {
     const toolInput = input.tool_input || input.toolInput || {};
     if (toolInput.run_in_background !== true) {
       // tool_use_id links the start and end events; fall back to hashing the
@@ -120,14 +188,16 @@ export function hookToReports(input) {
   // AfterAgent in Gemini CLI; a main-thread prompt or Stop elsewhere) cannot
   // happen while the parent waits for a foreground agent, so one still
   // working then has been orphaned.
+  if (event === 'Stop' && Array.isArray(input.background_tasks)) reports.push(runningShells(input.background_tasks));
   if (!insideSubagent && TURN_BOUNDARY_EVENTS.has(event)) reports.push({ finishForeground: true });
 
-  const model = insideSubagent ? null : event === 'PostModelSwitch'
+  const model = insideSubagent || toolEvent ? null : event === 'PostModelSwitch'
     ? text(input.to_model)
     : text(input.model, input.modelId, input.llm_request?.model);
   if (model) reports.push({ model });
 
-  // Gemini CLI has no session-start event; its turn start stands in.
+  if (!insideSubagent && event === 'SessionStart') reports.push({ hello: true });
+
   const toolSessionId = insideSubagent ? null : text(input.session_id, input.sessionId);
   if (toolSessionId && (event === 'SessionStart' || event === 'BeforeAgent')) reports.push({ toolSessionId });
   return reports;

package/web/app.js

@@ -354,23 +354,69 @@ function paintProviderIcon(el, provider) {
 
 const FAMILIARS = ['flame', 'leaf', 'night', 'aether'];
 
-function renderAgents(container, agents) {
+const REPORTING_TEXT = {
+  pending: 'waiting for hooks',
+  unavailable: 'no reports yet',
+  setup_required: 'reporting off',
+  unsupported: 'not supported',
+};
+
+function paintReporting(row, s) {
+  const reporting = s.status === 'running' ? s.reporting : null;
+  const agents = row.querySelector('.agents');
+  agents.dataset.empty = REPORTING_TEXT[reporting?.state] || 'none reported';
+  agents.classList.toggle('reporting-attention', ['unavailable', 'setup_required', 'unsupported'].includes(reporting?.state));
+  const why = row.querySelector('.reporting-why');
+  const reason = reporting?.state !== 'active' ? reporting?.reason || '' : '';
+  why.hidden = !reason;
+  why.title = reason;
+  why.setAttribute('aria-label', `Why agent reporting says ${agents.dataset.empty}: ${reason}`);
+  why.onclick = () => toast(reason, 12000);
+}
+
+const MAX_SHELLS_SHOWN = 16;
+
+function renderAgents(container, agents, shells = []) {
   const known = container.dataset.rendered ? new Set([...container.children].map((el) => el.dataset.agent)) : null;
   container.dataset.rendered = 'true';
-  container.replaceChildren(...agents.map((agent) => {
+  const familiar = (id, name, hue) => {
     const el = document.createElement('span');
-    el.className = `agent ${agent.status}`;
-    el.dataset.agent = agent.id;
-    if (known && !known.has(agent.id)) el.classList.add('summon');
-    el.style.setProperty('--c', `hsl(${hueFor(agent.name)} 65% 50%)`);
-    el.dataset.familiar = FAMILIARS[hueFor(agent.name) % FAMILIARS.length];
+    el.dataset.agent = id;
+    if (known && !known.has(id)) el.classList.add('summon');
+    el.style.setProperty('--c', `hsl(${hue} 65% 50%)`);
+    el.dataset.familiar = FAMILIARS[hue % FAMILIARS.length];
+    el.setAttribute('role', 'img');
+    return el;
+  };
+  const agentEls = agents.map((agent) => {
+    const el = familiar(agent.id, agent.name, hueFor(agent.name));
+    el.classList.add('agent', agent.status);
     el.textContent = (agent.name || '?').charAt(0).toUpperCase();
     const detail = agent.detail ? ` — ${agent.detail}` : '';
     el.title = `${agent.name} (${agent.status})${detail}`;
-    el.setAttribute('role', 'img');
     el.setAttribute('aria-label', el.title);
     return el;
-  }));
+  });
+  const shellEls = shells.slice(0, MAX_SHELLS_SHOWN).map((shell) => {
+    const el = familiar(shell.id, 'Shell', hueFor(shell.id));
+    el.classList.add('agent', 'working', 'shell');
+    el.textContent = '>';
+    el.title = 'Shell command (running)';
+    el.setAttribute('aria-label', el.title);
+    return el;
+  });
+  if (shells.length > MAX_SHELLS_SHOWN) {
+    const more = document.createElement('span');
+    const hidden = shells.length - MAX_SHELLS_SHOWN;
+    more.className = 'agent-overflow';
+    more.dataset.agent = 'shell-overflow';
+    more.textContent = `+${hidden}`;
+    more.title = `${shells.length} shell commands running; ${hidden} more not drawn`;
+    more.setAttribute('role', 'img');
+    more.setAttribute('aria-label', more.title);
+    shellEls.push(more);
+  }
+  container.replaceChildren(...agentEls, ...shellEls);
 }
 
 // ---- API ------------------------------------------------------------------
@@ -431,6 +477,7 @@ function renderAccounts(card, provider) {
         selectAccount(provider, account.id);
         renderAccounts(card, provider);
         renderUsage(card, provider);
+        renderReportingSetup(card, provider);
       });
       return chip;
     }));
@@ -444,6 +491,33 @@ function renderAccounts(card, provider) {
   });
 }
 
+function renderReportingSetup(card, provider) {
+  const row = card.querySelector('.reporting-row');
+  const account = selectedAccount(provider);
+  row.hidden = !provider.available || typeof account.reportingEnabled !== 'boolean';
+  if (row.hidden) return;
+  const on = account.reportingEnabled;
+  const whose = (provider.accounts || []).length > 1 ? ` for the ${account.label} account` : '';
+  row.querySelector('.reporting-text').textContent = `Agent reporting ${on ? 'on' : 'off'}`;
+  const button = row.querySelector('.reporting-toggle');
+  button.textContent = on ? 'Turn off' : 'Turn on';
+  button.title = on
+    ? `Remove the Agent Guild extension from ${provider.tool}${whose}. New sessions stop reporting sub-agents.`
+    : `Link the Agent Guild extension into ${provider.tool}${whose} with "${provider.command} extensions link", so new sessions show their sub-agents. It does nothing in sessions started outside Agent Guild.`;
+  button.onclick = async () => {
+    button.disabled = true;
+    try {
+      await api('POST', `/providers/${provider.id}/reporting`, { account: account.id, enabled: !on });
+      toast(on ? `Agent reporting is off for ${provider.tool}${whose}.` : `Agent reporting is on for ${provider.tool}${whose}. It applies to new sessions.`);
+    } catch (err) {
+      if (err instanceof AuthError) return showAuth(err.message);
+      toast(err.message, 10000);
+    } finally {
+      button.disabled = false;
+    }
+  };
+}
+
 let dealt = false;
 
 function renderProviders() {
@@ -487,6 +561,7 @@ function renderProviders() {
     renderConsoleLinks(node, provider);
     renderAccounts(node, provider);
     renderUsage(node, provider);
+    renderReportingSetup(node, provider);
     renderModelStats(node, provider);
     return node;
   }));
@@ -2541,7 +2616,8 @@ function updateCard(node, s) {
   // The LRM keeps a leading "/" in place under the right-to-left truncation style.
   cwd.textContent = `\u200E${s.cwd}`;
   cwd.title = s.cwd;
-  renderAgents(node.querySelector('.agents'), s.agents);
+  renderAgents(node.querySelector('.agents'), s.agents, s.shells || []);
+  paintReporting(node.querySelector('.agents-row'), s);
   node.classList.toggle('exited', s.status === 'exited');
   node.querySelector('.stop').hidden = s.status !== 'running';
   node.querySelector('.remove').hidden = s.status === 'running';
@@ -2553,7 +2629,9 @@ function updateCard(node, s) {
   resume.title = `Start ${s.provider.tool} again on this session${id ? ` (${id})` : ''} in ${s.cwd}`;
   const modelLabel = s.model ? `, model ${modelText(s)}` : '';
   const accountName = accountLabel(s) ? `, ${accountLabel(s)} account` : '';
-  node.setAttribute('aria-label', `${s.name}, ${s.provider.vendor}${accountName}${modelLabel}, ${statusText(s)}, ${s.agents.length} agents`);
+  const shellCount = (s.shells || []).length;
+  const reportingNote = s.status === 'running' && REPORTING_TEXT[s.reporting?.state] ? `, agent reporting: ${REPORTING_TEXT[s.reporting.state]}` : '';
+  node.setAttribute('aria-label', `${s.name}, ${s.provider.vendor}${accountName}${modelLabel}, ${statusText(s)}, ${s.agents.length} agents${shellCount ? `, ${shellCount} shell command${shellCount === 1 ? '' : 's'} running` : ''}${reportingNote}`);
 }
 
 function renderSessions() {
@@ -2810,7 +2888,7 @@ function updatePanel() {
   const id = toolSessionId(s);
   $('panel-sub').textContent = [s.provider.tool, accountLabel(s), modelText(s), statusText(s), s.cwd, id && `session ${id}`].filter(Boolean).join(' · ');
   $('panel-sub').title = modelTitle(s);
-  renderAgents($('panel-agents'), s.agents);
+  renderAgents($('panel-agents'), s.agents, s.shells || []);
   const stop = $('panel-stop');
   stop.textContent = s.status === 'running' ? 'Stop' : 'Remove';
 }