@xemahq/opencode-xema-plugin 0.1.13 → 0.2.0

package/README.md

@@ -28,16 +28,44 @@
 
 ## Overview
 
-An Opencode plugin that registers Xema-namespaced runtime tools and a dynamic
-system-prompt overlay hook. The plugin is evaluated once at agent startup; it
-registers its tools unconditionally and defers per-role authorization to
-tool-execution time, where each tool reads the invocation context from the
-worker filesystem and rejects calls the invoking role is not permitted to make.
+An Opencode plugin that registers Xema-namespaced runtime tools, a dynamic
+system-prompt overlay hook, and the sub-agent fan-out ceiling. The plugin is
+evaluated once at agent startup; it registers its tools unconditionally and
+defers per-role authorization to tool-execution time, where each tool reads the
+invocation context from the worker filesystem and rejects calls the invoking
+role is not permitted to make.
 
 ## When to use it
 
 - Use it to add the Xema runtime tools and prompt overlay to an Opencode agent
   runtime.
+- Use it to bound how many sub-agents one worker may run at once.
+
+## The sub-agent fan-out ceiling
+
+Opencode bounds how DEEP delegation may nest (`subagent_depth`). Nothing bounds
+how WIDE a turn may go, so at the platform's declared depth an unbounded
+branching factor is an unbounded process — every `task` call is forked with no
+pool, no semaphore and no queue.
+
+This plugin adds the missing pool cap. It is BACKPRESSURE, not a refusal: when
+the worker is already running its ceiling of sub-agents, the next `task` call
+WAITS for a slot instead of being denied. An agent that cannot spawn a helper
+would produce a wrong answer; one that waits produces a slower right one.
+
+Configuration exists to TIGHTEN, never to enable:
+
+| | |
+|---|---|
+| Default | 8 concurrent `task` calls per worker |
+| Tighten with | `XEMA_SUBAGENT_FANOUT_LIMIT` (1..8) |
+| Unset or empty | the platform default — never zero, never "off" |
+| Above the default | refused at boot, with the reason |
+
+Every degradation is logged: a task that waits says so and for how long, and
+both leak backstops (a `session.idle` sweep and a per-permit TTL) name what they
+reclaimed. A ceiling that silently stops binding is indistinguishable from
+working software until somebody asks.
 
 ## Installation
 

package/dist/.source-stamp.json

@@ -1,5 +1,5 @@
 {
   "algorithm": "sha256/len-framed-v1",
-  "hash": "db148b94ce3037192dfbb8b60936b8b7af6162413cc6073819a29863cc5a79af",
-  "fileCount": 14
+  "hash": "1ed948cb2970db3cd244537af9583485fe1afb833942f2b1f1812500f5597960",
+  "fileCount": 15
 }

package/dist/hooks/subagent-fanout-ceiling.d.ts

@@ -0,0 +1,39 @@
+export declare const TASK_TOOL_ID = "task";
+export declare const DEFAULT_SUBAGENT_FANOUT_LIMIT = 8;
+export declare const DEFAULT_FANOUT_WAIT_TIMEOUT_MS: number;
+export declare const DEFAULT_PERMIT_TTL_MS: number;
+export declare const FANOUT_LIMIT_ENV = "XEMA_SUBAGENT_FANOUT_LIMIT";
+export declare function resolveSubagentFanoutLimit(env?: Readonly<Record<string, string | undefined>>): number;
+export interface FanoutCeilingStats {
+    readonly limit: number;
+    readonly inFlight: number;
+    readonly waiting: number;
+    readonly waitedCount: number;
+    readonly timedOutCount: number;
+    readonly sweptCount: number;
+    readonly ttlReclaimedCount: number;
+    readonly armedTimers: number;
+}
+export interface SubagentFanoutCeiling {
+    readonly before: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }) => Promise<void>;
+    readonly after: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }) => void;
+    readonly onSessionIdle: (sessionId: string) => void;
+    readonly dispose: () => void;
+    readonly stats: () => FanoutCeilingStats;
+}
+export interface FanoutCeilingOptions {
+    readonly limit: number;
+    readonly waitTimeoutMs?: number;
+    readonly permitTtlMs?: number;
+    readonly now?: () => number;
+}
+export declare function createSubagentFanoutCeiling(options: FanoutCeilingOptions): SubagentFanoutCeiling;
+//# sourceMappingURL=subagent-fanout-ceiling.d.ts.map

