@byokit/openclaw 0.22.2 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## 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.
+
 ## 0.22.2 (2026-10-19)
 
 - Dependency update: pins @byokit/accounts 0.28.2.

package/README.md

@@ -131,7 +131,9 @@ API key (billed per use) entry still requires explicit selection; there is no su
 To choose the model for a run, pass `model: 'provider/model'` in the run spec (for example
 `'openai/gpt-5.1'`, where `provider` is an id `kit.providers(member)` lists). That provider is the one called and billed for this run only, with no fallback to another
 provider or model. If the member isn't signed in to it, the run ends `{ ok: false, kind: 'signed-out' }` and the
-engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
+engine is never called. A signed-out `claude-cli` run also carries `cause: { code: 'needs_cli_login', cli: 'claude', home, configDir?, signIn }`:
+with `signIn: true` offer `kit.signIn(member, { authChoice: 'anthropic-cli' })`, which runs the Claude Code login; with
+`signIn: false` ask the person to run `claude` on this machine to sign in. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
 To let the kit choose among a member's accounts, pass `account: 'auto'` (the account with the most room left, decided
@@ -441,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.
@@ -494,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
@@ -508,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/device.d.ts

@@ -4,7 +4,7 @@ import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
 import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, RunFrame, SignInView, AccountRef } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
