plans and docs

src/api_hooks.py

@@ -7,6 +7,35 @@ from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
 from typing import Any
 import logging
 from src import session_logger
+"""
+API Hooks - REST API for external automation and state inspection.
+
+This module implements the HookServer, which exposes internal application state to external HTTP requests on port 8999 using Python's
+ ThreadingHTTPServer. All endpoints are thread-safe and reads that pass through lock-guarded lists,
+ while stateful reads use the GUI thread trampoline pattern.
+
+Architecture:
+ - HookServer: ThreadingHTTPServer with app reference
+ - HookHandler: BaseHTTPRequestHandler per request
+ - Request handling uses trampoline pattern for GUI state reads
+ - GUI Thread Trampoline: Create threading.Event + result dict
+   - Push callback to `_pending_gui_tasks`
+   - Wait for event (timeout)
+   - Return result as JSON
+
+Thread Safety:
+ - All reads use lock-protected lists
+ - All state mutations happen on the GUI thread
+ - The module does to maintain separation between App and AppController
+
+Configuration:
+ - `--enable-test-hooks`: Required for Hook API to be available
+ - `gemini_cli` provider: Hook API is automatically available for synchronous HITL
+
+See Also:
+ - docs/guide_tools.md for full API reference
+ - api_hook_client.py for the client implementation
+"""
 
 def _get_app_attr(app: Any, name: str, default: Any = None) -> Any:
  if hasattr(app, name):