@byokit/openclaw 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.24.0 (2026-10-20)
+
+- FEAT: a helper's delegated run now speaks as its helper. A native `sessions_send` carries no system text, so the kit's plugin adds the helper's recorded persona (from `ensureHelper`) as system context to the admitted helper child's run, and only to it. No app change: Chief's `helperDelegates` send to `agent:<agent>:h-<helper>:<rest>` is enough. The kit plugin's config entry now sets `hooks.allowConversationAccess: true` for this hook. `sessions_spawn` children get no persona.
+- FEAT: a tracked `sessions_spawn` into the run's own agent (`delegates` naming it, e.g. Chief spawning under its own signed-in agent) reaches the engine as its own-agent spawn, so an app `subagents.allowAgents` list that names only other agents no longer refuses it.
+- FIX: a delegated child the engine no longer knows (as after an engine restart, when its end never reached the kit) now ends `lost` (new `DelegatedEvent.reason`, outcome unknown) at reconnect instead of staying admitted forever, and a dispatch that finds the 1024-entry journal full reconciles with the engine first, so those children can no longer block delegation. One unreadable `agent.wait` no longer fails the whole reconnect.
+
 ## 0.23.0 (2026-10-20)
 
 - FEATURE: A signed-out `claude-cli` run now says why: its end carries `cause: { code: 'needs_cli_login', cli: 'claude', home, configDir?, signIn }` (the new `CliLoginCause` type, also on `./device`). `signIn: true` means `kit.signIn(member, { authChoice: 'anthropic-cli' })` runs the Claude Code login into the kit's own folder (subscription billing); `signIn: false` means the engine reads the person's own Claude Code login, so they run `claude` on that machine. An `anthropic-cli` sign-in the kit cannot run carries the same `cause` on its failed view. `kind`, `message` and every other run end are unchanged.

package/README.md

@@ -443,14 +443,17 @@ Pass `delegates: { scout: ['report'] }` on `kit.run` to permit native delegation
 that app-tool subset. Ensure the target member first and configure the engine's own A2A/visibility/subagent policy;
 this option does not enable engine tools or bypass `host.gate`. The parent subset narrows descendants too.
 Tracked `sessions_send` requires an explicit full `sessionKey` and `timeoutSeconds: 0`; tracked `sessions_spawn`
-requires an explicit allowed `agentId` and native runtime (not ACP). Unknown children fail closed.
+requires an explicit allowed `agentId` and native runtime (not ACP). A tracked spawn into the run's own agent
+(`delegates: { chief: [...] }` on a `chief` run) goes to the engine as its own-agent spawn, so an app
+`subagents.allowAgents` list for other agents does not refuse it. Unknown children fail closed.
 
 `kit.delegatedRuns()` lists admitted children. `kit.onEvent('byokit.delegated', fn)` reports admission, native streams
 and terminal observations with exact `runId`, `agentId`, `member`, `sessionKey`, `parent` and `root` identity.
 The same identity reaches `ToolHost`; each delegated action has its own gate/approval. Tool arguments/results
 are omitted from this event surface. An accepted native dispatch is not finished work or proof of delivery.
 
-Admitted exact run IDs survive parent settlement and are reconciled on reconnect/start. `abort(rootSessionKey)`
+Admitted exact run IDs survive parent settlement and are reconciled on reconnect/start; a child the engine no longer
+knows (as after an engine restart) ends `lost`, and a dispatch that finds the journal full reconciles first. `abort(rootSessionKey)`
 durably revokes its recorded subtree, closes parked gates/active calls, then asks the engine to abort; a child key
 revokes its subtree. An engine resume with a different run ID, or a dispatch with no retained receipt, is not
 silently granted authority. No prefix grants or `allowOnce` bypass are used.
