openclaw - 💡(How to fix) Fix [Feature]: tool:before hook — per-tool-call interception for user feedback & visual audit trail [1 participants]

Summary

Add a tool:before hook event so hooks can intercept individual tool executions before they run, enabling screenshot/screen-recording confirmation workflows without relying on model self-discipline.

Problem to solve

Currently OpenClaw hooks only support: agent:bootstrap (once per session) and message:preprocessed (once per message). There is no event that fires before each individual tool execution.

This makes it impossible to implement visual feedback workflows where:

• Privacy-sensitive operations (file deletion, screenshot, clipboard access) require screenshot confirmation before proceeding
• Multi-step operations are screen-recorded so users can see exactly what was done
• Single-step operations are screenshot before and after to prove correctness

The only available workaround is hoping the AI model "remembers" to do this on its own — which is unreliable, depends on model honesty, and fails consistently in practice. Users have a legitimate right to know what an AI agent is doing on their machine before it happens.

Proposed solution

Add a new hook event tool:before that fires before each tool execution, allowing hooks to intercept, inspect, and conditionally block tool calls.

Proposed handler signature:

const handler = async (event: { type: "tool", action: "before" | "after", toolName: string, // e.g. "exec", "browser", "message" toolCallId: string, params: Record<string, any>, session: Session }) => { // Return options: // { allow: true } → proceed with execution // { allow: false, reason: string } → block, return error to agent // { screenshot: true } → pause, screenshot, resume on user confirm };

The hook receives full tool parameters so it can make context-aware decisions (e.g. only pause on delete operations, not on read operations).

Alternative: extend message:preprocessed to include tool planning metadata so hooks can inject conditional reminders based on which tools will be called.

Alternatives considered

1. Rely on model self-discipline: The agent "remembers" to screenshot/confirm before sensitive operations. This is unreliable and fails consistently in practice — the model does not consistently follow its own guidelines.

2. Bootstrap reminder only: agent:bootstrap fires once per session; the reminder is forgotten after a few turns. Cannot enforce ongoing behavior.

3. message:preprocessed: Fires per message, not per tool call. Cannot distinguish which tools will be called within a message, so hooks cannot make targeted interception decisions.

4. Per-tool configuration: Add a config flag like tools.exec.requireScreenshot: ["delete", "rm", "trash"]. This is more rigid, requires user config for each tool, and cannot handle conditional logic (e.g. "only screenshot if path contains user data").

Impact

Affected users: All OpenClaw users who want visual transparency into what the AI is doing on their machine.

Severity: High for users who prioritize safety and transparency. The current architecture makes it impossible to build trustworthy visual audit trails without this event.

Frequency: Any tool execution that could affect the user's system (exec, file operations, clipboard, screenshots, messages).

Consequences: Without this, users must blindly trust that the AI will "remember" to screenshot/confirm — which it consistently fails to do in practice. This erodes trust and prevents deployment of OpenClaw in security-sensitive environments. With this event, users can build wake-up-rec style workflows that give genuine visual accountability.

Evidence/examples

No response

Additional information

No response