openclaw - 💡(How to fix) Fix [Feature] Hook: tool:before-execute event for exec/tool pre-execution interception [1 comments, 2 participants]

Summary

Add a hook event that fires before AI executes a tool or exec command, enabling pre-execution approval/interception

Problem to solve

AI agents can autonomously decide to execute shell commands or tools (via exec tool). Currently there is no mechanism to intercept this decision point. The existing hook system only fires on message:preprocessed and agent:bootstrap events — these intercept user messages but cannot see when the AI itself decides to call a tool or run exec.

The security problem: when a user implicitly authorizes an action (e.g. "yes delete those files" or "clean up that folder"), the AI may immediately execute exec calls without any confirmation prompt. The message:preprocessed hook only sees the user's original message — it cannot detect that the AI has decided to run exec, and cannot inject a skill call or approval step before the exec actually fires.

Use case: A "wake-up-rec" skill that wants to enforce screen capture + user confirmation before any file deletion or exec. Today this is impossible because the hook fires on the user's message (before the AI decides on exec), not on the AI's decision to actually run exec.

Proposed solution

Introduce a new hook event tool:before-execute (or exec:before) that fires when the AI decides to execute a tool or run exec, before the actual execution happens.

Proposed API:

// Hook handler signature
const handler: HookHandler = async (event) => {
  if (event.type !== "tool" || event.action !== "before-execute") {
    return;
  }
  
  const ctx = event.context as {
    toolName: string,      // "exec", "browser", etc.
    command?: string,      // for exec: the actual shell command
    args?: object,        // tool arguments
    sessionKey: string,
  };
  
  // Hook can:
  // - Return { approved: true } → allow execution
  // - Return { approved: false, reason: "..." } → deny + return error to AI
  // - Modify args (sanitize commands) before execution
  // - Inject approval workflow (e.g. send Feishu message, await user reply)
};

This enables:

1. Pre-execution approval hooks (confirm before dangerous exec)
2. Command sanitization/filtering
3. Audit logging of all exec calls
4. Rate limiting on exec calls per session

The hook should support both sync (allow/deny immediately) and async (await external approval) patterns.

Alternatives considered

1. exec-approvals.json (current): Works for approval but requires a separate daemon socket process, and has limitations with async approval flows and Feishu integration.

2. Text injection via message:preprocessed: Hooks inject text into the user's message to suggest calling a skill, but the AI can ignore this and execute exec directly. Not enforceable.

3. System prompt rules: Adding "always confirm before exec" to SOUL.md — relies on AI self-discipline, not enforceable, and wastes tokens.

4. Mandatory skill invocation via hook: Having the hook inject a skill call like skill:approve-exec before every exec — hacky and fragile.

None of these provide a genuine pre-execution interception point. Only a dedicated hook event can achieve that.

Impact

Affected users: Anyone running OpenClaw agents with exec tool access, especially in shared/group environments.

Severity: High for security-conscious deployments. Currently if the AI decides to run an exec, no hook can stop it.

Frequency: The gap manifests whenever the AI autonomously decides to execute a command in response to user intent (which is the primary use case for AI agents).

Consequences: Without this, dangerous operations (file deletion, system config changes) cannot be intercepted and confirmed before execution, creating a security gap.

Evidence/examples

Example scenario:

1. User says "clean up those leftover files in workspace"
2. AI understands intent, decides to run rm -rf ~/.openclaw/workspace/trading-hub
3. message:preprocessed hook only sees the user's message — no "delete" keyword is matched (the word "clean up" is not in the hook's trigger list)
4. AI executes rm command directly — no interception possible

The hook system correctly identifies the message, but the decision to execute exec is made inside the AI's reasoning process, invisible to the hook.

OpenClaw hooks documentation: https://docs.openclaw.ai/automation/hooks Current supported events: agent:bootstrap, gateway:startup, message:preprocessed, message:sent, command

Additional information

No response