@chatpanel/events 0.90.0 → 0.91.0

package/board-tool.js

@@ -6,10 +6,15 @@
 // person to answer it, from either client. Members do not chat freely: a post is typed, a
 // reply hangs off a post, and an ask pauses the member's own task, never the run.
 //
+// A fifth, `request`: a member hands a PIECE of its task to someone else — the runner turns
+// it into a sub-task with its own thread, offers it to the members that fit, posts it on the
+// job board when none does, and (by default) waits for it and returns its findings here.
+//
 // Bound per task: the member's role and task are fixed at bind time, so a member cannot post
 // as someone else, and its ask lands in its own task's context.
 
 import { boardText, POST_KINDS, ASK_TYPES } from './team-board.js';
+import { normalizeRequest } from './team-subtask.js';
 
 export const BOARD_TOOL_NAME = 'board';
 export const DEFAULT_ASK_TIMEOUT_MS = 10 * 60_000;
@@ -24,11 +29,12 @@ export function boardToolSpec() {
       + '{"action":"post","kind":"note|draft|question","text":"…","refs":["…"]} a post in your task\'s thread; '
       + '{"action":"reply","postId":"…","kind":"note","text":"…","refs":["…"]} a reply to another member\'s post — agree, dispute with a ref, extend; '
       + '{"action":"ask","type":"info|budget|permission|direction","text":"what you need and why","options":["…"]} asks the USER and waits for the answer (minutes). '
-      + 'Ask only when you are stuck — a fact you could not find, a choice only the user can make. Otherwise decide, say what you assumed, and go on.',
+      + '{"action":"request","title":"check the valuation","brief":"what to do and what done looks like","skills":["finance"],"grants":["web"],"wait":true} hands a piece of your task to another member (or, if none fits, to the job board): a sub-task with its own thread; with wait (default) you get its findings back here. '
+      + 'Ask only when you are stuck — a fact you could not find, a choice only the user can make. Otherwise decide, say what you assumed, and go on. Request only work you should not do yourself — another skill, a tool you lack, or a second pair of eyes.',
     parameters: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['read', 'post', 'reply', 'ask'] },
+        action: { type: 'string', enum: ['read', 'post', 'reply', 'ask', 'request'] },
         kind: { type: 'string', enum: POST_KINDS.filter((k) => k !== 'finding' && k !== 'answer' && k !== 'decision') },
         text: { type: 'string' },
         refs: { type: 'array', items: { type: 'string' } },
@@ -36,6 +42,11 @@ export function boardToolSpec() {
         threadId: { type: 'string', description: 'For post: another thread you may see (default: your task\'s).' },
         type: { type: 'string', enum: [...ASK_TYPES], description: 'For ask.' },
         options: { type: 'array', items: { type: 'string' }, description: 'For ask: choices to offer the user.' },
+        title: { type: 'string', description: 'For request: the sub-task in a few words.' },
+        brief: { type: 'string', description: 'For request: what to do and what done looks like.' },
+        skills: { type: 'array', items: { type: 'string' }, description: 'For request: skills it needs.' },
+        grants: { type: 'array', items: { type: 'string' }, description: 'For request: tools it needs — data, web, history, mcp, shell, fs:write, scm:read, scm:push, scm:pr.' },
+        wait: { type: 'boolean', description: 'For request: wait for it and get its findings back (default true); false queues it after your task.' },
       },
       required: ['action'],
     },
@@ -51,8 +62,10 @@ const json = (v) => JSON.stringify(v);
  * @param taskIds   the tasks this member may read (its dependencies, or null for all)
  * @param waitFor   `async (threadId, timeoutMs, signal) => { text, by } | null` — the runner's answer box
  * @param onAsk     `(thread, post) => void` — the runner marks the task waiting
+ * @param onRequest `async ({ title, brief, needs, wait }) => result` — the runner turns a request
+ *                  into a sub-task (team-subtask.js); absent, a member is told to do it itself
  */
