Summary

Add a trusted pre-plugin tool policy stage and plugin-owned tool metadata so bundled/trusted plugins can enforce host-level policy and so plugin tools can appear with first-class catalog/display/safety metadata.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode must block mutating tools while approval is pending. That gate must run before ordinary plugin before_tool_call hooks so another plugin cannot reorder, rewrite, or bypass the policy accidentally. Plan Mode tools also need catalog/display/safety metadata without hardcoded core tool catalog patches.

The same primitive applies to budget guards, deployment freezes, workspace policy plugins, dangerous-action wrappers, compliance plugins, and tool catalog extensions.

Current SDK surface

OpenClaw currently has before_tool_call, which can rewrite params, block, or require approval. Core config also filters tools before hook wrapping, and plugin tools have basic catalog fields.

Those surfaces are useful but insufficient: before_tool_call is a normal plugin hook, not a bundled/trusted pre-plugin policy tier. Plugin metadata is not a full display/safety registry, and core-owned tools such as update_plan cannot be safely decorated by plugins.

Proposed solution

Expose trusted policy registration such as:

api.registerToolPolicy({
  id,
  stage: "pre_plugin_hooks",
  trust: "bundled",
  handler,
});

Expose metadata registration such as:

api.registerToolMetadata({
  name,
  title,
  category,
  display,
  safety,
});

Maintainers must also decide whether bundled plugins can decorate core-owned tools such as update_plan, or whether those plugins should own parallel tools.

Reusable plugin examples

• Plan Mode blocks mutating tools while approval is pending and labels Plan Mode tools.
• Budget plugins block or require approval for expensive models/tools.
• Workspace policy plugins block filesystem, browser, or network tools that violate path or data-egress rules.
• Deployment plugins gate deploy and rollback tools during freeze windows.
• Dangerous-action wrappers require scoped approval for high-risk mutations.
• Compliance plugins add audit and safety labels to plugin-owned tools.
• Tool catalog plugins publish display, risk, category, and ownership metadata without hardcoding host display maps.

Decisions needed

• Trust tier for pre-plugin policy hooks.
• Policy decision shape and terminal behavior.
• Plugin tool display/safety metadata schema.
• Whether core-owned tools such as update_plan can be decorated.
• Disablement behavior for policy, metadata, and decorated tool state.
• Negative enforcement for external/untrusted plugins attempting privileged policy registration.

Acceptance criteria

• Fixture trusted policy blocks before ordinary before_tool_call hooks.
• Normal plugins cannot override a trusted block.
• External plugins cannot register trusted pre-plugin policy.
• Fixture tool metadata appears in tool catalog and UI/tool display lookup.
• Disabling the fixture plugin removes metadata, decoration, and policy.

References

• RFC PR: [plugin sdk] docs: plugin host hook RFC #71731
• Source behavior/parity oracle: Plan Mode rebased onto upstream/main + executing-state subsystem #71676
• Full RFC packet: docs/plan/plan-mode-plugin-host-hooks-rfc.md

Current replacement stack (2026-04-30)

#72082 was the earlier implementation vehicle. Current review should use the merged foundation #72287 plus #73384 and draft #74483. For this trusted policy / tool metadata slice, #72287 carries the foundation surface; #73384 adds workflow-facing hardening and contract coverage around trusted policy behavior and plugin-owned metadata semantics. This does not close broader open tool capability/provenance proposals such as #48510, #48503, or #62962.