@bubblebrain-ai/bubble 0.0.19 → 0.0.20

package/dist/agent/internal-reminder-sanitizer.d.ts

@@ -2,6 +2,7 @@ import type { AssistantProviderMetadata } from "../types.js";
 export declare function formatInternalReminderBlock(kind: string, content: string): string;
 export declare function formatInternalContextBlock(kind: string, content: string): string;
 export declare function sanitizeInternalReminderBlocks(text: string): string;
+export declare function sanitizeInternalReasoningText(text: string): string;
 export declare function sanitizeAssistantProviderMetadata(metadata: AssistantProviderMetadata | undefined): AssistantProviderMetadata | undefined;
 export declare function createStreamingInternalReminderSanitizer(): {
     push(delta: string): string;

package/dist/agent/internal-reminder-sanitizer.js

@@ -1,4 +1,5 @@
 const INTERNAL_TAG_PREFIX = "<bubble_internal_";
+const MEMORY_CITATION_TAG = "<oai-mem-citation";
 const INTERNAL_TAG_NAMES = ["reminder", "context"];
 const LEGACY_RUNTIME_MARKERS = [
     "Runtime reminder:\n",
@@ -6,6 +7,7 @@ const LEGACY_RUNTIME_MARKERS = [
 ];
 const STREAM_MARKERS = [
     INTERNAL_TAG_PREFIX,
+    MEMORY_CITATION_TAG,
     ...LEGACY_RUNTIME_MARKERS,
 ];
 const LEGACY_REMINDER_END_PHRASES = [
@@ -37,6 +39,15 @@ export function sanitizeInternalReminderBlocks(text) {
     const sanitizer = createStreamingInternalReminderSanitizer();
     return sanitizer.push(text) + sanitizer.flush();
 }
+export function sanitizeInternalReasoningText(text) {
+    const withoutBlocks = sanitizeInternalReminderBlocks(text);
+    if (!withoutBlocks)
+        return withoutBlocks;
+    return withoutBlocks
+        .split(/\n{2,}/)
+        .filter((paragraph) => !containsInternalReminderReference(paragraph))
+        .join("\n\n");
+}
 export function sanitizeAssistantProviderMetadata(metadata) {
     const anthropic = metadata?.anthropic;
     const blocks = anthropic?.contentBlocks;
@@ -119,10 +130,31 @@ function formatInternalBlock(type, kind, content) {
     const safeKind = kind.replace(/[^a-zA-Z0-9_-]/g, "-");
     return `<bubble_internal_${type} kind="${safeKind}">\n${content}\n</bubble_internal_${type}>`;
 }
+function containsInternalReminderReference(text) {
+    return INTERNAL_REASONING_REFERENCE_PATTERNS.some((pattern) => pattern.test(text));
+}
+const INTERNAL_REASONING_REFERENCE_PATTERNS = [
+    /<bubble_internal_(?:reminder|context)\b/i,
+    /\bsystem\s+reminder\b/i,
+    /\bruntime\s+reminder\b/i,
+    /\bsystem\s+prompt\b/i,
+    /The following deferred tools are available via tool_search/i,
+    /Known deferred tools/i,
+    /\bdeferred tools\b/i,
+    /\bmcp__[a-z0-9_]+/i,
+    /\bMCP\s+arxiv\s+tools\b/i,
+    /\barxiv\s+MCP\s+tools\b/i,
+    /Subagent lifecycle truth/i,
+    /Count unique agent_id values only/i,
+    /Do not describe a subagent as running or still working/i,
+];
 function consumeInternalBlockAtStart(text, final) {
     if (text.startsWith(INTERNAL_TAG_PREFIX)) {
         return consumeStructuredInternalBlock(text, final);
     }
+    if (text.startsWith(MEMORY_CITATION_TAG)) {
+        return consumeMemoryCitationBlock(text, final);
+    }
     if (text.startsWith("Runtime reminder:\n")) {
         return consumeLegacyRuntimeReminder(text, final);
     }
@@ -131,6 +163,20 @@ function consumeInternalBlockAtStart(text, final) {
     }
     return undefined;
 }
+function consumeMemoryCitationBlock(text, final) {
+    const openMatch = text.match(/^<oai-mem-citation\b[^>]*>/);
+    if (!openMatch) {
+        return isPrefixOf(MEMORY_CITATION_TAG, text)
+            ? final ? { consume: text.length } : { hold: true }
+            : undefined;
+    }
+    const closeTag = "</oai-mem-citation>";
+    const closeIndex = text.indexOf(closeTag, openMatch[0].length);
+    if (closeIndex < 0) {
+        return final ? { consume: text.length } : { hold: true };
+    }
+    return { consume: consumeTrailingLineBreaks(text, closeIndex + closeTag.length) };
+}
 function consumeStructuredInternalBlock(text, final) {
     for (const tagName of INTERNAL_TAG_NAMES) {
         const openMatch = text.match(new RegExp(`^<bubble_internal_${tagName}\\b[^>]*>`));

package/dist/agent.d.ts

@@ -5,6 +5,7 @@
 import { type ContextUsageSnapshot } from "./context/usage.js";
 import type { AgentEvent, AgentInputController, ContentPart, PermissionMode, Message, Provider, ThinkingLevel, Todo, ToolResult, ToolRegistryEntry, ToolUpdate } from "./types.js";
 import { type TurnHooks } from "./orchestrator/hooks.js";
+import type { ExternalHookController } from "./hooks/controller.js";
 import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "./agent/categories.js";
 import { BudgetLedger } from "./agent/budget-ledger.js";
 import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
@@ -35,6 +36,9 @@ export interface AgentOptions {
     onTodosUpdate?: (todos: Todo[]) => void;
     onModeUpdate?: (mode: PermissionMode) => void;
     hooks?: TurnHooks[];
+    externalHooks?: ExternalHookController;
+    agentRole?: "parent" | "subagent";
+    subAgentId?: string;
     budgetLedger?: BudgetLedger;
     budgetSource?: {
         runId: string;
@@ -69,6 +73,9 @@ export declare class Agent {
     private onMessageAppend?;
     private onToolResult?;
     private hookDefinitions;
+    private externalHooks?;
+    private agentRole;
+    private subAgentId?;
     private maxTurns?;
     private taskBudget?;
     private budgetLedger?;
@@ -83,6 +90,8 @@ export declare class Agent {
     private lastInputTokens;
     private lastAnchorMessageCount;
     constructor(options: AgentOptions);
+    private runExternalHook;
+    private injectHookModelContext;
     /** Unlock a list of deferred tools so they're included in subsequent turns. */
     unlockDeferredTools(names: string[]): void;
     /** All deferred tools in this session (for tool_search to inspect). */

package/dist/agent.js

@@ -8,11 +8,13 @@ import { compactMessagesWithLLM } from "./context/compact-llm.js";
 import { estimateContextTokens, getContextBudget } from "./context/budget.js";
 import { buildContextUsageSnapshot } from "./context/usage.js";
 import { isContextOverflowError } from "./context/overflow.js";
+import { computeRetryDelayMs, isProviderStreamInterruption, MAX_STREAM_INTERRUPTION_RETRIES, sleepBeforeRetry, } from "./network/retry.js";
 import { projectMessages } from "./context/projector.js";
 import { aggressivePruneMessages, markStableCurrentToolResultsForCache } from "./context/prune.js";
 import { truncateToolOutputForModel } from "./context/tool-output-truncate.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
+import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
 import { resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
 import { getSubtaskPolicy } from "./agent/subtask-policy.js";
@@ -20,7 +22,7 @@ import { composeAbortSignals } from "./agent/budget-ledger.js";
 import { assignAgentNickname, builtinAgentProfiles, mergeUsage, selectToolsForAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
 import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subagent-control.js";
 import { isHiddenToolResult } from "./agent/discovery-barrier.js";
-import { createStreamingInternalReminderSanitizer, sanitizeAssistantProviderMetadata, sanitizeInternalReminderBlocks } from "./agent/internal-reminder-sanitizer.js";
+import { createStreamingInternalReminderSanitizer, sanitizeAssistantProviderMetadata, sanitizeInternalReasoningText, sanitizeInternalReminderBlocks, } from "./agent/internal-reminder-sanitizer.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { isOnlyProviderProtocolArtifacts, stripProviderProtocolArtifacts } from "./provider-artifacts.js";
 import { debugReasoningStream, summarizeDebugText } from "./reasoning-debug.js";
@@ -39,6 +41,38 @@ const EMPTY_ASSISTANT_RECOVERY_REMINDER = "The previous model response contained
     "Do not put the final answer only in hidden reasoning.";
 const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";
 const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
+function agentEventFromHookProgress(event) {
+    const source = `${event.source.scope}:${event.source.index}`;
+    if (event.type === "hook_start") {
+        return {
+            type: "hook_start",
+            eventName: event.eventName,
+            hookId: event.hookId,
+            source,
+        };
+    }
+    if (event.type === "hook_end") {
+        return {
+            type: "hook_end",
+            eventName: event.eventName,
+            hookId: event.hookId,
+            source,
+            elapsedMs: event.elapsedMs ?? 0,
+            decision: event.decision ?? "allow",
+            reason: event.reason,
+        };
+    }
+    return {
+        type: "hook_error",
+        eventName: event.eventName,
+        hookId: event.hookId,
+        source,
+        elapsedMs: event.elapsedMs,
+        decision: event.decision,
+        reason: event.reason,
+        error: event.error ?? "Hook failed.",
+    };
+}
 export class AgentAbortError extends Error {
     constructor(message = "Agent run cancelled.") {
         super(message);
@@ -64,6 +98,9 @@ export class Agent {
     onMessageAppend;
     onToolResult;
     hookDefinitions;
+    externalHooks;
+    agentRole;
+    subAgentId;
     maxTurns;
     taskBudget;
     budgetLedger;
@@ -91,6 +128,9 @@ export class Agent {
         this.onTodosUpdate = options.onTodosUpdate;
         this.onModeUpdate = options.onModeUpdate;
         this.hookDefinitions = options.hooks ?? [];
+        this.externalHooks = options.externalHooks;
+        this.agentRole = options.agentRole ?? "parent";
+        this.subAgentId = options.subAgentId;
         this.maxTurns = options.maxTurns ?? options.steps;
         this.taskBudget = options.taskBudget;
         this.budgetLedger = options.budgetLedger;
@@ -120,6 +160,37 @@ export class Agent {
             this.injectSystemReminder(buildDeferredToolsReminder(deferredNames));
         }
     }
+    async runExternalHook(request, abortSignal) {
+        const events = [];
+        if (!this.externalHooks) {
+            return {
+                result: {
+                    eventName: request.eventName,
+                    decision: "allow",
+                    modelContext: [],
+                    results: [],
+                    diagnostics: [],
+                    matched: 0,
+                },
+                events,
+            };
+        }
+        const result = await this.externalHooks.runEvent({
+            agentRole: this.agentRole,
+            subAgentId: this.subAgentId,
+            sessionId: this.sessionID,
+            ...request,
+        }, {
+            abortSignal,
+            onProgress: (event) => events.push(agentEventFromHookProgress(event)),
+        });
+        return { result, events };
+    }
+    injectHookModelContext(result) {
+        for (const context of result.modelContext) {
+            this.injectSystemReminder(`[Hook ${result.eventName}] ${context}`);
+        }
+    }
     /** Unlock a list of deferred tools so they're included in subsequent turns. */
     unlockDeferredTools(names) {
         for (const n of names) {
@@ -259,6 +330,7 @@ export class Agent {
             provider: this._providerId || "none",
             model: this.apiModel || "none",
         };
+        const runId = randomUUID();
         const emit = (event) => {
             traceEvent("agent_event", summarizeAgentEventForTrace(event), traceContext);
             return event;
@@ -284,37 +356,68 @@ export class Agent {
             reminderQueue.push(reminder);
         };
         const pendingInputCount = () => inputController?.pendingInputCount() ?? 0;
-        const applyPendingInputs = () => {
+        const applyPendingInputs = async () => {
             const pendingInputs = inputController?.drainPendingInputs() ?? [];
             if (pendingInputs.length === 0)
                 return [];
+            const events = [];
             for (const input of pendingInputs) {
+                const hook = await this.runExternalHook({
+                    eventName: "SteerInputApplied",
+                    cwd,
+                    runId,
+                    target: "current_turn",
+                    payload: {
+                        id: input.id,
+                        target: "current_turn",
+                        ...normalizeHookInput(input.content),
+                    },
+                    fullPayload: { prompt: input.content },
+                }, abortSignal);
+                events.push(...hook.events);
+                this.injectHookModelContext(hook.result);
                 this.appendMessage({ role: "user", content: input.content });
-            }
-            return [
-                ...pendingInputs.map((input) => ({
+                events.push({
                     type: "input_applied",
                     id: input.id,
                     content: input.content,
                     target: "current_turn",
-                })),
-                { type: "input_pending_changed", pending: pendingInputCount() },
-            ];
+                });
+            }
+            events.push({ type: "input_pending_changed", pending: pendingInputCount() });
+            return events;
         };
-        const rejectPendingInputs = (reason) => {
+        const rejectPendingInputs = async (reason) => {
             const pendingInputs = inputController?.drainPendingInputs() ?? [];
             if (pendingInputs.length === 0)
                 return [];
-            return [
-                ...pendingInputs.map((input) => ({
+            const events = [];
+            for (const input of pendingInputs) {
+                const hook = await this.runExternalHook({
+                    eventName: "QueuedInputRejected",
+                    cwd,
+                    runId,
+                    target: "next_turn",
+                    payload: {
+                        id: input.id,
+                        reason,
+                        target: "next_turn",
+                        ...normalizeHookInput(input.content),
+                    },
+                    fullPayload: { prompt: input.content },
+                }, abortSignal);
+                events.push(...hook.events);
+                this.injectHookModelContext(hook.result);
+                events.push({
                     type: "input_rejected",
                     id: input.id,
                     content: input.content,
                     reason,
                     target: "next_turn",
-                })),
-                { type: "input_pending_changed", pending: pendingInputCount() },
-            ];
+                });
+            }
+            events.push({ type: "input_pending_changed", pending: pendingInputCount() });
+            return events;
         };
         const flushGovernorReminders = () => {
             for (const reminder of reminderQueue.splice(0, reminderQueue.length)) {
@@ -325,6 +428,26 @@ export class Agent {
             this.setTodos([]);
             yield emit({ type: "todos_updated", todos: [] });
         }
+        const promptHook = await this.runExternalHook({
+            eventName: "UserPromptSubmit",
+            cwd,
+            runId,
+            target: typeof userInput === "string" ? userInput : "content_parts",
+            payload: normalizeHookInput(userInput),
+            fullPayload: { prompt: userInput },
+        }, abortSignal);
+        for (const event of promptHook.events)
+            yield emit(event);
+        if (promptHook.result.decision === "deny") {
+            const message = promptHook.result.reason
+                ?? `Prompt blocked by hook ${promptHook.result.sourceHookId ?? "<unknown>"}.`;
+            yield emit({ type: "turn_start" });
+            yield emit({ type: "text_delta", content: message });
+            yield emit({ type: "turn_end", willContinue: false });
+            yield emit({ type: "agent_end" });
+            return;
+        }
+        this.injectHookModelContext(promptHook.result);
         this.appendMessage({ role: "user", content: userInput });
         await hookBus.runBeforeTurn({
             agent: this,
@@ -337,6 +460,7 @@ export class Agent {
         flushGovernorReminders();
         let consecutiveOverflowRecoveries = 0;
         let consecutiveEmptyAssistantRecoveries = 0;
+        let consecutiveStreamInterruptionRetries = 0;
         let step = 0;
         let autoServersStopped = false;
         const stopOwnedAutoServers = async () => {
@@ -353,7 +477,7 @@ export class Agent {
                 flushGovernorReminders();
                 for (const update of this.drainSubagentToolUpdates())
                     yield emit(update);
-                for (const event of applyPendingInputs())
+                for (const event of await applyPendingInputs())
                     yield emit(event);
                 yield emit({ type: "turn_start" });
                 step += 1;
@@ -404,6 +528,23 @@ export class Agent {
                 };
                 await hookBus.runBeforeModelCall(beforeModelCallCtx);
                 toolEntries = beforeModelCallCtx.toolEntries;
+                const preModelHook = await this.runExternalHook({
+                    eventName: "PreModelCall",
+                    cwd,
+                    runId,
+                    target: this.apiModel,
+                    payload: {
+                        providerId: this.providerId,
+                        model: this.apiModel,
+                        mode: this._mode,
+                        toolCount: toolEntries.length,
+                        ...normalizeHookInput(userInput),
+                    },
+                    fullPayload: { prompt: userInput },
+                }, abortSignal);
+                for (const event of preModelHook.events)
+                    yield emit(event);
+                this.injectHookModelContext(preModelHook.result);
                 flushGovernorReminders();
                 const textOnly = !!hookState.forceTextOnlyReason;
                 const toolDefinitions = toolEntries
@@ -610,6 +751,23 @@ export class Agent {
                     if (assistantAppended) {
                         throw error;
                     }
+                    if (isProviderStreamInterruption(error)
+                        && !isAbortLikeError(error, abortSignal)
+                        && consecutiveStreamInterruptionRetries < MAX_STREAM_INTERRUPTION_RETRIES) {
+                        // The provider stream died after partial content. The half-built
+                        // assistantMsg was never appended to this.messages, and the next
+                        // turn_start resets the streaming display, so re-issuing the whole
+                        // request is safe.
+                        consecutiveStreamInterruptionRetries += 1;
+                        yield emit({
+                            type: "provider_retry",
+                            attempt: consecutiveStreamInterruptionRetries,
+                            maxAttempts: MAX_STREAM_INTERRUPTION_RETRIES,
+                            reason: "Provider stream interrupted mid-response.",
+                        });
+                        await sleepBeforeRetry(computeRetryDelayMs(consecutiveStreamInterruptionRetries), abortSignal).catch(() => undefined);
+                        continue;
+                    }
                     if (!isContextOverflowError(error)) {
                         if (!isAbortLikeError(error, abortSignal) && shouldAppendModelInterruptedBoundary(this.messages)) {
                             this.appendMessage(createModelInterruptedMessage(error, {
@@ -631,6 +789,7 @@ export class Agent {
                 }
                 consecutiveOverflowRecoveries = 0;
                 consecutiveEmptyAssistantRecoveries = 0;
+                consecutiveStreamInterruptionRetries = 0;
                 // Execute tools if any
                 if (assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0) {
                     const parsedCalls = [];
@@ -695,6 +854,37 @@ export class Agent {
                                 blockedResult = result;
                             },
                         });
+                        const preToolHook = await this.runExternalHook({
+                            eventName: "PreToolUse",
+                            cwd,
+                            runId,
+                            target: tc.name,
+                            payload: {
+                                id: tc.id,
+                                name: tc.name,
+                                argsPreview: truncateHookText(tc.arguments, 1000),
+                            },
+                            fullPayload: {
+                                toolArgs: tc.parsedArgs,
+                                toolArguments: tc.arguments,
+                            },
+                        }, abortSignal);
+                        for (const event of preToolHook.events)
+                            yield emit(event);
+                        this.injectHookModelContext(preToolHook.result);
+                        if (preToolHook.result.decision === "deny") {
+                            blockedResult = {
+                                content: preToolHook.result.reason
+                                    ?? `Tool call blocked by hook ${preToolHook.result.sourceHookId ?? "<unknown>"}.`,
+                                isError: true,
+                                metadata: {
+                                    hook: {
+                                        eventName: "PreToolUse",
+                                        hookId: preToolHook.result.sourceHookId,
+                                    },
+                                },
+                            };
+                        }
                         assistantMsg.toolCalls[index] = {
                             id: tc.id,
                             name: tc.name,
@@ -729,6 +919,27 @@ export class Agent {
                                     result = next;
                                 },
                             });
+                            const postToolHook = await this.runExternalHook({
+                                eventName: result.isError ? "PostToolUseFailure" : "PostToolUse",
+                                cwd,
+                                runId,
+                                target: tc.name,
+                                payload: {
+                                    id: tc.id,
+                                    name: tc.name,
+                                    argsPreview: truncateHookText(tc.arguments, 1000),
+                                    resultPreview: truncateHookText(result.content, 1000),
+                                    isError: result.isError === true,
+                                },
+                                fullPayload: {
+                                    toolArgs: tc.parsedArgs,
+                                    toolArguments: tc.arguments,
+                                    toolResult: result,
+                                },
+                            }, abortSignal);
+                            for (const event of postToolHook.events)
+                                yield emit(event);
+                            this.injectHookModelContext(postToolHook.result);
                             traceEvent("speculative_read_blocked", {
                                 id: tc.id,
                                 name: tc.name,
@@ -814,6 +1025,27 @@ export class Agent {
                                 result = next;
                             },
                         });
+                        const postToolHook = await this.runExternalHook({
+                            eventName: result.isError ? "PostToolUseFailure" : "PostToolUse",
+                            cwd,
+                            runId,
+                            target: tc.name,
+                            payload: {
+                                id: tc.id,
+                                name: tc.name,
+                                argsPreview: truncateHookText(tc.arguments, 1000),
+                                resultPreview: truncateHookText(result.content, 1000),
+                                isError: result.isError === true,
+                            },
+                            fullPayload: {
+                                toolArgs: tc.parsedArgs,
+                                toolArguments: tc.arguments,
+                                toolResult: result,
+                            },
+                        }, abortSignal);
+                        for (const event of postToolHook.events)
+                            yield emit(event);
+                        this.injectHookModelContext(postToolHook.result);
                         // Honor the model's server-declared per-tool-output token cap (e.g.
                         // gpt-5.5 reports 10000). Without this, 4-5 large file reads in a row
                         // blow past the input window even though our local estimate looks fine.
@@ -885,13 +1117,28 @@ export class Agent {
                     flushReminders: flushGovernorReminders,
                 });
                 flushGovernorReminders();
+                const stopHook = await this.runExternalHook({
+                    eventName: "Stop",
+                    cwd,
+                    runId,
+                    target: "turn",
+                    payload: {
+                        providerId: this.providerId,
+                        model: this.apiModel,
+                        mode: this._mode,
+                        assistantChars: assistantMsg.content.length,
+                        toolCalls: assistantMsg.toolCalls?.length ?? 0,
+                    },
+                }, abortSignal);
+                for (const event of stopHook.events)
+                    yield emit(event);
                 const willContinue = !!hookState.forceContinuationReason;
                 yield emit({ type: "turn_end", usage: turnUsage, willContinue });
                 if (willContinue) {
                     delete hookState.forceContinuationReason;
                     continue;
                 }
-                for (const event of rejectPendingInputs("no_continuation"))
+                for (const event of await rejectPendingInputs("no_continuation"))
                     yield emit(event);
                 break;
             }
@@ -913,6 +1160,19 @@ export class Agent {
                     yield emit({ type: "todos_updated", todos: this.getTodos() });
                 }
             }
+            else {
+                const stopFailureHook = await this.runExternalHook({
+                    eventName: "StopFailure",
+                    cwd,
+                    runId,
+                    target: "run_error",
+                    payload: {
+                        error: summarizeTraceError(error),
+                    },
+                }, abortSignal);
+                for (const event of stopFailureHook.events)
+                    yield emit(event);
+            }
             throw error;
         }
         finally {
@@ -1226,6 +1486,26 @@ export class Agent {
                 this.pendingSubagentUpdates.push({ id: record.parentToolCallId, name: record.parentToolName, update });
             }
         };
+        const runSubagentLifecycleHook = async (eventName, status, error) => {
+            try {
+                await this.runExternalHook({
+                    eventName,
+                    cwd,
+                    runId: record.runId,
+                    target: record.profile.name,
+                    payload: {
+                        agentId: record.agentId,
+                        nickname: record.nickname,
+                        profile: record.profile.name,
+                        status,
+                        error,
+                    },
+                }, options.abortSignal);
+            }
+            catch {
+                // Subagent lifecycle hooks are observe-only; never fail the subagent.
+            }
+        };
         const allTools = [...this.tools.values()];
         const diagnostics = validateAgentProfileTools(allTools, record.profile, options.approval);
         const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
@@ -1236,6 +1516,7 @@ export class Agent {
             record.status = "blocked";
             record.error = blockingDiagnostics.map((diagnostic) => diagnostic.message).join("\n");
             record.updatedAt = Date.now();
+            await runSubagentLifecycleHook("SubagentStop", record.status, record.error);
             emit("blocked", undefined, record.error);
             this.notifySubagentWaiters(record);
             return;
@@ -1251,6 +1532,7 @@ export class Agent {
             record.status = "blocked";
             record.error = error?.message || String(error);
             record.updatedAt = Date.now();
+            await runSubagentLifecycleHook("SubagentStop", record.status, record.error);
             emit("blocked", undefined, record.error);
             this.notifySubagentWaiters(record);
             return;
@@ -1258,6 +1540,7 @@ export class Agent {
         record.agent = subAgent;
         record.status = "running";
         record.updatedAt = Date.now();
+        await runSubagentLifecycleHook("SubagentStart", record.status);
         emit("running", undefined, `Running ${record.nickname} (${record.profile.name})...`);
         let turnSummaryBuffer = "";
         let turnHadToolCall = false;
@@ -1304,6 +1587,7 @@ export class Agent {
             record.summary = sanitizeSubagentSummary(record.summary);
             record.error = error?.message || String(error);
             record.updatedAt = Date.now();
+            await runSubagentLifecycleHook("SubagentStop", record.status, record.error);
             emit(record.status, undefined, record.error);
             this.notifySubagentWaiters(record);
             return;
@@ -1315,6 +1599,7 @@ export class Agent {
         record.status = "completed";
         record.summary = sanitizeSubagentSummary(record.summary);
         record.updatedAt = Date.now();
+        await runSubagentLifecycleHook("SubagentStop", record.status);
         emit("completed", undefined, record.summary || `${record.nickname} completed`);
         this.notifySubagentWaiters(record);
     }
@@ -1394,6 +1679,9 @@ export class Agent {
             budgetSource: { runId: record.runId, subAgentId: record.agentId },
             systemPrompt: childSystemPrompt,
             hooks: this.hookDefinitions,
+            externalHooks: this.externalHooks,
+            agentRole: "subagent",
+            subAgentId: record.agentId,
             agentCategories: this.agentCategories,
             providerFactory: this.providerFactory,
         });
@@ -1550,7 +1838,7 @@ export class Agent {
             message.content = sanitizeInternalReminderBlocks(message.content);
         }
         if (message.role === "assistant" && message.reasoning) {
-            message.reasoning = sanitizeInternalReminderBlocks(message.reasoning);
+            message.reasoning = sanitizeInternalReasoningText(message.reasoning);
         }
         if (message.role === "assistant" && message.providerMetadata) {
             message.providerMetadata = sanitizeAssistantProviderMetadata(message.providerMetadata);

package/dist/approval/controller.d.ts

@@ -1,5 +1,6 @@
 import type { PermissionCheckResult, PermissionQuery, PermissionRuleSet } from "../permissions/types.js";
 import type { PermissionMode } from "../types.js";
+import type { ExternalHookController } from "../hooks/controller.js";
 import type { BashAllowlist } from "./session-cache.js";
 import type { ApprovalController, ApprovalDecision, ApprovalRequest } from "./types.js";
 export interface ApprovalControllerOptions {
@@ -23,6 +24,9 @@ export interface ApprovalControllerOptions {
      * /permissions take effect immediately. Omit to disable rule-based gating.
      */
     getRuleSet?: () => PermissionRuleSet;
+    /** External lifecycle hooks may observe or reject pending permission requests. */
+    externalHooks?: ExternalHookController;
+    sessionId?: string;
 }
 /**
  * Default ApprovalController. Decision tree:
@@ -46,4 +50,6 @@ export declare class PermissionAwareApprovalController implements ApprovalContro
     request(req: ApprovalRequest): Promise<ApprovalDecision>;
     private requestToQuery;
     private checkRequestRules;
+    private runPermissionRequestHook;
+    private runPermissionResultHook;
 }