Guardrails: skip hooks for internal runs

Reapor-Yurnero · Feb 1, 2026 · Feb 1, 2026 · Feb 1, 2026 · Feb 1, 2026 · Feb 1, 2026
commit 211dde8515c05d3ee9b4fc595ae7ce018f163546
diff --git a/extensions/gpt-oss-safeguard/index.ts b/extensions/gpt-oss-safeguard/index.ts
@@ -18,10 +18,10 @@ import {
   type OpenClawPluginApi,
   cleanupTempDir,
   collectText,
+  createGuardrailRunId,
   createGuardrailPlugin,
   createGuardrailTempDir,
   extractMessagesContent,
-  generateSessionId,
   loadRunEmbeddedPiAgent,
 } from "openclaw/plugin-sdk";
 
@@ -185,7 +185,7 @@ async function callSafeguard(params: {
   let tmpDir: string | null = null;
   try {
     tmpDir = await createGuardrailTempDir("safeguard");
-    const sessionId = generateSessionId("safeguard");
+    const sessionId = createGuardrailRunId("gpt-oss-safeguard");
     const sessionFile = path.join(tmpDir, "session.json");
 
     const runEmbeddedPiAgent = await loadRunEmbeddedPiAgent();

diff --git a/src/agents/pi-embedded-runner/run/attempt.ts b/src/agents/pi-embedded-runner/run/attempt.ts
@@ -87,6 +87,7 @@ import { resolveSandboxRuntimeStatus } from "../../sandbox/runtime-status.js";
 import { buildTtsSystemPromptHint } from "../../../tts/tts.js";
 import { isTimeoutError } from "../../failover-error.js";
 import { getGlobalHookRunner } from "../../../plugins/hook-runner-global.js";
+import { isGuardrailRunId } from "../../../plugins/guardrails-utils.js";
 import { MAX_IMAGE_BYTES } from "../../../media/constants.js";
 import type { ToolHookContext } from "../../pi-tool-definition-adapter.js";
 
@@ -734,7 +735,9 @@ export async function runEmbeddedAttempt(
       }
 
       // Get hook runner once for both before_agent_start and agent_end hooks
-      const hookRunner = getGlobalHookRunner();
+      const skipGuardrailHooks =
+        isGuardrailRunId(params.sessionId) || isGuardrailRunId(params.runId);
+      const hookRunner = skipGuardrailHooks ? null : getGlobalHookRunner();
 
       let promptError: unknown = null;
       try {

diff --git a/src/plugin-sdk/index.ts b/src/plugin-sdk/index.ts
@@ -133,13 +133,15 @@ export {
   buildToolCallSummary,
   cleanupTempDir,
   collectText,
+  createGuardrailRunId,
   createGuardrailPlugin,
   createGuardrailTempDir,
   extractMessagesContent,
   extractTextFromContent,
   extractToolResultText,
   generateSessionId,
   isStageEnabled,
+  isGuardrailRunId,
   loadRunEmbeddedPiAgent,
   resolveBlockMode,
   resolveStageConfig,

diff --git a/src/plugins/guardrails-utils.test.ts b/src/plugins/guardrails-utils.test.ts
@@ -3,10 +3,12 @@ import { describe, expect, it } from "vitest";
 import {
   appendWarningToToolResult,
   buildToolCallSummary,
+  createGuardrailRunId,
   extractMessagesContent,
   extractTextFromContent,
   extractToolResultText,
   generateSessionId,
+  isGuardrailRunId,
   isStageEnabled,
   replaceToolResultWithWarning,
   resolveBlockMode,
@@ -154,6 +156,19 @@ describe("replaceToolResultWithWarning", () => {
   });
 });
 
+describe("guardrail run id helpers", () => {
+  it("creates guardrail run ids with the expected prefix", () => {
+    const runId = createGuardrailRunId("gpt-oss-safeguard");
+    expect(runId.startsWith("guardrail:")).toBe(true);
+    expect(isGuardrailRunId(runId)).toBe(true);
+  });
+
+  it("returns false for non-guardrail ids", () => {
+    expect(isGuardrailRunId("session-123")).toBe(false);
+    expect(isGuardrailRunId(undefined)).toBe(false);
+  });
+});
+
 describe("buildToolCallSummary", () => {
   it("builds JSON summary of tool call", () => {
     const summary = buildToolCallSummary("readFile", "call-123", { path: "/test.txt" });

diff --git a/src/plugins/guardrails-utils.ts b/src/plugins/guardrails-utils.ts
@@ -283,6 +283,26 @@ export function generateSessionId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
+const GUARDRAIL_RUN_ID_PREFIX = "guardrail:";
+
+/**
+ * Generate a unique run/session ID for guardrail-internal model calls.
+ */
+export function createGuardrailRunId(guardrailId: string): string {
+  const safeId = guardrailId.trim() || "unknown";
+  return `${GUARDRAIL_RUN_ID_PREFIX}${generateSessionId(safeId)}`;
+}
+
+/**
+ * Check if a run/session ID belongs to a guardrail-internal call.
+ */
+export function isGuardrailRunId(id?: string | null): boolean {
+  if (!id) {
+    return false;
+  }
+  return id.startsWith(GUARDRAIL_RUN_ID_PREFIX);
+}
+
 // ============================================================================
 // JSON Utilities
 // ============================================================================