openclaw - 💡(How to fix) Fix [Bug]: bundled MCP tools lose session context in before_tool_call hooks [2 comments, 2 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

Bundled MCP tools can fire before_tool_call hooks without the session context that core tools such as exec receive, so hook handlers cannot read fields such as sessionKey, sessionId, agentId, or runId for MCP tool calls.

Steps to reproduce

1. Install a local plugin that registers a before_tool_call hook and logs both the event payload and hook context.
2. Trigger a normal built-in/core tool call such as exec.
3. Trigger a bundled MCP tool call from the same OpenClaw session.
4. Compare the logged hook context for both calls.

Observed locally: core tools include session-related context, while the bundled MCP tool path does not include the same session/run context.

Expected behavior

before_tool_call hooks should receive consistent context for bundled MCP tools and normal OpenClaw tools. At minimum, the MCP tool path should preserve the same session/run fields already available when wrapping ordinary tools, such as agentId, sessionKey, sessionId, runId, channel id when applicable, tracing, loop detection, and onToolOutcome plumbing.

Actual behavior

For bundled MCP tools, the hook fires, but the context lacks the session/run data that is present for non-MCP tools in the same session. This prevents plugins from correlating the MCP tool call with the active OpenClaw session.

OpenClaw version

Current checkout reports [email protected] from pnpm docs:list.

Operating system

macOS development checkout; the affected code path is platform-independent TypeScript runtime code.

Install method

pnpm dev / local development checkout

Model

NOT_ENOUGH_INFO

Provider / routing chain

NOT_ENOUGH_INFO

Additional provider/model setup details

NOT_ENOUGH_INFO

Logs, screenshots, and evidence

Code-path analysis points to the bundled MCP tool materialization path skipping the wrapper that supplies hook context:

src/agents/pi-embedded-runner/run/attempt.ts
  getOrCreateSessionMcpRuntime({ sessionId: params.sessionId, sessionKey: params.sessionKey, ... })
  materializeBundleMcpToolsForRun({ runtime: bundleMcpSessionRuntime, ... })

src/agents/pi-bundle-mcp-materialize.ts
  creates agentTool entries for bundled MCP tools
  sets plugin tool metadata with pluginId: "bundle-mcp"
  does not wrap the tool with wrapToolWithBeforeToolCallHook(..., ctx)

src/agents/pi-embedded-runner/tool-split.ts
  passes the resulting tool list onward

src/agents/pi-tool-definition-adapter.ts
  fallback path calls runBeforeToolCallHook({ toolName, params, toolCallId }) without ctx

By contrast, ordinary tools are wrapped with hook context before they reach the adapter:

src/agents/pi-tools.ts
  wrapToolWithBeforeToolCallHook(tool, {
    agentId,
    config,
    cwd,
    sessionKey,
    sessionId,
    runId,
    trace,
    loopDetection,
    onToolOutcome,
    ...
  })

src/agents/openclaw-tools.ts
  also builds HookContext with session-related fields for the tool wrapper

This means the MCP runtime receives sessionId / sessionKey when it is created, but those values are not threaded into the before_tool_call hook context for the materialized bundled MCP tools.

Impact and severity

Affected: plugins that use before_tool_call hooks to audit, gate, or correlate tool calls, especially MCP tools.

Severity: workflow-blocking for plugins that need per-session or per-channel policy enforcement around MCP tools.

Frequency: appears deterministic for direct bundled MCP tool calls on this path.

Consequence: plugins can see the MCP tool call and params, but cannot reliably identify which OpenClaw session/run caused it.

Additional information

Related to #19381, but this is not the same reported surface. #19381 covered plugin-registered tools and is closed as stale. This report concerns direct bundled MCP tools created through the bundle MCP materialization path.

Potential fix direction: pass a HookContext into materializeBundleMcpToolsForRun, or wrap the resulting bundled MCP tools in attempt.ts with wrapToolWithBeforeToolCallHook before they are converted by toToolDefinitions(). The context should mirror the nearby catalog/core tool context, including values such as:

{
  agentId: sessionAgentId,
  config: params.config,
  cwd: effectiveWorkspace,
  sessionKey: sandboxSessionKey,
  sessionId: params.sessionId,
  runId: params.runId,
  channelId: params.currentChannelId,
  trace: runTrace,
  loopDetection: resolveToolLoopDetectionConfig({ cfg: params.config, agentId: sessionAgentId }),
  onToolOutcome: params.onToolOutcome,
}

That should cause toToolDefinitions() to see an already wrapped tool and avoid the fallback runBeforeToolCallHook(...) call that has no context.