-export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
+export type { Approval, CliLoginCause, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
 export type OpenClawLinkEvent = {
     [E in GatewayEventName]: {

package/dist/engine.d.ts

@@ -1,7 +1,7 @@
 import { remoteCliHost } from '@byokit/accounts/cli';
 import { AuthStore, AuthStoreSealSizeError } from './auth-store.ts';
 import type { KitOptions } from './kit.ts';
-import type { KitState, ToolSpec } from './types.ts';
+import type { CliLoginCause, KitState, ToolSpec } from './types.ts';
 /** The app's stateDir as an absolute path with no symlinked ancestor (macOS /tmp and /var are symlinks):
  * the native Claude login's accounts store refuses any other, so a relative or symlinked stateDir failed it. */
 export declare function canonicalStateDir(dir: string): string;
@@ -83,9 +83,10 @@ export declare class Engine {
     refreshInstalledClaudeLogin(): Promise<boolean>;
     /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin(): ReturnType<typeof remoteCliHost>;
-    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
-     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
-    claudeLoginUnread(): boolean;
+    /** Where a Claude Code login must be for this engine's gateway to read it. `signIn: false` when a fallback sign-in
+     * would write a folder the gateway does not read: it started on the person's login location (installed sign-in, or
+     * a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginCause(): CliLoginCause;
     resetNativeClaudeLogin(): Promise<void>;
     doctor(timeoutMs: number): {
         status: number | null;

package/dist/engine.js

@@ -528,9 +528,16 @@ export class Engine {
         this.claudeLogin = remoteCliHost({ cli, bins });
         return this.claudeLogin;
     }
-    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
-     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
-    claudeLoginUnread() { return Boolean(this.o.spawnEngine) && !this.claudeFallback; }
+    /** Where a Claude Code login must be for this engine's gateway to read it. `signIn: false` when a fallback sign-in
+     * would write a folder the gateway does not read: it started on the person's login location (installed sign-in, or
+     * a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginCause() {
+        if (this.o.spawnEngine && !this.claudeFallback) {
+            const { HOME, CLAUDE_CONFIG_DIR } = personal();
+            return { code: 'needs_cli_login', cli: 'claude', home: HOME, ...CLAUDE_CONFIG_DIR ? { configDir: CLAUDE_CONFIG_DIR } : {}, signIn: false };
+        }
+        return { code: 'needs_cli_login', cli: 'claude', home: join(this.root, 'home'), configDir: this.claudeFolder, signIn: true };
+    }
     resetNativeClaudeLogin() {
         if (this.claudeReset)
             return this.claudeReset;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, Helper, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, CliLoginCause, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, Helper, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';

package/dist/kit.js

@@ -1120,7 +1120,7 @@ export class OpenClawKit {
             ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455,
             nativeClaudeLogin: () => this.engine.nativeClaudeLogin(),
             resetNativeClaudeLogin: () => this.engine.resetNativeClaudeLogin(),
-            claudeLoginUnread: () => this.engine.claudeLoginUnread(),
+            claudeLogin: () => this.engine.claudeLoginCause(),
             onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; },
             stopSignal: this.engine.stopSignal,
             authConfig: () => this.authSnapshot(),
@@ -1387,6 +1387,7 @@ export class OpenClawKit {
             request: (method, params, o) => this.request()(method, params, o),
             authStatus: this.admission.read,
             invalidateAuth: this.admission.invalidate,
+            claudeLogin: () => this.engine.claudeLoginCause(),
             onEvent: (fn) => {
                 this.listeners.add(fn);
                 return () => {

package/dist/runs.d.ts

@@ -5,7 +5,7 @@ import type { createAccounts } from './accounts.ts';
 import type { createLocks } from './locks.ts';
 import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
-import type { GatewayTransport, Member, RunEnd, RunEvent, RunFrame, RunSpec } from './types.ts';
+import type { CliLoginCause, GatewayTransport, Member, RunEnd, RunEvent, RunFrame, RunSpec } from './types.ts';
 export declare const USABLE: Set<string>;
 /**
  * The providers a `models.authStatus` answer shows usable (the rule a picked account is checked by), lowercased and
@@ -35,6 +35,7 @@ export declare function createRuns(ctx: {
     request: GatewayTransport['request'];
     authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
     invalidateAuth?: () => void;
+    claudeLogin?: () => CliLoginCause;
     onEvent: GatewayTransport['onEvent'];
     ensure(member: Member): Promise<{
         agentId: string;

package/dist/runs.js

@@ -154,11 +154,14 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
-    const failure = (message) => {
+    // A signed-out claude-cli run names where its Claude Code login is missing (`cause`).
+    const cause = (provider) => provider === 'claude-cli' && ctx.claudeLogin ? { cause: ctx.claudeLogin() } : {};
+    const signedOut = (provider, message) => ({ ok: false, kind: 'signed-out', message, ...cause(provider) });
+    const failure = (message, provider) => {
         const classified = classify(message);
         if (classified.kind === 'signed-out')
             ctx.invalidateAuth?.();
-        return { ok: false, ...classified, message };
+        return { ok: false, ...classified, message, ...classified.kind === 'signed-out' ? cause(provider) : {} };
     };
     const execute = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request. A key
@@ -268,7 +271,7 @@ export function createRuns(ctx) {
                 try {
                     on?.({ type: 'account', account: pick.account.id, model: pick.model, sessionKey, how: pick.how, why: pick.why, considered: pick.considered });
                     if (!ready)
-                        return { ok: false, kind: 'signed-out', message: `${pick.account.name} is not signed in` };
+                        return signedOut(pick.account.provider, `${pick.account.name} is not signed in`);
                     return await start(spec, on, { agentId: agent, sessionKey, idempotencyKey, system,
                         picked: pick.model ? await accountOf(pick.model) : undefined, output, chosen: pick }); // '' = no override
                 }
@@ -359,7 +362,7 @@ export function createRuns(ctx) {
                     return { ok: false, kind: 'other', message: String(auth.unavailable.message ?? 'account status unavailable') };
                 const row = (auth.providers ?? []).find((e) => (typeof e === 'string' ? e : e?.provider) === picked.provider);
                 if (!row || !usable(row))
-                    return { ok: false, kind: 'signed-out', message: `${picked.provider} is not signed in for ${spec.member}` };
+                    return signedOut(picked.provider, `${picked.provider} is not signed in for ${spec.member}`);
             }
             // One `agent` request: its interim `accepted` frame names the run, its final frame (after the run) carries the
             // run's usage. The wait below still decides how the run ended. Thinking is clamped to the catalog before the
@@ -425,11 +428,11 @@ export function createRuns(ctx) {
                 return { ok: false, aborted: true };
             const message = typeof result.error === 'string' ? result.error
                 : typeof result.message === 'string' ? result.message : '';
-            return failure(message);
+            return failure(message, picked?.provider);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            return failure(message);
+            return failure(message, picked?.provider);
         }
         finally {
             ended = true;

package/dist/signin.d.ts

@@ -1,6 +1,6 @@
 import type { remoteCliHost } from '@byokit/accounts/cli';
 import { authStatus } from './auth-status.ts';
-import type { GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
+import type { CliLoginCause, GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
 export type SignInCtx = {
     request: GatewayTransport['request'];
     authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
@@ -10,7 +10,7 @@ export type SignInCtx = {
     callbackPort: number;
     nativeClaudeLogin?(): ReturnType<typeof remoteCliHost>;
     resetNativeClaudeLogin?(): Promise<void>;
-    claudeLoginUnread?(): boolean;
+    claudeLogin?(): CliLoginCause;
     onDisconnect?(fn: () => void): () => void;
     authConfig(): string;
     restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;

package/dist/signin.js

@@ -241,8 +241,9 @@ export function signIn(ctx, member, o, on) {
                 };
                 native = ctx.nativeClaudeLogin?.();
                 if (!await detected()) {
-                    if (ctx.claudeLoginUnread?.())
-                        return { state: 'failed', via, why: 'failed', error: 'Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.' };
+                    const cause = ctx.claudeLogin?.();
+                    if (cause?.signIn === false)
+                        return { state: 'failed', via, why: 'failed', error: 'Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.', cause };
                     if (!native)
                         return { state: 'failed', via, why: 'failed', error: 'Claude Code sign-in is not available on this engine.' };
                     let started = await native.start('claude', { signal });

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?: {
@@ -180,6 +181,18 @@ export type RunEnd<T = unknown> = {
     kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other' | 'output';
     until?: number;
     message: string;
+    cause?: CliLoginCause;
+};
+/** Why a `claude-cli` run or `anthropic-cli` sign-in failed: Claude Code has no login where this engine reads it (5.5).
+ * `signIn` true: `signIn(member, { authChoice: 'anthropic-cli' })` runs that login into `configDir` (subscription
+ * billing, the person's Claude plan). False: the engine reads the person's own login, which the kit never writes; the
+ * person runs `claude` on this machine, as `home`, to sign in (`configDir` only when they set CLAUDE_CONFIG_DIR). */
+export type CliLoginCause = {
+    code: 'needs_cli_login';
+    cli: 'claude';
+    home: string;
+    configDir?: string;
+    signIn: boolean;
 };
 export type SignInOptions = {
     authChoice: string;
@@ -196,6 +209,7 @@ export type SignInView = {
     prompt?: string;
     error?: string;
     why?: 'busy' | 'declined' | 'expired' | 'failed';
+    cause?: CliLoginCause;
 };
 export type Approval = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.22.2",
+  "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