feat: expose active model plugin context

CHANGELOG.md

@@ -12,6 +12,7 @@ Docs: https://docs.openclaw.ai
 - Plugin SDK: deprecate public subpaths currently used by only one or two bundled plugin owners, keeping them importable while steering new plugin code to focused shared SDK seams or plugin-owned APIs.
 - Plugin SDK: remove the owner-specific `provider-auth-login` public subpath after moving Chutes, GitHub Copilot, and OpenAI Codex auth flows back to provider-owned modules.
 - Plugin SDK: remove provider-specific model, stream, and xAI compatibility helpers from public exports after moving bundled callers to provider-owned modules.
+- Plugin SDK: expose runtime-supplied active model metadata to native plugin tool factories for diagnostics and plugin-owned policy decisions. Fixes #77857. Thanks @jamiezigelbaum.
 - QA/Mantis: add Telegram live PR evidence automation with Convex-leased credentials, Crabbox transcript capture, motion GIF previews, and inline PR comments.
 - QA/Mantis: add a Telegram desktop scenario builder that leases Crabbox, installs native Telegram Desktop, configures an OpenClaw Telegram gateway with leased bot credentials, and records VNC screenshot/video artifacts.
 - Discord/voice: add realtime voice diagnostics for speaker turns, playback resets, barge-in detection, and audio cutoff analysis.

docs/plugins/building-plugins.md

@@ -248,6 +248,14 @@ register(api) {
 }
 ```
 
+Tool factories receive a runtime-supplied context object. Use
+`ctx.activeModel` when a tool needs to log, display, or adapt to the active
+model for the current turn. The object can include `provider`, `modelId`, and
+`modelRef`. Treat it as informational runtime metadata, not as a security
+boundary against the local operator, installed plugin code, or a modified
+OpenClaw runtime. For sensitive local tools, keep an explicit plugin or operator
+opt-in and fail closed when the active model metadata is missing or unsuitable.
+
 Every tool registered with `api.registerTool(...)` must also be declared in the
 plugin manifest:
 

src/agents/openclaw-plugin-tools.ts

@@ -24,6 +24,7 @@ type ResolveOpenClawPluginToolsOptions = OpenClawPluginToolOptions & {
   sandboxRoot?: string;
   modelHasVision?: boolean;
   modelProvider?: string;
+  modelId?: string;
   allowMediaInvokeCommands?: boolean;
   requesterAgentIdOverride?: string;
   requireExplicitMessageTarget?: boolean;

src/agents/openclaw-tools.plugin-context.test.ts

@@ -42,6 +42,22 @@ describe("openclaw plugin tool context", () => {
     expect(result.context.sessionId).toBe("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
   });
 
+  it("forwards runtime-owned active model metadata", () => {
+    const result = resolveOpenClawPluginToolInputs({
+      options: {
+        config: {} as never,
+        modelProvider: " local-provider ",
+        modelId: " local-model ",
+      },
+    });
+
+    expect(result.context.activeModel).toStrictEqual({
+      provider: "local-provider",
+      modelId: "local-model",
+      modelRef: "local-provider/local-model",
+    });
+  });
+
   it("infers the default agent workspace when workspaceDir is omitted", () => {
     const workspaceDir = path.join(process.cwd(), "tmp-main-workspace");
     const result = resolveOpenClawPluginToolInputs({

src/agents/openclaw-tools.plugin-context.ts

@@ -15,6 +15,8 @@ export type OpenClawPluginToolOptions = {
   workspaceDir?: string;
   config?: OpenClawConfig;
   fsPolicy?: ToolFsPolicy;
+  modelProvider?: string;
+  modelId?: string;
   requesterSenderId?: string | null;
   requesterAgentIdOverride?: string;
   senderIsOwner?: boolean;
@@ -42,6 +44,16 @@ export function resolveOpenClawPluginToolInputs(params: {
       ? undefined
       : resolveAgentWorkspaceDir(resolvedConfig, sessionAgentId);
   const workspaceDir = resolveWorkspaceRoot(options?.workspaceDir ?? inferredWorkspaceDir);
+  const modelProvider = options?.modelProvider?.trim();
+  const modelId = options?.modelId?.trim();
+  const activeModel =
+    modelProvider || modelId
+      ? {
+          ...(modelProvider ? { provider: modelProvider } : {}),
+          ...(modelId ? { modelId } : {}),
+          ...(modelProvider && modelId ? { modelRef: `${modelProvider}/${modelId}` } : {}),
+        }
+      : undefined;
   const deliveryContext = normalizeDeliveryContext({
     channel: options?.agentChannel,
     to: options?.agentTo,
@@ -60,6 +72,7 @@ export function resolveOpenClawPluginToolInputs(params: {
       agentId: sessionAgentId,
       sessionKey: options?.agentSessionKey,
       sessionId: options?.sessionId,
+      activeModel,
       browser: {
         sandboxBridgeUrl: options?.sandboxBrowserBridgeUrl,
         allowHostControl: options?.allowHostBrowserControl,

src/plugin-sdk/core.ts

@@ -121,7 +121,11 @@ export type {
   UnifiedModelCatalogSource,
 } from "../model-catalog/types.js";
 export type { ProviderRuntimeModel } from "../plugins/provider-runtime-model.types.js";
-export type { OpenClawPluginToolContext, OpenClawPluginToolFactory } from "../plugins/types.js";
+export type {
+  OpenClawPluginActiveModelContext,
+  OpenClawPluginToolContext,
+  OpenClawPluginToolFactory,
+} from "../plugins/types.js";
 export type {
   MemoryPluginCapability,
   MemoryPluginPublicArtifact,

src/plugins/tool-types.ts

@@ -4,6 +4,12 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { HookEntry } from "../hooks/types.js";
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
 
+export type OpenClawPluginActiveModelContext = {
+  provider?: string;
+  modelId?: string;
+  modelRef?: string;
+};
+
 /** Trusted execution context passed to plugin-owned agent tool factories. */
 export type OpenClawPluginToolContext = {
   config?: OpenClawConfig;
@@ -19,6 +25,12 @@ export type OpenClawPluginToolContext = {
   sessionKey?: string;
   /** Ephemeral session UUID - regenerated on /new and /reset. Use for per-conversation isolation. */
   sessionId?: string;
+  /**
+   * Runtime-supplied active model metadata for informational use, diagnostics,
+   * and plugin-owned policy decisions. This is not a security boundary against
+   * the local operator, installed plugin code, or a modified OpenClaw runtime.
+   */
+  activeModel?: OpenClawPluginActiveModelContext;
   browser?: {
     sandboxBridgeUrl?: string;
     allowHostControl?: boolean;

src/plugins/types.ts

@@ -151,6 +151,7 @@ export type {
   PluginFormat,
 } from "./manifest-types.js";
 export type {
+  OpenClawPluginActiveModelContext,
   OpenClawPluginHookOptions,
   OpenClawPluginToolContext,
   OpenClawPluginToolFactory,