studd

Author: MichaelYochpaz

.ai-workspace/docs/configuration.md

@@ -75,19 +75,9 @@ Controls repository status reporting at session start. Section: `[repositories]`
 
 ## Session hooks
 
-Session hooks are pre-configured statically in each tool's config directory -- they're committed to the repo and work out of the box.
+Session hooks are pre-configured in each tool's config directory -- they're committed to the repo and work out of the box. No configuration needed.
 
-The session-start script (`.ai-workspace/scripts/session-start.py`) runs two tasks:
-
-1. **Repository status** -- Reports each submodule's branch, uncommitted changes, and how far behind remote
-2. **Tool discovery** -- Detects installed CLI tools and injects usage instructions
-
-The output is wrapped in `<session-context>` XML tags that agents consume automatically.
-
-Hook configurations are stored in:
-
-- **Claude Code** -- `.claude/settings.json`
-- **OpenCode** -- `.opencode/plugins/session-sync.ts`
+The session-start script runs repository status reporting and tool discovery, then injects the results into the agent's context. See [Session Hooks](development/session-hooks.md) for supported tools and details.
 
 ---
 

.ai-workspace/docs/features/tool-discovery.md

@@ -4,7 +4,7 @@ Tool Discovery detects installed CLI tools on your system and tells AI agents ab
 
 !!! info "Requires hook support"
 
-    Tool discovery context is injected via session hooks, which currently work with [Claude Code](https://code.claude.com/docs/en/hooks) and [OpenCode](https://opencode.ai/docs/plugins/).
+    Tool discovery context is injected via session hooks. See [Session Hooks](../development/session-hooks.md) for which tools are supported and how to add more.
 
     Other tools can still use the workspace but won't receive automatic tool discovery context.
 

.ai-workspace/docs/index.md

@@ -70,7 +70,7 @@ A meta-repository template that aggregates related repositories using git submod
 
 Some AI tools support **hooks** -- scripts that run automatically at specific lifecycle points (e.g., session start, pre-prompt). This workspace uses a session-start hook to inject context into the agent before it begins work.
 
-For tools with hook support ([Claude Code](https://code.claude.com/docs/en/hooks), [OpenCode](https://opencode.ai/docs/plugins/)), the session-start script runs automatically when an AI session begins:
+For tools with hook support ([Claude Code](https://code.claude.com/docs/en/hooks), [OpenCode](https://opencode.ai/docs/plugins/), [Cursor](https://cursor.com/docs/agent/hooks), [Gemini CLI](https://geminicli.com/docs/hooks/)), the session-start script runs automatically when an AI session begins:
 
 ``` mermaid
 graph LR
@@ -95,7 +95,7 @@ These are two independent flows -- session hooks handle runtime context, pre-com
 
 !!! info "Other AI tools"
 
-    Tools without hook support (Cursor, Roo Code, etc.) still work with skills, commands, and agent docs -- they just won't get automatic session-start context injection.
+    Tools without hook support still work with skills, commands, and agent docs -- they just won't get automatic session-start context injection. See [Session Hooks](development/session-hooks.md) for which tools are supported and how to add more.
 
 ## Project structure
 

.ai-workspace/scripts/session-start.py

@@ -1,15 +1,25 @@
 #!/usr/bin/env python3
-"""Main session-start orchestrator for AI tool hooks.
+"""Session-start orchestrator for AI tool hooks.
 
-This script runs at the start of AI tool sessions (OpenCode, Claude Code, etc.)
-and collects context from multiple sources into a unified output.
+Runs at the start of AI tool sessions and collects context from multiple
+sources into a unified output.
 
-Each source adds its section to the SessionContext, and the final output
-is wrapped in <session-context> tags for the LLM to understand.
+Supports two output modes:
+  - Plain text (default): For tools that capture stdout directly
+    (Claude Code, OpenCode, manual runs).
+  - JSON (--tool <name>): For tools that require a JSON hook protocol
+    (Cursor, Gemini CLI). Each tool's JSON schema is defined in FORMATTERS.
+
+Adding a new tool: add an entry to FORMATTERS and create the tool's config file.
 """
 
+from __future__ import annotations
+
+import argparse
+import json
 import sys
 from pathlib import Path
+from typing import Any
 
 # Add lib to path for imports
 sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
@@ -20,9 +30,17 @@
 from repository_status import run_repository_status
 from tool_discovery import run_tool_discovery
 
+# JSON output formatters for tools that use a JSON hook protocol.
+# Each formatter receives the rendered context string and returns a dict
+# matching the tool's expected sessionStart output schema.
+FORMATTERS: dict[str, Any] = {
+    "cursor": lambda ctx: {"additional_context": ctx},
+    "gemini": lambda ctx: {"hookSpecificOutput": {"additionalContext": ctx}},
+}
 
-def main() -> None:
-    """Run all session-start tasks and output unified context."""
+
+def collect_context() -> str:
+    """Run all session-start tasks and return the rendered context."""
     ctx = SessionContext()
 
     # Get repository root (scripts are in .ai-workspace/scripts/)
@@ -34,8 +52,33 @@ def main() -> None:
     # Run tool discovery
     run_tool_discovery(ctx, repo_root)
 
-    # Output the combined context
-    ctx.print()
+    return ctx.render()
+
+
+def main() -> None:
+    """Run session-start tasks and output context in the requested format."""
+    parser = argparse.ArgumentParser(description="Session-start context collector")
+    parser.add_argument(
+        "--tool",
+        choices=FORMATTERS,
+        help="Output JSON in the specified tool's hook format. "
+        "Without this flag, outputs plain text.",
+    )
+    args = parser.parse_args()
+
+    # Tools with JSON protocols send input on stdin; consume it so the
+    # process doesn't hang.
+    if args.tool:
+        sys.stdin.read()
+
+    output = collect_context()
+
+    if args.tool:
+        response = FORMATTERS[args.tool](output) if output else {}
+        json.dump(response, sys.stdout)
+    else:
+        if output:
+            print(output)
 
 
 if __name__ == "__main__":

.ai-workspace/zensical.toml

@@ -17,6 +17,9 @@ nav = [
         { Skills = "features/skills.md" },
         { Commands = "features/commands.md" },
     ] },
+    { Development = [
+        { "Session Hooks" = "development/session-hooks.md" },
+    ] },
 
 ]
 

.cursor/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "uv run .cursor/hooks/session-start.py",
+        "command": "uv run .ai-workspace/scripts/session-start.py --tool cursor",
         "timeout": 120
       }
     ]