Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): restore parent session context for subagent hooks (#3565)

Ruiffb12769fd43
diff --git a/.changeset/tidy-subagent-hook-context.md b/.changeset/tidy-subagent-hook-context.md
new file mode 100644
index 000000000..c50f131f6
--- /dev/null
+++ b/.changeset/tidy-subagent-hook-context.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Fix background subagent calls failing the parent session when typed or wildcard hooks subscribe to subagent events. These hooks now receive the parent session context after workflow step boundaries.
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 070cdf06b..982098144 100644
--- a/docs/guides/hooks.md
+++ b/docs/guides/hooks.md
@@ -86,6 +86,10 @@ handle can also automatically resume on later I/O. A hook failure, including a
failed stop, follows the normal
[hook failure behavior](#what-happens-when-a-hook-throws).
+For `subagent.called` and `subagent.completed`, `ctx.session.id` identifies the
+parent session. Typed handlers and `*` handlers receive this context even when
+the subagent event arrives between parent turns.
+
### Narrowing tool results
`toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:
diff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
index 5b4c6c537..41e189991 100644
--- a/e2e/fixtures/agent-workflow-tools/agent/agent.ts
+++ b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
@@ -7,6 +7,42 @@ import { mockModel, type MockModelRequest, type MockModelResponse } from "eve/ev
* service "api"; once the turn holds a tool result the reply echoes it.
*/
function respond(request: MockModelRequest): MockModelResponse | string {
+ const hookScenario = request.userMessages.find((entry) => entry.includes("SUBAGENT-HOOKS:"));
+ if (hookScenario !== undefined) {
+ const mode = /SUBAGENT-HOOKS:(direct|waiting|background)/u.exec(hookScenario)?.[1];
+ if (request.lastUserMessage?.includes("SUBAGENT-HOOKS:AUDIT")) {
+ const audit = request.toolResults.find((entry) => entry.name === "read_subagent_hooks");
+ return audit === undefined
+ ? { toolCalls: [{ name: "read_subagent_hooks", input: {} }] }
+ : JSON.stringify(audit.output);
+ }
+ const tool =
+ mode === "direct"
+ ? "workflow-marker"
+ : mode === "waiting"
+ ? "blocking_agent"
+ : "background_agent";
+ if (!request.toolResults.some((entry) => entry.name === tool)) {
+ return {
+ toolCalls: [
+ {
+ name: tool,
+ input:
+ mode === "direct" ? { message: "Alice's hook audit" } : { service: "hook-audit" },
+ },
+ ],
+ };
+ }
+ const delivery = [...request.userMessages]
+ .reverse()
+ .find((entry) => entry.startsWith("[Task state]\n") || entry.startsWith("Background task "));
+ const result = request.toolResults.find((entry) => entry.name === tool);
+ return (
+ delivery ??
+ (typeof result?.output === "string" ? result.output : JSON.stringify(result?.output))
+ );
+ }
+
const message =
[...request.userMessages]
.reverse()
diff --git a/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.ts b/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.ts
new file mode 100644
index 000000000..cc1a6ddd0
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.ts
@@ -0,0 +1,10 @@
+import { defineHook } from "eve/hooks";
+import { recordSubagentHook } from "../../subagent-hook-audit";
+
+export default defineHook({
+ events: {
+ "subagent.called": (event, ctx) => recordSubagentHook("typed", event, ctx),
+ "subagent.completed": (event, ctx) => recordSubagentHook("typed", event, ctx),
+ "*": (event, ctx) => recordSubagentHook("wildcard", event, ctx),
+ },
+});
diff --git a/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts
new file mode 100644
index 000000000..ded69e8eb
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts
@@ -0,0 +1,9 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { subagentHookAudit } from "../../subagent-hook-audit";
+
+export default defineTool({
+ description: "Read the parent session's durable subagent hook observations.",
+ inputSchema: z.strictObject({}),
+ execute: () => subagentHookAudit.get(),
+});
diff --git a/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts
new file mode 100644
index 000000000..f0e8907b7
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts
@@ -0,0 +1,69 @@
+import { defineEval } from "eve/evals";
+import type { SubagentHookObservation } from "../subagent-hook-audit";
+
+export default (["direct", "waiting", "background"] as const).map((mode) =>
+ defineEval({
+ description: `${mode} subagent delegation delivers typed and wildcard hooks with the parent session context.`,
+ async test(t) {
+ const initial = await t.send(
+ `Alice asks Bob to review a short report and return his result. SUBAGENT-HOOKS:${mode}`,
+ );
+ initial.expectOk();
+ const marker =
+ mode === "direct"
+ ? "Alice's hook audit"
+ : `hook-audit:${mode === "waiting" ? "blocking" : "background"}`;
+ const completed =
+ mode === "waiting"
+ ? initial
+ : await t.target
+ .watchTurn(initial.sessionId, { startIndex: initial.session.state.streamIndex })
+ .result();
+ completed.expectOk();
+ completed.messageIncludes(marker);
+
+ const audit = await completed.session.send(
+ "Alice reviews the recorded hook observations for Bob's completed report. SUBAGENT-HOOKS:AUDIT",
+ );
+ audit.expectOk();
+ audit.calledTool("read_subagent_hooks", { count: 1, status: "completed" });
+ const observations = audit.toolCalls.find(
+ (call) => call.name === "read_subagent_hooks",
+ )?.output;
+ t.eventsSatisfy(
+ "both hook subscriptions receive the parent's exact child result once",
+ (events) => {
+ if (!Array.isArray(observations) || observations.length !== 4) return false;
+ const completion = events.find((event) => event.type === "subagent.completed");
+ if (completion?.type !== "subagent.completed") return false;
+ if (!completion.data.output.startsWith("WORKFLOW-CHILD:")) return false;
+ if (!completed.message?.includes(completion.data.output)) return false;
+ const records = observations as SubagentHookObservation[];
+ return (
+ records.every(
+ (record) =>
+ record.sessionId === initial.sessionId && record.callId === completion.data.callId,
+ ) &&
+ (["typed", "wildcard"] as const).every(
+ (subscriber) =>
+ records.filter(
+ (record) => record.subscriber === subscriber && record.type === "subagent.called",
+ ).length === 1 &&
+ records.filter(
+ (record) =>
+ record.subscriber === subscriber &&
+ record.type === "subagent.completed" &&
+ record.output === completion.data.output,
+ ).length === 1,
+ )
+ );
+ },
+ );
+ t.event("subagent.called", { data: { name: "workflow-marker" }, count: 1 });
+ t.event("subagent.completed", { data: { subagentName: "workflow-marker" }, count: 1 });
+ t.notEvent("session.failed");
+ t.noFailedActions();
+ t.succeeded();
+ },
+ }),
+);
diff --git a/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts
new file mode 100644
index 000000000..dc955b90e
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts
@@ -0,0 +1,36 @@
+import { defineState } from "eve/context";
+import type { HookContext, HookEvent } from "eve/hooks";
+
+export interface SubagentHookObservation {
+ readonly subscriber: "typed" | "wildcard";
+ readonly type: "subagent.called" | "subagent.completed";
+ readonly callId: string;
+ readonly sessionId: string;
+ readonly output?: string;
+}
+
+export const subagentHookAudit = defineState<SubagentHookObservation[]>(
+ "workflow-fixture.subagent-hook-audit",
+ () => [],
+);
+
+export function recordSubagentHook(
+ subscriber: SubagentHookObservation["subscriber"],
+ event: HookEvent,
+ ctx: HookContext,
+): void {
+ if (event.type !== "subagent.called" && event.type !== "subagent.completed") return;
+ if (event.type === "subagent.called" && ctx.session.id !== event.data.sessionId) {
+ throw new Error("Subagent hook received a different parent session.");
+ }
+ subagentHookAudit.update((observations) => [
+ ...observations,
+ {
+ subscriber,
+ type: event.type,
+ callId: event.data.callId,
+ sessionId: ctx.session.id,
+ output: event.type === "subagent.completed" ? event.data.output : undefined,
+ },
+ ]);
+}
diff --git a/packages/eve/src/context/providers/session.ts b/packages/eve/src/context/providers/session.ts
index c446429bc..67566560e 100644
--- a/packages/eve/src/context/providers/session.ts
+++ b/packages/eve/src/context/providers/session.ts
@@ -6,12 +6,14 @@ import {
SessionIdKey,
SessionKey,
} from "#context/keys.js";
+import type { ContextReader } from "#context/key.js";
+import type { HarnessSession } from "#harness/types.js";
import type { FrameworkContextProvider } from "#context/provider.js";
import { getHarnessEmissionState } from "#harness/emission.js";
-export const sessionProvider: FrameworkContextProvider<Session> = {
+export const sessionProvider = {
key: SessionKey,
- create(ctx, session) {
+ create(ctx: ContextReader, session: Pick<HarnessSession, "state">) {
const currentAuth = ctx.require(AuthKey);
const emission = getHarnessEmissionState(session.state);
const turnId = emission.turnId.length > 0 ? emission.turnId : `turn_${emission.sequence}`;
@@ -28,4 +30,4 @@ export const sessionProvider: FrameworkContextProvider<Session> = {
}),
};
},
-};
+} satisfies FrameworkContextProvider<Session>;
diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
index 13c78ea6b..1d9a2207c 100644
--- a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
@@ -1,10 +1,12 @@
import { beforeEach, expect, it, vi } from "vitest";
import { ContextContainer, loadContext } from "#context/container.js";
-import { SessionIdKey, SessionKey, SessionTitleKey } from "#context/keys.js";
+import { AuthKey, SessionIdKey, SessionKey, SessionTitleKey } from "#context/keys.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { emitSubagentEventStep } from "#execution/tools/subagent/emit-event-step.js";
import { createTestSessionState } from "#internal/testing/session-state.js";
+import type { MessageStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
+import type { HookContext, HookEvent, StreamEventHook } from "#public/definitions/hook.js";
import { createRuntimeHookRegistry } from "#runtime/hooks/registry.js";
import {
BundleKey,
@@ -19,46 +21,71 @@ vi.mock("#context/serialize.js", () => ({
beforeEach(() => vi.resetAllMocks());
-it.each([false, true])(
- "delivers completion to typed and wildcard hooks and releases the writer (hook fails: %s)",
- async (fails) => {
+const events: UnstampedMessageStreamEvent[] = [
+ {
+ type: "subagent.called",
+ data: {
+ callId: "call",
+ name: "research",
+ toolName: "research",
+ sessionId: "parent",
+ childSessionId: "child",
+ childStreamPath: "/child",
+ workflowId: "workflow",
+ turnId: "turn",
+ sequence: 0,
+ },
+ },
+ {
+ type: "subagent.completed",
+ data: { callId: "call", subagentName: "research", output: "done" },
+ },
+];
+
+it.each(
+ events.flatMap((event) =>
+ (["typed", "wildcard", "both"] as const).flatMap((subscription) =>
+ [false, true].map((fails) => ({ event, subscription, fails })),
+ ),
+ ),
+)(
+ "restores parent context for $event.type ($subscription, hook fails: $fails)",
+ async ({ event, subscription, fails }) => {
const calls: string[] = [];
const ctx = new ContextContainer();
ctx.set(SessionIdKey, "parent");
- ctx.set(SessionKey, {
- sessionId: "parent",
- auth: { current: null, initiator: null },
- turn: { id: "turn", sequence: 0 },
- });
+ ctx.set(AuthKey, null);
+ // SessionKey is virtual: a production deserializer cannot restore it.
+ expect(ctx.has(SessionKey)).toBe(false);
ctx.set(ChannelKey, {
kind: "test",
state: {},
- "subagent.completed"(_data, adapterCtx) {
+ [event.type](_data: unknown, adapterCtx: { state: unknown }) {
calls.push("adapter");
- adapterCtx.state = { completed: true };
+ adapterCtx.state = { delivered: true };
},
});
+ const handler = (kind: string) => async (received: HookEvent, hookCtx: HookContext) => {
+ expect(hookCtx.session.id).toBe("parent");
+ expect(hookCtx.session.auth).toEqual({ current: null, initiator: null });
+ expect(received.type).toBe(event.type);
+ if (received.type === "subagent.completed") expect(received.data.output).toBe("done");
+ expect(loadContext()).toBe(ctx);
+ calls.push(kind);
+ if (fails) throw new Error("subagent subscriber failed");
+ ctx.set(SessionTitleKey, "Research event received");
+ };
+ const handlers: Record<string, StreamEventHook<MessageStreamEvent>> = {};
+ if (subscription !== "wildcard") handlers[event.type] = handler("typed");
+ if (subscription !== "typed") handlers["*"] = handler("wildcard");
const hookRegistry = createRuntimeHookRegistry([
{
- slug: "completion",
- logicalPath: "hooks/completion.ts",
- sourceId: "hooks/completion.ts",
+ slug: "subagent-events",
+ logicalPath: "hooks/subagent-events.ts",
+ sourceId: "hooks/subagent-events.ts",
sourceKind: "module",
exportName: undefined,
- events: {
- "subagent.completed": async (event, hookCtx) => {
- expect(hookCtx.session.id).toBe("parent");
- if (event.type !== "subagent.completed") throw new Error("Unexpected event type");
- expect(event.data.output).toBe("done");
- expect(loadContext()).toBe(ctx);
- calls.push("typed");
- if (fails) throw new Error("completion subscriber failed");
- ctx.set(SessionTitleKey, "Completed research");
- },
- "*": async (event) => {
- calls.push(`wildcard:${event.type}`);
- },
- },
+ events: handlers,
},
]);
ctx.set(BundleKey, {
@@ -69,10 +96,9 @@ it.each([false, true])(
hookRegistry,
} as CompiledBundle);
vi.mocked(deserializeContext).mockResolvedValue(ctx);
- vi.mocked(serializeContext).mockImplementation((context) => ({
- title: context.get(SessionTitleKey),
- channelState: context.get(ChannelKey)?.state,
- }));
+ vi.mocked(serializeContext).mockImplementation((context) =>
+ Object.fromEntries([...context.entries()].map(([key, value]) => [key.name, value])),
+ );
const chunks: Uint8Array[] = [];
const stream = new WritableStream<Uint8Array>({
write(chunk) {
@@ -81,25 +107,29 @@ it.each([false, true])(
},
});
const emitted = emitSubagentEventStep({
- event: {
- type: "subagent.completed",
- data: { callId: "call", subagentName: "research", output: "done" },
- },
+ event,
sessionWritable: stream,
serializedContext: {},
sessionState: createTestSessionState({ sessionId: "parent" }),
});
+ const firstHandler = subscription === "wildcard" ? "wildcard" : "typed";
if (fails) {
- await expect(emitted).rejects.toThrow("completion subscriber failed");
- expect(calls).toEqual(["adapter", "stream", "typed"]);
+ await expect(emitted).rejects.toThrow("subagent subscriber failed");
+ expect(calls).toEqual(["adapter", "stream", firstHandler]);
} else {
- await expect(emitted).resolves.toEqual({
- serializedContext: { title: "Completed research", channelState: { completed: true } },
- });
- expect(calls).toEqual(["adapter", "stream", "typed", "wildcard:subagent.completed"]);
+ const result = await emitted;
+ expect(result.serializedContext[SessionTitleKey.name]).toBe("Research event received");
+ expect(result.serializedContext[SessionKey.name]).toBeUndefined();
+ expect(ctx.require(ChannelKey).state).toEqual({ delivered: true });
+ expect(calls).toEqual([
+ "adapter",
+ "stream",
+ firstHandler,
+ ...(subscription === "both" ? ["wildcard"] : []),
+ ]);
}
expect(chunks).toHaveLength(1);
- expect(new TextDecoder().decode(chunks[0])).toContain('"type":"subagent.completed"');
+ expect(new TextDecoder().decode(chunks[0])).toContain(`"type":"${event.type}"`);
expect(stream.locked).toBe(false);
},
);
diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.ts
index 5ac31aede..f2f3fdd83 100644
--- a/packages/eve/src/execution/tools/subagent/emit-event-step.ts
+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.ts
@@ -1,3 +1,4 @@
+import { sessionProvider } from "#context/providers/session.js";
import { contextStorage } from "#context/container.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { readDurableSession, type DurableSessionState } from "#execution/durable-session-store.js";
@@ -18,6 +19,7 @@ export async function emitSubagentEventStep(input: {
const ctx = await deserializeContext(input.serializedContext);
const bundle = ctx.require(BundleKey);
const session = readDurableSession(input.sessionState);
+ ctx.setVirtualContext(sessionProvider.key, sessionProvider.create(ctx, session).value);
const sink = createSessionEventSink({
abortSignal: undefined,
adapter: ctx.require(ChannelKey),