@lloyal-labs/lloyal-agents 2.0.0 → 3.0.0

package/dist/agent-pool.js

@@ -9,6 +9,7 @@ const sdk_2 = require("@lloyal-labs/sdk");
 const trace_scope_1 = require("./trace-scope");
 const Agent_1 = require("./Agent");
 const AgentPolicy_1 = require("./AgentPolicy");
+const Tool_1 = require("./Tool");
 /**
  * Immutable KV budget snapshot for one tick of the agent loop
  *
@@ -177,16 +178,16 @@ function* recoverInline(agent, policy, ctx, store, tw, parentTraceId, events, pr
                 type: 'pool:recoveryProduce', agentId: agent.id,
                 tokenCount: producedTokens, outputLength: output.length,
             });
-            // Parse + report
+            // Parse + return (recovery path — emits agent:recovered, NOT agent:return)
             try {
                 const parsed = JSON.parse(output);
                 if (parsed?.result) {
-                    agent.reportResult(parsed.result, 'scratchpad');
-                    yield* events.send({ type: 'agent:report', agentId: agent.id, result: agent.result });
+                    agent.setResult(stripDanglingToolCall(parsed.result), 'recovery');
+                    yield* events.send({ type: 'agent:recovered', agentId: agent.id, result: agent.result });
                     reported = true;
                     tw.write({
                         traceId: tw.nextId(), parentTraceId, ts: performance.now(),
-                        type: 'pool:recoveryReport', agentId: agent.id,
+                        type: 'pool:recoveryReturn', agentId: agent.id,
                         resultLength: parsed.result.length,
                     });
                 }
@@ -221,10 +222,27 @@ function* recoverInline(agent, policy, ctx, store, tw, parentTraceId, events, pr
 // ── PRODUCE action handlers ─────────────────────────────────────
 // Each handler encapsulates state transitions, events, and trace for one
 // policy action outcome. The PRODUCE switch dispatches to these.
-function* handleFreeTextReport(a, content, events) {
-    a.reportResult(content, 'free_text');
+/**
+ * Strip a trailing UNCLOSED `<tool_call>` fragment from text captured as an
+ * agent result. When generation is cut mid-tool-call-emission (produce
+ * budget, pressure, maxTurns), the parser finds no complete call and the
+ * raw tail — `…</think>\n<tool_call><function=read_file>…` with no closing
+ * tags — rides into `a.result` verbatim. Any downstream consumer that
+ * injects results into another agent's prompt (synth findings, delegation
+ * returns) then carries a literal in-context demonstration of emitting tool
+ * calls, priming no-tool agents to imitate it (observed:
+ * trace-2026-06-11T00-02, agent 65539 → synth rabbit hole).
+ *
+ * Complete `<tool_call>…</tool_call>` blocks are left alone — they are
+ * either parsed before reaching a capture path or deliberate quoting.
+ */
+function stripDanglingToolCall(text) {
+    return text.replace(/<tool_call>(?:(?!<\/tool_call>)[\s\S])*$/, '').trimEnd();
+}
+function* handleFreeTextReturn(a, content, events) {
+    a.setResult(stripDanglingToolCall(content), 'free_text');
     a.transition('idle');
-    yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
+    yield* events.send({ type: 'agent:return', agentId: a.id, result: a.result });
     yield* events.send({ type: 'agent:done', agentId: a.id });
 }
 function* handleIdleDrop(a, reason, events, tw, parentTraceId) {
@@ -246,14 +264,14 @@ function* handleNudge(a, message, tc, ctx, tools) {
     a.resetTurn();
     return { agentId: a.id, prefillTokens, toolName: tc?.name || '', callId, args: tc?.arguments || '', probe };
 }
-function* handleReport(a, result, tc, terminalTool, pruneOnReport, events) {
-    a.reportResult(result, 'report_tool');
+function* handleReturn(a, result, tc, terminalToolName, pruneOnReturn, events) {
+    a.setResult(stripDanglingToolCall(result), 'voluntary_return');
     a.transition('idle');
     a.incrementToolCalls();
-    yield* events.send({ type: 'agent:tool_call', agentId: a.id, tool: terminalTool, args: tc.arguments });
-    yield* events.send({ type: 'agent:report', agentId: a.id, result: a.result });
+    yield* events.send({ type: 'agent:tool_call', agentId: a.id, tool: terminalToolName, args: tc.arguments });
+    yield* events.send({ type: 'agent:return', agentId: a.id, result: a.result });
     yield* events.send({ type: 'agent:done', agentId: a.id });
-    if (pruneOnReport && !a.branch.disposed)
+    if (pruneOnReturn && !a.branch.disposed)
         a.branch.pruneSync();
 }
 /**
@@ -264,19 +282,19 @@ function* handleReport(a, result, tc, terminalTool, pruneOnReport, events) {
  * automatically — the orphaned-branch leak is structurally impossible.
  */
 function* setupAgent(parent, task, ctx, enableThinking) {
-    // Probe shared-root mode. When set, the queryRoot already has the
-    // [system + tools] chat header prefilled and we MUST NOT re-emit them
-    // in the agent's suffix — the bytes are already in attention via fork
-    // prefix-share. The new agent inherits parser/grammar/format/triggers
-    // from sharedFmt so tool dispatch keeps working.
+    // Probe shared-mode. When set, the spine already has the [system + tools]
+    // chat header prefilled and we MUST NOT re-emit them in the agent's
+    // suffix — the bytes are already in attention via fork prefix-share. The
+    // new agent inherits parser/grammar/format/triggers from sharedFmt so
+    // tool dispatch keeps working.
     let sharedFmt = null;
     try {
-        sharedFmt = (yield* context_1.RootFmt.get()) ?? null;
+        sharedFmt = (yield* context_1.SpineFmt.get()) ?? null;
     }
     catch { /* not in shared mode */ }
     // Compose the messages to format into the suffix. In shared mode with
     // an empty per-spec systemPrompt, drop the system message — the role
-    // lives at the root, the agent only contributes a user turn. With a
+    // lives at the spine, the agent only contributes a user turn. With a
     // non-empty per-spec systemPrompt, include it: the agent's KV will
     // contain TWO system messages in lineage, which Qwen3 handles (recovery
     // ships on the same multi-system pattern).
@@ -287,13 +305,13 @@ function* setupAgent(parent, task, ctx, enableThinking) {
             { role: 'user', content: task.content },
         ];
     const fmtOpts = { enableThinking };
-    // Tools belong at the root in shared mode; emitting them again here
+    // Tools belong at the spine in shared mode; emitting them again here
     // would re-prefill the same schema bytes for nothing.
     if (task.tools && !sharedFmt)
         fmtOpts.tools = task.tools;
     const fmt = ctx.formatChatSync(JSON.stringify(messages), fmtOpts);
     // Tool-support guard runs only on the non-shared path. Shared mode's
-    // root already passed the equivalent check at withSharedRoot setup.
+    // spine already passed the equivalent check at withSpine setup.
     if (task.tools && !sharedFmt
         && (fmt.format === sdk_1.CHAT_FORMAT_CONTENT_ONLY || fmt.format === sdk_1.CHAT_FORMAT_GENERIC)) {
         // Error before fork — no branch to clean up
@@ -312,9 +330,14 @@ function* setupAgent(parent, task, ctx, enableThinking) {
             callingAgent = a;
     }
     catch { /* top-level — no caller */ }
+    // The spawn's app membership is now a non-enforcing label:
+    // the authGuard gates tools by `Tool.protected` + session grants at the
+    // pool level, not by app-scoped allow-lists. The label is carried for
+    // trace attribution (`tool:authReject`) and harness UI only.
+    const assignedApp = task.assignedApp ?? null;
     // In shared mode the new agent's parser/grammar/format/triggers come
-    // from the root's pre-computed fmt — those fields know about the tool
-    // palette that's in attention via the inherited prefix. In non-shared
+    // from the spine's pre-computed fmt — those fields know about the tool
+    // set that's in attention via the inherited prefix. In non-shared
     // mode, fresh fmt drives those fields (existing behavior).
     const fmtConfig = sharedFmt
         ? {
@@ -344,6 +367,7 @@ function* setupAgent(parent, task, ctx, enableThinking) {
         parent: callingAgent,
         task: task.content,
         fmt: fmtConfig,
+        assignedApp,
     });
     return { agent, suffixTokens, formattedPrompt: fmt.prompt };
 }
@@ -373,17 +397,17 @@ function* setupAgent(parent, task, ctx, enableThinking) {
  * @param opts - Pool configuration: tasks, tools, sampling params, max turns
  * @returns Agent pool result with per-agent findings and aggregate statistics
  *
- * @example Shared root with agent pool
+ * @example Spine with agent pool
  * ```typescript
- * const pool = yield* withSharedRoot(
+ * const pool = yield* withSpine(
  *   { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
- *   function*(root) {
+ *   function*(spine) {
  *     return yield* useAgentPool({
  *       tasks: questions.map(q => ({
  *         systemPrompt: RESEARCH_PROMPT,
  *         content: q,
  *         tools: toolsJson,
- *         parent: root,
+ *         parent: spine,
  *       })),
  *       tools: toolMap,
  *       maxTurns: 6,
@@ -409,7 +433,7 @@ function useAgentPool(opts) {
             }
         });
         const tw = yield* context_1.Trace.expect();
-        const { root, orchestrate, toolsJson, tools, maxTurns = 100, terminalTool, trace = false, pruneOnReport = false, enableThinking = false } = opts;
+        const { spine, orchestrate, toolsJson, tools, maxTurns = 100, terminalToolName, trace = false, pruneOnReturn = false, enableThinking = false, eagerGrammar } = opts;
         // Tool index map for trace — position in toolkit array
         const toolIndexMap = new Map([...tools.keys()].map((name, i) => [name, i]));
         const toolkitSize = tools.size;
@@ -421,7 +445,7 @@ function useAgentPool(opts) {
                 poolParentTraceId = p;
         }
         catch { /* top level */ }
-        const poolScope = (0, trace_scope_1.traceScope)(tw, poolParentTraceId, 'pool', { maxTurns, terminalTool });
+        const poolScope = (0, trace_scope_1.traceScope)(tw, poolParentTraceId, 'pool', { maxTurns, terminalToolName });
         // Whether the pool's tool registry contains tools besides the terminal tool.
         // When false, agents are allowed to call the terminal tool as their first
         // action (e.g. reporter sub-agents that only have `report()`). When true,
@@ -432,7 +456,7 @@ function useAgentPool(opts) {
         // schemas (`task.tools`). A reporter pool must pass only the terminal tool
         // in its registry — passing the full tool map makes this flag true and
         // traps reporters in an infinite rejection loop.
-        const hasNonTerminalTools = terminalTool ? [...tools.keys()].some(k => k !== terminalTool) : tools.size > 0;
+        const hasNonTerminalTools = terminalToolName ? [...tools.keys()].some(k => k !== terminalToolName) : tools.size > 0;
         const policy = opts.policy ?? new AgentPolicy_1.DefaultAgentPolicy();
         const pressureOpts = policy.pressureThresholds
             ?? { softLimit: ContextPressure.DEFAULT_SOFT_LIMIT, hardLimit: ContextPressure.DEFAULT_HARD_LIMIT };
@@ -450,7 +474,23 @@ function useAgentPool(opts) {
                 `Recovery reserves hardLimit cells for its own decode; if smaller than nBatch, the next batch ` +
                 `allocation will OOM. Increase policy.budget.context.hardLimit to at least ${nBatch}.`);
         }
-        const policyConfig = { maxTurns, terminalTool, hasNonTerminalTools };
+        // authGuard inputs, resolved once per pool:
+        //   • protectedTools — names this pool's registry flags `Tool.protected`.
+        //   • grants — protected names the session is authorized to call, read
+        //     from GrantStoreCtx. Absent store = fail-closed (no grants).
+        // When nothing is protected (the common case) the authGuard never fires.
+        const protectedTools = new Set([...tools].filter(([, t]) => t.protected).map(([name]) => name));
+        let grants = new Set();
+        if (protectedTools.size > 0) {
+            try {
+                const grantStore = yield* context_1.GrantStoreCtx.expect();
+                grants = new Set(yield* grantStore.granted());
+            }
+            catch { /* no grant store on context — fail-closed (no grants) */ }
+        }
+        const policyConfig = {
+            maxTurns, terminalToolName, hasNonTerminalTools, protectedTools, grants,
+        };
         // ── Orchestrator-driven setup ────────────────────────────
         // Agents are spawned lazily via `ctx.spawn` from the orchestrator.
         // The tick loop iterates over whatever agents are currently active.
@@ -469,7 +509,24 @@ function useAgentPool(opts) {
         });
         // Lazy grammar setup — applied inside ctx.spawn after prefill completes.
         const applyLazyGrammar = (a) => {
-            if (a.fmt.grammar && a.fmt.grammarLazy && a.fmt.grammarTriggers.length > 0) {
+            // Eager grammar (schema-based agents like the planner) takes priority
+            // over lazy tool-call grammar. Qwen3.5's chat template emits a lazy
+            // tool-call grammar even when no tools are passed (a non-empty
+            // fmt.grammar with a `<tool_call>` trigger), which would otherwise
+            // overwrite a schema grammar set elsewhere — the planner would still
+            // be unconstrained. With eager set, we use the strict schema grammar
+            // and skip the (no-tools-anyway) lazy trigger.
+            if (eagerGrammar) {
+                a.branch.setGrammar(eagerGrammar);
+            }
+            else if (tools.size > 0 && a.fmt.grammar && a.fmt.grammarLazy && a.fmt.grammarTriggers.length > 0) {
+                // tools.size guard: with an empty toolkit there is nothing to
+                // dispatch, but the template still emits a tool-call grammar (see
+                // above). Installing it would not BLOCK the `<tool_call>` trigger —
+                // lazy grammars activate on the trigger, they don't prevent it —
+                // but once triggered it FORCES syntactic completion of a full call
+                // the model may have sampled into by accident. A no-tool agent
+                // (synth, eval) must be free to wander back to prose instead.
                 const triggers = a.fmt.grammarTriggers.map(t => {
                     if (t.type === sdk_1.GrammarTriggerType.WORD) {
                         const nlIdx = t.value.indexOf('\n');
@@ -492,21 +549,29 @@ function useAgentPool(opts) {
         });
         // ── PoolContext — orchestrator's API surface ─────────────
         const poolContext = {
-            root,
+            spine,
             *spawn(spec) {
-                const parent = spec.parent ?? root;
+                const parent = spec.parent ?? spine;
                 const task = {
                     systemPrompt: spec.systemPrompt,
                     content: spec.content,
                     tools: toolsJson,
                     seed: spec.seed,
                     parent,
+                    assignedApp: spec.assignedApp,
                 };
                 // Synchronous setup — fork, tokenize suffix, pressure check.
                 // No native store call yet; that's the tick loop's SPAWN phase's job.
                 const { agent, suffixTokens, formattedPrompt } = yield* setupAgent(parent, task, ctx, enableThinking);
                 const pressure = new ContextPressure(ctx, pressureOpts);
-                if (!pressure.canFit(suffixTokens.length)) {
+                // Reserve for batch-mates: spawns/extends admitted earlier this tick
+                // haven't prefilled yet, so raw pressure doesn't see them. Without
+                // the reservation, N individually-valid spawns cram N suffixes into
+                // one SPAWN-phase prefill and every agent dies pressure_softcut on
+                // turn 0 (trace-2026-06-11T06-21: 6 × 4,819-token suffixes vs 32k).
+                const reserved = pendingSpawns.reduce((acc, ps) => acc + ps.suffixTokens.length, 0) +
+                    pendingExtends.reduce((acc, pe) => acc + (pe.discarded ? 0 : pe.tokens.length), 0);
+                if (!pressure.canFit(reserved + suffixTokens.length)) {
                     agent.branch.pruneSync();
                     agent.dispose();
                     tw.write({
@@ -543,7 +608,7 @@ function useAgentPool(opts) {
                 }
                 return agent;
             },
-            *extendRoot(userContent, assistantContent) {
+            *extendSpine(userContent, assistantContent) {
                 if (!assistantContent)
                     return 0;
                 const turnTokens = (0, sdk_2.buildTurnDelta)(ctx, userContent, assistantContent);
@@ -661,10 +726,18 @@ function useAgentPool(opts) {
                     }
                     return deferred;
                 }
+                /** Transient-failure parking: a ToolRetryError'd call waits here with its
+                 *  agent in `awaiting_tool` (PRODUCE skips it — no turns, no tokens, no
+                 *  KV) until `notBefore`, then re-enters DISPATCH. Whether to park and
+                 *  for how long is the POLICY's call (`onToolRetry`); this queue is
+                 *  pure mechanism, like SETTLE's deferral. Keep retry delays above the
+                 *  provider's own breaker cooldown or the retry lands on an open
+                 *  breaker. */
+                const pendingRetries = [];
                 /** DISPATCH: execute tool calls sequentially, return settled items for next tick */
                 function* dispatch(calls) {
                     const results = [];
-                    for (const { agent, tc } of calls) {
+                    for (const { agent, tc, retryAttempt, retryCallId } of calls) {
                         let toolArgs;
                         try {
                             toolArgs = JSON.parse(tc.arguments);
@@ -672,11 +745,15 @@ function useAgentPool(opts) {
                         catch {
                             toolArgs = {};
                         }
-                        const callId = tc.id || `call_${agent.toolCallCount}`;
-                        agent.incrementToolCalls();
-                        totalToolCalls++;
-                        agent.incrementTurns();
-                        yield* poolChannel.send({ type: 'agent:tool_call', agentId: agent.id, tool: tc.name, args: tc.arguments });
+                        const callId = retryCallId ?? (tc.id || `call_${agent.toolCallCount}`);
+                        // Retries re-execute the SAME call — turn/tool-call counters and the
+                        // agent:tool_call event belong to the original attempt only.
+                        if (retryAttempt === undefined) {
+                            agent.incrementToolCalls();
+                            totalToolCalls++;
+                            agent.incrementTurns();
+                            yield* poolChannel.send({ type: 'agent:tool_call', agentId: agent.id, tool: tc.name, args: tc.arguments });
+                        }
                         const tool = tools.get(tc.name);
                         const dispatchPressure = new ContextPressure(ctx, pressureOpts);
                         const explore = policy.shouldExplore?.(agent, dispatchPressure) ?? true;
@@ -704,8 +781,19 @@ function useAgentPool(opts) {
                         try {
                             yield* context_1.TraceParent.set(dispatchTraceId);
                             yield* context_1.CallingAgent.set(agent);
+                            // Unknown-tool messaging branches on toolkit emptiness: a no-tool
+                            // agent emitting tool calls is imitating markup from its context
+                            // (inherited spine KV or contaminated findings) — a generic
+                            // "Unknown tool" error reads as transient and invites rephrased
+                            // retries until maxTurns (observed: trace-2026-06-11T00-02 synth,
+                            // 10 turns of mimicry). The directive form names the actual
+                            // situation so the model can recover in one turn.
                             const result = yield* (0, effection_1.scoped)(function* () {
-                                return yield* (0, effection_1.call)(() => tool ? tool.execute(toolArgs, toolContext) : Promise.resolve({ error: `Unknown tool: ${tc.name}` }));
+                                return yield* (0, effection_1.call)(() => tool ? tool.execute(toolArgs, toolContext) : Promise.resolve({
+                                    error: tools.size === 0
+                                        ? 'No tools are available to this agent. Do not emit tool calls — write your answer directly as plain text.'
+                                        : `Unknown tool: ${tc.name}`,
+                                }));
                             });
                             const postToolPressure = new ContextPressure(ctx, pressureOpts);
                             const contextAvailablePercent = postToolPressure.percentAvailable;
@@ -730,8 +818,52 @@ function useAgentPool(opts) {
                                 durationMs: performance.now() - toolT0 });
                         }
                         catch (err) {
+                            if (err instanceof Tool_1.ToolRetryError) {
+                                const attempt = (retryAttempt ?? 0) + 1;
+                                // Strategy is the policy's: park-and-retry (optionally overriding
+                                // the tool's delay estimate) or fail the call so the model can
+                                // pivot. Hook absent → one retry at the tool's estimate.
+                                const retryAction = policy.onToolRetry?.(agent, tc.name, err, attempt)
+                                    ?? (attempt <= 1 ? { type: 'retry' } : { type: 'fail' });
+                                if (retryAction.type === 'retry') {
+                                    // Park: no SettledTool, nothing prefilled — the agent's KV
+                                    // never sees transient infrastructure weather. Surfaced to
+                                    // the TUI + trace so a waiting agent reads as waiting, not hung.
+                                    const afterMs = retryAction.afterMs ?? err.retryAfterMs;
+                                    pendingRetries.push({
+                                        agent, tc, callId,
+                                        notBefore: performance.now() + afterMs,
+                                        attempt,
+                                    });
+                                    yield* poolChannel.send({
+                                        type: 'agent:tool_retry', agentId: agent.id, tool: tc.name,
+                                        retryAfterMs: afterMs, attempt,
+                                    });
+                                    tw.write({ traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
+                                        type: 'tool:retry', agentId: agent.id, tool: tc.name,
+                                        callId, retryAfterMs: afterMs, attempt });
+                                    continue;
+                                }
+                                // Policy chose fail — the outage is now a fact the model needs.
+                                // Settle an honest, directive result through the normal path
+                                // (NOT the tool_error path, which kills the agent's run).
+                                const exhausted = {
+                                    error: retryAction.message
+                                        ?? `${tc.name} is currently unavailable (rate-limited; retry failed). ` +
+                                            `Do not call ${tc.name} again — use other sources or proceed with your current findings.`,
+                                };
+                                const resultStr = JSON.stringify(exhausted);
+                                yield* poolChannel.send({ type: 'agent:tool_result', agentId: agent.id, tool: tc.name, result: resultStr });
+                                const prefillTokens = (0, sdk_2.buildToolResultDelta)(ctx, resultStr, callId, { enableThinking: agent.fmt.enableThinking });
+                                results.push({ agentId: agent.id, prefillTokens, toolName: tc.name, callId, args: tc.arguments, probe: undefined });
+                                tw.write({ traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
+                                    type: 'tool:result', agentId: agent.id, tool: tc.name,
+                                    result: exhausted, prefillTokenCount: prefillTokens.length,
+                                    durationMs: performance.now() - toolT0 });
+                                continue;
+                            }
                             agent.transition('idle');
-                            agent.reportResult(`Tool error: ${err.message}`, 'tool_error');
+                            agent.setResult(`Tool error: ${err.message}`, 'tool_error');
                             tw.write({ traceId: tw.nextId(), parentTraceId: dispatchTraceId, ts: performance.now(),
                                 type: 'tool:error', agentId: agent.id, tool: tc.name,
                                 error: err.message });
@@ -757,7 +889,7 @@ function useAgentPool(opts) {
                         continue;
                     }
                     // -- Phase 0: SPAWN+EXTEND -- drain pending spawns AND pending extends,
-                    // batching all fork-suffix prefills and extend-onto-root prefills into
+                    // batching all fork-suffix prefills and extend-onto-spine prefills into
                     // ONE native store.prefill call. All store-level native calls in this
                     // pool are issued from this fiber (the tick loop), never concurrently
                     // with the orchestrator's fiber. Piggybacking extend in this phase
@@ -770,7 +902,7 @@ function useAgentPool(opts) {
                             .filter(e => !e.discarded);
                         const prefillPairs = [
                             ...drainedSpawns.map(s => [s.agent.branch, s.suffixTokens]),
-                            ...drainedExtends.map(e => [root, e.tokens]),
+                            ...drainedExtends.map(e => [spine, e.tokens]),
                         ];
                         try {
                             if (prefillPairs.length > 0) {
@@ -782,7 +914,7 @@ function useAgentPool(opts) {
                                 e.reject(err);
                             throw err;
                         }
-                        // Resolve extend requests with the delta token count. root.position
+                        // Resolve extend requests with the delta token count. spine.position
                         // has advanced by the sum of extend token counts at this point.
                         for (const e of drainedExtends) {
                             tw.write({
@@ -791,7 +923,7 @@ function useAgentPool(opts) {
                                 userContent: e.userContent,
                                 assistantContent: e.assistantContent,
                                 deltaTokens: e.tokens.length,
-                                positionAfter: root.position,
+                                positionAfter: spine.position,
                             });
                             e.resolve(e.tokens.length);
                         }
@@ -860,19 +992,32 @@ function useAgentPool(opts) {
                             // Policy decides what to do with the parsed output
                             const action = policy.onProduced(a, parsed, pressure, policyConfig);
                             switch (action.type) {
-                                case 'free_text_report':
-                                    yield* handleFreeTextReport(a, action.content, poolChannel);
+                                case 'free_text_return':
+                                    yield* handleFreeTextReturn(a, action.content, poolChannel);
                                     continue;
                                 case 'idle':
                                     yield* handleIdleDrop(a, action.reason, poolChannel, tw, poolScope.traceId);
                                     continue;
                                 case 'nudge':
+                                    // authGuard rejection: emit the structured
+                                    // tool:authReject event BEFORE the generic agentNudge so a
+                                    // single trace pass captures attribution + rejection context.
+                                    if (action.guard === 'auth_reject') {
+                                        tw.write({
+                                            traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
+                                            type: 'tool:authReject',
+                                            agentId: a.id,
+                                            assignedApp: a.assignedApp,
+                                            attemptedTool: parsed.toolCalls[0].name,
+                                            lineageHistory: a.walkAncestors((x) => x.toolHistory),
+                                        });
+                                    }
                                     nudges.push(yield* handleNudge(a, action.message, parsed.toolCalls[0], ctx, tools));
                                     tw.write({ traceId: tw.nextId(), parentTraceId: poolScope.traceId, ts: performance.now(),
                                         type: 'pool:agentNudge', agentId: a.id, reason: 'nudge', message: action.message });
                                     continue;
-                                case 'report':
-                                    yield* handleReport(a, action.result, parsed.toolCalls[0], terminalTool, pruneOnReport, poolChannel);
+                                case 'return':
+                                    yield* handleReturn(a, action.result, parsed.toolCalls[0], terminalToolName, pruneOnReturn, poolChannel);
                                     totalToolCalls++;
                                     continue;
                                 case 'tool_call':
@@ -971,7 +1116,19 @@ function useAgentPool(opts) {
                         deferred.push(...resolved);
                     }
                     // -- Phase 4: DISPATCH
-                    const dispatched = yield* dispatch(toolCalls);
+                    // Due retries re-enter first — their agents have been parked since the
+                    // ToolRetryError and re-execute the same call (same callId, no counter
+                    // increments).
+                    const nowTs = performance.now();
+                    const dueRetries = [];
+                    for (let i = pendingRetries.length - 1; i >= 0; i--) {
+                        if (pendingRetries[i].notBefore <= nowTs)
+                            dueRetries.unshift(...pendingRetries.splice(i, 1));
+                    }
+                    const dispatched = yield* dispatch([
+                        ...dueRetries.map(r => ({ agent: r.agent, tc: r.tc, retryAttempt: r.attempt, retryCallId: r.callId })),
+                        ...toolCalls,
+                    ]);
                     // Deferred + new dispatch results → next tick's SETTLE
                     pendingSettled = [...deferred, ...dispatched];
                     // -- Termination + recovery
@@ -996,6 +1153,20 @@ function useAgentPool(opts) {
                         // All current agents done but orchestrator may spawn more.
                         yield* (0, effection_1.sleep)(1);
                     }
+                    // All-parked: nothing active, nothing to settle — only future retries.
+                    // Without this the loop busy-spins until the earliest notBefore (parked
+                    // agents are awaiting_tool, so the allIdle sleep above never fires).
+                    // Cap the nap at 50ms so orchestrator spawns/extends are picked up
+                    // promptly.
+                    if (pendingRetries.length > 0
+                        && pendingSettled.length === 0
+                        && pendingSpawns.length === 0
+                        && pendingExtends.length === 0
+                        && !agents.some(a => a.status === 'active')) {
+                        const nextDue = Math.min(...pendingRetries.map(r => r.notBefore));
+                        const nap = Math.max(1, Math.min(50, nextDue - performance.now()));
+                        yield* (0, effection_1.sleep)(nap);
+                    }
                 }
                 // ── Close channel with result — consumers get AgentPoolResult as close value ───────
                 // Branch cleanup is handled by each branch's ensure() from setupAgent —