openclaw - 💡(How to fix) Fix [Feature]: Fine-grained hook permission for agent state (separate from conversation access) [2 comments, 3 participants]

Summary

Add a state-only hook permission level so plugins that only track agent lifecycle state (e.g. processing/communicating/sleeping) don't need full conversation access.

Problem to solve

Since 2026.4.26, non-bundled plugins using agent_end, before_agent_reply, or before_tool_call must set hooks.allowConversationAccess: true. This makes sense for hooks that read raw conversation content — but not all plugins using these hooks read any conversation data at all. My plugin, OpenClaw Interaction Bridge, uses agent_end solely to send a state string (processing, communicating, sleeping) to an external display. The only data accessed is sessionKey. No conversation content is read.

Users must grant full conversation access just to get agent state updates on a physical display. The current all-or-nothing gate makes a simple "show me when the AI is thinking" use case require the same permission as "read everything the AI says." This is intimidating for users: "I just want the sleeping face to work — why do I need to grant conversation access?"

Proposed solution

Proposed solution: Add hooks.allowStateAccess: true as a granular alternative to allowConversationAccess. This would cover hooks that only need agent lifecycle state, not conversation content:

• agent_end — "the agent finished its turn"
• before_agent_reply — "the agent started generating"
• before_tool_call — "the agent is using a tool"

These hooks signal that something happened, not what was said. They don't expose conversation text, model output, or user input. Alternative: split agent_end to emit a minimal state-only payload (no conversation content) that doesn't require any permission flag, while hooks that expose content (llm_input, llm_output, before_agent_finalize) remain gated behind allowConversationAccess.

Alternatives considered

• Current workaround (allowConversationAccess: true) — works but over-grants permissions and requires config file editing for basic state tracking
• Removing the hook entirely and using timeouts — loses real-time state transitions, makes display behavior unreliable

Impact

• Affected: All plugin authors using agent lifecycle hooks for state tracking, display drivers, LED indicators, status APIs
• Severity: Blocks workflow — plugins that should work out of the box require manual config editing and a scary permission grant
• Frequency: Always — every install of a state-tracking plugin hits this
• Consequence: Poor out-of-box experience, user confusion about why conversation access is needed for a display, reduced plugin adoption

Evidence/examples

OpenClaw Interaction Bridge — physical display plugin that only needs agent_end for state tracking but must request allowConversationAccess The plugin's README now documents this as an "optional config" step: https://github.com/snarflakes/openclaw-interaction-bridge/blob/development/README.md

Additional information

This is particularly relevant for hardware integration use cases (Raspberry Pi displays, LED strips, status APIs) where the plugin never touches conversation content but needs to know when the agent is active vs idle. Making state tracking permission-free would improve the plugin ecosystem for physical computing and IoT integrations.