package/dist/hooks/subagent-fanout-ceiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-fanout-ceiling.d.ts","sourceRoot":"","sources":["../../src/hooks/subagent-fanout-ceiling.ts"],"names":[],"mappings":"AA0FA,eAAO,MAAM,YAAY,SAAS,CAAC;AA6CnC,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAW/C,eAAO,MAAM,8BAA8B,QAAiB,CAAC;AAU7D,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAGpD,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAyB7D,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,CA8BR;AAoBD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAiBnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpB,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,IAAI,CAAC;IAEX,QAAQ,CAAC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAgBpD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,kBAAkB,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAOD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAC5B,qBAAqB,CAgPvB"}

package/dist/hooks/subagent-fanout-ceiling.js

@@ -0,0 +1,188 @@
+import { info, warn, debug } from '../logger.js';
+export const TASK_TOOL_ID = 'task';
+export const DEFAULT_SUBAGENT_FANOUT_LIMIT = 8;
+export const DEFAULT_FANOUT_WAIT_TIMEOUT_MS = 10 * 60 * 1000;
+export const DEFAULT_PERMIT_TTL_MS = 30 * 60 * 1000;
+export const FANOUT_LIMIT_ENV = 'XEMA_SUBAGENT_FANOUT_LIMIT';
+export function resolveSubagentFanoutLimit(env = process.env) {
+    const declared = env[FANOUT_LIMIT_ENV];
+    if (declared === undefined || declared.trim() === '') {
+        return DEFAULT_SUBAGENT_FANOUT_LIMIT;
+    }
+    const parsed = Number(declared.trim());
+    if (!Number.isInteger(parsed)) {
+        throw new Error(`${FANOUT_LIMIT_ENV}="${declared}" is not an integer. Expected a whole number of ` +
+            `concurrently executing sub-agent tasks between 1 and ${DEFAULT_SUBAGENT_FANOUT_LIMIT}.`);
+    }
+    if (parsed < 1) {
+        throw new Error(`${FANOUT_LIMIT_ENV}="${declared}" is below 1. A ceiling of 0 would park EVERY delegation ` +
+            `until it timed out, turning a resource bound into an outage. Remove the variable to ` +
+            `accept the platform default (${DEFAULT_SUBAGENT_FANOUT_LIMIT}).`);
+    }
+    if (parsed > DEFAULT_SUBAGENT_FANOUT_LIMIT) {
+        throw new Error(`${FANOUT_LIMIT_ENV}="${declared}" is above the platform default ` +
+            `(${DEFAULT_SUBAGENT_FANOUT_LIMIT}). Configuration may only TIGHTEN this ceiling. The ` +
+            `default is a stated platform decision; a wider one moves ` +
+            `DEFAULT_SUBAGENT_FANOUT_LIMIT, where the grounds are recorded.`);
+    }
+    return parsed;
+}
+export function createSubagentFanoutCeiling(options) {
+    const limit = options.limit;
+    const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_FANOUT_WAIT_TIMEOUT_MS;
+    const permitTtlMs = options.permitTtlMs ?? DEFAULT_PERMIT_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const held = new Map();
+    const waiters = [];
+    let waitedCount = 0;
+    let timedOutCount = 0;
+    let sweptCount = 0;
+    let ttlReclaimedCount = 0;
+    const armed = new Set();
+    function arm(fn, ms, keepProcessAlive) {
+        const timer = setTimeout(() => {
+            armed.delete(timer);
+            fn();
+        }, ms);
+        if (!keepProcessAlive)
+            timer.unref?.();
+        armed.add(timer);
+        return timer;
+    }
+    function disarm(timer) {
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        armed.delete(timer);
+    }
+    function take(callId, sessionId) {
+        const ttlTimer = arm(() => {
+            if (!held.has(callId))
+                return;
+            ttlReclaimedCount += 1;
+            warn(`fanout-ceiling: permit TTL expired for call=${callId} session=${sessionId} after ` +
+                `${permitTtlMs}ms — force-releasing. A task held a slot longer than any healthy ` +
+                `sub-agent turn; the pool would otherwise have shrunk permanently.`);
+            release(callId, 'ttl');
+        }, permitTtlMs, false);
+        held.set(callId, { sessionId, acquiredAt: now(), ttlTimer });
+    }
+    function release(callId, reason) {
+        const permit = held.get(callId);
+        if (permit === undefined)
+            return;
+        disarm(permit.ttlTimer);
+        held.delete(callId);
+        if (reason !== 'completed') {
+            debug(`fanout-ceiling: reclaimed call=${callId} via ${reason} ` +
+                `(held ${now() - permit.acquiredAt}ms)`);
+        }
+        drain();
+    }
+    function drain() {
+        while (waiters.length > 0 && held.size < limit) {
+            const next = waiters.shift();
+            if (next === undefined)
+                return;
+            disarm(next.timer);
+            const waitedMs = now() - next.since;
+            waitedCount += 1;
+            take(next.callId, next.sessionId);
+            info(`fanout-ceiling: admitted call=${next.callId} session=${next.sessionId} after waiting ` +
+                `${waitedMs}ms (limit=${limit}, in-flight=${held.size}, still waiting=${waiters.length})`);
+            next.grant();
+        }
+    }
+    async function before(input) {
+        if (input.tool !== TASK_TOOL_ID)
+            return;
+        const { callID: callId, sessionID: sessionId } = input;
+        if (held.size < limit) {
+            take(callId, sessionId);
+            debug(`fanout-ceiling: admitted call=${callId} immediately ` +
+                `(in-flight=${held.size}/${limit})`);
+            return;
+        }
+        const since = now();
+        warn(`fanout-ceiling: sub-agent fan-out at ceiling — call=${callId} session=${sessionId} is ` +
+            `WAITING (limit=${limit}, in-flight=${held.size}, already waiting=${waiters.length}). ` +
+            `This is backpressure, not a refusal: the task will start when a slot frees.`);
+        await new Promise((resolve) => {
+            const waiter = {
+                callId,
+                sessionId,
+                since,
+                grant: resolve,
+                timer: undefined,
+            };
+            waiter.timer = arm(() => {
+                const idx = waiters.indexOf(waiter);
+                if (idx === -1)
+                    return;
+                waiters.splice(idx, 1);
+                timedOutCount += 1;
+                warn(`fanout-ceiling: call=${callId} session=${sessionId} waited ${waitTimeoutMs}ms and is ` +
+                    `being ADMITTED OVER the ceiling (limit=${limit}, in-flight=${held.size}). The pool ` +
+                    `did not free a slot in that window — suspect a leaked permit or a stuck sub-agent.`);
+                take(callId, sessionId);
+                resolve();
+            }, waitTimeoutMs, true);
+            waiters.push(waiter);
+        });
+    }
+    function after(input) {
+        if (input.tool !== TASK_TOOL_ID)
+            return;
+        release(input.callID, 'completed');
+    }
+    function onSessionIdle(sessionId) {
+        const stale = [];
+        for (const [callId, permit] of held) {
+            if (permit.sessionId === sessionId)
+                stale.push(callId);
+        }
+        if (stale.length === 0)
+            return;
+        sweptCount += stale.length;
+        warn(`fanout-ceiling: session=${sessionId} went idle still holding ${stale.length} permit(s) ` +
+            `[${stale.join(', ')}] — reclaiming. These tasks ended without a tool.execute.after, ` +
+            `which upstream does not fire on the failure path.`);
+        for (const callId of stale)
+            release(callId, 'session-idle');
+    }
+    function dispose() {
+        const parked = waiters.length;
+        const outstanding = held.size;
+        while (waiters.length > 0) {
+            const w = waiters.shift();
+            if (w === undefined)
+                break;
+            disarm(w.timer);
+            w.grant();
+        }
+        for (const permit of held.values())
+            disarm(permit.ttlTimer);
+        held.clear();
+        if (parked > 0 || outstanding > 0) {
+            info(`fanout-ceiling: disposed — released ${parked} parked task(s) and disarmed ` +
+                `${outstanding} permit timer(s).`);
+        }
+    }
+    return {
+        before,
+        after,
+        onSessionIdle,
+        dispose,
+        stats: () => ({
+            limit,
+            inFlight: held.size,
+            waiting: waiters.length,
+            waitedCount,
+            timedOutCount,
+            sweptCount,
+            ttlReclaimedCount,
+            armedTimers: armed.size,
+        }),
+    };
+}
+//# sourceMappingURL=subagent-fanout-ceiling.js.map

