@standardagents/builder 0.39.0 → 0.40.0

package/dist/built-in-routes.js

@@ -1462,6 +1462,9 @@ function normalizeToolCallMessageSequence(messages) {
   for (const message of messages) {
     const isAssistantToolCallMessage = message.role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
     if (!pending) {
+      if (message.role === "tool") {
+        continue;
+      }
       if (!isAssistantToolCallMessage) {
         normalized.push(message);
         continue;
@@ -6677,6 +6680,255 @@ var init_context = __esm({
   }
 });
 
+// src/packing/resolver.ts
+function parseQualifiedName(name15) {
+  if (name15.startsWith("@")) {
+    const firstSlash = name15.indexOf("/");
+    if (firstSlash === -1) {
+      return [null, name15];
+    }
+    const secondSlash = name15.indexOf("/", firstSlash + 1);
+    if (secondSlash === -1) {
+      return [null, name15];
+    }
+    return [name15.substring(0, secondSlash), name15.substring(secondSlash + 1)];
+  }
+  const separatorIndex = name15.indexOf("/");
+  if (separatorIndex === -1) {
+    return [null, name15];
+  }
+  return [name15.substring(0, separatorIndex), name15.substring(separatorIndex + 1)];
+}
+function qualifyName(packageId, shortName) {
+  return `${packageId}/${shortName}`;
+}
+var init_resolver = __esm({
+  "src/packing/resolver.ts"() {
+  }
+});
+
+// src/agents/ParentHookResolver.ts
+function packageOf(definition) {
+  return definition?.__package ?? definition?._package;
+}
+function qualifyWithinPackage(name15, packageId) {
+  if (!packageId || parseQualifiedName(name15)[0] !== null) {
+    return name15;
+  }
+  return qualifyName(packageId, name15);
+}
+function promptHooks(prompt) {
+  if (!prompt) return [];
+  return Array.isArray(prompt.hooks) ? prompt.hooks : Array.isArray(prompt._hooks) ? prompt._hooks : [];
+}
+function promptTools(prompt) {
+  if (!prompt) return [];
+  return Array.isArray(prompt.tools) ? prompt.tools : Array.isArray(prompt._tools) ? prompt._tools : [];
+}
+function relationDescriptor(entry) {
+  if (typeof entry === "string") {
+    return {
+      relationshipName: entry,
+      implementingAgent: entry,
+      explicitlyAgentShaped: false
+    };
+  }
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+  const config = entry;
+  if (typeof config.name !== "string" || !config.name) {
+    return null;
+  }
+  const implementingAgent = typeof config.agent === "string" && config.agent ? config.agent : config.name;
+  const explicitlyAgentShaped = "agent" in config || "blocking" in config || "resumable" in config || "immediate" in config || "parentCommunication" in config || "hidden" in config;
+  return {
+    relationshipName: config.name,
+    implementingAgent,
+    optional: typeof config.optional === "string" ? config.optional : void 0,
+    explicitlyAgentShaped
+  };
+}
+function hookLoader(host, owner, hookId) {
+  const ownerPackage = packageOf(owner);
+  if (!ownerPackage) {
+    return host.hooks()[hookId];
+  }
+  return host.registry?.()?.packages?.[ownerPackage.packageId]?.hooks?.[hookId];
+}
+async function loadBinding(host, owner, hookId, hookType, context, required) {
+  const loader = hookLoader(host, owner, hookId);
+  if (!loader) {
+    if (required) {
+      throw new Error(
+        `Required parent hook '${hookId}' was not found in the child agent namespace`
+      );
+    }
+    return null;
+  }
+  let loaded;
+  try {
+    loaded = await loader();
+  } catch (error) {
+    if (required) throw error;
+    console.error(`[Hooks] Failed to load hook '${hookId}':`, error);
+    return null;
+  }
+  if (!loaded) {
+    if (required) {
+      throw new Error(`Required parent hook '${hookId}' did not export a hook definition`);
+    }
+    return null;
+  }
+  if (typeof loaded.id !== "string" || loaded.id !== hookId) {
+    if (required) {
+      throw new Error(`Required parent hook '${hookId}' exported a mismatched hook ID`);
+    }
+    return null;
+  }
+  if (typeof loaded.execute !== "function") {
+    if (required) {
+      throw new Error(`Required parent hook '${hookId}' did not export an execute function`);
+    }
+    return null;
+  }
+  if (USER_HOOK_NAMES.has(loaded.hook)) {
+    if (required) {
+      throw new Error(
+        `Required parent hook '${hookId}' uses user-scoped hook type '${loaded.hook}'`
+      );
+    }
+    return null;
+  }
+  if (!THREAD_HOOK_NAMES.has(loaded.hook)) {
+    if (required) {
+      throw new Error(`Required parent hook '${hookId}' exported invalid hook type '${loaded.hook}'`);
+    }
+    return null;
+  }
+  if (loaded.hook !== hookType) {
+    return null;
+  }
+  return {
+    id: hookId,
+    hook: hookType,
+    execute: loaded.execute,
+    context
+  };
+}
+async function resolveHooksForPrompt(input, hookType) {
+  const agent = input.agent ?? await input.host.loadAgent(input.agentName);
+  const agentPackage = packageOf(agent);
+  const unqualifiedPromptName = input.promptName ?? agent.sideA?.prompt;
+  const resolvedPromptName = unqualifiedPromptName ? qualifyWithinPackage(unqualifiedPromptName, agentPackage?.packageId) : void 0;
+  const prompt = input.prompt ?? (resolvedPromptName ? await input.host.loadPrompt(resolvedPromptName) : void 0);
+  const promptName = prompt?.name ?? prompt?.id ?? resolvedPromptName ?? "unknown_prompt";
+  const before = [];
+  const after = [];
+  for (const entry of promptTools(prompt)) {
+    const relation = relationDescriptor(entry);
+    if (!relation) continue;
+    if (relation.optional && input.isOptionalRelationshipEnabled && !await input.isOptionalRelationshipEnabled(relation.optional)) {
+      continue;
+    }
+    const promptPackage = packageOf(prompt) ?? agentPackage;
+    const childReference = qualifyWithinPackage(
+      relation.implementingAgent,
+      promptPackage?.packageId
+    );
+    let child;
+    try {
+      child = await input.host.loadAgent(childReference);
+    } catch (error) {
+      if (relation.explicitlyAgentShaped) throw error;
+      continue;
+    }
+    if (child.type !== "dual_ai") continue;
+    if (child.parentHooks !== void 0 && child.exposeAsTool !== true) {
+      throw new Error(
+        `Child agent '${childReference}' declares parentHooks but is not exposed as a tool`
+      );
+    }
+    if (child.parentHooks !== void 0 && !Array.isArray(child.parentHooks)) {
+      throw new Error(`Child agent '${childReference}' has an invalid parentHooks declaration`);
+    }
+    const requirements = child.parentHooks ?? [];
+    const seenRequirements = /* @__PURE__ */ new Set();
+    for (const requirement of requirements) {
+      if (!requirement || typeof requirement !== "object" || typeof requirement.hook !== "string" || !requirement.hook || typeof requirement.reason !== "string" || !requirement.reason.trim() || requirement.stage !== void 0 && requirement.stage !== "before_parent" && requirement.stage !== "after_parent" || seenRequirements.has(requirement.hook)) {
+        throw new Error(`Child agent '${childReference}' has an invalid parentHooks requirement`);
+      }
+      seenRequirements.add(requirement.hook);
+      const loaded = await loadBinding(
+        input.host,
+        child,
+        requirement.hook,
+        hookType,
+        {
+          source: {
+            kind: "child",
+            relationshipName: relation.relationshipName,
+            agentName: childReference,
+            package: packageOf(child)
+          }
+        },
+        true
+      );
+      if (!loaded) continue;
+      if ((requirement.stage ?? "after_parent") === "before_parent") {
+        before.push(loaded);
+      } else {
+        after.push(loaded);
+      }
+    }
+  }
+  const promptHookIds = promptHooks(prompt);
+  const promptOwnsBaseHooks = promptHookIds.length > 0 && prompt !== void 0;
+  const baseOwner = promptOwnsBaseHooks ? prompt : agent;
+  const baseIds = promptHookIds.length > 0 ? promptHookIds : Array.isArray(agent.hooks) ? agent.hooks : [];
+  const baseContext = promptOwnsBaseHooks ? { source: { kind: "prompt", promptName } } : { source: { kind: "agent", agentName: input.agentName } };
+  const base = [];
+  for (const hookId of baseIds) {
+    const loaded = await loadBinding(
+      input.host,
+      baseOwner,
+      hookId,
+      hookType,
+      baseContext,
+      false
+    );
+    if (loaded) base.push(loaded);
+  }
+  return [...before, ...base, ...after];
+}
+var USER_HOOK_NAMES, THREAD_HOOK_NAMES;
+var init_ParentHookResolver = __esm({
+  "src/agents/ParentHookResolver.ts"() {
+    init_resolver();
+    USER_HOOK_NAMES = /* @__PURE__ */ new Set([
+      "user_client_attached",
+      "user_client_detached",
+      "user_value_changed"
+    ]);
+    THREAD_HOOK_NAMES = /* @__PURE__ */ new Set([
+      "after_thread_created",
+      "after_subagent_created",
+      "after_system_message",
+      "filter_messages",
+      "prefilter_llm_history",
+      "before_create_message",
+      "after_create_message",
+      "before_update_message",
+      "after_update_message",
+      "before_store_tool_result",
+      "after_tool_call_success",
+      "after_tool_call_failure",
+      "tool_call_started",
+      "tool_call_done"
+    ]);
+  }
+});
+
 // src/agents/FlowEngine.ts
 var FlowEngine_exports = {};
 __export(FlowEngine_exports, {
@@ -6693,6 +6945,7 @@ var init_FlowEngine = __esm({
     init_context();
     init_sessionTools();
     init_ThreadStateImpl();
+    init_ParentHookResolver();
     IMMEDIATE_BOOTSTRAP_TOOL_NAME = "bootstrap_immediate_subagent";
     HookBlockedExecutionError = class extends Error {
       constructor(message) {
@@ -7035,7 +7288,8 @@ This usually points to something I can't fix from here \u2014 for example the wo
           _variables: def.variables ?? [],
           _env: def.env ?? def.tenvs ?? {},
           _requiredSchema: def.requiredSchema ?? null,
-          _hooks: def.hooks ?? []
+          _hooks: def.hooks ?? [],
+          _package: def.__package
         };
       }
       /**
@@ -7425,6 +7679,8 @@ This usually points to something I can't fix from here \u2014 for example the wo
             type: newAgentDef.type,
             created_at: Date.now(),
             max_session_turns: newAgentDef.maxSessionTurns ?? null,
+            hooks: newAgentDef.hooks ?? [],
+            _package: newAgentDef.__package,
             side_a_label: newAgentDef.sideA?.label ?? null,
             side_a_agent_prompt: newAgentDef.sideA?.prompt ?? null,
             side_a_stop_on_response: newAgentDef.sideA?.stopOnResponse ?? true,
@@ -7515,28 +7771,12 @@ This usually points to something I can't fix from here \u2014 for example the wo
           state.promptPath = [sideAPrompt.name];
           state.pendingImmediateAfterHandoff = true;
           if (userMessageContent || userMessageAttachments) {
-            const handoffMessageId = crypto.randomUUID();
-            const handoffTimestamp = Date.now() * 1e3;
-            const handoffMessage = {
-              id: handoffMessageId,
-              role: "user",
-              content: userMessageContent || "",
-              created_at: handoffTimestamp,
-              attachments: userMessageAttachments
-            };
-            await state.storage.sql.exec(
-              `INSERT INTO messages (id, role, content, attachments, created_at, prompt) VALUES (?, ?, ?, ?, ?, ?)`,
-              handoffMessage.id,
-              handoffMessage.role,
-              handoffMessage.content,
-              handoffMessage.attachments || null,
-              handoffMessage.created_at,
+            await this.persistHandoffUserMessage(
+              state,
+              userMessageContent || "",
+              userMessageAttachments,
               sideAPrompt.name
             );
-            state.messageHistory.push(handoffMessage);
-            if (state.emitMessage) {
-              state.emitMessage(handoffMessage);
-            }
           }
           state.pendingHandoff = void 0;
           state.emitTelemetry?.({
@@ -7551,6 +7791,37 @@ This usually points to something I can't fix from here \u2014 for example the wo
           throw error;
         }
       }
+      /**
+       * Persist the user message that rides an agent handoff, applying the
+       * create-message lifecycle hooks like every other insertion path.
+       */
+      static async persistHandoffUserMessage(state, content, attachments, promptName) {
+        let handoffMessage = {
+          id: crypto.randomUUID(),
+          role: "user",
+          content,
+          created_at: Date.now() * 1e3,
+          status: "completed",
+          attachments: attachments ?? null
+        };
+        handoffMessage = await this.runBeforeCreateMessageHook(state, handoffMessage);
+        await state.storage.sql.exec(
+          `INSERT INTO messages (id, role, content, attachments, created_at, status, silent, prompt) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+          handoffMessage.id,
+          handoffMessage.role,
+          handoffMessage.content,
+          handoffMessage.attachments || null,
+          handoffMessage.created_at,
+          handoffMessage.status ?? "completed",
+          handoffMessage.silent ? 1 : 0,
+          promptName
+        );
+        state.messageHistory.push(handoffMessage);
+        await this.runAfterCreateMessageHook(state, handoffMessage);
+        if (state.emitMessage) {
+          state.emitMessage(handoffMessage);
+        }
+      }
       static isEnabledEnvFlag(value) {
         if (value === null || value === void 0) return false;
         const normalized = value.trim().toLowerCase();
@@ -7570,7 +7841,7 @@ This usually points to something I can't fix from here \u2014 for example the wo
             return null;
           }
           return await stub.resolveThreadEnv({
-            threadId: state.threadId,
+            threadId: state.thread.metadata.id,
             property,
             promptName: state.prompt?.name
           });
@@ -8092,8 +8363,8 @@ This usually points to something I can't fix from here \u2014 for example the wo
         state.context[key] = existing;
       }
       static async runImmediateToolsIfNeeded(state) {
-        const promptTools = Array.isArray(state.prompt._tools) ? state.prompt._tools : [];
-        if (promptTools.length === 0) {
+        const promptTools2 = Array.isArray(state.prompt._tools) ? state.prompt._tools : [];
+        if (promptTools2.length === 0) {
           return false;
         }
         if (!state.immediatePromptRuns) {
@@ -8129,7 +8400,7 @@ This usually points to something I can't fix from here \u2014 for example the wo
             (activeInstanceCounts.get(child.name) ?? 0) + 1
           );
         }
-        for (const toolConfig of promptTools) {
+        for (const toolConfig of promptTools2) {
           if (!toolConfig || typeof toolConfig !== "object") {
             continue;
           }
@@ -8295,10 +8566,10 @@ This usually points to something I can't fix from here \u2014 for example the wo
        * model's to clean up, and terminate_subagent on an infrastructure child
        * kills work the runtime depends on. Static and pure for direct testing.
        */
-      static filterModelVisibleSubagents(registry, promptTools) {
+      static filterModelVisibleSubagents(registry, promptTools2) {
         if (registry.length === 0) return registry;
         const hidden = /* @__PURE__ */ new Set();
-        for (const config of promptTools ?? []) {
+        for (const config of promptTools2 ?? []) {
           if (typeof config === "object" && config !== null && "name" in config && config.hidden === true) {
             hidden.add(config.name);
           }
@@ -8448,7 +8719,16 @@ This usually points to something I can't fix from here \u2014 for example the wo
           role: "system",
           content: systemPromptText
         });
-        const completedMessages = state.messageHistory.filter(
+        const historySnapshot = state.messageHistory.filter(
+          (msg) => msg.status !== "pending"
+        );
+        const filteredHistory = await this.runFilterMessagesHook(
+          state.thread.instance,
+          state,
+          historySnapshot
+        );
+        const contextHistory = this.filterOrphanedToolCalls(filteredHistory);
+        const completedMessages = contextHistory.filter(
           (msg) => msg.status !== "pending"
         );
         const recentMessageThreshold = state.prompt.recentImageThreshold ?? 10;
@@ -9319,8 +9599,8 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         try {
           const nativeTools = await this.loadNativeTools(state);
           tools.push(...nativeTools);
-          const promptTools = await this.loadPromptTools(state);
-          tools.push(...promptTools);
+          const promptTools2 = await this.loadPromptTools(state);
+          tools.push(...promptTools2);
           const agentTools = await this.loadAgentTools(state);
           tools.push(...agentTools);
           const toolNameSources = /* @__PURE__ */ new Map();
@@ -9329,7 +9609,7 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
             sources.add("native tool");
             toolNameSources.set(tool3.function.name, sources);
           }
-          for (const tool3 of promptTools) {
+          for (const tool3 of promptTools2) {
             const sources = toolNameSources.get(tool3.function.name) || /* @__PURE__ */ new Set();
             sources.add("prompt");
             toolNameSources.set(tool3.function.name, sources);
@@ -9471,24 +9751,8 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
       // Hook Resolution Helpers
       // ==========================================================================
       /**
-       * Get the list of hook IDs that should run for the current context.
-       * Resolution: prompt hooks > agent hooks > empty array
-       *
-       * @param state - Flow state with prompt and agent configuration
-       * @returns Array of hook IDs to execute
-       */
-      static getActiveHookIds(state) {
-        if (state.prompt?._hooks !== void 0 && state.prompt._hooks.length > 0) {
-          return state.prompt._hooks;
-        }
-        if (state.agentConfig.hooks !== void 0 && state.agentConfig.hooks.length > 0) {
-          return state.agentConfig.hooks;
-        }
-        return [];
-      }
-      /**
-       * Get hooks of a specific type from the active hook IDs.
-       * Returns typed hook executors in the order they appear in the hooks array.
+       * Resolve hooks of a specific type for the active prompt, including required
+       * hooks contributed automatically by its enabled direct child agents.
        *
        * @template K - The hook type name (ensures type-safe executors)
        * @param state - Flow state with hook configuration
@@ -9496,24 +9760,17 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
        * @returns Array of typed hook executor functions
        */
       static async getHooksForType(state, hookType) {
-        const hookIds = this.getActiveHookIds(state);
-        if (hookIds.length === 0) return [];
-        const hooksRegistry = state.thread.instance.hooks();
-        if (!hooksRegistry) return [];
-        const executors = [];
-        for (const hookId of hookIds) {
-          const hookLoader = hooksRegistry[hookId];
-          if (!hookLoader) continue;
-          try {
-            const hookDef = await hookLoader();
-            if (hookDef && hookDef.hook === hookType) {
-              executors.push(hookDef.execute);
-            }
-          } catch (error) {
-            console.error(`[Hooks] Failed to load hook '${hookId}':`, error);
-          }
-        }
-        return executors;
+        return await resolveHooksForPrompt(
+          {
+            host: state.thread.instance,
+            agentName: state.agentConfig.id,
+            agent: state.agentConfig,
+            promptName: state.prompt?.id,
+            prompt: state.prompt,
+            isOptionalRelationshipEnabled: (envName) => this.isOptionalToolEnabled(state, envName)
+          },
+          hookType
+        );
       }
       // ==========================================================================
       // Hook Runner Methods
@@ -9531,9 +9788,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return messages;
         let result = messages;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            result = await executor(threadState, result);
+            result = await execute(threadState, result, context);
           } catch (error) {
             if (error && typeof error === "object" && error.block === true) {
               throw new HookBlockedExecutionError(error instanceof Error ? error.message : String(error));
@@ -9551,9 +9808,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return systemMessage;
         let result = systemMessage;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            const next = await executor(threadState, result);
+            const next = await execute(threadState, result, context);
             if (next !== null && next !== void 0) {
               result = next;
             }
@@ -9570,9 +9827,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         const executors = await this.getHooksForType(state, "after_subagent_created");
         if (executors.length === 0) return;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            await executor(threadState, childState);
+            await execute(threadState, childState, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running after_subagent_created hook:", error);
           }
@@ -9586,20 +9843,27 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
        * @param message - Message object to be created
        * @returns Processed message (or original if hook doesn't exist/fails)
        */
-      static async runBeforeCreateMessageHook(state, message) {
+      static async runBeforeCreateMessageHook(state, message, threadStateOverride, options) {
         const executors = await this.getHooksForType(state, "before_create_message");
         if (executors.length === 0) return message;
         let result = message;
-        const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        const threadState = threadStateOverride ?? ThreadStateImpl.fromFlowState(state);
+        for (const { execute, context } of executors) {
           try {
-            const hooked = await executor(threadState, _FlowEngine.rowToHookMessage(result));
+            const hooked = await execute(
+              threadState,
+              _FlowEngine.rowToHookMessage(result),
+              context
+            );
             result = {
               ...result,
               ...hooked,
               attachments: hooked.attachments === void 0 ? result.attachments : hooked.attachments === null ? null : typeof hooked.attachments === "string" ? hooked.attachments : JSON.stringify(hooked.attachments)
             };
           } catch (error) {
+            if (options?.propagateHookErrors) {
+              throw error;
+            }
             console.error("[Hooks] \u2717 Error running before_create_message hook:", error);
           }
         }
@@ -9612,13 +9876,13 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
        * @param state - Flow state with execution context
        * @param message - The created message object
        */
-      static async runAfterCreateMessageHook(state, message) {
+      static async runAfterCreateMessageHook(state, message, threadStateOverride) {
         const executors = await this.getHooksForType(state, "after_create_message");
         if (executors.length === 0) return;
-        const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        const threadState = threadStateOverride ?? ThreadStateImpl.fromFlowState(state);
+        for (const { execute, context } of executors) {
           try {
-            await executor(threadState, _FlowEngine.rowToHookMessage(message));
+            await execute(threadState, _FlowEngine.rowToHookMessage(message), context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running after_create_message hook:", error);
           }
@@ -9659,9 +9923,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return updates;
         let result = updates;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            result = await executor(threadState, messageId, result);
+            result = await execute(threadState, messageId, result, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running before_update_message hook:", error);
           }
@@ -9679,9 +9943,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         const executors = await this.getHooksForType(state, "after_update_message");
         if (executors.length === 0) return;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            await executor(threadState, _FlowEngine.rowToHookMessage(message));
+            await execute(threadState, _FlowEngine.rowToHookMessage(message), context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running after_update_message hook:", error);
           }
@@ -9701,9 +9965,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return toolResult;
         let result = toolResult;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            result = await executor(threadState, toolCall, result);
+            result = await execute(threadState, toolCall, result, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running before_store_tool_result hook:", error);
           }
@@ -9723,10 +9987,10 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return toolResult;
         let result = toolResult;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           if (result === null) break;
           try {
-            result = await executor(threadState, toolCall, result);
+            result = await execute(threadState, toolCall, result, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running after_tool_call_success hook:", error);
           }
@@ -9746,10 +10010,10 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return toolResult;
         let result = toolResult;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           if (result === null) break;
           try {
-            result = await executor(threadState, toolCall, result);
+            result = await execute(threadState, toolCall, result, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running after_tool_call_failure hook:", error);
           }
@@ -9779,9 +10043,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         const executors = await this.getHooksForType(state, "tool_call_started");
         if (executors.length === 0) return;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            await executor(threadState, toolCall, progress);
+            await execute(threadState, toolCall, progress, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running tool_call_started hook:", error);
           }
@@ -9809,9 +10073,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         const executors = await this.getHooksForType(state, "tool_call_done");
         if (executors.length === 0) return;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
-            await executor(threadState, toolCall, toolResult);
+            await execute(threadState, toolCall, toolResult, context);
           } catch (error) {
             console.error("[Hooks] \u2717 Error running tool_call_done hook:", error);
           }
@@ -10116,7 +10380,7 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
           }
           existingPathMessages.add(content);
           const attachmentsJson = JSON.stringify([ref]);
-          const silentMessage = {
+          let silentMessage = {
             id: crypto.randomUUID(),
             role: sourceMessage.role,
             content,
@@ -10127,6 +10391,7 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
             parent_id: parentId,
             depth
           };
+          silentMessage = await this.runBeforeCreateMessageHook(state, silentMessage);
           await state.storage.sql.exec(
             `
         INSERT INTO messages (
@@ -10137,15 +10402,16 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
             silentMessage.id,
             silentMessage.role,
             silentMessage.content,
-            attachmentsJson,
-            1,
+            silentMessage.attachments ?? null,
+            silentMessage.silent ? 1 : 0,
             silentMessage.created_at,
-            silentMessage.status,
+            silentMessage.status ?? "completed",
             silentMessage.parent_id,
             silentMessage.depth,
             currentPrompt
           );
           state.messageHistory.push(silentMessage);
+          await this.runAfterCreateMessageHook(state, silentMessage);
           if (state.emitMessage) {
             state.emitMessage(silentMessage);
           }
@@ -10684,7 +10950,7 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
        */
       static async loadMessageHistory(state) {
         const storage = state.storage;
-        const thread = state.thread;
+        state.thread;
         const includeParentHistory = state.prompt.include_chat ?? true;
         const includeToolCalls = state.prompt.include_past_tools ?? true;
         try {
@@ -10720,8 +10986,11 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
             rows = cursor.toArray();
           }
           if (state.extraMessages && state.extraMessages.length > 0) {
-            rows.push(...state.extraMessages);
-            rows.sort((a, b) => a.created_at - b.created_at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            const persistedIds = new Set(rows.map((row) => row.id));
+            rows.push(
+              ...state.extraMessages.filter((entry) => !persistedIds.has(entry.id))
+            );
+            rows.sort((a, b) => a.created_at - b.created_at);
           }
           const messages = rows.map((row) => ({
             id: row.id,
@@ -10744,43 +11013,77 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
             reasoning_content: row.reasoning_content,
             reasoning_details: row.reasoning_details
           }));
-          return this.runFilterMessagesHook(
-            thread.instance,
-            state,
-            this.filterOrphanedToolCalls(messages)
-          );
+          return messages;
         } catch (error) {
           console.error("Error loading message history:", error);
           return [];
         }
       }
       /**
-       * Run the filter_messages hook if it exists
-       * This hook allows developers to modify SQL row data before transformation
-       *
-       * @param thread - Thread instance with hooks registry
-       * @param state - Flow state for hook context
-       * @param rows - SQL rows from messages table
-       * @returns Processed rows (or original if hook doesn't exist/fails)
+       * Build request-context rows from persisted history.
+       * Mutations and synthetic messages stay in the request context.
        */
       static async runFilterMessagesHook(thread, state, messages) {
         const executors = await this.getHooksForType(state, "filter_messages");
         if (executors.length === 0) return messages;
         let result = messages;
         const threadState = ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        for (const { execute, context } of executors) {
           try {
             const byId = /* @__PURE__ */ new Map();
             for (const row of result) if (row.id) byId.set(row.id, row);
             const hookView = result.map((row) => _FlowEngine.rowToHookMessage(row));
-            const kept = await executor(threadState, hookView);
-            result = kept.map((m) => m.id && byId.get(m.id) || null).filter((row) => row !== null);
+            const kept = await execute(threadState, hookView, context);
+            result = kept.map((hookedMessage) => {
+              const original = hookedMessage.id ? byId.get(hookedMessage.id) : void 0;
+              if (original) {
+                return _FlowEngine.applyHookMessageToRow(original, hookedMessage);
+              }
+              return _FlowEngine.hookMessageToContextRow(hookedMessage);
+            });
           } catch (error) {
             console.error("[Hooks] \u2717 Error running filter_messages hook:", error);
           }
         }
         return result;
       }
+      /**
+       * Copy a persisted row and apply hook edits. The original live-history
+       * object is left unchanged.
+       */
+      static applyHookMessageToRow(original, hooked) {
+        const attachments = hooked.attachments === void 0 ? original.attachments : hooked.attachments === null ? null : typeof hooked.attachments === "string" ? hooked.attachments : JSON.stringify(hooked.attachments);
+        return {
+          ...original,
+          role: hooked.role ?? original.role,
+          content: hooked.content !== void 0 ? hooked.content : original.content,
+          name: hooked.name !== void 0 ? hooked.name : original.name,
+          tool_calls: hooked.tool_calls !== void 0 ? hooked.tool_calls : original.tool_calls,
+          tool_call_id: hooked.tool_call_id !== void 0 ? hooked.tool_call_id : original.tool_call_id,
+          silent: hooked.silent !== void 0 ? hooked.silent : original.silent,
+          attachments
+        };
+      }
+      /**
+       * Convert a synthetic hook message into a request-context-only builder row.
+       */
+      static hookMessageToContextRow(hooked) {
+        const attachments = hooked.attachments === void 0 || hooked.attachments === null ? hooked.attachments ?? null : typeof hooked.attachments === "string" ? hooked.attachments : JSON.stringify(hooked.attachments);
+        return {
+          id: hooked.id || crypto.randomUUID(),
+          role: hooked.role,
+          content: hooked.content ?? null,
+          name: hooked.name ?? null,
+          tool_calls: typeof hooked.tool_calls === "string" ? hooked.tool_calls : null,
+          tool_call_id: hooked.tool_call_id ?? null,
+          created_at: hooked.created_at ?? Date.now() * TIMESTAMP_MULTIPLIER,
+          parent_id: hooked.parent_id ?? null,
+          depth: hooked.depth ?? 0,
+          silent: hooked.silent ?? false,
+          status: "completed",
+          attachments
+        };
+      }
       /**
        * Log an error to the logs table (best-effort)
        * Creates a log entry with error details but no associated message_id
@@ -10951,7 +11254,7 @@ async function injectMessage(flow, options) {
   const timestamp = Date.now() * TIMESTAMP_MULTIPLIER;
   const silent = options.silent ?? false;
   const forceTopLevel = options.forceTopLevel ?? false;
-  const message = {
+  let message = {
     id: messageId,
     role: options.role,
     content: options.content,
@@ -10965,41 +11268,52 @@ async function injectMessage(flow, options) {
     metadata: options.metadata
   };
   if (options.beforeMessageId) {
-    const cursor = await flow.storage.sql.exec(
-      `SELECT created_at FROM messages WHERE id = ?`,
-      options.beforeMessageId
+    const liveTarget = flow.messageHistory.find(
+      (entry) => entry.id === options.beforeMessageId
     );
-    const rows = cursor.toArray();
-    const targetMessage = rows[0];
-    if (!targetMessage) {
-      throw new Error(
-        `Message with id ${options.beforeMessageId} not found`
+    let targetCreatedAt = liveTarget?.created_at;
+    if (targetCreatedAt === void 0) {
+      const cursor = await flow.storage.sql.exec(
+        `SELECT created_at FROM messages WHERE id = ?`,
+        options.beforeMessageId
       );
+      const rows = cursor.toArray();
+      const targetMessage = rows[0];
+      if (!targetMessage) {
+        throw new Error(
+          `Message with id ${options.beforeMessageId} not found`
+        );
+      }
+      targetCreatedAt = targetMessage.created_at;
     }
-    message.created_at = targetMessage.created_at - 1;
+    message.created_at = targetCreatedAt - 1;
   }
   const currentPrompt = flow.promptPath.length > 0 ? flow.promptPath[flow.promptPath.length - 1] : null;
-  const metadataJson = options.metadata ? JSON.stringify(options.metadata) : null;
+  const { FlowEngine: FlowEngine2 } = await Promise.resolve().then(() => (init_FlowEngine(), FlowEngine_exports));
+  message = await FlowEngine2.runBeforeCreateMessageHook(flow, message, void 0, {
+    propagateHookErrors: true
+  });
+  const metadataJson = message.metadata === void 0 ? null : JSON.stringify(message.metadata);
   await flow.storage.sql.exec(
     `INSERT INTO messages (id, role, content, name, tool_call_id, created_at, status, silent, parent_id, depth, metadata, prompt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    messageId,
+    message.id,
     message.role,
     message.content,
     message.name,
     message.tool_call_id,
     message.created_at,
     message.status,
-    silent ? 1 : 0,
+    message.silent ? 1 : 0,
     message.parent_id,
     message.depth,
     metadataJson,
     currentPrompt
   );
-  if (!silent) {
-    flow.messageHistory.push(message);
-  } else {
-    flow.messageHistory = await reloadHistory(flow);
+  appendLiveExecutionHistory(flow, message, options.beforeMessageId);
+  if (flow.prompt.include_chat === false || message.parent_id !== null || (message.depth ?? 0) > 0) {
+    appendInjectedContextMessage(flow.extraMessages, message);
   }
+  await FlowEngine2.runAfterCreateMessageHook(flow, message);
   if (flow.emitMessage) {
     flow.emitMessage(message);
   }
@@ -11008,10 +11322,41 @@ async function injectMessage(flow, options) {
   }
   return message;
 }
-async function reloadHistory(state) {
-  const { FlowEngine: FlowEngine2 } = await Promise.resolve().then(() => (init_FlowEngine(), FlowEngine_exports));
-  state.messageHistory = await FlowEngine2.loadMessageHistory(state);
-  return state.messageHistory;
+function appendLiveExecutionHistory(flow, message, beforeMessageId) {
+  const history = flow.messageHistory;
+  const existing = history.findIndex((entry) => entry.id === message.id);
+  if (existing >= 0) {
+    history.splice(existing, 1);
+  }
+  if (beforeMessageId) {
+    const targetIndex = history.findIndex((entry) => entry.id === beforeMessageId);
+    if (targetIndex >= 0) {
+      history.splice(targetIndex, 0, message);
+      return;
+    }
+  }
+  const insertAt = history.findIndex(
+    (entry) => entry.created_at > message.created_at
+  );
+  if (insertAt === -1) {
+    history.push(message);
+    return;
+  }
+  history.splice(insertAt, 0, message);
+}
+function appendInjectedContextMessage(extraMessages, message) {
+  const existing = extraMessages.findIndex((entry) => entry.id === message.id);
+  if (existing >= 0) {
+    extraMessages.splice(existing, 1);
+  }
+  const insertAt = extraMessages.findIndex(
+    (entry) => entry.created_at > message.created_at
+  );
+  if (insertAt === -1) {
+    extraMessages.push(message);
+    return;
+  }
+  extraMessages.splice(insertAt, 0, message);
 }
 function forceTurn(flow, side) {
   if (flow.sequence.isHandling) {
@@ -14692,11 +15037,19 @@ async function extractPromptTools(sourceCode) {
               result.tools.push(element.text);
             } else if (ts.isObjectLiteralExpression(element)) {
               result.hasSubpromptConfigs = true;
+              let configuredName;
+              let implementingAgent;
               for (const objProp of element.properties) {
-                if (ts.isPropertyAssignment(objProp) && ts.isIdentifier(objProp.name) && objProp.name.text === "name" && ts.isStringLiteral(objProp.initializer)) {
-                  result.tools.push(objProp.initializer.text);
+                if (ts.isPropertyAssignment(objProp) && ts.isIdentifier(objProp.name) && ts.isStringLiteral(objProp.initializer)) {
+                  if (objProp.name.text === "name") {
+                    configuredName = objProp.initializer.text;
+                  } else if (objProp.name.text === "agent") {
+                    implementingAgent = objProp.initializer.text;
+                  }
                 }
               }
+              const dependencyName = implementingAgent ?? configuredName;
+              if (dependencyName) result.tools.push(dependencyName);
             }
           }
         }
@@ -14819,6 +15172,106 @@ async function extractAgentPrompts(sourceCode) {
   visit2(sourceFile);
   return result;
 }
+async function extractAgentHooks(sourceCode) {
+  const ts = await loadTypeScript();
+  const sourceFile = ts.createSourceFile(
+    "agent.ts",
+    sourceCode,
+    ts.ScriptTarget.ESNext,
+    true
+  );
+  const arrays = /* @__PURE__ */ new Map();
+  const result = {
+    hooks: [],
+    parentHooks: [],
+    parentHookRequirements: []
+  };
+  const unwrapArray = (expression) => {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+      current = current.expression;
+    }
+    if (ts.isArrayLiteralExpression(current)) return current;
+    if (ts.isIdentifier(current)) return arrays.get(current.text) ?? null;
+    return null;
+  };
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.initializer) {
+        const array44 = unwrapArray(declaration.initializer);
+        if (array44) arrays.set(declaration.name.text, array44);
+      }
+    }
+  }
+  const pushUnique = (target, value) => {
+    if (!target.includes(value)) target.push(value);
+  };
+  function visit2(node) {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "defineAgent" && node.arguments.length > 0 && ts.isObjectLiteralExpression(node.arguments[0])) {
+      for (const property of node.arguments[0].properties) {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) continue;
+        const array44 = unwrapArray(property.initializer);
+        if (!array44) continue;
+        if (property.name.text === "hooks") {
+          for (const element of array44.elements) {
+            if (ts.isStringLiteral(element)) pushUnique(result.hooks, element.text);
+          }
+        }
+        if (property.name.text === "parentHooks") {
+          for (const element of array44.elements) {
+            if (!ts.isObjectLiteralExpression(element)) continue;
+            let hook;
+            let reason;
+            let stage;
+            for (const requirement of element.properties) {
+              if (ts.isPropertyAssignment(requirement) && ts.isIdentifier(requirement.name) && ts.isStringLiteral(requirement.initializer)) {
+                if (requirement.name.text === "hook") hook = requirement.initializer.text;
+                if (requirement.name.text === "reason") reason = requirement.initializer.text;
+                if (requirement.name.text === "stage" && (requirement.initializer.text === "before_parent" || requirement.initializer.text === "after_parent")) {
+                  stage = requirement.initializer.text;
+                }
+              }
+            }
+            if (hook) {
+              pushUnique(result.parentHooks, hook);
+              if (reason) result.parentHookRequirements.push({ hook, reason, stage });
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit2);
+  }
+  visit2(sourceFile);
+  return result;
+}
+async function extractPromptHooks(sourceCode) {
+  const ts = await loadTypeScript();
+  const sourceFile = ts.createSourceFile(
+    "prompt.ts",
+    sourceCode,
+    ts.ScriptTarget.ESNext,
+    true
+  );
+  const hooks = [];
+  function visit2(node) {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "definePrompt" && node.arguments.length > 0 && ts.isObjectLiteralExpression(node.arguments[0])) {
+      for (const property of node.arguments[0].properties) {
+        if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === "hooks" && ts.isArrayLiteralExpression(property.initializer)) {
+          for (const element of property.initializer.elements) {
+            if (ts.isStringLiteral(element) && !hooks.includes(element.text)) {
+              hooks.push(element.text);
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit2);
+  }
+  visit2(sourceFile);
+  return hooks;
+}
 async function extractAgentDescription(sourceCode) {
   const ts = await loadTypeScript();
   const sourceFile = ts.createSourceFile(
@@ -15074,6 +15527,13 @@ var init_packing_service = __esm({
         });
         const agentSource = fs4.readFileSync(agentFilePath, "utf-8");
         const agentPrompts = await extractAgentPrompts(agentSource);
+        const agentHooks = await extractAgentHooks(agentSource);
+        for (const hookId of agentHooks.hooks) {
+          await this.analyzeHook(hookId, agentsDir, analysis, false, `agent:${agentName}`);
+        }
+        for (const hookId of agentHooks.parentHooks) {
+          await this.analyzeHook(hookId, agentsDir, analysis, true, `agent:${agentName}`);
+        }
         if (agentPrompts.sideA) {
           analysis.primaryPrompt = agentPrompts.sideA;
           await this.analyzePrompt(agentPrompts.sideA, agentsDir, analysis, /* @__PURE__ */ new Set(), `agent:${agentName}`);
@@ -15276,6 +15736,9 @@ var init_packing_service = __esm({
         }
         visited.add(`prompt:${promptName}`);
         const promptSource = fs4.readFileSync(promptFilePath, "utf-8");
+        for (const hookId of await extractPromptHooks(promptSource)) {
+          await this.analyzeHook(hookId, agentsDir, analysis, false, thisKey);
+        }
         const modelName = await extractPromptModel(promptSource);
         if (modelName) {
           await this.analyzeModel(modelName, agentsDir, analysis, visited, thisKey);
@@ -15360,6 +15823,13 @@ var init_packing_service = __esm({
         visited.add(`agent:${agentName}`);
         const agentSource = fs4.readFileSync(agentFilePath, "utf-8");
         const agentPrompts = await extractAgentPrompts(agentSource);
+        const agentHooks = await extractAgentHooks(agentSource);
+        for (const hookId of agentHooks.hooks) {
+          await this.analyzeHook(hookId, agentsDir, analysis, false, thisKey);
+        }
+        for (const hookId of agentHooks.parentHooks) {
+          await this.analyzeHook(hookId, agentsDir, analysis, true, thisKey);
+        }
         if (agentPrompts.sideA) {
           await this.analyzePrompt(agentPrompts.sideA, agentsDir, analysis, visited, thisKey);
         }
@@ -15367,6 +15837,27 @@ var init_packing_service = __esm({
           await this.analyzePrompt(agentPrompts.sideB, agentsDir, analysis, visited, thisKey);
         }
       }
+      /** Add a hook referenced by an agent or prompt to the packed graph. */
+      async analyzeHook(hookId, agentsDir, analysis, required, parentKey) {
+        const hookFilePath = await this.findFile(path4.join(agentsDir, "hooks"), hookId);
+        if (!hookFilePath) {
+          const message = `Hook file not found for ID: ${hookId}`;
+          if (required) analysis.errors.push(message);
+          else analysis.warnings.push(message);
+          return;
+        }
+        if (!analysis.constituents.hooks.some(
+          (hook) => hook.name === hookId && hook.parentKey === parentKey
+        )) {
+          analysis.constituents.hooks.push({
+            name: hookId,
+            filePath: hookFilePath,
+            discoveredVia: "static",
+            sharedWith: [],
+            parentKey
+          });
+        }
+      }
       /**
        * Analyze a model and its fallbacks.
        */
@@ -15501,11 +15992,17 @@ var init_packing_service = __esm({
         } = options;
         const finalPackageName = packageName || packageId;
         const packedAt = Date.now();
+        const entryAgentFile = await this.findFile(
+          path4.join(rootDir, "agents", "agents"),
+          agentName
+        );
+        const entryParentHooks = entryAgentFile ? (await extractAgentHooks(fs4.readFileSync(entryAgentFile, "utf-8"))).parentHookRequirements : [];
         const meta = {
           packageId,
           version,
           entryAgents: [agentName],
-          packedAt
+          packedAt,
+          ...entryParentHooks.length > 0 ? { parentHooks: { [agentName]: entryParentHooks } } : {}
         };
         const result = {
           success: false,
@@ -15614,6 +16111,7 @@ var init_packing_service = __esm({
             agentName,
             this.deduplicateConstituents(analysis).effects.map((effect) => effect.name),
             this.deduplicateConstituents(analysis).threadEndpoints.map((endpoint) => endpoint.name),
+            meta.parentHooks,
             externalDeps,
             rootDir,
             license,
@@ -16005,7 +16503,7 @@ var init_packing_service = __esm({
       /**
        * Generate the package.json file with dependencies.
        */
-      generatePackageJson(packageName, version, agentName, effects, threadEndpoints, externalDeps, rootDir, license, licenseOwner) {
+      generatePackageJson(packageName, version, agentName, effects, threadEndpoints, parentHooks, externalDeps, rootDir, license, licenseOwner) {
         const dependencies = {
           "@standardagents/spec": this.resolvePackageVersion("@standardagents/spec", rootDir)
         };
@@ -16027,6 +16525,7 @@ var init_packing_service = __esm({
           keywords: ["standardagent"],
           standardagent: {
             entryAgents: [agentName],
+            ...parentHooks ? { parentHooks } : {},
             ...effects.length > 0 ? { effects } : {},
             ...threadEndpoints.length > 0 ? { threadEndpoints } : {}
           },
@@ -16322,6 +16821,22 @@ ${license || "See LICENSE file"}
     };
   }
 });
+function validParentHooks(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((requirements) => {
+    if (!Array.isArray(requirements)) return false;
+    const seen = /* @__PURE__ */ new Set();
+    return requirements.every((requirement) => {
+      if (typeof requirement !== "object" || requirement === null) return false;
+      const item = requirement;
+      if (typeof item.hook !== "string" || !item.hook.trim() || typeof item.reason !== "string" || !item.reason.trim() || item.stage !== void 0 && item.stage !== "before_parent" && item.stage !== "after_parent" || seen.has(item.hook)) {
+        return false;
+      }
+      seen.add(item.hook);
+      return true;
+    });
+  });
+}
 var PackageDiscoveryService;
 var init_discovery = __esm({
   "src/packing/discovery.ts"() {
@@ -16420,6 +16935,7 @@ var init_discovery = __esm({
           }
           const effects = Array.isArray(pkgJson.standardagent.effects) && pkgJson.standardagent.effects.every((effectName) => typeof effectName === "string") ? pkgJson.standardagent.effects : void 0;
           const threadEndpoints = Array.isArray(pkgJson.standardagent.threadEndpoints) && pkgJson.standardagent.threadEndpoints.every((endpoint) => typeof endpoint === "string") ? pkgJson.standardagent.threadEndpoints : void 0;
+          const parentHooks = validParentHooks(pkgJson.standardagent.parentHooks) ? pkgJson.standardagent.parentHooks : void 0;
           return {
             packageId: pkgJson.name || pkgName,
             version: pkgJson.version || "0.0.0",
@@ -16428,6 +16944,7 @@ var init_discovery = __esm({
             entryAgents: pkgJson.standardagent.entryAgents,
             ...effects ? { effects } : {},
             ...threadEndpoints ? { threadEndpoints } : {},
+            ...parentHooks ? { parentHooks } : {},
             description: pkgJson.description
           };
         } catch (error) {
@@ -16489,6 +17006,7 @@ var init_discovery = __esm({
           }
           const effects = Array.isArray(pkgJson.standardagent.effects) && pkgJson.standardagent.effects.every((effectName) => typeof effectName === "string") ? pkgJson.standardagent.effects : void 0;
           const threadEndpoints = Array.isArray(pkgJson.standardagent.threadEndpoints) && pkgJson.standardagent.threadEndpoints.every((endpoint) => typeof endpoint === "string") ? pkgJson.standardagent.threadEndpoints : void 0;
+          const parentHooks = validParentHooks(pkgJson.standardagent.parentHooks) ? pkgJson.standardagent.parentHooks : void 0;
           return {
             packageId: pkgJson.name || dirName,
             version: pkgJson.version || "0.0.0",
@@ -16497,6 +17015,7 @@ var init_discovery = __esm({
             entryAgents: pkgJson.standardagent.entryAgents,
             ...effects ? { effects } : {},
             ...threadEndpoints ? { threadEndpoints } : {},
+            ...parentHooks ? { parentHooks } : {},
             description: pkgJson.description
           };
         } catch (error) {
@@ -16525,7 +17044,8 @@ var init_discovery = __esm({
         const hasValidEntryAgents = Array.isArray(f.entryAgents) && f.entryAgents.length > 0 && f.entryAgents.every((e) => typeof e === "string");
         const hasValidEffects = f.effects === void 0 || Array.isArray(f.effects) && f.effects.every((effectName) => typeof effectName === "string");
         const hasValidThreadEndpoints = f.threadEndpoints === void 0 || Array.isArray(f.threadEndpoints) && f.threadEndpoints.every((endpoint) => typeof endpoint === "string");
-        return hasValidEntryAgents && hasValidEffects && hasValidThreadEndpoints;
+        const hasValidParentHooks = f.parentHooks === void 0 || validParentHooks(f.parentHooks);
+        return hasValidEntryAgents && hasValidEffects && hasValidThreadEndpoints && hasValidParentHooks;
       }
       /**
        * Get a package by ID.
@@ -67824,8 +68344,10 @@ var agents_get_default = defineController2(async ({ agents, agentNames, registry
             title: definition.title || definition.name,
             type: definition.type || "ai_human",
             description: definition.description || null,
+            tool_description: definition.toolDescription || null,
             icon: definition.icon || null,
             primary: definition.primary !== false,
+            parentHooks: definition.parentHooks || [],
             ...includeAuthoringDetails ? {
               default_prompt: definition.sideA?.prompt || "",
               default_model: "",
@@ -67861,8 +68383,10 @@ var agents_get_default = defineController2(async ({ agents, agentNames, registry
             title: definition.title || definition.name,
             type: definition.type || "ai_human",
             description: definition.description || null,
+            tool_description: definition.toolDescription || null,
             icon: definition.icon || null,
             primary: definition.primary !== false,
+            parentHooks: definition.parentHooks || [],
             ...includeAuthoringDetails ? {
               default_prompt: definition.sideA?.prompt || "",
               default_model: "",
@@ -68370,7 +68894,7 @@ var config_get_default = defineController2(async ({ config, env: env2, req }) =>
 });
 
 // src/version.ts
-var BUILDER_VERSION = "0.39.0".length > 0 ? "0.39.0" : "dev";
+var BUILDER_VERSION = "0.40.0".length > 0 ? "0.40.0" : "dev";
 
 // src/api/diagnostics.get.ts
 init_LLMRequest();
@@ -69743,8 +70267,10 @@ migrations.reduce(
 );
 
 // src/durable-objects/DurableAgentBuilder.ts
+init_resolver();
 init_types();
 init_scope();
+init_ParentHookResolver();
 var THREAD_PREVIEW_MAX_CHARS = 140;
 var buildThreadPreview = (content) => {
   const collapsed = content.replace(/\s+/g, " ").trim();
@@ -70271,6 +70797,7 @@ var name_get_default = defineController2(async ({ params, agents, prompts, promp
       expose_as_tool: definition.exposeAsTool || false,
       primary: definition.primary !== false,
       tool_description: definition.toolDescription || null,
+      parent_hooks: definition.parentHooks || [],
       env: agentEnv,
       tenvs: agentEnv,
       // deprecated alias