---
name: hook-management
description: Implement lifecycle hooks (PreToolUse/PostToolUse) using OpenClaw's existing tools and config
---

## When to use
Use when you need to:
- Add validation before dangerous tools (exec, write, edit)
- Audit/log all tool usage
- Enforce custom security policies
- Track costs/metrics around tool calls
- Transform tool outputs before they reach the model

**Note**: OpenClaw does not have native PreToolUse/PostToolUse hooks. This skill shows you how to achieve similar effects using available mechanisms.

## Approach 1: Permission Mode + Rules (Built-in)

OpenClaw already has a permission system. Use it:

### Set permission mode
```bash
# Ask before every write/exec (default safe)
gateway config set tools.exec.security full

# Or use plan mode to block all writes
# (requires implementing plan_mode toggle)
```

### Path-level rules in config
Edit `openclaw.json`:
```json
{
  "permissions": {
    "path_rules": [
      { "pattern": "**/secrets/**", "allow": false },
      { "pattern": "**/*.key", "allow": false }
    ],
    "denied_commands": ["rm -rf /", "DROP TABLE *", "format c:"]
  }
}
```

## Approach 2: Wrapper Scripts (Shell Proxy)

Create wrapper scripts that add validation/logging:

### Example: Safe exec wrapper
```bash
# ~/.openclaw/wrappers/exec-safe
#!/bin/bash
# PreToolUse validation
CMD="$1"
if echo "$CMD" | grep -qE "(rm -rf|dd if=|mkfs)"; then
  echo "ERROR: Dangerous command blocked: $CMD" >&2
  exit 1
fi

# Audit log
echo "$(date -Iseconds) USER EXEC: $CMD" >> ~/.openclaw/logs/exec-audit.log

# Execute
exec /usr/lib/openclaw/tools/exec.real "$@"
```

Then configure OpenClaw to use the wrapper instead of the built-in exec tool.

## Approach 3: Plugin Interception (If Plugin System Supports)

If OpenClaw plugins can intercept tool calls:

```json
{
  "name": "audit-plugin",
  "version": "1.0.0",
  "preToolUse": {
    "command": "audit-log",
    "priority": 1000
  }
}
```

**Check plugin docs** to see if `preToolUse`/`postToolUse` are supported.

## Approach 4: Custom Agent with Restricted Tools

Spawn a subagent with limited tool set:

```bash
clawteam spawn tmux openclaw \
  --agent-type restricted \
  --tools "read,write,web_search"  # no exec, no dangerous tools
```

## Common Use Cases & Solutions

### Audit logging all tool calls
- **Solution**: Wrapper scripts that log to file
- Or use OpenClaw's built-in logging if available

### Block dangerous commands
- **Solution**: `denied_commands` in config
- Or wrapper validation

### Rate limiting
- **Solution**: Track in session memory, check before allowing
- No built-in — implement in custom plugin/agent

### Cost tracking
- **Solution**: Parse logs, aggregate token usage
- OpenClaw may already log token counts

### Input sanitization
- **Solution**: Pre-process arguments in wrapper
- Or validate in agent logic before calling tool

## Verification Checklist
- [ ] Hooks/validation are actually triggered
- [ ] Dangerous operations are blocked as intended
- [ ] Audit logs capture necessary details (who, what, when)
- [ ] No performance degradation (wrappers are fast)
- [ ] Rules don't interfere with normal operations
- [ ] Fail open/closed appropriately (security vs availability)

## Limitations

- No native hook priority system — order depends on wrapper chain
- No automatic hook discovery — manual registration needed
- Wrapper approach requires maintaining extra scripts
- Not as elegant as built-in hook system

## Future: Request Native Hooks

If hooks are critical, consider:
- Feature request to OpenClaw maintainers
- Contributing a hook system implementation
- Using OpenHarness as an alternative (has native hooks)