-export function boardToolProvider({ board, role, taskId, taskIds = null, waitFor = null, onAsk = null, askTimeoutMs = DEFAULT_ASK_TIMEOUT_MS, signal = null } = {}) {
+export function boardToolProvider({ board, role, taskId, taskIds = null, waitFor = null, onAsk = null, onRequest = null, askTimeoutMs = DEFAULT_ASK_TIMEOUT_MS, signal = null } = {}) {
   const ownThread = () => board.threadForTask(taskId) || board.openThread({ taskId, kind: 'task', title: taskId, by: 'runner' });
   return {
     id: 'board',
@@ -90,7 +103,16 @@ export function boardToolProvider({ board, role, taskId, taskIds = null, waitFor
         if (!answer) return json({ answered: false, threadId: thread.id, hint: 'No answer arrived in time. Proceed on your best assumption, say what you assumed, and note that the user did not answer.' });
         return json({ answered: true, threadId: thread.id, answer: answer.text, by: answer.by });
       }
-      return json({ error: `Unknown action "${action}". Use read, post, reply or ask.` });
+      if (action === 'request') {
+        if (typeof onRequest !== 'function') return json({ error: 'This run cannot delegate. Do the work yourself with the tools you have, and say what you could not do.' });
+        const r = normalizeRequest(input);
+        if (!r.ok) return json({ error: r.error });
+        // The request is a post in the member's own thread — the record of who asked for what.
+        const post = board.post({ threadId: ownThread().id, by: role, kind: 'request', text: `${r.request.title}${r.request.brief && r.request.brief !== r.request.title ? ` — ${r.request.brief}` : ''}`, refs: [] });
+        const result = await onRequest({ ...r.request, postId: post.id });
+        return json(result || { error: 'the request was not taken' });
+      }
+      return json({ error: `Unknown action "${action}". Use read, post, reply, ask or request.` });
     },
   };
 }

package/index.js

@@ -70,7 +70,7 @@ export {
   WEATHER_HOST, WEATHER_TIMEOUT_MS, WeatherError,
 } from './weather.js';
 export { defineToolGroup, createToolGroupRegistry, ToolGroupError } from './tool-groups.js';
-export { toolNeedFor } from './tool-need.js';
+export { toolNeedFor, grantsNeededFor } from './tool-need.js';
 export { parseFlowchart, layoutFlowchart, renderFlowchartSvg } from './flowchart.js';
 export { validateView, validateViewInvocation, viewResult } from './view.js';
 export { validateWidget, validateWidgetMessage, effectiveGrants, widgetIcon, WIDGET_SURFACES } from './widget.js';
@@ -207,13 +207,14 @@ export { ENGINE_KINDS as ENGINE_SPEC_KINDS, ROUTE_PREFERS, normalizePolicy, norm
 export { AGENT_ID_RE, APPLIES_TO, EGRESS_CLASSES, ASSISTANT_ID, AgentError, validateAgent, normalizeAgent, defineAgent, assistantAgent, engineOf, describeAgent, slugAgentId, resolveTeam, STARTER_AGENTS, starterAgents, blankAgent, agentFromForm, poolFor } from './agent.js';
 export { LEDGER_VERSION, LEDGER_ENTRY_KINDS, DECLINE_REASONS, WITHDRAW_AFTER, ledgerKey, normalizeCall, makeLedgerEntry, summarizeEngine } from './model-ledger.js';
 // Recruiting (F8 §12.2.4, pillars §13.4): the pool applies at once; an (agent, engine) pair is recruited; the evaluator is one optional structured call.
-export { RECRUIT_SCHEMA, MIN_FIT, engineRow, engineRows, needForJob, routeFor, engineWorth, applications as jobApplications, evaluatorPrompt, parseEvaluation, decide as decideRecruit, proposalFromNeeds, proposalToAgent, carveBudget, recruitEvents, recruitJob } from './recruit.js';
+export { RECRUIT_SCHEMA, MIN_FIT, engineRow, engineRows, needForJob, routeFor, engineWorth, applications as jobApplications, evaluatorPrompt, parseEvaluation, decide as decideRecruit, recruitForRun, proposalFromNeeds, proposalToAgent, carveBudget, recruitEvents, recruitJob } from './recruit.js';
 export { DEFAULT_MIN_CALLS, cardOverride, applyCard } from './model-candidates.js';
 export { SCM_KINDS, validateConnection, normalizeConnection, parseRemote, connectionFor, branchFor, worktreeDirFor, credentialEnv, describeConnection, blankConnection, connectionFromForm } from './scm-connection.js';
 export { messagesFor, mergeTranscript, clipTranscript, clipMessage, newSteps, continuationNote, createControl, STEP_MAX_CHARS, TASK_TRANSCRIPT_MAX_CHARS } from './team-task.js';
 export { runTeam, resumeTeam, dryRunTeam, isModelUnavailable, TeamRunError, RUN_STATUSES } from './team-run.js';
 export { teamToolProvider, teamToolSpec, teamToolTimeoutMs, describeTeamForApproval, TEAM_TOOL_NAME } from './team-tool.js';
 export { workLogFor, workLogText, workLogEvidence, describeCall, WORKLOG_KINDS } from './team-worklog.js';
+export { normalizeRequest, subtaskFromRequest, takeUp, takeUpLine, holdsGrants, jobFromSubtask, extendDependents, taskTree, threadRows, MAX_SUBTASKS, MAX_DEPTH, MIN_TAKEUP_FIT } from './team-subtask.js';
 export { teamLine, teamLanes } from './team-trail.js';
 export { mcpDispatchProvider, MCP_TOOL_NAME } from './mcp-dispatch.js';
 export { createManifest, ManifestError, SOURCES } from './manifest.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -99,6 +99,7 @@
     "./team-cache.js": "./team-cache.js",
     "./team-task.js": "./team-task.js",
     "./team-record.js": "./team-record.js",
+    "./team-subtask.js": "./team-subtask.js",
     "./scorecard.js": "./scorecard.js",
     "./project.js": "./project.js",
     "./job.js": "./job.js",
@@ -231,6 +232,7 @@
     "team-cache.js",
     "team-task.js",
     "team-record.js",
+    "team-subtask.js",
     "scorecard.js",
     "project.js",
     "job.js",

package/recruit.js

@@ -30,8 +30,8 @@
 import { fit, engineKey, normalizeEngine } from './scorecard.js';
 import { cardOverride, DEFAULT_MIN_CALLS } from './model-ledger.js';
 import { normalizeEngineSpec, engineKeyOf, describeEngine } from './engine.js';
-import { engineOf, agentFromForm } from './agent.js';
-import { applyAll } from './job.js';
+import { engineOf, agentFromForm, normalizeAgent, resolveTeam } from './agent.js';
+import { applyAll, jobToRole } from './job.js';
 import { WORK_GRANTS } from './team.js';
 import { defineSchema, describeSchema, coerce } from './structured.js';
 import { normalizeBudget } from './budget.js';
@@ -422,3 +422,36 @@ export async function recruitJob(job, pool, { summaries = {}, rows = [], reach =
   const decision = decide(job, apps, { evaluation, minFit });
   return { applications: apps, evaluation, decision, events: recruitEvents(job, apps, decision, { by: decision.by === 'evaluator' ? by : 'fit', at: now, record }), prompt };
 }
+
+// ── A run's job board (§15.2): the host's `recruit` hook, shared ─────────────────────────
+
+/**
+ * What a host hands the runner as `recruit`: one pass over the pool for a sub-task's job,
+ * the pick made into a ROLE the run can appoint (job.js `jobToRole`, resolved through the
+ * pool so it carries the agent's prompt, grants, skills and a model target — agent.js
+ * `resolveTeam`). Returns `{ role, agentId, engine, why, fit, applications, events }` or,
+ * when no one is recruited, `{ why, proposal, applications, events }` with `proposal` the
+ * agent card a person may approve (the runner posts it). `create` is that card once
+ * approved — the host has persisted it to its pool before calling — and it applies with
+ * the rest. `events` are the project-record events of the pass (recruit.js `recruitEvents`)
+ * for a host that has a project to land them on; the run's own record has its own.
+ */
+export async function recruitForRun(job, pool, { rows = [], summaries = {}, reach = 'any', chatModel = null, targetFor = null, ask = null, minFit = MIN_FIT, create = null, now = Date.now() } = {}) {
+  const list = (Array.isArray(pool) ? pool : []).filter((a) => a && a.id);
+  if (create && isRecord(create)) {
+    try { const made = normalizeAgent(create); if (!list.some((a) => a.id === made.id)) list.push(made); } catch { /* an unusable card applies as nothing */ }
+  }
+  const pass = await recruitJob(job, list, { summaries, rows, reach, chatModel, ask, minFit, now });
+  const d = pass.decision;
+  if (d.kind !== 'recruit') {
+    const card = proposalToAgent(d.proposal || proposalFromNeeds(job), job, { by: d.by || 'evaluator' });
+    return { why: d.why, proposal: card?.ok === false ? null : (card?.agent || card), applications: pass.applications, events: pass.events };
+  }
+  const agent = list.find((a) => a.id === d.agentId);
+  const base = jobToRole(job, agent);
+  let role = { ...base, agent: agent.id, engine: d.engine };
+  try {
+    role = resolveTeam({ name: 'recruit', roles: [role], budget: { tokens: 1 } }, list, { chatModel, targetFor }).roles[0];
+  } catch { /* unresolved: the runner's appointer decides from the engine */ }
+  return { role, agentId: d.agentId, engine: d.engine, why: d.why, fit: d.fit ?? null, applications: pass.applications, events: pass.events };
+}

package/team-board.js

@@ -77,7 +77,9 @@ export const THREAD_KINDS = Object.freeze(['task', 'ask', 'discussion', 'proposa
 // `failed`: the task behind the thread ended without an answer (every model on the roster
 // tried, or a hard error) — not `resolved`, which read as "done" on the board.
 export const THREAD_STATUSES = Object.freeze(['open', 'waiting', 'resolved', 'failed', 'approved', 'rejected']);
-export const POST_KINDS = Object.freeze(['finding', 'note', 'question', 'answer', 'draft', 'decision']);
+// `request`: a member asks for a piece of its task to be done by someone else — the runner
+// turns it into a sub-task with its own thread (team-subtask.js).
+export const POST_KINDS = Object.freeze(['finding', 'note', 'question', 'answer', 'draft', 'decision', 'request']);
 export const POST_STATUSES = Object.freeze(['open', 'proposed', 'approved', 'rejected']);
 export const ASK_TYPES = Object.freeze(['info', 'budget', 'permission', 'direction']);
 export const RUNNER = 'runner';
@@ -110,7 +112,7 @@ export function foldBoard(state, ev) {
     if (x) { x.status = p.status; x.decidedBy = p.by; x.decidedAt = p.at ?? ev?.at; }
   } else if (type === 'board.thread-status' && p.threadId) {
     const t = s.threads.find((x) => x.id === p.threadId);
-    if (t) { t.status = p.status; if (p.status !== 'waiting') t.waitingOn = null; }
+    if (t) { t.status = p.status; if (p.status !== 'waiting') t.waitingOn = null; if (p.holder) t.holder = p.holder; }
   }
   return s;
 }
@@ -132,22 +134,25 @@ export function createBoard({ now = () => Date.now(), newId = null, state = null
 
   const api = {
     /** Open a thread. A task's thread is opened once; asking for it again returns it. */
-    openThread({ id = null, taskId = null, kind = 'discussion', title = '', by = RUNNER, status = 'open', ask = null } = {}) {
+    openThread({ id = null, taskId = null, kind = 'discussion', title = '', by = RUNNER, status = 'open', ask = null, parent = null, holder = null } = {}) {
       if (kind === 'task' && taskId) { const had = threadForTask(taskId); if (had) return had; }
-      const thread = { id: id || mk('th'), kind: THREAD_KINDS.includes(kind) ? kind : 'discussion', taskId, title: clip(title, 200), by, status: THREAD_STATUSES.includes(status) ? status : 'open', at: now(), posts: 0, ...(ask ? { ask } : {}) };
+      // `parent`: the task this one was requested from (a sub-task's thread hangs under its
+      // parent's on the board); `holder`: the member that took it.
+      const thread = { id: id || mk('th'), kind: THREAD_KINDS.includes(kind) ? kind : 'discussion', taskId, title: clip(title, 200), by, status: THREAD_STATUSES.includes(status) ? status : 'open', at: now(), posts: 0, ...(ask ? { ask } : {}), ...(parent ? { parent } : {}), ...(holder ? { holder } : {}) };
       st.threads.push(thread);
       say('board.thread', { thread: { ...thread } });
       return thread;
     },
     /** A post in a thread; `replyTo` makes it a reply. */
-    post({ id = null, threadId, by, kind = 'note', text = '', refs = [], replyTo = null, status = 'open', finding = null, ask = null } = {}) {
+    /** `proposal` rides on a draft a person decides on — `{ kind: 'agent', agent, jobId }` (§15.2): the card the host creates when the post is approved. */
+    post({ id = null, threadId, by, kind = 'note', text = '', refs = [], replyTo = null, status = 'open', finding = null, ask = null, proposal = null } = {}) {
       const t = threadOf(threadId);
       if (!t) throw new Error(`no thread ${threadId}`);
       if (id && postOf(id)) return postOf(id);
       const post = {
         id: id || mk('p'), threadId, by: String(by || RUNNER), kind: POST_KINDS.includes(kind) ? kind : 'note',
         text: clip(text, MAX_POST_TEXT), refs: refsOf(refs), replyTo, status: POST_STATUSES.includes(status) ? status : 'open', at: now(),
-        ...(finding ? { finding } : {}), ...(ask ? { ask } : {}),
+        ...(finding ? { finding } : {}), ...(ask ? { ask } : {}), ...(proposal && typeof proposal === 'object' ? { proposal } : {}),
       };
       st.posts.push(post);
       t.lastAt = post.at; t.lastBy = post.by; t.posts = (t.posts || 0) + 1;
@@ -283,7 +288,7 @@ function threadedLines(state, { taskIds, role }) {
   for (const t of threads) {
     const own = posts.filter((x) => x.threadId === t.id && x.status !== 'rejected');
     if (!own.length) continue;
-    out.push(`## ${t.kind}${t.by && t.by !== RUNNER ? ` by ${t.by}` : ''}: ${t.title}${t.status === 'resolved' && t.kind === 'ask' ? ' (answered)' : ''}`);
+    out.push(`## ${t.kind}${t.by && t.by !== RUNNER ? ` by ${t.by}` : ''}: ${t.title}${t.holder ? ` (held by ${t.holder})` : ''}${t.status === 'resolved' && t.kind === 'ask' ? ' (answered)' : ''}`);
     const line = (x, depth) => {
       const tag = [x.kind === 'finding' ? (x.finding?.kind || 'claim') : x.kind, x.by, x.finding?.confidence != null ? `${Math.round(x.finding.confidence * 100)}%` : null, x.status === 'approved' ? 'APPROVED' : x.status === 'proposed' ? 'proposed' : null, x.kind === 'decision' || x.by === PERSON ? 'SETTLED' : null].filter(Boolean).join(' · ');
       out.push(`${'  '.repeat(depth)}- [${tag}] ${x.text}${x.refs?.length ? ` (refs: ${x.refs.join(', ')})` : ''}`);

package/team-plan.js

@@ -12,6 +12,7 @@
 // the board. That is the whole scheduling model — the same one a tool round uses.
 
 import { defineSchema, describeSchema, coerce } from './structured.js';
+import { GRANT_RE } from './team.js';
 
 export const MAX_TASKS = 12;
 
@@ -28,6 +29,11 @@ export const TEAM_PLAN_SCHEMA = defineSchema({
         title: { type: 'string', required: true, max: 80 },
         prompt: { type: 'string', required: true, max: 1200, describe: 'the focused instruction for this task' },
         dependsOn: { type: 'string[]', maxItems: 6, describe: 'task ids whose findings this one needs' },
+        // The planner's TOOL PROPOSAL (§15.2): which of the role's tools this task will need,
+        // and why — posted on the board as a proposal a person reads; a task that then ends
+        // without touching a tool it was said to need is nudged once before it may finish.
+        grants: { type: 'string[]', maxItems: 6, describe: 'the tools this task needs, from the role\'s own: data, web, history, mcp, shell, fs:write, scm:read, scm:push, scm:pr — or none' },
+        why: { type: 'string', max: 160, describe: 'why those tools, in a few words' },
       },
     },
   },
@@ -43,7 +49,7 @@ export function plannerPrompt(team, request) {
     '',
     `Request: ${String(request || '').trim()}`,
     '',
-    'Prefer tasks that can run at the same time; use dependsOn only when a task truly needs another\'s findings. Do not assign a role a task it has no tools for.',
+    'Prefer tasks that can run at the same time; use dependsOn only when a task truly needs another\'s findings. Do not assign a role a task it has no tools for. For each task, say which of the role\'s tools it will need (grants) and why — do not miss a tool that would help.',
     '',
     describeSchema(TEAM_PLAN_SCHEMA),
   ].join('\n');
@@ -81,6 +87,7 @@ export function parsePlan(text, team) {
       title: String(t.title || t.prompt).slice(0, 80),
       prompt: String(t.prompt).trim(),
       dependsOn: Array.isArray(t.dependsOn) ? t.dependsOn.map(String) : [],
+      ...(Array.isArray(t.grants) && t.grants.length ? { grants: [...new Set(t.grants.map((g) => String(g).trim().toLowerCase()).filter((g) => GRANT_RE.test(g) && g !== 'none'))].slice(0, 6), ...(t.why ? { why: String(t.why).slice(0, 160) } : {}) } : {}),
     }))
     .slice(0, MAX_TASKS);
   const ids = new Set(tasks.map((t) => t.id));

package/team-record.js

@@ -14,7 +14,7 @@ export const RESUMABLE_RUN_STATUSES = Object.freeze(['waiting', 'stopped', 'fail
 const TASK_TEXT_MAX = 20_000;
 
 export function emptyRun({ id, client = '', now = Date.now() } = {}) {
-  return { id, client: String(client || '').slice(0, 40), createdAt: now, lastEventAt: now, status: 'planning', team: '', request: '', roles: [], plan: null, tasks: [], board: [], threads: emptyBoardState(), checkpoint: null, proposal: null, usage: null, stopRequested: null, startedAt: null, endedAt: null };
+  return { id, client: String(client || '').slice(0, 40), createdAt: now, lastEventAt: now, status: 'planning', team: '', request: '', roles: [], plan: null, tasks: [], jobs: [], board: [], threads: emptyBoardState(), checkpoint: null, proposal: null, usage: null, stopRequested: null, startedAt: null, endedAt: null };
 }
 
 const taskOf = (run, id) => run.tasks.find((x) => x.id === id);
@@ -35,9 +35,24 @@ export function foldRun(run, ev) {
     case 'plan.ready':
       run.plan = { by: p.by || 'fixed', tasks: Array.isArray(p.tasks) ? p.tasks : [] };
       // A resume replays the plan: keep what the tasks already hold (transcripts, attempts).
-      run.tasks = run.plan.tasks.map((t) => ({ ...(taskOf(run, t.id) || {}), id: t.id, role: t.role, title: t.title, status: taskOf(run, t.id)?.status === 'ok' ? 'ok' : 'pending', findings: taskOf(run, t.id)?.findings || 0 }));
+      run.tasks = run.plan.tasks.map((t) => ({ ...(taskOf(run, t.id) || {}), id: t.id, role: t.role, title: t.title, status: taskOf(run, t.id)?.status === 'ok' ? 'ok' : (t.parent && !t.role ? 'unassigned' : 'pending'), findings: taskOf(run, t.id)?.findings || 0, ...(t.parent ? { parent: t.parent, requestedBy: t.requestedBy || null } : {}), ...(t.grants ? { grants: t.grants, why: t.why || '' } : {}) }));
       run.status = 'running';
       break;
+    // A SUB-TASK (§15.2): requested by a member mid-run, it joins the plan under its parent;
+    // taken by a member, recruited from the pool, created on a person's approval — or not.
+    case 'task.requested':
+      if (p.taskId && !taskOf(run, p.taskId)) {
+        const task = { id: p.taskId, role: null, title: p.title || p.taskId, prompt: p.prompt || '', dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : [], parent: p.parent || null, requestedBy: p.by || null, needs: p.needs || null, depth: p.depth || 1, wait: p.wait !== false };
+        if (run.plan) run.plan.tasks = [...(run.plan.tasks || []), task];
+        run.tasks.push({ id: task.id, role: null, title: task.title, status: 'requested', findings: 0, parent: task.parent, requestedBy: task.requestedBy, needs: task.needs, requestedAt: at });
+      }
+      break;
+    case 'task.taken': { const t = taskOf(run, p.taskId); if (t) { t.role = p.role; t.status = 'pending'; t.takenBy = { by: p.by || 'fit', role: p.role, fit: p.fit ?? null, reasons: p.reasons || [], agentId: p.agentId || null, engine: p.engine || null, why: p.why || '', at }; } const pt = run.plan?.tasks?.find((x) => x.id === p.taskId); if (pt) pt.role = p.role; break; }
+    case 'task.posted': { const t = taskOf(run, p.taskId); if (t) t.job = p.job || null; if (p.job && !run.jobs.some((j) => j.id === p.job.id)) run.jobs.push({ ...p.job, taskId: p.taskId, at }); break; }
+    case 'task.proposed': { const t = taskOf(run, p.taskId); if (t) t.proposal = { agent: p.agent || null, threadId: p.threadId || null, postId: p.postId || null, why: p.why || '', at }; break; }
+    case 'task.unassigned': { const t = taskOf(run, p.taskId); if (t) { t.status = 'unassigned'; t.error = p.why || null; t.endedAt = at; } const j = run.jobs.find((x) => x.taskId === p.taskId); if (j) j.status = 'failed'; break; }
+    case 'task.nudged': { const t = taskOf(run, p.taskId); if (t) t.nudged = [...(t.nudged || []), { grants: p.grants || [], at }]; break; }
+    case 'run.role-added': if (p.role?.id && !run.roles.includes(p.role.id)) { run.roles.push(p.role.id); run.recruited = [...(run.recruited || []), { ...p.role, jobId: p.jobId || null, at }]; const j = run.jobs.find((x) => x.id === p.jobId); if (j) { j.status = 'recruited'; j.recruited = { agentId: p.role.agent || p.role.id, engine: p.role.engine || null, at }; } } break;
     case 'task.started': { const t = taskOf(run, p.taskId); if (t) { t.status = 'running'; t.startedAt = at; t.error = null; } run.status = 'running'; break; }
     case 'task.model': { const t = taskOf(run, p.taskId); if (t) { t.model = p.model; t.attempts = [...(t.attempts || []), { model: p.model, at, attempt: p.attempt }]; } break; }
     case 'task.step': { const t = taskOf(run, p.taskId); if (t && Array.isArray(p.steps)) t.transcript = [...(t.transcript || []), ...p.steps]; break; }
@@ -49,7 +64,14 @@ export function foldRun(run, ev) {
       break;
     case 'task.waiting': { const t = taskOf(run, p.taskId); if (t) { t.status = 'waiting'; t.waitingOn = p.threadId; } break; }
     case 'task.done':
-    case 'task.failed': { const t = taskOf(run, p.taskId); if (t) { t.status = p.status || (type === 'task.done' ? 'ok' : 'failed'); t.error = p.error || null; t.ms = p.ms; t.endedAt = at; } break; }
+    case 'task.failed': {
+      const t = taskOf(run, p.taskId);
+      if (t) { t.status = p.status || (type === 'task.done' ? 'ok' : 'failed'); t.error = p.error || null; t.ms = p.ms; t.endedAt = at; }
+      // A job posting's outcome is the sub-task's (§15.2.5): taken by, finished how.
+      const j = run.jobs.find((x) => x.taskId === p.taskId);
+      if (j) { j.status = type === 'task.done' ? 'done' : 'failed'; j.endedAt = at; }
+      break;
+    }
     case 'run.merging': run.status = 'merging'; break;
     case 'run.waiting': run.status = 'running'; break;
     case 'run.usage': run.usage = p.usage || run.usage; break;

package/team-run.js

@@ -8,6 +8,10 @@
 //
 // Tasks run in WAVES (team-plan.js): everything with its dependencies met runs together
 // through the same pool a tool round uses; a dependent task waits and reads the board. A
+// member may REQUEST a piece of its task be done by someone else (board tool `request`,
+// team-subtask.js): the sub-task joins the plan with its own thread under the parent's, is
+// offered to the members that fit, then to the pool through the host's `recruit`, then
+// proposed as a new agent to the person — so the plan is a tree the board draws as one. A
 // task ends with findings; the merge turns the board into ONE proposal — agreed claims
 // (converge, W7), a judged answer, or the members' work side by side — and the proposal is
 // what a person sees. Nothing here lands anywhere.
@@ -19,8 +23,11 @@
 import { normalizeTeam } from './team.js';
 import { normalizeEngine, normalizeScm } from './scorecard.js';
 import { createBudget } from './budget.js';
-import { fixedPlan, plannerPrompt, parsePlan, waves } from './team-plan.js';
-import { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, RUNNER } from './team-board.js';
+import { fixedPlan, plannerPrompt, parsePlan } from './team-plan.js';
+import { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, RUNNER, PERSON } from './team-board.js';
+import { subtaskFromRequest, takeUp, takeUpLine, jobFromSubtask, extendDependents, MAX_SUBTASKS, MAX_DEPTH } from './team-subtask.js';
+import { proposalToAgent, proposalFromNeeds } from './recruit.js';
+import { grantsNeededFor } from './tool-need.js';
 import { boardToolProvider, createAnswerBox, withBoardTool, DEFAULT_ASK_TIMEOUT_MS } from './board-tool.js';
 import { createRunCache, withRunCache } from './team-cache.js';
 import { messagesFor, mergeTranscript, clipTranscript, clipMessage as clipTranscriptOne, newSteps, continuationNote, isThought } from './team-task.js';
@@ -94,6 +101,14 @@ export function dryRunTeam(team, request, { appoint = null } = {}) {
  *                   `reasons` and `alternatives` are why this one and who else could have —
  *                   said as `task.routed`, which every run records from here on (pillars §13)
  * @param runRecipe  `async (name, params) => result` for `mode: 'recipe'` roles (optional)
+ * @param recruit    `async (job, { runId, requestedBy, create? }) => { role, agentId?, engine?, why?, fit? }
+ *                   | { proposal? , why? } | null` — the host's job board (recruit.js over its
+ *                   pool): a sub-task nobody in the run fits is posted as `job`; the host
+ *                   answers with the role to add (job.js jobToRole, resolved to a model), or
+ *                   nothing, optionally with the agent it would propose. With `create` (the
+ *                   card a person approved on the board) the host adds it to the pool first.
+ *                   Absent, a sub-task nobody fits is recorded unassigned.
+ * @param projectId  the project a job posting belongs to, when the run has one (else the run id)
  * @param emit       `(type, payload)` — run.started · plan.ready · task.started · task.finding ·
  *                   task.done · task.failed · run.merging · run.done; the host forwards them to
  *                   its UI and to the gateway's run store
@@ -111,6 +126,7 @@ export async function runTeam({
   // The host's control channel (team-task.js createControl): a person hands a task to another
   // model from the board, on either client; the runner continues the task's transcript there.
   control = null,
+  recruit = null, projectId = null,
 } = {}) {
   if (typeof callModel !== 'function') throw new TeamRunError('BAD_RUN', 'callModel required');
   const t = normalizeTeam(team); // throws on a team without a budget — O1
@@ -178,9 +194,16 @@ export async function runTeam({
     }
   }
   if (!tasks) tasks = fixedPlan(t, request);
-  say('plan.ready', { by: planBy, tasks: tasks.map((x) => ({ id: x.id, role: x.role, title: x.title, dependsOn: x.dependsOn })) });
+  say('plan.ready', { by: planBy, tasks: tasks.map((x) => ({ id: x.id, role: x.role, title: x.title, dependsOn: x.dependsOn, ...(x.parent ? { parent: x.parent, requestedBy: x.requestedBy || null } : {}), ...(x.grants ? { grants: x.grants, why: x.why || '' } : {}) })) });
   // A thread per task, before anything runs: a member's findings and replies have a home.
-  for (const task of tasks) board.openThread({ taskId: task.id, kind: 'task', title: task.title || task.id, by: RUNNER });
+  for (const task of tasks) board.openThread({ taskId: task.id, kind: 'task', title: task.title || task.id, by: task.requestedBy || RUNNER, ...(task.parent ? { parent: task.parent } : {}), ...(task.role && task.parent ? { holder: task.role } : {}) });
+  // The planner's TOOL PROPOSAL (§15.2): which tools each task will need and why, as a
+  // proposal thread a person reads — and what the nudge below holds the member to.
+  if (!resume && tasks.some((x) => x.grants?.length)) {
+    const th = board.openThread({ kind: 'proposal', title: 'Tools per task', by: t.roles.find((r) => r.id === (tasks[0]?.role))?.id || RUNNER });
+    const lines = tasks.filter((x) => x.grants?.length).map((x) => { const held = t.roles.find((r) => r.id === x.role)?.grants || []; const missing = x.grants.filter((g) => !held.includes(g) && !(g.startsWith('mcp:') && held.includes('mcp'))); return `${x.role} (${x.id}): ${x.grants.join(', ')}${x.why ? ` — ${x.why}` : ''}${missing.length ? ` (not granted: ${missing.join(', ')})` : ''}`; });
+    board.post({ threadId: th.id, by: RUNNER, kind: 'draft', status: 'proposed', text: lines.join('\n') });
+  }
 
   const finish = (status, extra = {}) => {
     const usage = budget.snapshot();
@@ -205,17 +228,99 @@ export async function runTeam({
   };
   let waitingOnPerson = false; // a task that timed out on its ask — the run checkpoints
 
-  // ── fan out, in waves ─────────────────────────────────────────────────────────────────
+  // ── fan out: everything ready runs together; a sub-task requested mid-run joins the plan ──
   let overBudget = false;
   let budgetAsked = !!resume?.budgetAsked;
-  for (const wave of waves(tasks.filter((x) => !carried.has(x.id)))) {
-    if (stopped() || overBudget || waitingOnPerson) break;
-    await pool(wave, maxConcurrency, async (task) => {
-      if (stopped() || overBudget || waitingOnPerson) { tasksOut.push({ id: task.id, role: task.role, status: 'skipped', text: '', findings: [] }); return; }
+  const running = new Set();
+  const isDone = (tid) => carried.has(tid) || tasksOut.some((x) => x.id === tid);
+  // A sub-task with no holder cannot run; it is recorded `unassigned` at the end.
+  const ready = () => tasks.filter((x) => x.role && !isDone(x.id) && !running.has(x.id) && (x.dependsOn || []).every(isDone));
+  let subtasks = tasks.filter((x) => x.parent).length;
+
+  /**
+   * A member's REQUEST (board tool `request`): a sub-task with its own thread, offered to the
+   * run's members first, then to the pool through the host's `recruit`, then proposed as a
+   * new agent to the person. With `wait` the requester gets the findings back in its turn;
+   * without, the sub-task runs after it and whoever depended on the requester reads it too.
+   */
+  const onRequest = async (parentTask, role, req) => {
+    if (subtasks >= MAX_SUBTASKS) return { error: `This run has reached its limit of ${MAX_SUBTASKS} sub-tasks. Do this yourself, or say what you could not do.` };
+    if ((Number(parentTask.depth) || 0) >= MAX_DEPTH) return { error: 'A sub-task cannot delegate further. Do this yourself, or say what you could not do.' };
+    if (stopped() || overBudget) return { error: 'The run is stopping; do what you can and finish.' };
+    subtasks += 1;
+    const sub = subtaskFromRequest(req, parentTask, { id: `${parentTask.id}-s${subtasks}`, by: role.id, now: now() });
+    tasks.push(sub);
+    say('task.requested', { taskId: sub.id, parent: parentTask.id, by: role.id, title: sub.title, prompt: sub.prompt, needs: sub.needs, dependsOn: sub.dependsOn, depth: sub.depth, wait: sub.wait, postId: req.postId || null });
+    const thread = board.openThread({ taskId: sub.id, kind: 'task', title: sub.title, by: role.id, parent: parentTask.id });
+    // 1. The run's own members, by fit on skills and grants.
+    let pick = takeUp(sub, t.roles, { exclude: [role.id] });
+    let takenBy = null;
+    if (pick.roleId) {
+      takenBy = { by: 'fit', roleId: pick.roleId, fit: pick.fit, reasons: pick.reasons };
+    } else if (typeof recruit === 'function') {
+      // 2. The job board: the pool applies, the host recruits an (agent, engine) pair.
+      const job = jobFromSubtask(sub, { runId: id, projectId: projectId || null, by: role.id });
+      say('task.posted', { taskId: sub.id, job, why: pick.why });
+      board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `Posted on the job board — ${pick.why}. Needs: ${describeNeeds(sub.needs)}.` });
+      let r = null;
+      try { r = await recruit(job, { runId: id, requestedBy: role.id }); } catch (e) { board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `Recruiting failed: ${String(e?.message || e).slice(0, 200)}` }); }
+      if (r?.role) {
+        takenBy = { by: 'recruit', roleId: addRole(r.role, job), agentId: r.agentId || r.role.agent || null, engine: r.engine || null, why: r.why || '', fit: r.fit ?? null };
+      } else {
+        // 3. Nobody applies: propose the agent the job describes — a person decides; nothing
+        // is created here. With asks on, the person is asked now and the run goes on either way.
+        const card = r?.proposal || proposalToAgent(proposalFromNeeds(job), job, { by: 'runner' });
+        const agentCard = card?.ok === false ? null : (card?.agent || card);
+        const pth = board.openThread({ kind: 'proposal', title: `New agent for "${sub.title}"`, by: RUNNER, parent: parentTask.id });
+        const post = board.post({ threadId: pth.id, by: RUNNER, kind: 'draft', status: 'proposed', text: `No one in the pool fits "${sub.title}"${r?.why ? ` — ${r.why}` : ''}. Proposed: ${agentCard?.name || sub.title}${agentCard?.skills?.length ? ` — skills ${agentCard.skills.join(', ')}` : ''}${agentCard?.grants?.length ? `; grants ${agentCard.grants.join(', ')}` : ''}.`, refs: [`task:${sub.id}`], ...(agentCard ? { proposal: { kind: 'agent', agent: agentCard, jobId: job.id } } : {}) });
+        say('task.proposed', { taskId: sub.id, threadId: pth.id, postId: post.id, agent: agentCard, job, why: r?.why || pick.why });
+        const a = agentCard ? await askPerson({ type: 'permission', taskId: sub.id, text: `No one fits "${sub.title}". Create the agent "${agentCard.name}" (${describeNeeds({ skills: agentCard.skills, grants: agentCard.grants })}) and give it the job?`, options: ['Create it', 'Skip'] }) : null;
+        if (a && /create|yes|approve|allow|go/i.test(a.text)) {
+          board.decide(post.id, 'approved', a.by || PERSON);
+          let made = null;
+          try { made = await recruit(job, { runId: id, requestedBy: role.id, create: agentCard }); } catch (e) { board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `Creating the agent failed: ${String(e?.message || e).slice(0, 200)}` }); }
+          if (made?.role) takenBy = { by: 'created', roleId: addRole(made.role, job), agentId: made.agentId || made.role.agent || null, engine: made.engine || null, why: made.why || 'created for this job', fit: null };
+        } else if (a) board.decide(post.id, 'rejected', a.by || PERSON);
+      }
+    }
+    if (!takenBy) {
+      const why = typeof recruit === 'function' ? 'nobody in the run fits and no agent was recruited' : `${pick.why}; this run has no pool to recruit from`;
+      board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `Not taken: ${why}.` });
+      board.setThreadStatus(thread.id, 'failed');
+      say('task.unassigned', { taskId: sub.id, why });
+      return { taskId: sub.id, takenBy: null, why, hint: 'Nobody could take this. Do what you can yourself and say what is missing.' };
+    }
+    sub.role = takenBy.roleId;
+    board.setThreadStatus(thread.id, 'open', { holder: takenBy.roleId });
+    board.post({ threadId: thread.id, by: RUNNER, kind: 'decision', text: takenBy.by === 'fit' ? takeUpLine(sub, pick) : `${takenBy.roleId} ${takenBy.by === 'created' ? 'was created and' : 'was recruited from the pool and'} took: ${sub.title}${takenBy.why ? ` — ${takenBy.why}` : ''}` });
+    say('task.taken', { taskId: sub.id, role: takenBy.roleId, by: takenBy.by, fit: takenBy.fit ?? null, reasons: takenBy.reasons || [], agentId: takenBy.agentId || null, engine: takenBy.engine || null, why: takenBy.why || '' });
+    if (sub.wait) {
+      // Nested: the requester's turn holds while the sub-task runs; its findings come back here.
+      const row = await runTask(sub);
+      return { taskId: sub.id, takenBy: takenBy.roleId, status: row.status, ...(row.error ? { error: row.error } : {}), findings: (row.findings || []).map((f) => ({ kind: f.kind, text: f.text, refs: f.refs })), text: String(row.text || '').slice(0, 4000) };
+    }
+    const extended = extendDependents(tasks, parentTask.id, sub.id);
+    return { taskId: sub.id, takenBy: takenBy.roleId, queued: true, hint: `It runs after your task; ${extended.length ? `${extended.join(', ')} will read it too` : 'its findings will be on the board'}. Finish your task and say what depends on it.` };
+  };
+  /** A recruited agent joins the run as a role — the job's grants narrow it — and is appointed like any other. */
+  const addRole = (role, job) => {
+    const base = { ...role, id: String(role.id || job.id), grants: role.grants || job.needs?.grants || ['none'] };
+    const nt = normalizeTeam({ name: t.name, roles: [base], budget: t.budget });
+    const r = { ...nt.roles[0], ...(role.model ? { model: role.model } : {}), ...(role.engine ? { engine: role.engine } : {}), ...(role.skills ? { skills: role.skills } : {}), ...(role.workdir ? { workdir: role.workdir } : {}), recruited: true };
+    if (!t.roles.some((x) => x.id === r.id)) { t.roles.push(r); say('run.role-added', { role: { id: r.id, name: r.name, agent: r.agent || null, grants: r.grants, model: r.model || null, engine: r.engine || null }, jobId: job.id }); }
+    return r.id;
+  };
+
+  const runTask = async (task) => {
+    running.add(task.id);
+    try { return await runTaskInner(task); } finally { running.delete(task.id); }
+  };
+  const runTaskInner = async (task) => {
+      if (stopped() || overBudget || waitingOnPerson) { const row = { id: task.id, role: task.role, status: 'skipped', text: '', findings: [] }; tasksOut.push(row); return row; }
       const role = roleOf(task.role);
       const t0 = now();
       const was = interrupted.get(task.id) || null;
-      say('task.started', { taskId: task.id, role: task.role, title: task.title, ...(was ? { resumed: true, steps: was.transcript.length } : {}) });
+      say('task.started', { taskId: task.id, role: task.role, title: task.title, ...(task.parent ? { parent: task.parent } : {}), ...(was ? { resumed: true, steps: was.transcript.length } : {}) });
       let text = '';
       let usage = null;
       let status = 'ok';
@@ -247,7 +352,14 @@ export async function runTeam({
         const added = newSteps(before, after);
         if (added.length) say('task.step', { taskId: task.id, role: role.id, steps: added.map(stamp) });
       };
+      // The tool-choice guard (§15.2): what this task's wording — and the planner's proposal —
+      // say it needs among what the role holds. A model attempt that ends with zero calls
+      // while holding one of these is nudged once, then may finish.
+      const grantsHeld = role?.grants || [];
+      const mustUse = role?.mode === 'model' ? [...new Set([...grantsNeededFor(task.prompt, { held: grantsHeld }), ...(task.grants || []).filter((g) => grantsHeld.includes(g) || (g.startsWith('mcp:') && grantsHeld.includes('mcp')))])] : [];
+      let nudged = false;
       try {
+        if (!role) throw new Error(`no role "${task.role}" in the team`);
         if (role.mode === 'recipe') {
           if (typeof runRecipe !== 'function') throw new Error('this host cannot run recipes');
           const r = await runRecipe(role.recipe, { request: String(request || ''), task: task.prompt });
@@ -265,6 +377,7 @@ export async function runTeam({
           const boardTool = boardToolProvider({
             board, role: role.id, taskId: task.id, taskIds: task.dependsOn?.length ? task.dependsOn : null, askTimeoutMs: askMs, signal: taskAc.signal,
             onAsk: (thread) => { say('task.waiting', { taskId: task.id, role: role.id, threadId: thread.id, text: thread.title }); },
+            onRequest: (req) => onRequest(task, role, req),
             waitFor: askMs > 0 ? async (threadId, ms, sig) => {
               const a = await box.wait(threadId, ms, sig);
               if (!a && !stopped()) { askedAndWaiting = threadId; taskAc.abort(); }
@@ -293,6 +406,8 @@ export async function runTeam({
               note = continuationNote({ kind: 'handoff', from: lastModel, to: handoffTo.model, reason: `handed off by ${handoffTo.by}` });
               handoffTo = null;
               taskAc = new AbortController(); signal?.addEventListener?.('abort', onRunAbort, { once: true });
+            } else if (nudged && lastModel && !exclude.has(lastModel)) {
+              m = { model: lastModel, mode: role.mode }; // the nudge continues on the same model
             } else {
               m = modelFor(role, excluding(exclude));
             }
@@ -337,7 +452,20 @@ export async function runTeam({
             // died after its tool calls — is not a done task: three members "completed" empty
             // once, the run merged nothing, and the caller ran the team again. It is treated
             // like an unavailable model, so the next one on the roster gets the task.
-            if (res?.ok && String(res?.text || '').trim()) { text = String(res.text); break; }
+            if (res?.ok && String(res?.text || '').trim()) {
+              // Answered from memory while holding a tool the task calls for: one nudge, on
+              // the same model, continuing the transcript — then whatever it says stands.
+              const usedNone = !nudged && mustUse.length && routed?.engine?.kind !== 'harness' && !transcript.some((x) => x.role === 'assistant' && Array.isArray(x.tool_calls) && x.tool_calls.some((c) => c.function?.name && c.function.name !== 'board'));
+              if (usedNone && budget.canAfford({ tokens: 0 }) && !stopped()) {
+                nudged = true;
+                note = continuationNote({ kind: 'nudge', reason: mustUse.join(', ') });
+                const th = board.threadForTask(task.id);
+                if (th) board.post({ threadId: th.id, by: RUNNER, kind: 'note', text: `${role.id} answered without using ${mustUse.join(', ')}, which the task calls for — asked once to use it before finishing.` });
+                say('task.nudged', { taskId: task.id, role: role.id, grants: mustUse });
+                continue;
+              }
+              text = String(res.text); break;
+            }
             // A member that wrote on the board and then ran out of turn has still answered:
             // what it posted in its own thread during this attempt is its answer. A relayed
             // agent that posted its assessment and kept searching past the cap was being
@@ -363,45 +491,54 @@ export async function runTeam({
       } finally {
         unsubscribe?.();
       }
-      const findings = status === 'ok' ? parseFindings(text, { role: role.id, taskId: task.id }) : [];
-      if (findings.length) { board.add(findings); for (const f of findings) say('task.finding', { taskId: task.id, role: role.id, finding: f }); }
+      const findings = status === 'ok' ? parseFindings(text, { role: role?.id, taskId: task.id }) : [];
+      if (findings.length) { board.add(findings); for (const f of findings) say('task.finding', { taskId: task.id, role: role?.id, finding: f }); }
       const thread = board.threadForTask(task.id);
       // The thread says how the task ended. A failure is posted in it as well — a person reading
       // the board sees "researcher failed: network error" where it happened, and what was tried.
       if (thread && status === 'ok') board.setThreadStatus(thread.id, 'resolved');
       else if (thread && status !== 'waiting') {
-        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role.id} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.model).join(', ')})` : ''}.` });
+        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role?.id || task.role} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.model).join(', ')})` : ''}.` });
         board.setThreadStatus(thread.id, 'failed');
       }
-      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(routed ? { routed } : {}), ...(scm ? { scm } : {}), ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
+      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(task.parent ? { parent: task.parent } : {}), ...(routed ? { routed } : {}), ...(scm ? { scm } : {}), ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
       tasksOut.push(row);
       say(status === 'ok' ? 'task.done' : 'task.failed', { taskId: task.id, role: task.role, status, error, ms: row.ms, findings: findings.length, ...(askedAndWaiting ? { threadId: askedAndWaiting } : {}) });
       // The fact for the member's scorecard (scorecard.js): how big, with what, alongside whom,
       // in which role — produced here, attested by the store, never written by the agent.
-      if (status === 'ok' || status === 'failed') {
+      if (role && (status === 'ok' || status === 'failed')) {
         say('task.scored', {
           agentId: role.agent || role.id, taskId: task.id, role: role.id, model: lastModelOf(attempts), engine: routed?.engine || null, scm: scm || undefined, outcome: status === 'ok' ? 'task.done' : 'task.failed',
           size: { ms: row.ms, steps: (row.transcript || []).length, tools: (row.transcript || []).filter((m) => m.role === 'tool').length, findings: findings.length, tokens: usage ? Number(usage.input_tokens || usage.prompt_tokens || 0) + Number(usage.output_tokens || usage.completion_tokens || 0) : 0 },
           roleKind: 'ic', tools: toolNamesOf(row.transcript), with: t.roles.filter((r) => r.id !== role.id).map((r) => r.agent || r.id),
           refs: [`run:${id}`, ...(board.threadForTask(task.id) ? [`thread:${board.threadForTask(task.id).id}`] : [])], error: error || undefined,
+          ...(task.parent ? { parent: task.parent, requestedBy: task.requestedBy || null } : {}),
         });
       }
       // The spend so far, after every task — a ledger reads it live instead of at the end.
       say('run.usage', { usage: budget.snapshot() });
       if (budget.exhausted()) overBudget = true;
-    });
+      return row;
+  };
+
+  for (;;) {
+    if (stopped() || overBudget || waitingOnPerson) break;
+    const wave = ready();
+    if (!wave.length) break;
+    await pool(wave, maxConcurrency, runTask);
     // Over budget with work left: ask the person ONCE for more, on the board, before stopping.
     if (overBudget && !budgetAsked && !stopped()) {
       budgetAsked = true;
-      const left = tasks.filter((x) => !tasksOut.some((y) => y.id === x.id)).length;
+      const left = tasks.filter((x) => x.role && !tasksOut.some((y) => y.id === x.id)).length;
       const spent = budget.snapshot().spent;
       const what = left ? `${left} task${left === 1 ? '' : 's'} and the merge left` : 'only the merge left';
       const a = await askPerson({ type: 'budget', text: `The team has used its budget (${Object.entries(spent).filter(([k]) => budget.cap[k] !== undefined).map(([k, v]) => `${k} ${v} of ${budget.cap[k]}`).join(', ')}) with ${what}. Raise it by half, or stop here with what it has?`, options: ['Raise by half', 'Stop here'] });
       if (a && /raise|allow|yes|more|continue/i.test(a.text)) { budget.raise(1.5); overBudget = false; }
     }
   }
-  // Every planned task gets a row — what never ran is recorded as skipped, not forgotten.
-  for (const task of tasks) if (!tasksOut.some((x) => x.id === task.id)) tasksOut.push({ id: task.id, role: task.role, title: task.title, status: 'skipped', text: '', findings: [] });
+  // Every planned task gets a row — what never ran is recorded as skipped, not forgotten;
+  // a sub-task nobody took is `unassigned`, which is its own kind of undone.
+  for (const task of tasks) if (!tasksOut.some((x) => x.id === task.id)) tasksOut.push({ id: task.id, role: task.role, title: task.title, status: task.parent && !task.role ? 'unassigned' : 'skipped', text: '', findings: [], ...(task.parent ? { parent: task.parent } : {}) });
   if (stopped()) return finish('stopped');
   if (waitingOnPerson) return finish('waiting', { proposal: null, budgetAsked });
   // Over budget is a STOP only when it left work undone; a budget spent on the last task
@@ -485,6 +622,7 @@ export function resumeTeam({ checkpoint, ...deps } = {}) {
 }
 
 const lastModelOf = (attempts) => (attempts || []).at(-1)?.model || null;
+const describeNeeds = (n) => [n?.skills?.length ? `skills ${n.skills.join(', ')}` : '', n?.grants?.length ? `grants ${n.grants.join(', ')}` : '', n?.tools?.length ? `tools ${n.tools.join(', ')}` : ''].filter(Boolean).join('; ') || 'nothing in particular';
 const toolNamesOf = (transcript) => [...new Set((transcript || []).flatMap((m) => (m.role === 'assistant' && Array.isArray(m.tool_calls) ? m.tool_calls.map((c) => c.function?.name).filter(Boolean) : [])))];
 
 /** No model: the members' work side by side, findings first — always available. */

package/team-subtask.js

@@ -0,0 +1,192 @@
+// A sub-task — a member's request turned into a job on the run (F8 §15.2).
+//
+// A member breaks its task down by posting a REQUEST in its thread ("writer: I need the
+// valuation checked"); the runner turns each into a sub-task with its own thread, a `parent`
+// and the parent's dependencies, so the plan is a TREE. Take-up is proactive: the sub-task
+// is offered to the run's other members first — `takeUp` scores each on the skills and
+// grants the request names (scorecard.js `fit`, the same score a job posting uses) and the
+// best fit that meets the hard needs claims it. Nobody fits → the job board: `jobFromSubtask`
+// is the posting the pool applies to (recruit.js), and the host's `recruit` hook answers with
+// a role or nothing; nothing → an agent is PROPOSED to a person, never created (§7).
+//
+// Pure: no model call, no clock beyond what is handed in. The runner (team-run.js) owns the
+// flow; this module owns the shapes and the decisions that can be tested without a run.
+
+import { fit } from './scorecard.js';
+import { GRANT_RE, normalizeGrants } from './team.js';
+import { normalizeJob } from './job.js';
+
+export const MAX_SUBTASKS = 8; // per run — a member that needs more than this is re-planning, not delegating
+export const MAX_DEPTH = 2; // a sub-task may request a sub-sub-task; not deeper
+export const MIN_TAKEUP_FIT = 0.5;
+export const MAX_BRIEF = 4000;
+
+const clip = (s, n) => String(s || '').trim().slice(0, n);
+const lower = (xs) => (Array.isArray(xs) ? xs : typeof xs === 'string' ? xs.split(/[,\s]+/) : []).map((x) => String(x).trim().toLowerCase()).filter(Boolean);
+const uniq = (xs) => [...new Set(xs)];
+
+/** The request as a member states it, checked: a title, a brief, and what it needs. */
+export function normalizeRequest(input) {
+  const title = clip(input?.title, 120);
+  const brief = clip(input?.brief ?? input?.text, MAX_BRIEF);
+  if (!title && !brief) return { ok: false, error: 'a request needs a title and a brief — what to do and what done looks like' };
+  const grants = uniq(lower(input?.grants).filter((g) => GRANT_RE.test(g) && g !== 'none'));
+  return {
+    ok: true,
+    request: {
+      title: title || clip(brief, 80),
+      brief: brief || title,
+      needs: { skills: uniq(lower(input?.skills)).slice(0, 12), tools: uniq(lower(input?.tools)).slice(0, 12), grants: grants.slice(0, 8) },
+      wait: input?.wait !== false && input?.wait !== 'false',
+    },
+  };
+}
+
+/**
+ * The sub-task a request becomes: a task row like any planned one (team-plan.js) plus
+ * `parent`, `depth`, `needs`, `requestedBy`; `role` is null until someone takes it. It
+ * inherits the parent's dependencies so it may read what the parent read.
+ */
+export function subtaskFromRequest(request, parent, { id, by, now = Date.now() } = {}) {
+  const r = request;
+  return {
+    id,
+    role: null,
+    title: r.title,
+    prompt: [
+      `Sub-task requested by ${by} while working on "${clip(parent?.title || parent?.id, 120)}": ${r.title}`,
+      r.brief,
+      'Do this one thing and finish with your findings; whoever asked reads them on the board.',
+    ].join('\n\n'),
+    dependsOn: uniq([...(parent?.dependsOn || [])]).filter((d) => d !== id),
+    parent: parent?.id || null,
+    depth: (Number(parent?.depth) || 0) + 1,
+    needs: { skills: [...r.needs.skills], tools: [...r.needs.tools], grants: [...r.needs.grants] },
+    requestedBy: by,
+    requestedAt: now,
+    wait: !!r.wait,
+  };
+}
+
+/** Does this role hold every grant the request names? `mcp` covers `mcp:<server>`. */
+export function holdsGrants(role, grants) {
+  const have = new Set(normalizeGrants(role?.grants || []));
+  if (have.has('none') && (grants || []).length) return false;
+  return (grants || []).every((g) => have.has(g) || (g.startsWith('mcp:') && have.has('mcp')));
+}
+
+const coversSkills = (role, skills) => {
+  if (!skills?.length) return true;
+  const has = new Set(lower(role?.skills));
+  return skills.some((s) => has.has(s));
+};
+
+/**
+ * Offer a sub-task to the run's members: the best fit among those that hold every grant it
+ * needs and at least one skill it names (when it names any), at or above `minFit`. The
+ * requester is excluded — a request is a delegation — as are recipe roles (a recipe cannot
+ * take an arbitrary task) and anything in `exclude`. `summaries` are scorecard cards by
+ * agent or role id, when the host has them. Returns `{ roleId, fit, reasons }` or null with
+ * `why` on the side: `{ roleId: null, why }`.
+ */
+export function takeUp(task, roles, { exclude = [], summaries = {}, minFit = MIN_TAKEUP_FIT } = {}) {
+  const skip = new Set([task?.requestedBy, ...exclude].filter(Boolean));
+  const needs = task?.needs || { skills: [], tools: [], grants: [] };
+  const candidates = (roles || []).filter((r) => r && !skip.has(r.id) && r.mode !== 'recipe');
+  if (!candidates.length) return { roleId: null, why: 'no other member in the run' };
+  const scored = [];
+  const rejected = [];
+  for (const r of candidates) {
+    if (!holdsGrants(r, needs.grants)) { rejected.push(`${r.id} lacks ${needs.grants.filter((g) => !holdsGrants(r, [g])).join(', ')}`); continue; }
+    if (!coversSkills(r, needs.skills)) { rejected.push(`${r.id} has none of: ${needs.skills.join(', ')}`); continue; }
+    const f = fit({ needs, size: { steps: 0 } }, { skills: r.skills || [], tools: r.grants || [], grants: r.grants || [] }, summaries[r.agent || r.id] || null, { adjust: false });
+    scored.push({ roleId: r.id, fit: f.score, reasons: f.reasons });
+  }
+  scored.sort((a, b) => b.fit - a.fit);
+  const best = scored[0];
+  if (best && best.fit >= minFit) return best;
+  const why = best ? `${best.roleId} fits best at ${Math.round(best.fit * 100)}%, under the ${Math.round(minFit * 100)}% floor` : (rejected.length ? rejected.join('; ') : 'no member fits');
+  return { roleId: null, why };
+}
+
+/**
+ * The posting the pool applies to when nobody in the run fits (job.js). The run stands in
+ * for a project when there is none: `projectId` is the run's. The brief carries who asked
+ * and for what, so the evaluator and a person read the context.
+ */
+export function jobFromSubtask(task, { runId, projectId = null, budget = null, by = null } = {}) {
+  return normalizeJob({
+    id: task.id,
+    projectId: projectId || runId,
+    title: task.title,
+    brief: task.prompt,
+    needs: task.needs,
+    ...(budget ? { budget } : {}),
+    status: 'open',
+    postedBy: by || task.requestedBy || 'runner',
+    postedAt: task.requestedAt || Date.now(),
+    dependsOn: [],
+    origin: { kind: 'subtask', runId, parent: task.parent || null, requestedBy: task.requestedBy || null },
+  });
+}
+
+/**
+ * A queued sub-task (the requester did not wait for it) must be read by whoever would have
+ * read the requester: every task that depends on the parent now depends on the sub-task too.
+ * Mutates the plan in place; returns the ids it extended.
+ */
+export function extendDependents(tasks, parentId, subtaskId) {
+  const out = [];
+  for (const t of tasks || []) {
+    if (!t || t.id === subtaskId) continue;
+    if ((t.dependsOn || []).includes(parentId) && !(t.dependsOn || []).includes(subtaskId)) { t.dependsOn = [...t.dependsOn, subtaskId]; out.push(t.id); }
+  }
+  return out;
+}
+
+/** The plan as a tree — roots first, each with its children — for a board that draws it as one. */
+export function taskTree(tasks) {
+  const list = (tasks || []).filter(Boolean);
+  const ids = new Set(list.map((t) => t.id));
+  const byParent = new Map();
+  for (const t of list) {
+    const key = t.parent && ids.has(t.parent) ? t.parent : null;
+    if (!byParent.has(key)) byParent.set(key, []);
+    byParent.get(key).push(t);
+  }
+  const build = (key, seen) => (byParent.get(key) || []).filter((t) => !seen.has(t.id)).map((t) => ({ task: t, children: build(t.id, new Set([...seen, t.id])) }));
+  return build(null, new Set());
+}
+
+/** One line a person reads: "researcher took: check valuation (fit 85%)". */
+export function takeUpLine(task, pick) {
+  if (!pick?.roleId) return `nobody in the run fits "${task.title}"${pick?.why ? `: ${pick.why}` : ''}`;
+  return `${pick.roleId} took: ${task.title} (fit ${Math.round((pick.fit || 0) * 100)}%${pick.reasons?.length ? ` — ${pick.reasons[0]}` : ''})`;
+}
+
+/**
+ * A run's threads as the board lists them: a sub-task's thread (one whose `parent` names a
+ * task) follows its parent's thread, indented — `depth` on each row — so the tree reads as
+ * one. Roots keep the order given (a board sorts them newest first); children come in the
+ * order they were requested. A thread whose parent is not on the board is a root.
+ */
+export function threadRows(threads) {
+  const list = (threads || []).filter(Boolean);
+  const byTask = new Map(list.filter((t) => t.kind === 'task' && t.taskId).map((t) => [t.taskId, t]));
+  const children = new Map();
+  for (const t of list) {
+    if (!t.parent || !byTask.has(t.parent) || byTask.get(t.parent) === t) continue;
+    const key = byTask.get(t.parent).id;
+    if (!children.has(key)) children.set(key, []);
+    children.get(key).push(t);
+  }
+  const isChild = new Set([...children.values()].flat().map((t) => t.id));
+  const out = [];
+  const walk = (t, depth, seen) => {
+    if (seen.has(t.id)) return;
+    out.push({ ...t, depth });
+    for (const c of (children.get(t.id) || []).sort((a, b) => (a.at || 0) - (b.at || 0))) walk(c, depth + 1, new Set([...seen, t.id]));
+  };
+  for (const t of list) if (!isChild.has(t.id)) walk(t, 0, new Set());
+  return out;
+}

package/team-task.js

@@ -64,9 +64,11 @@ export function newSteps(prev, next) {
  *   handoff  — the previous attempt (another model / agent) stopped: an error, a person's choice
  *   resume   — the run itself was stopped or died and is being resumed from the record
  *   answer   — the task waited on a person and the answer is now on the board
+ *   nudge    — the attempt answered without touching a tool the task was said to need (§15.2)
  */
 export function continuationNote({ kind = 'handoff', from = '', to = '', reason = '', answer = '' } = {}) {
   const who = from ? ` by ${from}` : '';
+  if (kind === 'nudge') return `You answered without using ${reason || 'the tools you were given'}, which this task calls for. Use them now — look it up rather than answer from memory — then finish with your findings. If a tool is truly not needed, say why in one line and finish.`;
   if (kind === 'answer') return `The user has answered your question on the board (see the board, or: ${answer}). Continue the task from where you left off — do not repeat work already done above — and finish with your findings.`;
   if (kind === 'resume') return `This task was interrupted (${reason || 'the run was stopped'}) and is being resumed${to ? ` by ${to}` : ''}. Everything above is the work done so far — read it, do not redo it. Continue from where it stopped and finish with your findings.`;
   return `You are continuing this task. A previous attempt${who} stopped (${reason || 'it did not finish'}). Everything above is its work so far — read it, do not redo lookups already made. Continue from where it stopped and finish with your findings.`;

package/team-worklog.js

@@ -131,7 +131,7 @@ export function workLogText(entries, { resultChars = 200 } = {}) {
  * any opinion (a judge's, a peer's, a person's) is added beside it.
  */
 export function workLogEvidence(entries) {
-  const ev = { calls: 0, results: 0, resultErrors: 0, thoughts: 0, texts: 0, attempts: 0, handoffs: 0, posts: 0, findings: 0, decided: { approved: 0, rejected: 0 }, status: null, ms: 0 };
+  const ev = { calls: 0, results: 0, resultErrors: 0, thoughts: 0, texts: 0, attempts: 0, handoffs: 0, posts: 0, findings: 0, requests: 0, decided: { approved: 0, rejected: 0 }, status: null, ms: 0 };
   for (const e of entries || []) {
     if (e.kind === 'call') ev.calls++;
     else if (e.kind === 'result') { ev.results++; if (e.error) ev.resultErrors++; }
@@ -139,7 +139,7 @@ export function workLogEvidence(entries) {
     else if (e.kind === 'text') ev.texts++;
     else if (e.kind === 'attempt') ev.attempts++;
     else if (e.kind === 'handoff') ev.handoffs++;
-    else if (e.kind === 'post') { ev.posts++; if (e.post?.kind === 'finding') ev.findings++; if (e.post?.status === 'approved') ev.decided.approved++; if (e.post?.status === 'rejected') ev.decided.rejected++; }
+    else if (e.kind === 'post') { ev.posts++; if (e.post?.kind === 'finding') ev.findings++; if (e.post?.kind === 'request') ev.requests++; if (e.post?.status === 'approved') ev.decided.approved++; if (e.post?.status === 'rejected') ev.decided.rejected++; }
     else if (e.kind === 'end') { ev.status = e.status; ev.ms = e.ms; ev.findings = Math.max(ev.findings, e.findings || 0); }
   }
   return ev;

package/tool-need.js

@@ -94,3 +94,31 @@ export function toolNeedFor({ request = null, signals = null, attachments = [],
 
   return { tools: false, why: 'a greeting — nothing to look up' };
 }
+
+// ── Which GRANTS a task's wording calls for (F8 §15.2) ──────────────────────────────────
+//
+// A team member holding `web` that answers a "latest price" question from memory has not
+// done the task. This is the deterministic half of the tool-choice guard: read the task's
+// text for the vocabulary that names a source — the web, the person's own history, attached
+// material — and return the grants that vocabulary fits. The runner nudges a member ONCE
+// when it ends with zero calls while holding one of these. Conservative by construction:
+// nothing here fires on a task that could plausibly be answered from what the model knows.
+const NEEDS = Object.freeze([
+  ['web', /\b(search|google|look ?up|latest|current|recent|today|this (week|month|year)|news|price|prices|pricing|cost of|quote|stock|market|website|url|online|web|docs?umentation|release notes|changelog|versions?)\b/i],
+  ['history', /\b(our (meeting|call|notes?|chats?|conversation)|what (did|was) (we|i)|we (decided|agreed|discussed|said)|in (my|our) (notes?|meetings?|history|chats?)|past (chats?|meetings?|notes?)|earlier (meeting|conversation|chat|note)|transcript|standup|retro)\b/i],
+  ['data', /\b(attached|attachment|this (page|document|file|pdf|spreadsheet|sheet)|the (document|file|pdf|spreadsheet) (above|provided|attached))\b/i],
+]);
+
+/**
+ * The grants a task's text calls for, in the order they fit: `['web']`, `['history', 'web']`,
+ * `[]`. `held` narrows to what the role actually has, so the caller gets what is BOTH needed
+ * and available — an empty list means no nudge.
+ */
+export function grantsNeededFor(text, { held = null } = {}) {
+  const t = String(text || '');
+  if (!t.trim()) return [];
+  const out = NEEDS.filter(([, re]) => re.test(t)).map(([g]) => g);
+  if (!held) return out;
+  const have = new Set((Array.isArray(held) ? held : []).map((g) => String(g).toLowerCase()));
+  return out.filter((g) => have.has(g) || (g === 'history' && have.has('data')));
+}