@@ -496,8 +499,9 @@ above, builtin gating on): the engine's own `sessions_send` to the exact key `ag
 (`timeoutSeconds: 0`) is admitted from its receipt as writer's run, `RunRef.helper: 'writer'` on every gate and call.
 A target that is not a helper key, a helper on another account, one never ensured, or one the run was not given is
 refused before dispatch; the parent's tool result reads `session: …`, `bound: …` or `unknown_helper: …`.
-`abort(rootSessionKey)` revokes the children, and a helper whose account is removed loses them at their next call. The
-child runs without the helper's persona (a native send carries no system text).
+`abort(rootSessionKey)` revokes the children, and a helper whose account is removed loses them at their next call. A
+native send carries no system text, so the kit adds the helper's recorded persona as system context to the admitted
+child's run; a `sessions_spawn` child gets none.
 
 Conversations from before helpers (plain member sessions) move into a helper with
 `kit.adoptHelperSession({ member, sessionKey }, helper)`: the whole transcript forks to
@@ -510,8 +514,9 @@ both. A helper key, another member's key or a helper never ensured is a typed `H
 
 `kit.onEvent('byokit.delegated', fn)` follows each helper child start to finish: `admitted` (with `run.helper` and
 `run.tools`, its app-tool subset), the engine's events, then one `ended` whose `reason` is `terminal`, `cancelled` (an
-abort, or its admission ended), `error` (with `message`) or `resting`: the model's usage limit ended it, and the kit
-rests the helper's account `until` the stated reset, as a kit run's resting end does. An approval raised by a helper's
+abort, or its admission ended), `error` (with `message`), `lost` (the engine no longer knows the run: outcome unknown)
+or `resting`: the model's usage limit ended it, and the kit rests the helper's account `until` the stated reset, as a
+kit run's resting end does. An approval raised by a helper's
 run names it in `Approval.helper`.
 
 ## Owned browser (unqualified handoff)

package/dist/bridge.js

@@ -316,28 +316,35 @@ export class Bridge {
             return;
         }
         if (message.kind.startsWith('delegation-') && this.delegations) {
-            try {
+            const delegations = this.delegations;
+            void (async () => {
                 if (message.kind === 'delegation-prepare') {
                     if (typeof message.key !== 'string' || typeof message.runId !== 'string'
-                        || (!this.isRegisteredRun(message.key, message.runId) && !this.delegations.has(message.key, message.runId)))
+                        || (!this.isRegisteredRun(message.key, message.runId) && !delegations.has(message.key, message.runId)))
                         return this.deny(socket, 'unknown delegation parent');
-                    this.reply(socket, { tracked: this.delegations.prepare(message) });
+                    this.reply(socket, { tracked: await delegations.prepare(message) });
                 }
                 else if (message.kind === 'delegation-receipt') {
-                    this.delegations.receipt(message);
+                    delegations.receipt(message);
                     this.reply(socket, { ok: true });
                 }
                 else if (message.kind === 'delegation-event' && isRecord(message.event)) {
-                    this.delegations.event(message.event);
+                    delegations.event(message.event);
                     this.reply(socket, { ok: true });
                 }
+                // The plugin's prompt hook on a helper key: an admitted helper child speaks as its helper (5.8.3).
+                else if (message.kind === 'delegation-persona' && typeof message.key === 'string') {
+                    const runId = typeof message.runId === 'string' ? message.runId : undefined;
+                    // A kit run carries its own persona; only an engine-created child is looked up (it may wait for its receipt).
+                    const persona = runId && this.isRegisteredRun(message.key, runId) ? undefined : await delegations.persona(message.key, runId);
+                    this.reply(socket, persona === undefined ? {} : { persona });
+                }
                 else
                     this.deny(socket, 'invalid delegation message');
-            }
-            catch (error) {
+            })().catch((error) => {
                 // A typed helper refusal (5.8.3) reaches the parent's tool result with its code.
                 this.deny(socket, error instanceof HelperError ? `${error.code}: ${error.message}` : error instanceof Error ? error.message : 'delegation unavailable');
-            }
+            });
             return;
         }
         if (message.kind === 'gate')

package/dist/config.js

