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).

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:

{
  "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:

# 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).