pikiloom 0.4.38 → 0.4.40

package/packages/kernel/dist/drivers/claude.d.ts

@@ -1,5 +1,5 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec } from '../contracts/driver.js';
-import type { UniversalPlan } from '../protocol/index.js';
+import type { UniversalUsage, UniversalPlan } from '../protocol/index.js';
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -14,6 +14,17 @@ export declare class ClaudeDriver implements AgentDriver {
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     private usage;
 }
+export interface ClaudeUsageState {
+    input: number | null;
+    output: number | null;
+    cached: number | null;
+    cacheCreation?: number | null;
+    contextWindow?: number | null;
+    turnOutputTokensBase?: number | null;
+}
+export declare function claudeUsageOf(s: ClaudeUsageState): UniversalUsage;
+export declare function claudeContextWindowFromModel(model: unknown): number | null;
+export declare function claudeEffectiveContextWindow(advertised: number | null): number | null;
 export declare function handleClaudeEvent(ev: any, s: any, emit: (e: DriverEvent) => void): void;
 export declare function claudeUserMessage(text: string): string;
 export declare function emitClaudeImages(blocks: any[], s: any, emit: (e: DriverEvent) => void): void;

package/packages/kernel/dist/drivers/claude.js

@@ -46,6 +46,8 @@ export class ClaudeDriver {
             sessionId: null, model: null,
             stopReason: null, error: null,
             input: null, output: null, cached: null,
+            cacheCreation: null,
+            contextWindow: null, turnOutputTokensBase: 0,
             subAgents: new Map(),
             tools: new Map(),
         };
@@ -141,9 +143,45 @@ export class ClaudeDriver {
         });
     }
     usage(s) {
-        return { inputTokens: s.input, outputTokens: s.output, cachedInputTokens: s.cached, contextPercent: null };
+        return claudeUsageOf(s);
     }
 }
