Files/ComputerAssignments/CA2/HOOKS.md

# AirMouse Extended 5-Lifecycle Agent Hook System (`HOOKS.md`)

The AirMouse MCP server CLI & stdio engine includes a complete **Agent Lifecycle Hook System** supporting all 5 standard agent lifecycle events.

Hooks enable external logging, parameter validation, automated alerts, desktop notifications, tool chaining, or post-processing scripts without modifying core tool source code.

---

## 🔄 The 5 Agent Lifecycle Hook Types

| Hook Type | Canonical Name | Target / Filter | Execution Lifecycle & Trigger |
|---|---|---|---|
| **PreToolUse** | `pretool` (or `pre`) | Specific Tool or `*` | Executed **immediately before** an individual tool is invoked. |
| **PostToolUse** | `posttool` (or `post`) | Specific Tool or `*` | Executed **immediately after** an individual tool finishes execution. |
| **PreInvocation** | `preinvoke` | Global (`*`) | Executed **once at the start** of an invocation request session. |
| **PostInvocation** | `postinvoke` | Global (`*`) | Executed **once after** the entire invocation request completes (CLI command or stdio tool request). |
| **Stop** | `stop` | Global (`*`) | Executed **upon server shutdown / exit** (via signal handlers `SIGINT`/`SIGTERM` or `atexit`). |

> [!NOTE]
> **Backward Compatibility**: Legacy type values `"pre"` and `"post"` automatically map to `"pretool"` and `"posttool"`.

---

## 📁 Storage & Configuration

- **Hooks Configuration**: `~/.gemini/config/hooks.json` (auto-created with defaults if missing)
- **Execution Log**: `~/.gemini/logs/hooks.log`

Each hook entry object:
```json
{
  "id": 1,
  "tool": "*",
  "type": "preinvoke",
  "command": "echo 'Session starting at $(date)' >> ~/.gemini/logs/hooks.log",
  "script": null,
  "enabled": true
}
```

---

## 🌐 Environment Variables Passed to Hooks

Every hook execution process receives the following environment variables:
- `HOOK_TYPE`: The active lifecycle event (`pretool`, `posttool`, `preinvoke`, `postinvoke`, `stop`).
- `TOOL_NAME`: The name of the target tool (or `[GLOBAL]` for global invocation hooks).
- `ARGS`: A JSON-encoded string containing tool input arguments.
- `RESULT`: (PostToolUse / PostInvocation hooks) A JSON-encoded string of the tool's output dictionary.

---

## 💻 CLI Commands Reference

Manage hooks using the `hooks` subcommand:

```bash
# List all configured hooks across all 5 lifecycle events
python airmouse_server_mcp.py hooks list

# 1. Add a PreToolUse hook for a specific tool
python airmouse_server_mcp.py hooks add --tool move_mouse --type pretool --command "echo 'Moving mouse by \$dx, \$dy'"

# 2. Add a PostToolUse hook with a script file
python airmouse_server_mcp.py hooks add --tool build_android_debug --type posttool --script /path/to/notify.sh

# 3. Add a global PreInvocation hook (tool is optional/ignored)
python airmouse_server_mcp.py hooks add --type preinvoke --command "echo 'Session started at \$(date)' >> ~/.gemini/logs/hooks.log"

# 4. Add a global PostInvocation hook
python airmouse_server_mcp.py hooks add --type postinvoke --command "echo 'Session ended at \$(date)' >> ~/.gemini/logs/hooks.log"

# 5. Add a Stop graceful shutdown hook
python airmouse_server_mcp.py hooks add --type stop --command "osascript -e 'display notification \"Server exiting...\" with title \"AirMouse\"'"

# Enable / Disable / Remove / Test
python airmouse_server_mcp.py hooks disable 1
python airmouse_server_mcp.py hooks enable 1
python airmouse_server_mcp.py hooks remove 1
python airmouse_server_mcp.py hooks test --type preinvoke
python airmouse_server_mcp.py hooks test --tool move_mouse --type pretool --args '{"dx": 50, "dy": 50}'
```

---

## ⚡ CLI vs MCP Stdio Lifecycle Behavior

| Hook Type | CLI Mode Execution | Persistent MCP Stdio Mode Execution |
|---|---|---|
| **PreInvocation** (`preinvoke`) | Executed once at CLI startup immediately after argument parsing. | Executed once when the MCP server starts up (`mcp.run()`). |
| **PreToolUse** (`pretool`) | Executed before the specific tool subcommand runs. | Executed before each `@mcp.tool()` call received over stdio. |
| **PostToolUse** (`posttool`) | Executed after the tool returns a result. | Executed after each `@mcp.tool()` completes execution. |
| **PostInvocation** (`postinvoke`) | Executed after the final tool output is printed. | Executed after each individual tool response payload is returned to the client over stdio. |
| **Stop** (`stop`) | Executed when the CLI process terminates. | Executed when the MCP server receives `SIGINT`/`SIGTERM` or process exits (`atexit`). |