@@ -100,7 +100,9 @@ export function reconcileConfig(saved, o) {
             ...o.plugins ?? [],
             ...telegram ? ['telegram'] : []])];
     c.plugins.entries ??= {};
-    c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
+    // Conversation access lets the plugin's prompt hook give an admitted helper child its persona (5.8.3).
+    c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 },
+            allowConversationAccess: true } });
     if (o.browser) {
         // Replace, never merge caller-controlled profiles/targets. The dead default fails closed without our hook.
         c.browser = { enabled: true, defaultProfile: 'byokit-none', evaluateEnabled: false,
@@ -108,7 +110,6 @@ export function reconcileConfig(saved, o) {
             profiles: { 'byokit-none': { cdpUrl: 'http://127.0.0.1:1', attachOnly: true }, ...o.browser.profiles } };
         c.plugins.allow = [...new Set([...c.plugins.allow, 'browser'])];
         c.plugins.entries.browser = { enabled: true };
-        c.plugins.entries[o.pluginId].hooks.allowConversationAccess = true;
         c.tools ??= {};
         const browserTools = [...new Set([...(c.tools.alsoAllow ?? []), 'browser', 'request_sign_in', ...o.browser.tools])];
         // The stock schema rejects allow + alsoAllow in one scope; an explicit closed allow must absorb additions.

package/dist/delegations.d.ts

@@ -20,6 +20,7 @@ export declare class Delegations {
         helper(member: string, helper: string): {
             agentId: string;
             account: string;
+            persona: string;
         };
         rest(member: string, account: string, until: number): Promise<void>;
         request: GatewayTransport['request'];
@@ -33,9 +34,12 @@ export declare class Delegations {
     register(ref: RunRef, runId: string, tools: readonly string[] | undefined, delegates: Record<string, string[]>, sourceKey?: string, helpers?: Record<string, string[]>): () => void;
     list(): DelegatedRun[];
     has(key: string, runId: string): boolean;
-    prepare(m: Record<string, any>): boolean;
+    private full;
+    prepare(m: Record<string, any>): Promise<boolean>;
     receipt(m: Record<string, any>): void;
     resolve(key: string, runId?: string): Promise<Grant | undefined>;
+    /** The persona of the admitted helper child on this exact key and run, as its own run would carry it (5.8.3). */
+    persona(key: string, runId?: string): Promise<string | undefined>;
     private bound;
     event(event: Record<string, any>): void;
     private ended;

package/dist/delegations.js

@@ -70,8 +70,19 @@ export class Delegations {
         this.load();
         return (this.roots.get(runId) ?? this.children.get(runId))?.ref.sessionKey === key;
     }
-    prepare(m) {
+    full() {
+        for (const [id, p] of this.pending)
+            if (p.expires < Date.now())
+                this.pending.delete(id);
+        return this.pending.size + this.children.size >= 1024;
+    }
+    async prepare(m) {
         this.load();
+        // Children whose end never reached the kit would fill the journal for good: settle them with the engine first,
+        // before the parent is read, so an abort meanwhile is seen.
+        // ponytail: a full journal of live children re-reads all 1024 per dispatch; index ends by age if that shows up.
+        if (this.full())
+            await this.reconcile();
         const parent = this.roots.get(m.runId) ?? this.children.get(m.runId);
         if (!parent || parent.ref.sessionKey !== m.key)
             return false;
@@ -98,10 +109,7 @@ export class Delegations {
                 throw new HelperError('session', `refused: "${String(m.input.sessionKey ?? agent)}" is not a helper session`);
             throw new Error('delegation target or mode refused');
         }
-        for (const [id, p] of this.pending)
-            if (p.expires < Date.now())
-                this.pending.delete(id);
-        if (this.pending.size + this.children.size >= 1024)
+        if (this.full())
             throw new Error('delegated run journal is full');
         this.pending.set(actionKey(m), { parent: structuredClone(parent), agent: agent,
             ...(send ? { key: m.input.sessionKey } : {}), ...(helper !== undefined ? { helper } : {}), expires: Date.now() + 60_000 });
@@ -171,6 +179,11 @@ export class Delegations {
         }
         return grant;
     }
+    /** The persona of the admitted helper child on this exact key and run, as its own run would carry it (5.8.3). */
+    async persona(key, runId) {
+        const helper = (await this.resolve(key, runId))?.ref;
+        return helper?.helper === undefined ? undefined : this.o.helper(helper.member, helper.helper).persona;
+    }
     bound(member, helper, agent) {
         try {
             return this.o.helper(member, helper).agentId === agent;
@@ -223,12 +236,25 @@ export class Delegations {
         this.o.revoke(grant.ref.sessionKey, grant.ref.runId);
         this.o.emit({ type: 'ended', run: structuredClone(grant.ref), ...end });
     }
+    // An exact recorded run the engine finished ends as it ended. One the engine no longer knows (no job, no queued turn,
+    // no live run, as after an engine restart: a plain `timeout` in the `queue` phase that never reached a provider) ends
+    // `lost`. A live or queued run stays admitted; a run whose wait fails stays for the next reconcile.
     async reconcile() {
         for (const ref of this.list()) {
-            const end = await this.o.request('agent.wait', { runId: ref.runId, timeoutMs: 1 });
+            let end;
+            try {
+                end = await this.o.request('agent.wait', { runId: ref.runId, timeoutMs: 1 });
+            }
+            catch {
+                continue;
+            }
             const grant = this.children.get(ref.runId);
-            if (grant && ['ok', 'error'].includes(end.status ?? ''))
+            if (!grant)
+                continue;
+            if (end.status === 'ok' || end.status === 'error')
                 this.end(grant, { reason: end.status === 'ok' ? 'terminal' : 'error' });
+            else if (end.status === 'timeout' && end.timeoutPhase === 'queue' && end.providerStarted === false)
+                this.end(grant, { reason: 'lost' });
         }
     }
     async abort(key) {

package/dist/testing/fake-gateway.js

@@ -329,6 +329,12 @@ export function fakeGateway(script, o) {
         setTimeout(() => {
             void (async () => {
                 const table = bridgeSock ? pluginTable(bridgeSock) : undefined;
+                // As the plugin's prompt hook: a child on a helper key asks the kit for its helper's persona (5.8.3).
+                if (child && bridgeSock && /^agent:[^:]+:h-[a-z][a-z0-9-]{0,15}:/.test(run.sessionKey)) {
+                    const reply = await bridgeRequest(bridgeSock, { kind: 'delegation-persona', key: run.sessionKey, runId: run.runId }).catch(() => ({}));
+                    calls.push({ method: 'before_prompt_build', params: { sessionKey: run.sessionKey, runId: run.runId,
+                            ...(typeof reply.persona === 'string' ? { appendSystemContext: reply.persona } : {}) } });
+                }
                 let n = 0;
                 for (const call of toolCalls(message)) {
                     const toolCallId = `call-${++n}`;
@@ -688,14 +694,18 @@ export function fakeGateway(script, o) {
             return { status: 'cancelled' };
         },
         agent: (p, bridgeSock) => startRun(p, bridgeSock),
-        'agent.wait': (p) => new Promise((resolve, reject) => {
-            const run = runs.get(String(p.runId));
+        // The pin: a run it never had (or forgot, as after a restart) waits out as a `timeout` in the `queue` phase that never
+        // reached a provider; a live run past `timeoutMs` is a `timeout` while it drains.
+        'agent.wait': (p) => new Promise((resolve) => {
+            const runId = String(p.runId);
+            const run = runs.get(runId);
             if (!run)
-                return reject(new Error(`unknown run: ${p.runId}`));
+                return resolve({ runId, status: 'timeout', timeoutPhase: 'queue', providerStarted: false });
             if (run.result)
-                resolve(run.result);
-            else
-                run.waiters.push(resolve);
+                return resolve(run.result);
+            run.waiters.push(resolve);
+            if (typeof p.timeoutMs === 'number')
+                setTimeout(() => resolve({ runId, status: 'timeout', timeoutPhase: 'gateway_draining' }), p.timeoutMs).unref();
         }),
         'sessions.steer': () => ({}),
         // The pin: a key the agent holds answers its canonical key; a missing one errors unless `allowMissing`, which answers `{ ok: false }`.

package/dist/types.d.ts

@@ -46,12 +46,13 @@ export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' |
     tools: string[];
 };
 /** A delegated child's lifecycle (5.8.3 S3): `admitted`, its engine `event`s, then one `ended` whose `reason` is
- * `terminal` (finished), `error` (`message`), `resting` (its helper's account hit its limit and rests `until`) or
- * `cancelled` (aborted by the kit or the engine, or its admission ended). */
+ * `terminal` (finished), `error` (`message`), `resting` (its helper's account hit its limit and rests `until`),
+ * `cancelled` (aborted by the kit or the engine, or its admission ended) or `lost` (the engine no longer knows the run,
+ * as after an engine restart: outcome unknown, admission ended). */
 export type DelegatedEvent = {
     type: 'admitted' | 'event' | 'ended';
     run: DelegatedRun;
-    reason?: 'terminal' | 'error' | 'resting' | 'cancelled';
+    reason?: 'terminal' | 'error' | 'resting' | 'cancelled' | 'lost';
     until?: number;
     message?: string;
     event?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",

package/plugin/index.js

@@ -159,6 +159,17 @@ export default {
         callId: ctx?.toolCallId ?? event.toolCallId,
         result: { details: d && { status: d.status, runId: d.runId, sessionKey: d.sessionKey, childSessionKey: d.childSessionKey } } });
     });
+    // A native send carries no system text: an admitted helper child gets its helper's persona from the kit (5.8.3).
+    // Any other run, or no answer, adds nothing; the persona is the helper's voice, never a grant.
+    api.on('before_prompt_build', async (_event, ctx) => {
+      const key = ctx?.sessionKey;
+      if (typeof key !== 'string' || !/^agent:[^:]+:h-[a-z][a-z0-9-]{0,15}:/.test(key)) return undefined;
+      try {
+        const reply = await bridgeRequest({ kind: 'delegation-persona', key, runId: ctx?.runId }, { timeoutMs: 10_000 });
+        if (typeof reply?.persona === 'string' && reply.persona) return { appendSystemContext: reply.persona };
+      } catch { /* no kit: nothing added */ }
+      return undefined;
+    });
     api.registerAgentEventSubscription?.({ id: 'byokit-delegated-events', handle(event) {
       if (!['assistant', 'tool', 'thinking', 'lifecycle'].includes(event.stream)) return;
       const data = Object.fromEntries(['text', 'name', 'phase', 'toolCallId', 'isError', 'progressTokens', 'aborted', 'error', 'provider', 'model']
@@ -281,6 +292,12 @@ export default {
             callId: ctx?.toolCallId ?? event.toolCallId, tool: event.toolName, input: params });
           if (prepared.allow === false) return { block: true, blockReason: prepared.reason };
         } catch { return { block: true, blockReason: 'delegation admission unavailable' }; }
+        // A tracked spawn into the run's own agent goes without `agentId`, the engine's own-agent spawn, so an app's
+        // `subagents.allowAgents` list for other agents never refuses it. The kit already admitted that exact agent.
+        // Hook params merge over the model's, so the key is overridden, not left out.
+        const own = ctx?.agentId ?? /^agent:([^:]+):/.exec(key)?.[1];
+        if (event.toolName === 'sessions_spawn' && typeof own === 'string' && params.agentId === own)
+          return { params: { ...params, agentId: undefined } };
       }
       if (builtin) return BROWSER && event.toolName === 'browser' ? { params } : undefined;
       // The bridge mints a permit for permitted tools and admits the rest ticket-side; either way the run key