feat(plugins): expose runId in agent hook context (#54265)

src/agents/pi-embedded-runner/run.ts

@@ -146,6 +146,7 @@ export async function runEmbeddedPiAgent(
       await ensureOpenClawModelsJson(params.config, agentDir);
       const hookRunner = getGlobalHookRunner();
       const hookCtx = {
+        runId: params.runId,
         agentId: workspaceResolution.agentId,
         sessionKey: params.sessionKey,
         sessionId: params.sessionId,

src/agents/pi-embedded-runner/run/attempt.ts

@@ -1331,6 +1331,7 @@ export async function runEmbeddedAttempt(
           },
         );
         const hookCtx = {
+          runId: params.runId,
           agentId: hookAgentId,
           sessionKey: params.sessionKey,
           sessionId: params.sessionId,
@@ -1463,6 +1464,7 @@ export async function runEmbeddedAttempt(
                   imagesCount: imageResult.images.length,
                 },
                 {
+                  runId: params.runId,
                   agentId: hookAgentId,
                   sessionKey: params.sessionKey,
                   sessionId: params.sessionId,
@@ -1693,6 +1695,7 @@ export async function runEmbeddedAttempt(
                 durationMs: Date.now() - promptStartedAt,
               },
               {
+                runId: params.runId,
                 agentId: hookAgentId,
                 sessionKey: params.sessionKey,
                 sessionId: params.sessionId,
@@ -1755,6 +1758,7 @@ export async function runEmbeddedAttempt(
               usage: getUsageTotals(),
             },
             {
+              runId: params.runId,
               agentId: hookAgentId,
               sessionKey: params.sessionKey,
               sessionId: params.sessionId,

src/plugins/hooks.before-agent-start.test.ts

@@ -175,4 +175,24 @@ describe("before_agent_start hook merger", () => {
     expect(result?.modelOverride).toBe("llama3.3:8b");
     expect(result?.providerOverride).toBe("ollama");
   });
+
+  it("passes runId through the agent context to hook handlers", async () => {
+    const registry = createEmptyPluginRegistry();
+    let capturedCtx: typeof stubCtx | undefined;
+    addTestHook({
+      registry,
+      pluginId: "ctx-spy",
+      hookName: "before_agent_start",
+      handler: ((_event: unknown, ctx: typeof stubCtx) => {
+        capturedCtx = ctx;
+        return {};
+      }) as PluginHookRegistration["handler"],
+    });
+
+    const runner = createHookRunner(registry);
+    await runner.runBeforeAgentStart({ prompt: "test" }, stubCtx);
+
+    expect(capturedCtx).toBeDefined();
+    expect(capturedCtx?.runId).toBe("test-run-id");
+  });
 });

src/plugins/hooks.test-helpers.ts

@@ -40,6 +40,7 @@ export function createMockPluginRegistry(
 }
 
 export const TEST_PLUGIN_AGENT_CTX: PluginHookAgentContext = {
+  runId: "test-run-id",
   agentId: "test-agent",
   sessionKey: "test-session",
   sessionId: "test-session-id",

src/plugins/types.ts

@@ -1682,6 +1682,8 @@ export const isPromptInjectionHookName = (hookName: PluginHookName): boolean =>
 
 // Agent context shared across agent hooks
 export type PluginHookAgentContext = {
+  /** Unique identifier for this agent run. */
+  runId?: string;
   agentId?: string;
   sessionKey?: string;
   sessionId?: string;