Summary

• Problem: @openclaw/sdk exposes a tools namespace, but oc.tools.invoke() had no Gateway RPC method to call and remained unsupported.
• Why it matters: SDK clients need a typed WebSocket path for generic tool invocation that follows the same Gateway auth, tool policy, deny-list, and plugin approval semantics as the existing HTTP /tools/invoke route.
• What changed: adds tools.invoke to the Gateway RPC surface, protocol schemas, method discovery, scope gating, SDK client/types, and docs; shared Gateway tool-invoke logic now backs both HTTP and RPC paths.
• What did NOT change: no tool policy bypass, no default tool allow-list expansion, no config migration, and no replay cache beyond using idempotencyKey as the stable tool-call id when supplied.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Gateway RPC: add SDK-facing tools.invoke #74705
• Related SDK: stabilize app-client happy path for agents, sessions, runs #74704
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A

Regression Test Plan (if applicable)

N/A

User-visible / Behavior Changes

SDK clients can now call oc.tools.invoke(name, params) through the Gateway. The RPC method accepts name, optional args, sessionKey, agentId, confirm, and idempotencyKey fields.

Diagram (if applicable)

Before:
SDK oc.tools.invoke() -> unsupported error
HTTP POST /tools/invoke -> existing Gateway tool path

After:
SDK oc.tools.invoke() -> WS tools.invoke -> shared Gateway tool path -> policy/deny-list/approval/tool result
HTTP POST /tools/invoke -> shared Gateway tool path -> existing HTTP envelope

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) Yes
• Data access scope changed? (Yes/No) Yes
• If any Yes, explain risk + mitigation: This exposes an existing direct tool-invoke capability over Gateway WS for SDK clients. It is gated by operator.write, reuses the existing Gateway tool policy chain and HTTP deny-list semantics, preserves owner-only filtering for non-admin clients, and reports plugin approval-needed refusals unless the caller explicitly opts into confirm: true.

Repro + Verification

Environment

• OS: macOS local checkout and Ubuntu 24.04 Blacksmith Testbox
• Runtime/container: Node 22 / pnpm dev checkout
• Model/provider: N/A
• Integration/channel (if any): Gateway RPC + SDK
• Relevant config (redacted): default local test config

Steps

1. Call SDK oc.tools.invoke() before this change.
2. Observe it throws the existing unsupported namespace error because no Gateway tools.invoke method exists.
3. Apply this PR and call oc.tools.invoke("sessions_list", { args: {}, sessionKey: "main" }).
4. Verify the SDK sends tools.invoke, the Gateway enforces operator.write, and the response uses a typed tool result/refusal envelope.

Expected

• SDK clients can invoke allowed tools through Gateway RPC.
• Disallowed or approval-required tools do not bypass policy and return typed refusal state.
• HTTP /tools/invoke behavior remains compatible.

Actual

• Implemented as expected in targeted unit, gateway, agent, SDK, SDK e2e, protocol, Swift lint, and build coverage.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: SDK tools.invoke dispatch, Gateway tools.invoke handler success envelope, malformed RPC params rejection, operator.write method scope, HTTP /tools/invoke compatibility, plugin approval-needed typed refusal without opening an approval request by default, and mismatched sessionKey/agentId rejection.
• Edge cases checked: HTTP /tools/invoke compatibility, SDK name field, high-risk deny-list preservation, owner-only filtering path, configured session fallback, gateway.tools.allow/deny precedence, confirm: false approval reporting behavior, and confirm: true approval request behavior.
• What is not verified: live third-party SDK consumer behavior outside the repo tests.

Commands run:

pnpm exec oxfmt --check --threads=1 packages/sdk/src/client.ts packages/sdk/src/index.test.ts packages/sdk/src/types.ts src/gateway/protocol/schema/agents-models-skills.ts src/gateway/server-methods/tools-invoke.ts src/gateway/tools-invoke-http.test.ts src/gateway/tools-invoke-shared.ts
pnpm test src/gateway/tools-invoke-http.test.ts src/gateway/method-scopes.test.ts src/agents/pi-tools.before-tool-call.embedded-mode.test.ts packages/sdk/src/index.test.ts packages/sdk/src/index.e2e.test.ts src/gateway/protocol/index.test.ts -- --reporter=verbose
pnpm protocol:check
git diff --check
git diff --cached --check
pnpm check:docs
git diff --check origin/main...HEAD
pnpm lint:swift
pnpm testbox:run --id tbx_01kqgybv7jcdqmsge5mn24rzy8 -- "bash -lc '... install SwiftLint 0.63.2; OPENCLAW_TESTBOX=1 pnpm check:changed'"
pnpm testbox:run --id tbx_01kqgy113v5sgztapmczc604aw -- "OPENCLAW_TESTBOX=1 pnpm build"

pnpm check:changed passed in a fresh Testbox after installing SwiftLint 0.63.2 into the box for the app lint lane. After rebasing onto current origin/main, pnpm check:docs, pnpm protocol:check, and git diff --check origin/main...HEAD passed locally.

Duplicate / Related Threads

• feat(gateway): add SDK tools.invoke RPC #74786 is already closed as superseded by this PR and does not need to reopen.
• tools/invoke returns "Tool not available: message" in 2026.4.26 even with healthy telegram channel #74780 is config/policy diagnostics for HTTP message, not this SDK RPC.
• [Feature]: Invoke tools directly without LLM round-trip #37131 is broader direct tool invocation and still overlaps HTTP/coding-tool work.
• feat(gateway): wire coding tools into /tools/invoke HTTP surface #63919, fix(gateway): allow memory slot tool plugin invokes #75160, and feat(gateway): add audit logging for gateway tool calls #63557 are active HTTP/tool-policy/audit follow-ups, not duplicates of this RPC gap.
• feat(gateway): add SDK task ledger RPCs #74847 is task ledger RPC work tied to Gateway RPC: add SDK-facing task ledger APIs #74707, separate from tools.invoke.
• prtags.dutiful.dev returned 502 for both group listing and text search, so prtags sync is the only blocked curation write path.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: The new RPC surface could drift from the HTTP tool-invoke behavior over time.
  • Mitigation: HTTP and RPC now share the same Gateway tool-invoke helper, and tests cover both surfaces.
• Risk: Approval behavior could unexpectedly open approval prompts for SDK callers.
  • Mitigation: the default RPC path reports typed approval-needed refusal; callers must pass confirm: true to request approval explicitly.