Summary

• Problem: @openclaw/sdk exposes oc.tools.invoke() as an unsupported scaffold while the Gateway only supports direct tool invocation through HTTP /tools/invoke.
• Why it matters: SDK clients need a protocol-defined tool invocation path that preserves Gateway policy, owner-only filtering, and plugin approval semantics.
• What changed: added tools.invoke protocol schemas, method registration/scope, a Gateway handler, shared direct-tool invocation core reused by HTTP, SDK typing/client support, docs, changelog, and targeted tests.
• What did NOT change (scope boundary): did not broaden HTTP auth behavior, did not bypass existing tool policies, and did not allow high-risk direct tools unless the existing gateway.tools.allow path permits them.

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 #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: N/A
• Missing detection / guardrail: N/A
• Contributing context (if known): the SDK had an unsupported oc.tools.invoke() placeholder and the existing direct invocation implementation lived only in the HTTP route.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: packages/sdk/src/index.test.ts, src/gateway/server-methods/tools-invoke.test.ts, src/gateway/protocol/index.test.ts, src/gateway/method-scopes.test.ts, src/gateway/tools-invoke-http.test.ts, src/agents/pi-tools.before-tool-call.e2e.test.ts
• Scenario the test should lock in: SDK calls tools.invoke, Gateway validates the params/result contract, method scopes require operator write, direct invoke still uses Gateway allow/deny filtering, and plugin approvals can return typed approval-required state without waiting when confirm: true is omitted.
• Why this is the smallest reliable guardrail: these tests cover the SDK client seam, protocol validation, handler mapping, shared HTTP behavior, and plugin approval mode without broad end-to-end tool execution setup.
• Existing test that already covers this (if any): existing HTTP direct invocation tests covered /tools/invoke; this PR extends that path through the shared core.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

SDK clients can call oc.tools.invoke("tool-name", { args, sessionKey, agentId, confirm, idempotencyKey }). Without confirm: true, plugin approval requests return a typed { ok: false, requiresApproval: true, approvalId, error } result instead of waiting for approval and executing.

Diagram (if applicable)

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

After:
SDK -> tools.invoke RPC -> shared direct tool invoke core -> policy/hooks/approval/tool
HTTP -> /tools/invoke -> shared direct tool invoke core -> policy/hooks/approval/tool

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 adds a direct tool invocation RPC, so the handler requires operator.write, treats only operator.admin callers as owner for owner-only tools, reuses the same direct-invocation Gateway tool allow/deny filtering as HTTP /tools/invoke, runs the existing before-tool-call/plugin approval pipeline, and returns typed approval-required results when callers omit confirm: true.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): Gateway RPC / SDK
• Relevant config (redacted): default test config

Steps

1. Call oc.tools.invoke("demo", { args: { input: "hello" } }) from the SDK.
2. Call Gateway tools.invoke with { name, args, sessionKey, agentId, confirm }.
3. Exercise a plugin approval request without confirm: true.

Expected

• SDK sends tools.invoke RPC params.
• Gateway validates params, resolves the scoped tool through normal policy, and returns success or typed refusal.
• Plugin approval returns requiresApproval: true without executing when confirm: true is omitted.

Actual

• Matches expected in targeted tests.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: SDK tools.invoke request construction, protocol validation, method scope registration, Gateway handler mapping, shared HTTP direct invoke behavior, plugin approval request-only behavior, formatting, whitespace, and TypeScript checks.
• Edge cases checked: invalid params, admin owner context, typed approval-required result, HTTP high-risk tool deny filtering, plugin/core tool fallback, hook-blocked calls, tool input/auth errors, and agent/session mismatch handling in the core path.
• What you did not verify: live Gateway invocation against a real external plugin approval UI.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

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: direct tool invocation is a sensitive Gateway surface.
  • Mitigation: require operator scope, preserve owner-only filtering, reuse Gateway direct-tool allow/deny filtering, and keep plugin approval gates in the execution path.