+export function claudeUsageOf(s) {
+    const used = (s.input ?? 0) + (s.cached ?? 0) + (s.cacheCreation ?? 0) + (s.output ?? 0);
+    const window = s.contextWindow ?? null;
+    const contextPercent = window && used > 0 ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
+    const turnOutput = (s.turnOutputTokensBase ?? 0) + (s.output ?? 0);
+    return {
+        inputTokens: s.input,
+        outputTokens: s.output,
+        cachedInputTokens: s.cached,
+        contextUsedTokens: used > 0 ? used : null,
+        contextPercent,
+        turnOutputTokens: turnOutput > 0 ? turnOutput : null,
+    };
+}
+// Advertised context window by Claude model id (best-effort; unknown -> null so the
+// percent simply stays absent rather than wrong). Anchor-free so vendor-prefixed ids
+// (us.anthropic.claude-…) still match.
+export function claudeContextWindowFromModel(model) {
+    const id = String(model ?? '').trim().toLowerCase();
+    if (!id)
+        return null;
+    if (id === 'haiku' || /claude-haiku-/.test(id))
+        return 200_000;
+    if (id === 'opus' || id === 'sonnet' || id === 'fable')
+        return 1_000_000;
+    if (/claude-(opus|sonnet)-/.test(id) || /claude-fable-/.test(id))
+        return 1_000_000;
+    return null;
+}
+// Usable window = advertised minus Claude's max-output (20k) + autocompact (13k) reserve.
+const CLAUDE_USABLE_WINDOW_RESERVE = 33_000;
+export function claudeEffectiveContextWindow(advertised) {
+    if (advertised == null)
+        return null;
+    return advertised <= CLAUDE_USABLE_WINDOW_RESERVE ? advertised : advertised - CLAUDE_USABLE_WINDOW_RESERVE;
+}
 // Parse one claude stream-json event into kernel DriverEvents (pure + exported for
 // hermetic testing). Faithful to pikiloom's claudeParse shapes.
 export function handleClaudeEvent(ev, s, emit) {
@@ -178,15 +216,37 @@ export function handleClaudeEvent(ev, s, emit) {
             emit({ type: 'session', sessionId: ev.session_id });
         }
         s.model = ev.model ?? s.model;
+        s.contextWindow = claudeEffectiveContextWindow(claudeContextWindowFromModel(s.model)) ?? s.contextWindow;
         return;
     }
     if (t === 'stream_event') {
         const inner = ev.event || {};
         if (inner.type === 'message_start') {
             const u = inner.message?.usage;
-            if (u) {
-                s.input = u.input_tokens ?? s.input;
-                s.cached = u.cache_read_input_tokens ?? s.cached;
+            // Claude emits one message per tool-use round within a single turn. Carry the prior
+            // message's output into the per-turn base, then reset to the new message's prompt size
+            // so contextUsedTokens tracks current occupancy while turnOutputTokens sums the turn.
+            s.turnOutputTokensBase = (s.turnOutputTokensBase ?? 0) + (s.output ?? 0);
+            s.input = u?.input_tokens ?? 0;
+            s.cached = u?.cache_read_input_tokens ?? 0;
+            s.cacheCreation = u?.cache_creation_input_tokens ?? 0;
+            s.output = 0;
+        }
+        else if (inner.type === 'content_block_start') {
+            // Claude emits multiple text/thinking blocks per turn (one set per tool-use round). Insert a
+            // paragraph break before a NEW block when prior content exists, so the live preview shows
+            // breaks between segments instead of running them together. Mirrors the legacy driver; the
+            // separator is emitted as a delta so the runtime's accumulated snapshot stays in sync with s.
+            const bt = inner.content_block?.type;
+            if (bt === 'text' && s.text && !s.text.endsWith('\n\n')) {
+                const sep = s.text.endsWith('\n') ? '\n' : '\n\n';
+                s.text += sep;
+                emit({ type: 'text', delta: sep });
+            }
+            else if (bt === 'thinking' && s.reasoning && !s.reasoning.endsWith('\n\n')) {
+                const sep = s.reasoning.endsWith('\n') ? '\n' : '\n\n';
+                s.reasoning += sep;
+                emit({ type: 'reasoning', delta: sep });
             }
         }
         else if (inner.type === 'content_block_delta') {
@@ -211,7 +271,9 @@ export function handleClaudeEvent(ev, s, emit) {
                     s.input = u.input_tokens;
                 if (u.cache_read_input_tokens != null)
                     s.cached = u.cache_read_input_tokens;
-                emit({ type: 'usage', usage: { inputTokens: s.input, outputTokens: s.output, cachedInputTokens: s.cached, contextPercent: null } });
+                if (u.cache_creation_input_tokens != null)
+                    s.cacheCreation = u.cache_creation_input_tokens;
+                emit({ type: 'usage', usage: claudeUsageOf(s) });
             }
             if (inner.delta?.stop_reason)
                 s.stopReason = inner.delta.stop_reason;
@@ -312,6 +374,8 @@ export function handleClaudeEvent(ev, s, emit) {
             const cached = u.cache_read_input_tokens ?? u.cached_input_tokens;
             if (s.cached == null && cached != null)
                 s.cached = cached;
+            if (s.cacheCreation == null && u.cache_creation_input_tokens != null)
+                s.cacheCreation = u.cache_creation_input_tokens;
         }
         return;
     }

package/packages/kernel/dist/drivers/codex.d.ts

@@ -1,4 +1,22 @@
-import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { UniversalUsage } from '../protocol/index.js';
+export declare function codexToolSummary(item: any): {
+    id: string;
+    name: string;
+    summary: string;
+} | null;
+export interface CodexContentState {
+    text: string;
+    reasoning: string;
+    streamedReasoning: boolean;
+    msgs: string[];
+    thinkParts: string[];
+}
+export declare function codexReasoningItemText(item: any): string;
+export declare function captureCodexAgentMessage(item: any, s: CodexContentState, deltaItems: Set<string>, phases: Map<string, string>, emit: (e: DriverEvent) => void): void;
+export declare function captureCodexReasoning(text: string, s: CodexContentState, emit: (e: DriverEvent) => void): void;
+export declare function codexFinalText(s: CodexContentState): string;
+export declare function codexFinalReasoning(s: CodexContentState): string;
 export declare class CodexDriver implements AgentDriver {
     private readonly bin;
     readonly id = "codex";
@@ -12,3 +30,12 @@ export declare class CodexDriver implements AgentDriver {
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui(input: TuiInput): TuiSpec;
 }
+export interface CodexUsageState {
+    input: number | null;
+    output: number | null;
+    cached: number | null;
+    contextUsed?: number | null;
+    contextWindow?: number | null;
+}
+export declare function applyCodexTokenUsage(s: CodexUsageState, rawUsage: any): void;
+export declare function codexUsageOf(s: CodexUsageState): UniversalUsage;

package/packages/kernel/dist/drivers/codex.js

@@ -20,7 +20,12 @@ class AppServer {
     onServerRequest(cb) { this.requestResponder = cb; }
     async start() {
         const args = ['app-server'];
-        const overrides = this.configOverrides.some(c => /^features\.goals\s*=/.test(c)) ? this.configOverrides : [...this.configOverrides, 'features.goals=true'];
+        // Do NOT force model_reasoning_summary — codex reasoning summaries stay OFF by default
+        // (respecting ~/.codex/config.toml, which is the original behavior). A caller that wants
+        // thinking can pass `model_reasoning_summary=...` via configOverrides; we never inject it.
+        const overrides = [...this.configOverrides];
+        if (!overrides.some(c => /^features\.goals\s*=/.test(c)))
+            overrides.push('features.goals=true');
         for (const c of overrides)
             args.push('-c', c);
         try {
@@ -126,7 +131,12 @@ function codexFileChangeSummary(item) {
 }
 // Normalize a codex app-server item -> {id, name, summary}. The summary mirrors pikiloom's
 // vocabulary ("Run shell: <cmd>", "Edit <path>") so the activity projection reads naturally.
-function codexToolSummary(item) {
+// Only ACTUAL tool calls become Activity rows. agentMessage (the answer text) and reasoning
+// (thinking) are CONTENT — they render below as message text / thinking, never as tools. The old
+// fallback to `item.type` wrongly turned every item (incl. agentMessage/reasoning) into a bogus
+// "tool" in the Activity card. Mirrors the legacy driver's isCodexToolCallItem whitelist.
+const CODEX_TOOL_CALL_TYPES = new Set(['dynamicToolCall', 'mcpToolCall', 'collabAgentToolCall']);
+export function codexToolSummary(item) {
     const id = String(item?.id || '');
     if (!id)
         return null;
@@ -136,8 +146,13 @@ function codexToolSummary(item) {
     }
     if (item.type === 'fileChange' || item.type === 'patch')
         return { id, name: 'edit', summary: codexFileChangeSummary(item) };
-    const tool = typeof item?.tool === 'string' ? item.tool : typeof item?.name === 'string' ? item.name : item?.type;
-    return tool ? { id, name: String(tool), summary: String(tool) } : null;
+    if (CODEX_TOOL_CALL_TYPES.has(item.type)) {
+        const raw = typeof item.tool === 'string' && item.tool.trim() ? item.tool.trim()
+            : typeof item.name === 'string' && item.name.trim() ? item.name.trim() : '';
+        const name = raw ? (raw.split('.').pop() || raw) : 'tool';
+        return { id, name, summary: raw ? `Use ${name}` : 'Use tool' };
+    }
+    return null;
 }
 // codex `item/tool/requestUserInput` params -> a normalized UniversalInteraction
 // (faithful to the legacy codex driver's toAgentInteraction shape).
@@ -160,6 +175,51 @@ function codexUserInputToInteraction(params, promptId) {
         return null;
     return { promptId, kind: 'user-input', title: 'User Input Required', hint: 'Use the buttons when available, or reply with text.', questions };
 }
+// Reasoning text from a completed `reasoning` item (item/completed or rawResponseItem/completed):
+// summary/content arrays of plain strings or {text} objects.
+export function codexReasoningItemText(item) {
+    const parts = [
+        ...(Array.isArray(item?.summary) ? item.summary : []),
+        ...(Array.isArray(item?.content) ? item.content : []),
+    ];
+    return parts.map((p) => (typeof p === 'string' ? p : p?.text || '')).filter(Boolean).join('\n').trim();
+}
+// A completed final_answer agentMessage that did NOT stream deltas: append + emit it live.
+// deltaItems holds the ids already streamed, so a completed item echoing a streamed one is
+// not double-counted (matches the legacy driver's deltaSeenForItem guard).
+export function captureCodexAgentMessage(item, s, deltaItems, phases, emit) {
+    const phase = item?.phase || (item?.id ? phases.get(item.id) : null) || 'final_answer';
+    if (phase !== 'final_answer')
+        return;
+    const text = typeof item?.text === 'string' ? item.text.trim() : '';
+    if (!text)
+        return;
+    s.msgs.push(text);
+    if (item.id && deltaItems.has(item.id))
+        return;
+    const delta = s.text.trim() ? `\n\n${text}` : text;
+    s.text += delta;
+    emit({ type: 'text', delta });
+}
+// A completed reasoning item: keep it for the end-of-turn fallback, and stream it live only
+// when nothing arrived as reasoning deltas (so the streamed path is never double-emitted).
+export function captureCodexReasoning(text, s, emit) {
+    if (!text)
+        return;
+    s.thinkParts.push(text);
+    if (s.streamedReasoning)
+        return;
+    const delta = s.reasoning.trim() ? `\n\n${text}` : text;
+    s.reasoning += delta;
+    emit({ type: 'reasoning', delta });
+}
+// End-of-turn finalizers: prefer streamed text/reasoning, fall back to completed-item parts.
+export function codexFinalText(s) {
+    return s.text.trim() ? s.text : s.msgs.join('\n\n');
+}
+export function codexFinalReasoning(s) {
+    return s.reasoning.trim() ? s.reasoning : s.thinkParts.join('\n\n');
+}
 export class CodexDriver {
     bin;
     id = 'codex';
@@ -173,9 +233,10 @@ export class CodexDriver {
         // to the native account.
         const config = [...(input.configOverrides || [])];
         const srv = new AppServer(this.bin, config, input.env);
-        const state = { text: '', reasoning: '', sessionId: input.sessionId ?? null, input: null, output: null, cached: null, status: null, error: null, turnId: null };
+        const state = { text: '', reasoning: '', streamedReasoning: false, msgs: [], thinkParts: [], sessionId: input.sessionId ?? null, input: null, output: null, cached: null, contextUsed: null, contextWindow: null, status: null, error: null, turnId: null };
         const phases = new Map();
         const toolSummaries = new Map();
+        const deltaItems = new Set();
         let steerRegistered = false;
         const ok = await srv.start();
         if (!ok)
@@ -239,6 +300,8 @@ export class CodexDriver {
                         const phase = params?.itemId ? (phases.get(params.itemId) || 'final_answer') : 'final_answer';
                         if (phase === 'final_answer' && params?.delta) {
                             state.text += params.delta;
+                            if (params.itemId)
+                                deltaItems.add(params.itemId);
                             ctx.emit({ type: 'text', delta: params.delta });
                         }
                         break;
@@ -247,16 +310,28 @@ export class CodexDriver {
                     case 'item/reasoning/summaryTextDelta':
                         if (params?.delta) {
                             state.reasoning += params.delta;
+                            state.streamedReasoning = true;
                             ctx.emit({ type: 'reasoning', delta: params.delta });
                         }
                         break;
                     case 'item/completed': {
                         const item = params?.item || {};
+                        // Final answer / reasoning delivered as a completed item (no preceding deltas).
+                        if (item.type === 'agentMessage')
+                            captureCodexAgentMessage(item, state, deltaItems, phases, ctx.emit);
+                        else if (item.type === 'reasoning')
+                            captureCodexReasoning(codexReasoningItemText(item), state, ctx.emit);
                         const t = codexToolSummary(item);
                         if (t && toolSummaries.has(t.id))
                             ctx.emit({ type: 'tool', call: { id: t.id, name: t.name, summary: toolSummaries.get(t.id) || t.summary, status: item.status === 'failed' ? 'failed' : 'done' } });
                         break;
                     }
+                    case 'rawResponseItem/completed': {
+                        const item = params?.item || {};
+                        if (item?.type === 'reasoning')
+                            captureCodexReasoning(codexReasoningItemText(item), state, ctx.emit);
+                        break;
+                    }
                     case 'turn/plan/updated': {
                         const plan = planFromUpdate(params);
                         if (plan)
@@ -264,14 +339,8 @@ export class CodexDriver {
                         break;
                     }
                     case 'thread/tokenUsage/updated': {
-                        const u = params?.tokenUsage || params?.usage || {};
-                        if (u.input_tokens != null || u.inputTokens != null)
-                            state.input = u.input_tokens ?? u.inputTokens;
-                        if (u.output_tokens != null || u.outputTokens != null)
-                            state.output = u.output_tokens ?? u.outputTokens;
-                        if (u.cached_input_tokens != null || u.cachedInputTokens != null)
-                            state.cached = u.cached_input_tokens ?? u.cachedInputTokens;
-                        ctx.emit({ type: 'usage', usage: { inputTokens: state.input, outputTokens: state.output, cachedInputTokens: state.cached, contextPercent: null } });
+                        applyCodexTokenUsage(state, params?.tokenUsage || params?.usage);
+                        ctx.emit({ type: 'usage', usage: codexUsageOf(state) });
                         break;
                     }
                     case 'turn/completed': {
@@ -279,6 +348,8 @@ export class CodexDriver {
                         state.status = turn.status ?? 'completed';
                         if (turn.error)
                             state.error = turn.error.message || turn.error.code || 'turn error';
+                        applyCodexTokenUsage(state, params?.tokenUsage || turn.tokenUsage || turn.usage);
+                        ctx.emit({ type: 'usage', usage: codexUsageOf(state) });
                         settle();
                         break;
                     }
@@ -309,12 +380,13 @@ export class CodexDriver {
             if (turnResp.error)
                 return { ok: false, text: state.text, error: turnResp.error.message || 'turn/start failed', stopReason: 'error', sessionId: state.sessionId };
             await turnDone;
-            const usage = { inputTokens: state.input, outputTokens: state.output, cachedInputTokens: state.cached, contextPercent: null };
+            const usage = codexUsageOf(state);
             const ok2 = (state.status === 'completed' || state.status == null) && !state.error && !ctx.signal.aborted;
+            const finalReasoning = codexFinalReasoning(state);
             return {
                 ok: ok2,
-                text: state.text,
-                reasoning: state.reasoning || undefined,
+                text: codexFinalText(state),
+                reasoning: finalReasoning || undefined,
                 error: state.error || (ctx.signal.aborted ? 'Interrupted by user.' : null),
                 stopReason: ctx.signal.aborted ? 'interrupted' : (state.status || 'end_turn'),
                 sessionId: state.sessionId,
@@ -344,3 +416,76 @@ function buildTurnInput(prompt, attachments) {
     input.push({ type: 'text', text: prompt });
     return input;
 }
+function codexNum(...vals) {
+    for (const v of vals) {
+        const n = typeof v === 'number' ? v : Number(v);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return null;
+}
+// Context occupancy from one usage record: prefer total_tokens, else input(+output).
+function codexContextUsed(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const total = codexNum(raw.total_tokens, raw.totalTokens);
+    if (total != null && total >= 0)
+        return total;
+    const i = codexNum(raw.input_tokens, raw.inputTokens);
+    const o = codexNum(raw.output_tokens, raw.outputTokens);
+    if (i != null && o != null)
+        return i + o;
+    return i;
+}
+// Fold a codex tokenUsage payload into driver state: last-turn counts, context
+// occupancy, and the model window. Tolerant of nested {info:{…}} and flat shapes.
+export function applyCodexTokenUsage(s, rawUsage) {
+    if (!rawUsage || typeof rawUsage !== 'object')
+        return;
+    const info = rawUsage.info && typeof rawUsage.info === 'object' ? rawUsage.info : rawUsage;
+    const last = info.last ?? info.lastTokenUsage ?? info.last_token_usage ?? rawUsage.last;
+    const li = codexNum(last?.input_tokens, last?.inputTokens);
+    const lo = codexNum(last?.output_tokens, last?.outputTokens);
+    const lc = codexNum(last?.cached_input_tokens, last?.cachedInputTokens);
+    if (li != null)
+        s.input = li;
+    if (lo != null)
+        s.output = lo;
+    if (lc != null)
+        s.cached = lc;
+    const used = codexContextUsed(last);
+    if (used != null)
+        s.contextUsed = used;
+    // Cumulative total as fallback for the per-turn counts (the trailing `?? rawUsage`
+    // also catches the flat shape, where there is no nested `last`).
+    const total = info.total ?? info.totalTokenUsage ?? info.total_token_usage ?? rawUsage.total ?? rawUsage;
+    if (total && typeof total === 'object') {
+        const ti = codexNum(total.input_tokens, total.inputTokens);
+        const to = codexNum(total.output_tokens, total.outputTokens);
+        const tc = codexNum(total.cached_input_tokens, total.cachedInputTokens);
+        if (li == null && ti != null)
+            s.input = ti;
+        if (lo == null && to != null)
+            s.output = to;
+        if (lc == null && tc != null)
+            s.cached = tc;
+    }
+    const cw = codexNum(info.modelContextWindow, info.model_context_window, rawUsage.modelContextWindow, rawUsage.model_context_window);
+    if (cw != null && cw > 0)
+        s.contextWindow = cw;
+}
+export function codexUsageOf(s) {
+    const fallback = (s.input ?? 0) + (s.cached ?? 0);
+    const used = s.contextUsed ?? (fallback > 0 ? fallback : null);
+    const window = s.contextWindow ?? null;
+    const contextPercent = used != null && window ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
+    const turnOutput = s.output ?? 0;
+    return {
+        inputTokens: s.input,
+        outputTokens: s.output,
+        cachedInputTokens: s.cached,
+        contextUsedTokens: used,
+        contextPercent,
+        turnOutputTokens: turnOutput > 0 ? turnOutput : null,
+    };
+}

package/packages/kernel/dist/index.d.ts

@@ -6,7 +6,7 @@ export { PtyBridge, ptyAvailable, type PtyExit, type PtyOpenOpts } from './runti
 export { attachTui, type AttachTuiOptions } from './runtime/tui.js';
 export type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, SteerFn, McpServerSpec, TuiInput, TuiSpec, } from './contracts/driver.js';
 export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog, } from './contracts/ports.js';
-export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, } from './contracts/surface.js';
+export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 export { EchoDriver } from './drivers/echo.js';
 export { ClaudeDriver } from './drivers/claude.js';

package/packages/kernel/dist/runtime/hub.d.ts

@@ -49,6 +49,9 @@ export declare class Hub implements LoomIO {
     private queueView;
     private publishQueued;
     private collectTools;
+    private mergeSpawn;
+    private pluginSpawn;
+    private composeSystemPrompt;
     private onRunnerUpdate;
     stop(sessionKey: string): boolean;
     steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;

package/packages/kernel/dist/runtime/hub.js

@@ -45,7 +45,11 @@ export class Hub {
             throw new Error(`Driver "${agent}" does not support TUI mode`);
         const workdir = opts.workdir || this.deps.workdir;
         const injection = await this.deps.modelResolver.resolve(agent, { model: opts.model, profileId: null }).catch(() => null);
-        return driver.tui({ workdir, model: injection?.model ?? opts.model ?? null, sessionId: opts.sessionId ?? null, env: injection?.env });
+        const model = injection?.model ?? opts.model ?? null;
+        // Same merge as run(), so the raw-PTY rail also gets plugin env/args (e.g. a hijack redirect).
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'tui', opts.sessionId ?? null, model);
+        const spawn = this.mergeSpawn([{ env: injection?.env, extraArgs: injection?.extraArgs }, ...pluginParts]);
+        return driver.tui({ workdir, model, sessionId: opts.sessionId ?? null, env: spawn.env, extraArgs: spawn.extraArgs });
     }
     async prompt(input) {
         const agent = (input.agent || this.deps.defaultAgent || '').trim();
@@ -98,20 +102,28 @@ export class Hub {
         // prior turn's native session id and any refreshed credentials/tools.
         const rec = await this.deps.sessionStore.get(agent, sessionId);
         const injection = await this.deps.modelResolver.resolve(agent, { model: input.model, profileId: null }).catch(() => null);
-        const tools = await this.collectTools(agent, workdir, workspacePath);
         const model = injection?.model ?? input.model ?? null;
         const effort = input.effort ?? null;
-        const systemPrompt = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn: !preExisted });
+        const tools = await this.collectTools(agent, workdir, workspacePath);
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'run', sessionId, model);
+        // precedence: ModelResolver (model/creds) -> ToolProvider.env -> plugins (last, so a
+        // model-traffic hijack plugin can override the resolver's base URL).
+        const spawn = this.mergeSpawn([
+            { env: injection?.env, extraArgs: injection?.extraArgs, configOverrides: injection?.configOverrides },
+            { env: tools.env },
+            ...pluginParts,
+        ]);
+        const systemPrompt = await this.composeSystemPrompt(agent, workdir, !preExisted);
         const turnInput = {
             prompt: input.prompt,
             attachments: input.attachments,
             sessionId: rec?.nativeSessionId || (input.sessionKey ? sessionId : null),
             workdir,
             model, effort, systemPrompt,
-            env: injection?.env,
-            extraArgs: injection?.extraArgs, // BYOK flags from the ModelResolver
-            configOverrides: injection?.configOverrides, // codex BYOK -c routing
-            extraMcpServers: tools,
+            env: spawn.env,
+            extraArgs: spawn.extraArgs,
+            configOverrides: spawn.configOverrides,
+            extraMcpServers: tools.servers,
         };
         runner.run(driver, turnInput, input.prompt, model, effort)
             .then(async (result) => {
@@ -154,11 +166,16 @@ export class Hub {
         if (entry?.runner)
             this.onRunnerUpdate(sessionKey, entry.runner.snapshot, entry.runner.currentSeq);
     }
+    // MCP servers (ToolProvider + each plugin) PLUS the ToolProvider's session env (previously
+    // dropped) — surfaced so the spawn env merge can apply it.
     async collectTools(agent, workdir, workspacePath) {
-        const out = [];
+        const servers = [];
+        let env;
         try {
             const base = await this.deps.toolProvider.provideForSession({ agent, workdir, workspacePath });
-            out.push(...base.servers);
+            servers.push(...base.servers);
+            if (base.env && Object.keys(base.env).length)
+                env = base.env;
         }
         catch (e) {
             this.deps.log?.(`[hub] toolProvider failed: ${e?.message || e}`);
@@ -167,14 +184,71 @@ export class Hub {
             if (!plugin.tools)
                 continue;
             try {
-                out.push(...(await plugin.tools({ agent, workdir })));
+                servers.push(...(await plugin.tools({ agent, workdir })));
             }
             catch (e) {
                 this.deps.log?.(`[hub] plugin ${plugin.id} tools failed: ${e?.message || e}`);
             }
         }
+        return { servers, env };
+    }
+    // Merge ordered spawn contributions: env keys later-wins, extraArgs/configOverrides concatenate.
+    // Callers order parts [ModelResolver, ToolProvider.env, ...plugins] so a plugin (e.g. a model-
+    // traffic hijack) can override the resolver's base URL. Never touches global process.env.
+    mergeSpawn(parts) {
+        let env;
+        const extraArgs = [];
+        const configOverrides = [];
+        for (const p of parts) {
+            if (!p)
+                continue;
+            if (p.env && Object.keys(p.env).length)
+                env = { ...(env || {}), ...p.env };
+            if (p.extraArgs?.length)
+                extraArgs.push(...p.extraArgs);
+            if (p.configOverrides?.length)
+                configOverrides.push(...p.configOverrides);
+        }
+        return { env, extraArgs: extraArgs.length ? extraArgs : undefined, configOverrides: configOverrides.length ? configOverrides : undefined };
+    }
+    async pluginSpawn(agent, workdir, mode, sessionId, model) {
+        const out = [];
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.contributeSpawn)
+                continue;
+            try {
+                const c = await plugin.contributeSpawn({ agent, workdir, mode, sessionId, model });
+                if (c)
+                    out.push(c);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} contributeSpawn failed: ${e?.message || e}`);
+            }
+        }
         return out;
     }
+    // Final system/developer prompt = the singular SystemPromptBuilder base + each plugin's
+    // promptFragment (in registration order), joined. Delivered via AgentTurnInput.systemPrompt,
+    // which each driver applies its own way (claude --append-system-prompt / codex / gemini).
+    async composeSystemPrompt(agent, workdir, isFirstTurn) {
+        const parts = [];
+        const base = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn });
+        if (base && base.trim())
+            parts.push(base);
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.promptFragment)
+                continue;
+            try {
+                const f = await plugin.promptFragment({ agent, workdir, isFirstTurn });
+                if (f && f.trim())
+                    parts.push(f);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} promptFragment failed: ${e?.message || e}`);
+            }
+        }
+        return parts.length ? parts.join('\n\n') : undefined;
+    }
     onRunnerUpdate(sessionKey, snapshot, _seq) {
         const entry = this.sessions.get(sessionKey);
         if (!entry)

package/packages/kernel/dist/runtime/loom.d.ts

@@ -28,6 +28,7 @@ export interface LoomConfig {
 export interface Loom {
     readonly io: LoomIO;
     registerDriver(driver: AgentDriver): void;
+    registerPlugin(plugin: Plugin): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     status(): {

package/packages/kernel/dist/runtime/loom.js

@@ -10,6 +10,8 @@ export function createLoom(config = {}) {
     for (const d of config.drivers || [])
         drivers.set(d.id, d);
     const defaultAgent = config.defaultAgent || config.drivers?.[0]?.id || 'echo';
+    // Held as a live reference so registerPlugin() mutates the same array the Hub iterates.
+    const plugins = [...(config.plugins || [])];
     const hub = new Hub({
         drivers,
         defaultAgent,
@@ -21,7 +23,7 @@ export function createLoom(config = {}) {
         catalog: config.catalog || new NoopCatalog(),
         interactionHandler: config.interactionHandler || new DeferToTerminalInteractionHandler(),
         serialPerSession: config.serialPerSession,
-        plugins: config.plugins || [],
+        plugins,
         systemPromptBase: config.systemPromptBase,
         log,
     });
@@ -36,6 +38,7 @@ export function createLoom(config = {}) {
     return {
         io: hub,
         registerDriver(driver) { drivers.set(driver.id, driver); },
+        registerPlugin(plugin) { plugins.push(plugin); },
         async start() {
             if (started)
                 return;