Files/ComputerAssignments/CA2/HOOKS.html

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="utf-8">
<title>HOOKS</title>
<style>

body { font-family: Tahoma, 'Segoe UI', sans-serif; line-height: 2.0; font-size: 11pt; color: #0f172a; padding: 30px; background-color: #ffffff; }
h1 { color: #1e1b4b; border-bottom: 3px solid #4f46e5; padding-bottom: 10px; font-size: 22pt; margin-top: 30px; }
h2 { color: #1e293b; background-color: #f1f5f9; border-right: 5px solid #3b82f6; padding: 8px 12px; font-size: 16pt; margin-top: 25px; }
h3 { color: #2563eb; font-size: 13pt; margin-top: 20px; }
p { text-align: justify; margin-bottom: 15px; }
pre { background-color: #0f172a; color: #f8fafc; padding: 15px; border-radius: 6px; font-family: Courier, monospace; font-size: 10pt; overflow-x: auto; }
code { background-color: #f1f5f9; color: #0f172a; padding: 2px 5px; border-radius: 4px; font-family: Courier, monospace; }
table { border-collapse: collapse; width: 100%; margin: 20px 0; }
th, td { border: 1px solid #cbd5e1; padding: 10px; text-align: right; }
th { background-color: #f1f5f9; }
ul, ol { padding-right: 25px; }

</style>
</head>
<body>
<div class="container">
<h1>AirMouse Extended 5-Lifecycle Agent Hook System (<code>HOOKS.md</code>)</h1>
<p>The AirMouse MCP server CLI &amp; stdio engine includes a complete <strong>Agent Lifecycle Hook System</strong> supporting all 5 standard agent lifecycle events.</p>
<p>Hooks enable external logging, parameter validation, automated alerts, desktop notifications, tool chaining, or post-processing scripts without modifying core tool source code.</p>
<hr />
<h2>🔄 The 5 Agent Lifecycle Hook Types</h2>
<table>
<thead>
<tr>
<th>Hook Type</th>
<th>Canonical Name</th>
<th>Target / Filter</th>
<th>Execution Lifecycle &amp; Trigger</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>PreToolUse</strong></td>
<td><code>pretool</code> (or <code>pre</code>)</td>
<td>Specific Tool or <code>*</code></td>
<td>Executed <strong>immediately before</strong> an individual tool is invoked.</td>
</tr>
<tr>
<td><strong>PostToolUse</strong></td>
<td><code>posttool</code> (or <code>post</code>)</td>
<td>Specific Tool or <code>*</code></td>
<td>Executed <strong>immediately after</strong> an individual tool finishes execution.</td>
</tr>
<tr>
<td><strong>PreInvocation</strong></td>
<td><code>preinvoke</code></td>
<td>Global (<code>*</code>)</td>
<td>Executed <strong>once at the start</strong> of an invocation request session.</td>
</tr>
<tr>
<td><strong>PostInvocation</strong></td>
<td><code>postinvoke</code></td>
<td>Global (<code>*</code>)</td>
<td>Executed <strong>once after</strong> the entire invocation request completes (CLI command or stdio tool request).</td>
</tr>
<tr>
<td><strong>Stop</strong></td>
<td><code>stop</code></td>
<td>Global (<code>*</code>)</td>
<td>Executed <strong>upon server shutdown / exit</strong> (via signal handlers <code>SIGINT</code>/<code>SIGTERM</code> or <code>atexit</code>).</td>
</tr>
</tbody>
</table>
<blockquote>
<p>[!NOTE]
<strong>Backward Compatibility</strong>: Legacy type values <code>"pre"</code> and <code>"post"</code> automatically map to <code>"pretool"</code> and <code>"posttool"</code>.</p>
</blockquote>
<hr />
<h2>📁 Storage &amp; Configuration</h2>
<ul>
<li><strong>Hooks Configuration</strong>: <code>~/.gemini/config/hooks.json</code> (auto-created with defaults if missing)</li>
<li><strong>Execution Log</strong>: <code>~/.gemini/logs/hooks.log</code></li>
</ul>
<p>Each hook entry object:</p>
<pre><code class="language-json">{
  &quot;id&quot;: 1,
  &quot;tool&quot;: &quot;*&quot;,
  &quot;type&quot;: &quot;preinvoke&quot;,
  &quot;command&quot;: &quot;echo 'Session starting at $(date)' &gt;&gt; ~/.gemini/logs/hooks.log&quot;,
  &quot;script&quot;: null,
  &quot;enabled&quot;: true
}
</code></pre>
<hr />
<h2>🌐 Environment Variables Passed to Hooks</h2>
<p>Every hook execution process receives the following environment variables:
- <code>HOOK_TYPE</code>: The active lifecycle event (<code>pretool</code>, <code>posttool</code>, <code>preinvoke</code>, <code>postinvoke</code>, <code>stop</code>).
- <code>TOOL_NAME</code>: The name of the target tool (or <code>[GLOBAL]</code> for global invocation hooks).
- <code>ARGS</code>: A JSON-encoded string containing tool input arguments.
- <code>RESULT</code>: (PostToolUse / PostInvocation hooks) A JSON-encoded string of the tool's output dictionary.</p>
<hr />
<h2>💻 CLI Commands Reference</h2>
<p>Manage hooks using the <code>hooks</code> subcommand:</p>
<pre><code class="language-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 &quot;echo 'Moving mouse by \$dx, \$dy'&quot;

# 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 &quot;echo 'Session started at \$(date)' &gt;&gt; ~/.gemini/logs/hooks.log&quot;

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

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

# 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 '{&quot;dx&quot;: 50, &quot;dy&quot;: 50}'
</code></pre>
<hr />
<h2>⚡ CLI vs MCP Stdio Lifecycle Behavior</h2>
<table>
<thead>
<tr>
<th>Hook Type</th>
<th>CLI Mode Execution</th>
<th>Persistent MCP Stdio Mode Execution</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>PreInvocation</strong> (<code>preinvoke</code>)</td>
<td>Executed once at CLI startup immediately after argument parsing.</td>
<td>Executed once when the MCP server starts up (<code>mcp.run()</code>).</td>
</tr>
<tr>
<td><strong>PreToolUse</strong> (<code>pretool</code>)</td>
<td>Executed before the specific tool subcommand runs.</td>
<td>Executed before each <code>@mcp.tool()</code> call received over stdio.</td>
</tr>
<tr>
<td><strong>PostToolUse</strong> (<code>posttool</code>)</td>
<td>Executed after the tool returns a result.</td>
<td>Executed after each <code>@mcp.tool()</code> completes execution.</td>
</tr>
<tr>
<td><strong>PostInvocation</strong> (<code>postinvoke</code>)</td>
<td>Executed after the final tool output is printed.</td>
<td>Executed after each individual tool response payload is returned to the client over stdio.</td>
</tr>
<tr>
<td><strong>Stop</strong> (<code>stop</code>)</td>
<td>Executed when the CLI process terminates.</td>
<td>Executed when the MCP server receives <code>SIGINT</code>/<code>SIGTERM</code> or process exits (<code>atexit</code>).</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>