package/dist/hooks/subagent-fanout-ceiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-fanout-ceiling.js","sourceRoot":"","sources":["../../src/hooks/subagent-fanout-ceiling.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { Plugin } from './opencode-types.js';
 export declare const XemaPlugin: Plugin;
 export declare function __resetBootCacheForTests(): void;
 export default XemaPlugin;
+export { createSubagentFanoutCeiling, resolveSubagentFanoutLimit, DEFAULT_SUBAGENT_FANOUT_LIMIT, DEFAULT_FANOUT_WAIT_TIMEOUT_MS, DEFAULT_PERMIT_TTL_MS, FANOUT_LIMIT_ENV, TASK_TOOL_ID, type SubagentFanoutCeiling, type FanoutCeilingOptions, type FanoutCeilingStats, } from './hooks/subagent-fanout-ceiling.js';
 export { readInvocationContext } from './context.js';
 export type { InvocationContext, InvocationRole } from './context.js';
 export * from './errors.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAS,MAAM,EAAkB,MAAM,qBAAqB,CAAC;AAuBzE,eAAO,MAAM,UAAU,EAAE,MAgBxB,CAAC;AA+BF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAyBD,eAAe,UAAU,CAAC;AAG1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkEA,OAAO,KAAK,EAIV,MAAM,EAEP,MAAM,qBAAqB,CAAC;AAuB7B,eAAO,MAAM,UAAU,EAAE,MAgBxB,CAAC;AAgFF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAyBD,eAAe,UAAU,CAAC;AAG1B,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,6BAA6B,EAC7B,8BAA8B,EAC9B,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildSessionIdleAutocommit } from './hooks/session-idle-autocommit.js';
