elanous 0.2.34 → 0.2.36

package/src/skills/tools/agent.ts

@@ -60,8 +60,8 @@ export const AGENT_TOOL_DEFAULT_MAX_TURNS = 20;
 export const AGENT_TOOL_TURNS_CEILING = 50;
 
 /** Numeric ceiling on concurrent `run_in_background` Agent-tool fan-out.
- *  Pure declaration — enforcement in dispatchAgent is the follow-up cell
- *  TUI-AGENT-CAPS-WIRING (not wired here). */
+ *  Enforced at exactly one point in `dispatchAgent` (see the
+ *  `background-fanout-limit` block: after dedup, before `noteSeen`). */
 export const AGENT_TOOL_BACKGROUND_FANOUT_CEILING = 8;
 
 /** Clamp a caller-supplied `max_turns` onto `[1, AGENT_TOOL_TURNS_CEILING]`.
@@ -82,7 +82,9 @@ export function stripAgentToolForOneLevelNesting<T extends { name: string }>(
 }
 
 /** Live `run_in_background` tasks occupy fan-out slots until they terminal.
- *  Pure judgement — the ceiling check that uses it is TUI-AGENT-CAPS-WIRING. */
+ *  Counts a task list (e.g. `globalAgentRegistry.list()`). `dispatchAgent`
+ *  enforces the per-session ceiling over its own reservation ledger
+ *  (`backgroundFanoutSlots`) instead — see that field's doc. */
 export function countLiveBackgroundFanout(
   tasks: ReadonlyArray<{ background?: boolean; state?: string }>,
 ): number {
@@ -95,6 +97,145 @@ export function countLiveBackgroundFanout(
   return n;
 }
 
+/** Fallback fan-out session key for dispatches that carry no
+ *  `sessionCache` (agent-cli, one-off callers). All of their slots share
+ *  one process-wide bucket so the ceiling still binds for them. */
+const UNSCOPED_BACKGROUND_FANOUT_SESSION: object = Object.freeze({});
+
+/** Fan-out slots by session (the dispatching session's `SessionCache`
+ *  identity; WeakMap so a dropped session releases its key together with
+ *  the cache instance). A slot is RESERVED in the same synchronous block
+ *  as the ceiling check inside `dispatchAgent` — concurrent dispatches
+ *  that interleave at the async definition-resolution awaits cannot all
+ *  pass the check before any of them registers — and RELEASED when the
+ *  registered task reaches a terminal state (done/error/aborted) via
+ *  `globalAgentRegistry.onTaskDone`. A dispatch that throws before it
+ *  registers releases its own reservation (see
+ *  `releaseReservedFanoutSlot` inside `dispatchAgent`). */
+const backgroundFanoutSlots = new WeakMap<object, number>();
+
+/** Count this session's live fan-out slots (reserved or running). */
+export function countSessionBackgroundFanout(session: object): number {
+  return backgroundFanoutSlots.get(session) ?? 0;
+}
+
+/** Release one of this session's fan-out slots (floors at zero) and hand the
+ *  freed slot to the next waiting launch (see `admitNextBackgroundAdmission`). */
+function releaseBackgroundFanoutSlot(session: object): void {
+  const live = backgroundFanoutSlots.get(session);
+  if (live === undefined || live <= 1) backgroundFanoutSlots.delete(session);
+  else backgroundFanoutSlots.set(session, live - 1);
+  admitNextBackgroundAdmission(session);
+}
+
+/** Admission class for a waiting background launch. A launch that names a
+ *  concrete agent definition is a SUBAGENT spawn (the parent asked for a
+ *  specific worker); the default general-purpose fan-out is a GENERAL worker.
+ *  Subagent spawns enter the shared queue first because they carry the
+ *  parent's explicit delegation intent — a general worker can be re-issued
+ *  in the foreground at no cost, a named subagent cannot. */
+export type BackgroundAdmissionPriority = 'subagent' | 'general';
+
+/** A launch waiting for a fan-out slot. `seq` is the process-wide arrival
+ *  ordinal; equal-priority entries are admitted oldest-first (FIFO). */
+export interface BackgroundAdmissionEntry {
+  priority: BackgroundAdmissionPriority;
+  seq: number;
+}
+
+/** Pick the index of the next entry to admit from a waiting queue: subagent
+ *  entries before general ones, oldest (`seq`) first inside a class.
+ *  Returns -1 for an empty queue. Pure — the queue order itself never has to
+ *  be pre-sorted. */
+export function selectNextAdmissionIndex(
+  entries: readonly BackgroundAdmissionEntry[],
+): number {
+  let oldestSubagent = -1;
+  let oldestAny = -1;
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!;
+    if (oldestAny === -1 || entry.seq < entries[oldestAny]!.seq) oldestAny = i;
+    if (
+      entry.priority === 'subagent'
+      && (oldestSubagent === -1 || entry.seq < entries[oldestSubagent]!.seq)
+    ) {
+      oldestSubagent = i;
+    }
+  }
+  return oldestSubagent >= 0 ? oldestSubagent : oldestAny;
+}
+
+/** Classify a dispatch for admission priority (see BackgroundAdmissionPriority). */
+export function classifyBackgroundAdmissionPriority(
+  requestedType: string,
+): BackgroundAdmissionPriority {
+  return requestedType === 'general-purpose' ? 'general' : 'subagent';
+}
+
+interface QueuedBackgroundAdmission extends BackgroundAdmissionEntry {
+  admit: () => void;
+  abandon: () => void;
+}
+
+/** The SHARED waiting queue, per session (same scope as the slot ledger, so
+ *  a busy session's waiters cannot head-of-line block another session).
+ *  Entries live only while the fan-out ceiling is full and their launch
+ *  opted in with `wait_for_slot`; every other launch keeps the immediate
+ *  `background-fanout-limit` refusal. */
+const backgroundAdmissionQueues = new WeakMap<object, QueuedBackgroundAdmission[]>();
+let backgroundAdmissionSeq = 0;
+
+/** Park this launch on the session's shared queue and resolve `true` when it
+ *  is admitted — the admitting release has ALREADY reserved the slot for it,
+ *  so no dispatch can slip in between the handoff and the spawn. Resolves
+ *  `false` when the caller's abort signal fires while it waits. */
+function waitForBackgroundFanoutSlot(
+  session: object,
+  priority: BackgroundAdmissionPriority,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    const entry: QueuedBackgroundAdmission = {
+      priority,
+      seq: backgroundAdmissionSeq++,
+      admit: () => finish(true),
+      abandon: () => finish(false),
+    };
+    // Always mutate the CURRENT queue (never a snapshot): entries settle out of
+    // order under priority admission, and writing back a stale array would
+    // resurrect an entry that was already admitted or abandoned.
+    function finish(admitted: boolean): void {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      const rest = (backgroundAdmissionQueues.get(session) ?? []).filter(e => e !== entry);
+      if (rest.length > 0) backgroundAdmissionQueues.set(session, rest);
+      else backgroundAdmissionQueues.delete(session);
+      resolve(admitted);
+    }
+    const onAbort = (): void => { entry.abandon(); };
+    const queue = backgroundAdmissionQueues.get(session) ?? [];
+    queue.push(entry);
+    backgroundAdmissionQueues.set(session, queue);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** Admit exactly one waiter for a slot that just opened, reserving the slot
+ *  in this same synchronous block as the release. Selection is delegated to
+ *  the pure `selectNextAdmissionIndex` (subagent first, FIFO inside a class). */
+function admitNextBackgroundAdmission(session: object): void {
+  const queue = backgroundAdmissionQueues.get(session);
+  if (!queue || queue.length === 0) return;
+  const index = selectNextAdmissionIndex(queue);
+  if (index < 0) return;
+  const entry = queue[index]!;
+  backgroundFanoutSlots.set(session, countSessionBackgroundFanout(session) + 1);
+  entry.admit();
+}
+
 /** Fallback agent when subagent_type is missing or unresolvable. The
  *  loader picks this up from src/agents/general-purpose.md — built
  *  inline below as a defensive default in case that file is removed. */
@@ -130,6 +271,12 @@ export interface AgentToolArgs {
    *  child keeps running; completion emits a task-notification
    *  (P2) which the parent sees in the next turn's user message. */
   run_in_background?: boolean;
+  /** When true, a background launch that hits the fan-out ceiling WAITS on
+   *  the session's shared admission queue instead of being refused: it spawns
+   *  as soon as a live background agent terminals (subagent waits are
+   *  admitted before general-purpose ones, FIFO inside each class). Omitted
+   *  or false keeps the immediate `background-fanout-limit` refusal. */
+  wait_for_slot?: boolean;
   /** UI label for this spawn — shown on agent-roster so siblings
    *  sharing a definition are distinguishable. Takes precedence
    *  over `description` as task.label. */
@@ -199,6 +346,10 @@ export function buildAgentTool(): LLMToolSpec {
       '  • You want to fan out N independent workers in parallel — call Agent N times in the same turn; each runs independently.\n' +
       '  • A SKILL.md instructs you to "spawn N expert agents" / "use the Agent tool" — that is exactly this tool.\n' +
       '\n' +
+      'Delegate heavy multistep work that would overflow your context, fan out independent units in parallel, ' +
+      'and hand off long investigations; use run_in_background for long-running work so you can keep coordinating ' +
+      'and finish after the results arrive.\n' +
+      '\n' +
       'The sub-agent gets its own tools (Bash/Read/Edit/Grep/WebFetch by default) and its own ' +
       'turn budget (default 20). It returns ONE final message which becomes your tool_result. ' +
       'Pass everything the worker needs (data, persona, framing) inside `prompt` — the worker ' +
@@ -226,6 +377,10 @@ export function buildAgentTool(): LLMToolSpec {
           type: 'boolean',
           description: 'When true, returns the spawn handle immediately instead of waiting for completion. The child keeps running; its final message arrives in your next turn as a <task-notification> user message. Use for long-running explorations (multi-minute research, 10+ tool calls) so you can keep working in parallel.',
         },
+        wait_for_slot: {
+          type: 'boolean',
+          description: 'Only meaningful with run_in_background. When the per-session background fan-out ceiling is already full, this launch waits on the shared admission queue instead of being refused, and spawns as soon as one live background agent finishes. Waiting subagent spawns (ones that name a subagent_type) are admitted before general-purpose ones; launches with the same class keep arrival order. Omit it to get the immediate "NOT SPAWNED" refusal and re-issue later.',
+        },
         name: {
           type: 'string',
           description: 'Optional UI label for this spawn (shown in agent-roster / logs). Useful when fanning out N workers with the same subagent_type — give each a distinct name so the roster can tell them apart.',
@@ -246,12 +401,12 @@ export function buildAgentTool(): LLMToolSpec {
         },
         tool_filter: {
           type: 'object',
-          description: 'Optional per-spawn tool registry isolation (Gemini pattern). Omit this field to inherit the parent\'s full available tool registry. Use it only to narrow a child to a focused subset (for example, read-only deep research or a single-purpose worker): it composes with the agent definition\'s allowlist and cannot widen access. Over-narrowing can leave the child unable to complete its task; retain every tool the delegated work needs.',
+          description: 'Optional per-spawn tool filter. The sub-agent inherits the parent\'s full tool registry by default; usually omit this field. Only `deny` is applied (hide specific tools). `allow` is ignored unless the user explicitly enabled narrowing, so do not try to restrict the child with it.',
           properties: {
             allow: {
               type: 'array',
               items: { type: 'string' },
-              description: 'Whitelist of tool names the sub-agent may call. Empty array = pure text (no tools). Omitted = no allow constraint.',
+              description: 'Ignored by default (the child keeps every tool). Applied only when the user explicitly enabled narrowing; then unknown names are ignored with a warning and a filter that would leave 0 tools is refused (NOT SPAWNED).',
             },
             deny: {
               type: 'array',
@@ -352,6 +507,7 @@ export async function dispatchAgent(
 
   // PFC-S1 P1: new optional fields.
   const runInBackground = args.run_in_background === true;
+  const waitsForSlot = args.wait_for_slot === true;
   const spawnName = typeof args.name === 'string' && args.name.trim() ? args.name.trim() : undefined;
   const teamName = typeof args.team_name === 'string' && args.team_name.trim() ? args.team_name.trim() : undefined;
   const isolation = args.isolation === 'worktree' || args.isolation === 'cwd'
@@ -374,19 +530,22 @@ export async function dispatchAgent(
   // burn another turn on the same work. Return a stub that points
   // the parent back to its existing history. Parents stuck in a
   // "keep re-spawning Data Collector" loop escape via this gate.
-  if (opts.sessionCache) {
-    const key = agentCacheKey(requestedType, requestedType, prompt);
+  const sessionCache = opts.sessionCache;
+  const cacheKey = sessionCache
+    ? agentCacheKey(requestedType, requestedType, prompt)
+    : undefined;
+  if (sessionCache && cacheKey) {
     // Key strategy: description is noisy (parents sometimes vary the
     // label between calls); we hash the FUNCTIONAL signature only
     // — subagent_type + prompt. Same prompt to same agent = same
     // expected work, regardless of how the call was labelled.
-    const hit = opts.sessionCache.check(key);
+    const hit = sessionCache.check(cacheKey);
     if (hit) {
       const label = `Agent[${requestedType}] "${description.slice(0, 60)}"`;
       logDedupHit('agent.dedup', label, hit, {
         requestedType,
         description: description.slice(0, 80),
-        consecutive: opts.sessionCache.consecutiveHits,
+        consecutive: sessionCache.consecutiveHits,
       });
 
       // Runtime-level block: same treatment as Read. When the parent
@@ -395,16 +554,16 @@ export async function dispatchAgent(
       // tool_result carries is_error=true. Soft stubs have been
       // observed to produce 6+ retries in the wild; an error break
       // the reflex loop more reliably.
-      if (opts.sessionCache.consecutiveHits >= CONSECUTIVE_DEDUP_BLOCK_THRESHOLD) {
+      if (sessionCache.consecutiveHits >= CONSECUTIVE_DEDUP_BLOCK_THRESHOLD) {
         debug.log('agent.dedup', 'consecutive-block', {
           requestedType,
           description: description.slice(0, 80),
-          consecutive: opts.sessionCache.consecutiveHits,
+          consecutive: sessionCache.consecutiveHits,
           threshold: CONSECUTIVE_DEDUP_BLOCK_THRESHOLD,
         });
         throw new Error(
           `RUNTIME BLOCKED — Agent[${requestedType}] "${description.slice(0, 60)}" ` +
-          `has been spawned ${opts.sessionCache.consecutiveHits} times in a row with ` +
+          `has been spawned ${sessionCache.consecutiveHits} times in a row with ` +
           `no intervening progress. The previous sub-agent's final message is in ` +
           `your conversation history above — use that. Spawn an Agent with a ` +
           `DIFFERENT persona (different subagent_type or a substantively different ` +
@@ -420,9 +579,9 @@ export async function dispatchAgent(
       // ~500 chars of history noise per hit. We now emit the debug
       // event past threshold for traceability but return the normal
       // "spawn a different persona" stub — same message every hit.
-      if (opts.sessionCache.totalHits >= DEDUP_CASCADE_HALT_THRESHOLD) {
+      if (sessionCache.totalHits >= DEDUP_CASCADE_HALT_THRESHOLD) {
         debug.log('agent.dedup', 'cascade-threshold', {
-          totalHits: opts.sessionCache.totalHits,
+          totalHits: sessionCache.totalHits,
           threshold: DEDUP_CASCADE_HALT_THRESHOLD,
           requestedType,
           description: description.slice(0, 80),
@@ -444,7 +603,120 @@ export async function dispatchAgent(
         taskId: 'dedup',
       };
     }
-    opts.sessionCache.noteSeen(key, `Agent[${requestedType}] ${description.slice(0, 60)}`);
+  }
+
+  // ── TUI-AGENT-CAPS-FU: background fan-out ceiling ──
+  //
+  // The ONE enforcement point for AGENT_TOOL_BACKGROUND_FANOUT_CEILING, and
+  // it sits exactly between the dedup short-circuit above and `noteSeen`
+  // below on purpose:
+  //   • after dedup — a repeat of an already-answered prompt still gets the
+  //     dedup stub instead of a fan-out refusal (it never reaches here);
+  //   • before `noteSeen` — a refused launch must NOT register its cache
+  //     key. Otherwise the caller's retry (same prompt, once a slot opens)
+  //     would be answered with "you already got this result" even though no
+  //     child ever ran, permanently poisoning the cache with a spawn that
+  //     never happened.
+  //
+  // Live slots are counted over the shared task ledger: `background` tasks
+  // that have not reached a terminal state (done / error / aborted). So a
+  // slot re-opens the moment any background agent finishes, which is what
+  // lets the next launch through again.
+  let fanoutSession: object | undefined;
+  // Set when the shared admission queue handed this dispatch its slot while it
+  // waited (see `admitNextBackgroundAdmission`) — the reservation block below
+  // must then not take a second one.
+  let fanoutSlotReserved = false;
+  if (runInBackground) {
+    // Per-session scope: slots count against THIS session's cache
+    // identity (shared fallback bucket for cache-less callers), so a
+    // busy OTHER session cannot starve this one's first launch.
+    fanoutSession = opts.sessionCache ?? UNSCOPED_BACKGROUND_FANOUT_SESSION;
+    if (countSessionBackgroundFanout(fanoutSession) >= AGENT_TOOL_BACKGROUND_FANOUT_CEILING) {
+      // Not spawned: no registry task, no provider call, no cache entry.
+      // taskId is a sentinel (like 'dedup' above) so a caller can tell a
+      // refusal from a real spawn without parsing the prose. The live count
+      // is re-read here so an abandoned wait reports the current number.
+      const refuseForCeiling = (): AgentToolResult => {
+        const liveBackground = countSessionBackgroundFanout(fanoutSession!);
+        debug.log('agent.spawn', 'background-fanout-limit', {
+          cid: debugCorrelationId,
+          requestedType,
+          description: description.slice(0, 80),
+          liveBackground,
+          ceiling: AGENT_TOOL_BACKGROUND_FANOUT_CEILING,
+        }, { level: 'warn' });
+        return {
+          output:
+            `NOT SPAWNED — ${liveBackground} background agents are already live and the ` +
+            `fan-out ceiling is ${AGENT_TOOL_BACKGROUND_FANOUT_CEILING}. A slot reopens as ` +
+            `soon as one of them reaches a terminal state (done/error/aborted); its result ` +
+            `then arrives as a task-notification. Either wait for one to finish, fold this ` +
+            `work into an existing background spawn, or re-issue it without ` +
+            `run_in_background so it runs in the foreground.`,
+          agent: requestedType,
+          cid: debugCorrelationId,
+          durationMs: 0,
+          maxTurns: requestedMaxTurns,
+          taskId: 'background-fanout-limit',
+        };
+      };
+
+      // Shared waiting queue — opt-in only. Launches that did not pass
+      // `wait_for_slot` keep the immediate refusal above, byte for byte.
+      if (!waitsForSlot) return refuseForCeiling();
+
+      const admissionPriority = classifyBackgroundAdmissionPriority(requestedType);
+      debug.log('agent.spawn', 'background-queue-wait', {
+        cid: debugCorrelationId,
+        requestedType,
+        description: description.slice(0, 80),
+        priority: admissionPriority,
+        liveBackground: countSessionBackgroundFanout(fanoutSession),
+        ceiling: AGENT_TOOL_BACKGROUND_FANOUT_CEILING,
+      }, { level: 'warn' });
+      const admitted = await waitForBackgroundFanoutSlot(fanoutSession, admissionPriority, opts.signal);
+      if (!admitted) {
+        debug.log('agent.spawn', 'background-queue-abandoned', {
+          cid: debugCorrelationId,
+          requestedType,
+          description: description.slice(0, 80),
+          priority: admissionPriority,
+          reason: 'aborted-while-waiting',
+        }, { level: 'warn' });
+        return refuseForCeiling();
+      }
+      // The admitting release already reserved this dispatch's slot.
+      fanoutSlotReserved = true;
+      debug.log('agent.spawn', 'background-queue-admit', {
+        cid: debugCorrelationId,
+        requestedType,
+        description: description.slice(0, 80),
+        priority: admissionPriority,
+        liveBackground: countSessionBackgroundFanout(fanoutSession),
+      });
+    }
+  }
+
+  if (fanoutSession !== undefined && !fanoutSlotReserved) {
+    // Atomic reservation: taken in the SAME synchronous block as the
+    // ceiling check above, before any await — concurrent dispatches
+    // cannot all pass the check and push this session past the ceiling
+    // while their definitions resolve. Released when the registered
+    // task terminals (see the onTaskDone subscription at spawn); a
+    // dispatch that throws before registering releases it in the finally
+    // below, including failures from definition resolution and lazy imports.
+    backgroundFanoutSlots.set(fanoutSession, countSessionBackgroundFanout(fanoutSession) + 1);
+  }
+  const releaseReservedFanoutSlot = (): void => {
+    if (fanoutSession === undefined) return;
+    releaseBackgroundFanoutSlot(fanoutSession);
+    fanoutSession = undefined;
+  };
+
+  try {
+  if (sessionCache && cacheKey) {
+    sessionCache.noteSeen(cacheKey, `Agent[${requestedType}] ${description.slice(0, 60)}`);
   }
 
   // Resolve the agent definition. Try the 4-layer resolver first;
@@ -536,7 +808,9 @@ export async function dispatchAgent(
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      if (!message.includes('is not inside a git repo')) throw error;
+      if (!message.includes('is not inside a git repo')) {
+        throw error;
+      }
       childCwd = opts.cwd ?? getSessionCwd();
       appliedIsolation = 'cwd';
       debug.log('agent.spawn', 'worktree-fallback-cwd', {
@@ -608,32 +882,44 @@ export async function dispatchAgent(
   // Strip the Agent tool itself from the sub-agent's available tools.
   // One level of nesting only — see file header rationale.
   childTools = stripAgentToolForOneLevelNesting(childTools);
-  // Wave 5 E1 — apply per-spawn tool_filter. Narrows the intersection
-  // further (cannot widen the host's allowlist). When `allow` is
-  // explicit-empty `[]`, the worker runs text-only.
-  const toolFilter = (args.tool_filter && typeof args.tool_filter === 'object' && !Array.isArray(args.tool_filter))
-    ? args.tool_filter as { allow?: unknown; deny?: unknown }
-    : undefined;
-  if (toolFilter) {
-    const availableToolCount = childTools.length;
-    const allowList = Array.isArray(toolFilter.allow)
-      ? new Set((toolFilter.allow as unknown[]).filter((n): n is string => typeof n === 'string'))
-      : null;
-    const denyList = Array.isArray(toolFilter.deny)
-      ? new Set((toolFilter.deny as unknown[]).filter((n): n is string => typeof n === 'string'))
-      : null;
-    childTools = childTools.filter((t) => {
-      if (denyList && denyList.has(t.name)) return false;
-      if (allowList && !allowList.has(t.name)) return false;
-      return true;
-    });
+  // Wave 5 E1 — apply per-spawn tool_filter (SUBAGENT-TOOLS-EMPTY · 0.2.36 · 대표 «서브에이전트에 제약이 생기지 않게»).
+  //   기본 = 메인과 같은 도구 전부(필터 없음). allow 는 «좁히기»일 때만 — 모르는 이름은 무시하고 경고,
+  //   아는 이름이 하나도 없으면 allow 전체를 무시(이름 불일치로 49→0 이 되던 10-22 실물). 결과가 0개면
+  //   발사하지 않는다(조용히 빈손 금지 — «0 tools · Blocked» 로 끝나 «✓ done» 처럼 보이던 것).
+  //   SUBAGENT-NO-NARROWING(0.2.36 · 대표 22:5x «서브에이전트에 제약 없게») — 모델이 넘긴 allow 는 기본 «무시», deny 만 반영.
+  //   (10-22 n8n 실물: 49 → 9 로 좁혀진 자식 둘이 1분 만에 «완료 못함».) 좁히기는 사람이 명시할 때만 — ELANOUS_SUBAGENT_HONOR_ALLOW=1
+  //   또는 agent 정의(.md)의 tools 목록(위에서 이미 반영).
+  const filtered = applySpawnToolFilter(childTools, args.tool_filter, { honorAllow: subagentHonorsModelAllow() });
+  childTools = filtered.tools;
+  if (filtered.applied || filtered.unknownAllow.length > 0 || filtered.unknownDeny.length > 0) {
     debug.log('agent.spawn', 'tool-filter', {
-      allowSize: allowList?.size,
-      denySize: denyList?.size,
-      available: availableToolCount,
+      cid: debugCorrelationId,
+      allowSize: filtered.allowSize,
+      denySize: filtered.denySize,
+      available: filtered.available,
       remaining: childTools.length,
-      removed: availableToolCount - childTools.length,
-    });
+      removed: filtered.available - childTools.length,
+      ...(filtered.unknownAllow.length ? { unknownAllow: filtered.unknownAllow.slice(0, 20) } : {}),
+      ...(filtered.unknownDeny.length ? { unknownDeny: filtered.unknownDeny.slice(0, 20) } : {}),
+      ...(filtered.allowIgnored ? { allowIgnored: filtered.allowIgnored } : {}),
+    }, filtered.unknownAllow.length || filtered.unknownDeny.length || filtered.allowIgnored ? { level: 'warn' } : undefined);
+  }
+  if (childTools.length === 0 && filtered.available > 0) {
+    debug.log('agent.spawn', 'no-tools-refused', {
+      cid: debugCorrelationId, requestedType, description: description.slice(0, 80),
+      available: filtered.available, denySize: filtered.denySize,
+    }, { level: 'warn' });
+    return {
+      output:
+        `NOT SPAWNED — the tool_filter would leave this sub-agent with 0 of ${filtered.available} tools, ` +
+        `so it could not read files or run commands. Omit tool_filter to inherit the parent's full tool set, ` +
+        `or narrow with real tool names (for example: ${childToolNamesSample(filtered.availableNames)}).`,
+      agent: requestedType,
+      cid: debugCorrelationId,
+      durationMs: 0,
+      maxTurns: requestedMaxTurns,
+      taskId: 'no-tools-refused',
+    };
   }
 
   const hasNoTools = childTools.length === 0;
@@ -679,6 +965,19 @@ export async function dispatchAgent(
     ...(runInBackground ? { background: true } : {}),
   });
 
+  // Terminal release for this dispatch's reserved fan-out slot: the
+  // registry fires this exactly once per task when it reaches a
+  // terminal state (done/error/aborted); until then the slot counts as
+  // occupied against this session's ceiling above.
+  if (fanoutSession !== undefined) {
+    const fanoutSlotSession = fanoutSession;
+    const fanoutSlotSubscription = globalAgentRegistry.onTaskDone((task) => {
+      if (!task || task.id !== handle.task.id) return;
+      fanoutSlotSubscription.dispose();
+      releaseBackgroundFanoutSlot(fanoutSlotSession);
+    });
+    fanoutSession = undefined;  // the terminal subscription owns the release now
+  }
   // Forward parent abort to the spawned task. The registry owns the
   // child's controller; we just chain ours into it.
   if (opts.signal) {
@@ -907,4 +1206,73 @@ export async function dispatchAgent(
     ...(childCwd ? { cwd: childCwd } : {}),
     ...(appliedIsolation ? { isolation: appliedIsolation } : {}),
   };
+  } finally {
+    // The registered task owns its slot after the handoff above. Every
+    // pre-registration throw leaves fanoutSession set and releases it here.
+    releaseReservedFanoutSlot();
+  }
+}
+
+// ── SUBAGENT-TOOLS-EMPTY: per-spawn tool filter (pure) ──────────────────────────────────────
+
+export interface SpawnToolFilterResult<T extends { name: string }> {
+  tools: T[];
+  available: number;
+  availableNames: string[];
+  applied: boolean;
+  allowSize?: number;
+  denySize?: number;
+  unknownAllow: string[];
+  unknownDeny: string[];
+  /** allow 를 통째로 무시했다 — 이유(빈 배열 · 아는 이름 없음 · 모델이 넘긴 allow 는 기본 무시). */
+  allowIgnored?: 'empty' | 'no-known-names' | 'model-allow-ignored';
+}
+
+/** 모델이 넘긴 tool_filter.allow 로 좁히는가 — 사람이 명시할 때만(기본 false). */
+export function subagentHonorsModelAllow(env: NodeJS.ProcessEnv = process.env): boolean {
+  return /^(1|true|on)$/i.test((env.ELANOUS_SUBAGENT_HONOR_ALLOW ?? '').trim());
+}
+
+/** 기본 = 전부 상속 · deny = 아는 이름 빼기 · allow 는 `honorAllow` 일 때만 아는 이름으로 좁히기(없으면 무시). 넓히지는 못한다. */
+export function applySpawnToolFilter<T extends { name: string }>(
+  tools: readonly T[],
+  rawFilter: unknown,
+  opts: { honorAllow?: boolean } = {},
+): SpawnToolFilterResult<T> {
+  const available = tools.length;
+  const availableNames = tools.map((t) => t.name);
+  const known = new Set(availableNames);
+  const filter = rawFilter && typeof rawFilter === 'object' && !Array.isArray(rawFilter)
+    ? rawFilter as { allow?: unknown; deny?: unknown }
+    : undefined;
+  if (!filter) return { tools: [...tools], available, availableNames, applied: false, unknownAllow: [], unknownDeny: [] };
+  const names = (v: unknown): string[] | null => (Array.isArray(v) ? v.filter((n): n is string => typeof n === 'string' && n.trim() !== '') : null);
+  const allowRaw = names(filter.allow);
+  const denyRaw = names(filter.deny);
+  const unknownAllow = (allowRaw ?? []).filter((n) => !known.has(n));
+  const unknownDeny = (denyRaw ?? []).filter((n) => !known.has(n));
+  const allowKnown = (allowRaw ?? []).filter((n) => known.has(n));
+  let allowIgnored: SpawnToolFilterResult<T>['allowIgnored'];
+  let allow: Set<string> | null = null;
+  if (allowRaw) {
+    if (allowRaw.length === 0) allowIgnored = 'empty';
+    else if (!opts.honorAllow) allowIgnored = 'model-allow-ignored';
+    else if (allowKnown.length === 0) allowIgnored = 'no-known-names';
+    else allow = new Set(allowKnown);
+  }
+  const deny = new Set((denyRaw ?? []).filter((n) => known.has(n)));
+  const kept = tools.filter((t) => !deny.has(t.name) && (!allow || allow.has(t.name)));
+  return {
+    tools: kept, available, availableNames, applied: true,
+    ...(allowRaw ? { allowSize: allowRaw.length } : {}),
+    ...(denyRaw ? { denySize: denyRaw.length } : {}),
+    unknownAllow, unknownDeny,
+    ...(allowIgnored ? { allowIgnored } : {}),
+  };
 }
+
+function childToolNamesSample(names: readonly string[]): string {
+  const preferred = ['Read', 'Grep', 'Glob', 'RunShell', 'Write', 'Edit'].filter((n) => names.includes(n));
+  return (preferred.length ? preferred : names.slice(0, 6)).join(', ');
+}
+