openclaw - 💡(How to fix) Fix Feature: Pre/Post Tool Use Hooks (programmable safety rails) [2 comments, 3 participants]

Summary

Add configurable shell-script hooks that run before and after every tool execution, allowing users to programmatically approve, deny, or augment tool calls.

Motivation

Claude Code's architecture (and the Claw Code clean-room rewrite) implements a hook system where shell commands run at PreToolUse and PostToolUse stages. This enables:

• Safety guardrails: A PreToolUse hook could validate exec commands against security rules before execution
• Audit logging: A PostToolUse hook could log all external actions (sends, API calls)
• Custom workflows: Hooks could inject additional context, transform tool inputs, or gate dangerous operations

For personal AI assistants (like those built on OpenClaw), this is especially valuable — users could define workspace-specific policies that the agent can't bypass, enforced at the tool layer rather than relying solely on prompt instructions.

Proposed Design

Configuration

hooks:
  preToolUse:
    - ./hooks/validate-exec.sh
    - ./hooks/log-tool-use.sh
  postToolUse:
    - ./hooks/audit-external.sh

Hook Protocol

• Hooks receive tool context via environment variables: HOOK_TOOL_NAME, HOOK_TOOL_INPUT, HOOK_EVENT
• Full JSON payload piped to stdin
• Exit code 0 = Allow (stdout captured as optional feedback)
• Exit code 2 = Deny (stdout returned as denial reason to model)
• Any other exit code = Warn but allow (logged, execution continues)

Execution Flow

1. Agent requests tool call
2. All PreToolUse hooks run in order
3. If any hook exits 2 → tool call denied, error returned to model
4. Tool executes normally
5. All PostToolUse hooks run with tool output added to context
6. If PostToolUse hook exits 2 → result marked as error

Examples

Security validation hook

#!/bin/bash
# Deny rm -rf commands
if [ "$HOOK_TOOL_NAME" = "exec" ]; then
  echo "$HOOK_TOOL_INPUT" | grep -q 'rm -rf /' && {
    echo "Blocked: destructive rm command"
    exit 2
  }
fi
exit 0

Audit logging hook

#!/bin/bash
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $HOOK_EVENT $HOOK_TOOL_NAME" >> ~/.openclaw/audit.log
exit 0

Prior Art

• Claude Code: src/services/tools/toolHooks.ts
• Claw Code (Rust): rust/crates/runtime/src/hooks.rs, rust/crates/plugins/src/hooks.rs
• Both use the same exit-code protocol described above