+import { createSubagentFanoutCeiling, resolveSubagentFanoutLimit, } from './hooks/subagent-fanout-ceiling.js';
 import { buildSystemPromptOverlay } from './hooks/system-prompt-overlay.js';
-import { info, isDebug } from './logger.js';
+import { info, isDebug, warn } from './logger.js';
 import { buildXemaMemoryGetTool, buildXemaMemorySetTool, } from './tools/xema-memory.js';
 const bootCache = new Map();
 export const XemaPlugin = async (ctx) => {
@@ -29,10 +30,40 @@ async function doBoot(directory) {
     info(`boot: directory=${directory} tools=${toolNames.length} [${toolNames.join(', ')}] ` +
         `context.json=${contextPresentAtBoot ? 'present' : 'absent'} ` +
         `debug=${isDebug() ? 'on' : 'off'}`);
+    const fanoutLimit = resolveSubagentFanoutLimit();
+    const fanout = createSubagentFanoutCeiling({ limit: fanoutLimit });
+    const autocommit = buildSessionIdleAutocommit(directory);
+    info(`boot: subagent fan-out ceiling active (limit=${fanoutLimit} concurrent task calls ` +
+        `per worker; tighten with XEMA_SUBAGENT_FANOUT_LIMIT)`);
     const hooks = {
         tool: tools,
         'experimental.chat.system.transform': buildSystemPromptOverlay(directory),
-        event: buildSessionIdleAutocommit(directory),
+        'tool.execute.before': async (input) => {
+            await fanout.before(input);
+        },
+        'tool.execute.after': (input) => {
+            fanout.after(input);
+        },
+        dispose: async () => {
+            fanout.dispose();
+        },
+        event: async (input) => {
+            const evt = input.event;
+            if (evt.type === 'session.idle') {
+                const sessionId = evt.properties
+                    ?.sessionID;
+                if (sessionId) {
+                    try {
+                        fanout.onSessionIdle(sessionId);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        warn(`fanout-ceiling: session-idle sweep failed: ${message}`);
+                    }
+                }
+            }
+            await autocommit(input);
+        },
     };
     return hooks;
 }
@@ -46,6 +77,7 @@ function buildAllTools(workspaceDir) {
     };
 }
 export default XemaPlugin;
