@standardagents/builder 0.39.1 → 0.40.0

package/dist/built-in-routes.js

@@ -6680,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, {
@@ -6696,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) {
@@ -7038,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
         };
       }
       /**
@@ -7428,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,
@@ -7588,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
           });
@@ -8110,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) {
@@ -8147,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;
           }
@@ -8313,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);
           }
@@ -9346,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();
@@ -9356,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);
@@ -9498,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
@@ -9523,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
@@ -9558,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));
@@ -9578,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;
             }
@@ -9597,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);
           }
@@ -9618,9 +9848,13 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         if (executors.length === 0) return message;
         let result = message;
         const threadState = threadStateOverride ?? ThreadStateImpl.fromFlowState(state);
-        for (const executor of executors) {
+        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,
@@ -9646,9 +9880,9 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
         const executors = await this.getHooksForType(state, "after_create_message");
         if (executors.length === 0) return;
         const threadState = threadStateOverride ?? 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_create_message hook:", error);
           }
@@ -9689,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);
           }
@@ -9709,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);
           }
@@ -9731,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);
           }
@@ -9753,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);
           }
@@ -9776,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);
           }
@@ -9809,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);
           }
@@ -9839,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);
           }
@@ -10794,12 +11028,12 @@ ${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 {
             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);
+            const kept = await execute(threadState, hookView, context);
             result = kept.map((hookedMessage) => {
               const original = hookedMessage.id ? byId.get(hookedMessage.id) : void 0;
               if (original) {
@@ -14803,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);
             }
           }
         }
@@ -14930,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(
@@ -15185,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}`);
@@ -15387,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);
@@ -15471,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);
         }
@@ -15478,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.
        */
@@ -15612,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,
@@ -15725,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,
@@ -16116,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)
         };
@@ -16138,6 +16525,7 @@ var init_packing_service = __esm({
           keywords: ["standardagent"],
           standardagent: {
             entryAgents: [agentName],
+            ...parentHooks ? { parentHooks } : {},
             ...effects.length > 0 ? { effects } : {},
             ...threadEndpoints.length > 0 ? { threadEndpoints } : {}
           },
@@ -16433,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"() {
@@ -16531,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",
@@ -16539,6 +16944,7 @@ var init_discovery = __esm({
             entryAgents: pkgJson.standardagent.entryAgents,
             ...effects ? { effects } : {},
             ...threadEndpoints ? { threadEndpoints } : {},
+            ...parentHooks ? { parentHooks } : {},
             description: pkgJson.description
           };
         } catch (error) {
@@ -16600,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",
@@ -16608,6 +17015,7 @@ var init_discovery = __esm({
             entryAgents: pkgJson.standardagent.entryAgents,
             ...effects ? { effects } : {},
             ...threadEndpoints ? { threadEndpoints } : {},
+            ...parentHooks ? { parentHooks } : {},
             description: pkgJson.description
           };
         } catch (error) {
@@ -16636,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.
@@ -67935,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: "",
@@ -67972,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: "",
@@ -68481,7 +68894,7 @@ var config_get_default = defineController2(async ({ config, env: env2, req }) =>
 });
 
 // src/version.ts
-var BUILDER_VERSION = "0.39.1".length > 0 ? "0.39.1" : "dev";
+var BUILDER_VERSION = "0.40.0".length > 0 ? "0.40.0" : "dev";
 
 // src/api/diagnostics.get.ts
 init_LLMRequest();
@@ -69854,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();
@@ -70382,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