Voice

Preflight Totem

Name: Preflight Totem
Rating: 3.5 (1 reviews)
Author: lykeion-dev

By lykeion-dev 👁 25 views ▲ 0 votes

OpenClaw plugin: block first tool call of every turn and inject a pre-flight review reminder. Prevents impulsive agent actions.

GitHub

Configuration Example

{
  "plugins": {
    "preflight-totem": {
      "enabled": true
    }
  }
}

README

# preflight-totem

An [OpenClaw](https://github.com/openclaw/openclaw) plugin that prevents agents from acting impulsively by intercepting the first tool call of every turn and injecting a review reminder.

## What It Does

When an agent tries to use a tool (read, write, exec, etc.), this plugin:

1. **Blocks** the first tool call in the turn
2. **Injects** a system message reminding the agent to review documents, code, and instructions
3. **Allows** subsequent tool calls after the reminder

This forces a "pause and think" moment before any action — a pre-flight check.

## Why

LLM agents in long-lived sessions tend to act on assumptions, skip context review, and make mistakes that require cleanup. The preflight totem ensures the agent verifies its understanding before each turn's first action.

## Install

Copy the plugin files to your OpenClaw extensions directory:

```bash
cp -r . ~/.openclaw/extensions/preflight-totem/
```

Then enable it in your `openclaw.json`:

```json
{
  "plugins": {
    "preflight-totem": {
      "enabled": true
    }
  }
}
```

## Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `message` | string | _(see below)_ | Custom preflight reminder message |
| `placement` | string | `"prepend_context"` | Where to inject: `"prepend_context"` or `"append_context"` |
| `targetAgents` | string[] | `["*"]` | Agent IDs to target (supports `*` wildcard) |
| `targetSessions` | string[] | `["*"]` | Session key patterns to target (supports `*` wildcard) |
| `enabled` | boolean | `true` | Master on/off switch |

### Default Message

> This is a pre-flight message that is automatically injected and the tool call was temporarily halted before the first tool call in every assistant's turn, in order to avoid acting prematurely. This does NOT necessarily mean refusal of your tool call. Just make sure you reviewed the related documents, codebase, architecture, environment settings, and the user's exact instructions before taking any action. Ensure your planned actions fully comply with all rules and principles before proceeding. After that, you CAN RETRY this tool call if you are fully aware of what's going on.

### Scoped Example

Only target a specific agent:

```json
{
  "plugins": {
    "preflight-totem": {
      "targetAgents": ["main"],
      "message": "STOP. Review your context before acting."
    }
  }
}
```

## How It Works

```
User sends message
    │
    ▼
Agent starts processing
    │
    ▼
Agent tries tool call ──→ [before_tool_call hook]
    │                         │
    │                    session already blocked?
    │                    ├─ YES: allow (pass through)
    │                    └─ NO: block + mark session
    │                         │
    │                         ▼
    │                    Tool call blocked
    │                         │
    │                    [before_prompt_build hook] ──→ message injected
    │                         │
    │                         ▼
    │                    Agent sees reminder
    │                         │
    │                    Agent retries tool call ──→ allowed
    │
    ▼
[agent_end hook] ──→ reset session state
```

## Edge Cases

- **agent_end timing**: If `agent_end` fires between tool-call rounds, the session resets and the reminder shows again. This is conservative by design — the message is re-shown rather than silently suppressed.
- **Plugin reload**: State loss on reload means the first tool call after reload will be blocked again. Acceptable as a safety measure.
- **Sub-agents**: The hook fires for sub-agent sessions too. Use `targetAgents` or `targetSessions` to scope.
- **Non-tool-call turns**: If the agent's first action is text (no tool call), no interception occurs. The preflight is only about tool-based actions.
- **Concurrent sessions**: Each session is tracked independently by `sessionKey`.

## License

MIT

voice