+export { createSubagentFanoutCeiling, resolveSubagentFanoutLimit, DEFAULT_SUBAGENT_FANOUT_LIMIT, DEFAULT_FANOUT_WAIT_TIMEOUT_MS, DEFAULT_PERMIT_TTL_MS, FANOUT_LIMIT_ENV, TASK_TOOL_ID, } from './hooks/subagent-fanout-ceiling.js';
 export { readInvocationContext } from './context.js';
 export * from './errors.js';
 export { loadSessionState, loadSessionStateForTool, ensureRoleAllowed, ContextMissingError, RoleNotAllowedError, } from './session-state.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAgBhC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEpD,MAAM,CAAC,MAAM,UAAU,GAAW,KAAK,EAAE,GAAG,EAAE,EAAE;IAC9C,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC;IAC1B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QAGb,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC5B,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC,CAAC;AAEF,KAAK,UAAU,MAAM,CAAC,SAAiB;IACrC,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACpD,MAAM,oBAAoB,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IAErD,IAAI,CACF,mBAAmB,SAAS,UAAU,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACjF,gBAAgB,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,GAAG;QAC9D,SAAS,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CACtC,CAAC;IAEF,MAAM,KAAK,GAAU;QACnB,IAAI,EAAE,KAAK;QACX,oCAAoC,EAAE,wBAAwB,CAAC,SAAS,CAAC;QAMzE,KAAK,EAAE,0BAA0B,CAAC,SAAS,CAAC;KAC7C,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAMD,MAAM,UAAU,wBAAwB;IACtC,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC;AAED,SAAS,aAAa,CAAC,YAAoB;IACzC,OAAO;QACL,eAAe,EAAE,sBAAsB,CAAC,YAAY,CAAC;QACrD,eAAe,EAAE,sBAAsB,CAAC,YAAY,CAAC;KAiBtD,CAAC;AACJ,CAAC;AAED,eAAe,UAAU,CAAC;AAG1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/opencode-types.d.ts

@@ -37,8 +37,22 @@ export type OpencodeEvent = OpencodeSessionIdleEvent | {
     type: string;
     properties?: Record<string, unknown>;
 };
+export interface ToolExecuteHookInput {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}
 export interface Hooks {
     tool?: Record<string, ToolDefinition>;
+    dispose?: () => Promise<void>;
+    'tool.execute.before'?: (input: ToolExecuteHookInput, output: {
+        args: unknown;
+    }) => Promise<void> | void;
+    'tool.execute.after'?: (input: ToolExecuteHookInput, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void> | void;
     'experimental.chat.system.transform'?: (input: ExperimentalChatSystemTransformInput, output: ExperimentalChatSystemTransformOutput) => Promise<void> | void;
     event?: (input: {
         event: OpencodeEvent;

package/dist/opencode-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-types.d.ts","sourceRoot":"","sources":["../src/opencode-types.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/E;AAED,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CACL,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAChC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAQD,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oCAAoC;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,qBAAqB,CAAC;CAC9B;AAED,MAAM,WAAW,qCAAqC;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAUD,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,wBAAwB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAOtC,oCAAoC,CAAC,EAAE,CACrC,KAAK,EAAE,oCAAoC,EAC3C,MAAM,EAAE,qCAAqC,KAC1C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAQ1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,aAAa,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE;AAED,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;AAO5D,wBAAgB,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC,WAAW,EAC7C,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,GAC1B,cAAc,CAAC,IAAI,CAAC,CAEtB"}
+{"version":3,"file":"opencode-types.d.ts","sourceRoot":"","sources":["../src/opencode-types.ts"],"names":[],"mappings":"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"}

package/dist/opencode-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-types.js","sourceRoot":"","sources":["../src/opencode-types.ts"],"names":[],"mappings":"AAsGA,MAAM,UAAU,IAAI,CAClB,KAA2B;IAE3B,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"opencode-types.js","sourceRoot":"","sources":["../src/opencode-types.ts"],"names":[],"mappings":"AAoJA,MAAM,UAAU,IAAI,CAClB,KAA2B;IAE3B,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xemahq/opencode-xema-plugin",
-  "version": "0.1.13",
-  "description": "Opencode plugin providing Xema-namespaced runtime tools (xema_memory_*) and the dynamic system-prompt overlay hook.",
+  "version": "0.2.0",
+  "description": "Opencode plugin providing Xema-namespaced runtime tools (xema_memory_*), the dynamic system-prompt overlay hook, and the sub-agent fan-out ceiling.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
   "homepage": "https://xema.dev",
@@ -33,7 +33,7 @@
     "esbuild": "^0.25.4",
     "typescript": "5.9.3",
     "zod": "^4.3.6",
-    "@xemahq/kernel-contracts": "^19.0.0"
+    "@xemahq/kernel-contracts": "^33.5.0"
   },
   "exports": {
     ".": {

package/plugin.mjs

@@ -14866,6 +14866,185 @@ function sleep(ms) {
   });
 }
 
+// src/hooks/subagent-fanout-ceiling.ts
+var TASK_TOOL_ID = "task";
+var DEFAULT_SUBAGENT_FANOUT_LIMIT = 8;
+var DEFAULT_FANOUT_WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
+var DEFAULT_PERMIT_TTL_MS = 30 * 60 * 1e3;
+var FANOUT_LIMIT_ENV = "XEMA_SUBAGENT_FANOUT_LIMIT";
+function resolveSubagentFanoutLimit(env = process.env) {
+  const declared = env[FANOUT_LIMIT_ENV];
+  if (declared === void 0 || declared.trim() === "") {
+    return DEFAULT_SUBAGENT_FANOUT_LIMIT;
+  }
+  const parsed = Number(declared.trim());
+  if (!Number.isInteger(parsed)) {
+    throw new Error(
+      `${FANOUT_LIMIT_ENV}="${declared}" is not an integer. Expected a whole number of concurrently executing sub-agent tasks between 1 and ${DEFAULT_SUBAGENT_FANOUT_LIMIT}.`
+    );
+  }
+  if (parsed < 1) {
+    throw new Error(
+      `${FANOUT_LIMIT_ENV}="${declared}" is below 1. A ceiling of 0 would park EVERY delegation until it timed out, turning a resource bound into an outage. Remove the variable to accept the platform default (${DEFAULT_SUBAGENT_FANOUT_LIMIT}).`
+    );
+  }
+  if (parsed > DEFAULT_SUBAGENT_FANOUT_LIMIT) {
+    throw new Error(
+      `${FANOUT_LIMIT_ENV}="${declared}" is above the platform default (${DEFAULT_SUBAGENT_FANOUT_LIMIT}). Configuration may only TIGHTEN this ceiling. The default is a stated platform decision; a wider one moves DEFAULT_SUBAGENT_FANOUT_LIMIT, where the grounds are recorded.`
+    );
+  }
+  return parsed;
+}
+function createSubagentFanoutCeiling(options) {
+  const limit = options.limit;
+  const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_FANOUT_WAIT_TIMEOUT_MS;
+  const permitTtlMs = options.permitTtlMs ?? DEFAULT_PERMIT_TTL_MS;
+  const now = options.now ?? (() => Date.now());
+  const held = /* @__PURE__ */ new Map();
+  const waiters = [];
+  let waitedCount = 0;
+  let timedOutCount = 0;
+  let sweptCount = 0;
+  let ttlReclaimedCount = 0;
+  const armed = /* @__PURE__ */ new Set();
+  function arm(fn, ms, keepProcessAlive) {
+    const timer = setTimeout(() => {
+      armed.delete(timer);
+      fn();
+    }, ms);
+    if (!keepProcessAlive) timer.unref?.();
+    armed.add(timer);
+    return timer;
+  }
+  function disarm(timer) {
+    if (timer === void 0) return;
+    clearTimeout(timer);
+    armed.delete(timer);
+  }
+  function take(callId, sessionId) {
+    const ttlTimer = arm(() => {
+      if (!held.has(callId)) return;
+      ttlReclaimedCount += 1;
+      warn(
+        `fanout-ceiling: permit TTL expired for call=${callId} session=${sessionId} after ${permitTtlMs}ms \u2014 force-releasing. A task held a slot longer than any healthy sub-agent turn; the pool would otherwise have shrunk permanently.`
+      );
+      release(callId, "ttl");
+    }, permitTtlMs, false);
+    held.set(callId, { sessionId, acquiredAt: now(), ttlTimer });
+  }
+  function release(callId, reason) {
+    const permit = held.get(callId);
+    if (permit === void 0) return;
+    disarm(permit.ttlTimer);
+    held.delete(callId);
+    if (reason !== "completed") {
+      debug(
+        `fanout-ceiling: reclaimed call=${callId} via ${reason} (held ${now() - permit.acquiredAt}ms)`
+      );
+    }
+    drain();
+  }
+  function drain() {
+    while (waiters.length > 0 && held.size < limit) {
+      const next = waiters.shift();
+      if (next === void 0) return;
+      disarm(next.timer);
+      const waitedMs = now() - next.since;
+      waitedCount += 1;
+      take(next.callId, next.sessionId);
+      info(
+        `fanout-ceiling: admitted call=${next.callId} session=${next.sessionId} after waiting ${waitedMs}ms (limit=${limit}, in-flight=${held.size}, still waiting=${waiters.length})`
+      );
+      next.grant();
+    }
+  }
+  async function before(input) {
+    if (input.tool !== TASK_TOOL_ID) return;
+    const { callID: callId, sessionID: sessionId } = input;
+    if (held.size < limit) {
+      take(callId, sessionId);
+      debug(
+        `fanout-ceiling: admitted call=${callId} immediately (in-flight=${held.size}/${limit})`
+      );
+      return;
+    }
+    const since = now();
+    warn(
+      `fanout-ceiling: sub-agent fan-out at ceiling \u2014 call=${callId} session=${sessionId} is WAITING (limit=${limit}, in-flight=${held.size}, already waiting=${waiters.length}). This is backpressure, not a refusal: the task will start when a slot frees.`
+    );
+    await new Promise((resolve) => {
+      const waiter = {
+        callId,
+        sessionId,
+        since,
+        grant: resolve,
+        timer: void 0
+      };
+      waiter.timer = arm(() => {
+        const idx = waiters.indexOf(waiter);
+        if (idx === -1) return;
+        waiters.splice(idx, 1);
+        timedOutCount += 1;
+        warn(
+          `fanout-ceiling: call=${callId} session=${sessionId} waited ${waitTimeoutMs}ms and is being ADMITTED OVER the ceiling (limit=${limit}, in-flight=${held.size}). The pool did not free a slot in that window \u2014 suspect a leaked permit or a stuck sub-agent.`
+        );
+        take(callId, sessionId);
+        resolve();
+      }, waitTimeoutMs, true);
+      waiters.push(waiter);
+    });
+  }
+  function after(input) {
+    if (input.tool !== TASK_TOOL_ID) return;
+    release(input.callID, "completed");
+  }
+  function onSessionIdle(sessionId) {
+    const stale = [];
+    for (const [callId, permit] of held) {
+      if (permit.sessionId === sessionId) stale.push(callId);
+    }
+    if (stale.length === 0) return;
+    sweptCount += stale.length;
+    warn(
+      `fanout-ceiling: session=${sessionId} went idle still holding ${stale.length} permit(s) [${stale.join(", ")}] \u2014 reclaiming. These tasks ended without a tool.execute.after, which upstream does not fire on the failure path.`
+    );
+    for (const callId of stale) release(callId, "session-idle");
+  }
+  function dispose() {
+    const parked = waiters.length;
+    const outstanding = held.size;
+    while (waiters.length > 0) {
+      const w = waiters.shift();
+      if (w === void 0) break;
+      disarm(w.timer);
+      w.grant();
+    }
+    for (const permit of held.values()) disarm(permit.ttlTimer);
+    held.clear();
+    if (parked > 0 || outstanding > 0) {
+      info(
+        `fanout-ceiling: disposed \u2014 released ${parked} parked task(s) and disarmed ${outstanding} permit timer(s).`
+      );
+    }
+  }
+  return {
+    before,
+    after,
+    onSessionIdle,
+    dispose,
+    stats: () => ({
+      limit,
+      inFlight: held.size,
+      waiting: waiters.length,
+      waitedCount,
+      timedOutCount,
+      sweptCount,
+      ttlReclaimedCount,
+      armedTimers: armed.size
+    })
+  };
+}
+
 // src/hooks/system-prompt-overlay.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
 import { join as join4 } from "node:path";
@@ -15252,15 +15431,54 @@ async function doBoot(directory) {
   info(
     `boot: directory=${directory} tools=${toolNames.length} [${toolNames.join(", ")}] context.json=${contextPresentAtBoot ? "present" : "absent"} debug=${isDebug() ? "on" : "off"}`
   );
+  const fanoutLimit = resolveSubagentFanoutLimit();
+  const fanout = createSubagentFanoutCeiling({ limit: fanoutLimit });
+  const autocommit = buildSessionIdleAutocommit(directory);
+  info(
+    `boot: subagent fan-out ceiling active (limit=${fanoutLimit} concurrent task calls per worker; tighten with XEMA_SUBAGENT_FANOUT_LIMIT)`
+  );
   const hooks = {
     tool: tools,
     "experimental.chat.system.transform": buildSystemPromptOverlay(directory),
-    // Per-turn auto-commit. Listens for `session.idle` via the
-    // generic `event` channel — opencode 1.15.x does not expose a
-    // dedicated `session.idle` hook, only the event union. The handler
-    // is a no-op for sessions whose context.json does not opt in
-    // (`git.autoCommit !== 'enabled'`).
-    event: buildSessionIdleAutocommit(directory)
+    // Backpressure on sub-agent fan-out. Upstream awaits this hook immediately
+    // before the tool runs, so parking here parks the `task` call BEFORE the
+    // child session exists — a pool cap that makes the N+1th spawn wait, not a
+    // counter that aborts a run already paid for.
+    "tool.execute.before": async (input) => {
+      await fanout.before(input);
+    },
+    "tool.execute.after": (input) => {
+      fanout.after(input);
+    },
+    // Shutdown. Disarms the ceiling's timers and lets any parked `task` call
+    // through, so a torn-down worker leaves nothing armed and nothing pending.
+    dispose: async () => {
+      fanout.dispose();
+    },
+    // TWO consumers of `session.idle` now, so the channel fans out. opencode
+    // exposes session lifecycle only as a discriminated event union, not as
+    // dedicated hooks, and `Hooks.event` is a single function — so composition
+    // has to happen here.
+    //
+    // The order matters and the isolation matters more: the fan-out sweep is a
+    // LEAK BACKSTOP, so it must run even if auto-commit fails. Auto-commit
+    // already swallows its own errors by hard invariant, but relying on that
+    // from the outside would make this correct only by someone else's promise.
+    event: async (input) => {
+      const evt = input.event;
+      if (evt.type === "session.idle") {
+        const sessionId = evt.properties?.sessionID;
+        if (sessionId) {
+          try {
+            fanout.onSessionIdle(sessionId);
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warn(`fanout-ceiling: session-idle sweep failed: ${message}`);
+          }
+        }
+      }
+      await autocommit(input);
+    }
   };
   return hooks;
 }