@tecet/ollm 0.1.3

package/docs/Hooks/Architecture.md

@@ -0,0 +1,885 @@
+# Hook System Architecture
+
+**Technical Architecture and Design of the Hook System**
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [System Architecture](#system-architecture)
+3. [Core Components](#core-components)
+4. [Data Flow](#data-flow)
+5. [Integration Points](#integration-points)
+6. [Design Decisions](#design-decisions)
+7. [Security Model](#security-model)
+
+**See Also:**
+
+- [Hook User Guide](UserGuide.md) - Using hooks
+- [Hook Protocol](Protocol.md) - Technical protocol specification
+- [MCP Architecture](../MCP/MCP_Architecture.md) - System architecture
+- [MCP Commands](../MCP/MCP_Commands.md) - Hook command reference
+
+---
+
+## Overview
+
+The Hook System provides event-driven automation and safety gates for OLLM CLI. Hooks execute custom scripts in response to lifecycle events, enabling workflow automation, validation, and integration with external systems.
+
+### Key Features
+
+- ✅ 12 event types for comprehensive lifecycle coverage
+- ✅ JSON-based stdin/stdout protocol
+- ✅ Trust model with approval workflow
+- ✅ Rate limiting and execution planning
+- ✅ Parallel and sequential execution strategies
+- ✅ Command whitelist for security
+- ✅ Integration with MCP and extensions
+
+---
+
+## System Architecture
+
+### High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph Events["Event Sources"]
+        FileEvent["File Events"]
+        AgentEvent["Agent Events"]
+        ModelEvent["Model Events"]
+        ToolEvent["Tool Events"]
+        UserEvent["User Events"]
+    end
+
+    subgraph HookSystem["Hook System"]
+        EventHandler["Hook Event Handler"]
+        Registry["Hook Registry"]
+        Planner["Hook Planner"]
+        Runner["Hook Runner"]
+        Translator["Hook Translator"]
+        TrustModel["Trust Model"]
+    end
+
+    subgraph Execution["Execution"]
+        AskAgent["Ask Agent"]
+        RunCommand["Run Command"]
+    end
+
+    Events --> EventHandler
+    EventHandler --> Registry
+    Registry --> Planner
+    Planner --> TrustModel
+    TrustModel --> Runner
+    Runner --> Translator
+    Translator --> AskAgent
+    Translator --> RunCommand
+
+    style HookSystem fill:#f9f,stroke:#333,stroke-width:2px
+    style Events fill:#bbf,stroke:#333,stroke-width:2px
+    style Execution fill:#bfb,stroke:#333,stroke-width:2px
+```
+
+### Component Interaction Flow
+
+```mermaid
+flowchart LR
+    Event[Event Occurs] --> Handler[Event Handler]
+    Handler --> Registry[Hook Registry]
+    Registry --> Planner[Hook Planner]
+    Planner --> Trust[Trust Model]
+    Trust --> Runner[Hook Runner]
+    Runner --> Exec[Execute Hook]
+    Exec --> Result[Process Result]
+
+    style Event fill:#e1f5ff
+    style Trust fill:#ffe1e1
+    style Exec fill:#e8f5e9
+    style Result fill:#f3e5f5
+```
+
+---
+
+## Core Components
+
+### 1. Hook Event Handler
+
+**Location:** `packages/core/src/hooks/hookEventHandler.ts`
+
+**Responsibilities:**
+
+- Emit events when lifecycle points are reached
+- Provide event data to hook system
+- Manage event subscriptions
+
+**Key Methods:**
+
+```typescript
+interface HookEventHandler {
+  emit(eventType: string, eventData: any): Promise<void>;
+  on(eventType: string, handler: Function): void;
+  off(eventType: string, handler: Function): void;
+}
+```
+
+**Event Types (12 total):**
+
+1. `session_start` - Session initialization
+2. `session_end` - Session cleanup
+3. `before_agent` - Before agent processes request
+4. `after_agent` - After agent response
+5. `before_model` - Before model invocation
+6. `after_model` - After model response
+7. `before_tool_selection` - Before tool selection
+8. `before_tool` - Before tool execution
+9. `after_tool` - After tool execution
+10. `pre_compress` - Before context compression
+11. `post_compress` - After context compression
+12. `notification` - System notifications
+
+### 2. Hook Registry
+
+**Location:** `packages/core/src/hooks/hookRegistry.ts`
+
+**Responsibilities:**
+
+- Store and retrieve hook definitions
+- Filter hooks by event type
+- Manage hook lifecycle (register, unregister)
+- Track hook metadata
+
+**Key Methods:**
+
+```typescript
+interface HookRegistry {
+  registerHook(hook: HookDefinition): void;
+  unregisterHook(hookId: string): void;
+  getHooksForEvent(eventType: string): HookDefinition[];
+  getAllHooks(): HookDefinition[];
+  getHook(hookId: string): HookDefinition | undefined;
+}
+```
+
+**Hook Definition:**
+
+```typescript
+interface HookDefinition {
+  id: string;
+  name: string;
+  eventType: string;
+  filePatterns?: string[];
+  action: {
+    type: 'askAgent' | 'runCommand';
+    prompt?: string;
+    command?: string;
+  };
+  trusted: boolean;
+  enabled: boolean;
+  source: 'builtin' | 'user' | 'workspace' | 'extension';
+}
+```
+
+### 3. Hook Planner
+
+**Location:** `packages/core/src/hooks/hookPlanner.ts`
+
+**Responsibilities:**
+
+- Determine execution strategy (sequential, parallel, optimized)
+- Check execution conditions
+- Evaluate priorities
+- Apply rate limiting
+
+**Execution Strategies:**
+
+```mermaid
+graph TD
+    Start[Hook List] --> Analyze[Analyze Dependencies]
+    Analyze --> HasDeps{Has Dependencies?}
+
+    HasDeps -->|Yes| Sequential[Sequential Execution]
+    HasDeps -->|No| CheckParallel{Can Parallelize?}
+
+    CheckParallel -->|Yes| Parallel[Parallel Execution]
+    CheckParallel -->|No| Sequential
+
+    Sequential --> Execute1[Execute Hook 1]
+    Execute1 --> Execute2[Execute Hook 2]
+    Execute2 --> Execute3[Execute Hook 3]
+
+    Parallel --> ParallelExec[Execute All Hooks]
+    ParallelExec --> Wait[Wait for All]
+
+    Execute3 --> Done[Complete]
+    Wait --> Done
+
+    style Start fill:#e1f5ff
+    style Sequential fill:#fff4e1
+    style Parallel fill:#e8f5e9
+    style Done fill:#f3e5f5
+```
+
+**Rate Limiting:**
+
+- Per-hook rate limits
+- Global rate limits
+- Cooldown periods
+- Execution count tracking
+
+### 4. Hook Runner
+
+**Location:** `packages/core/src/hooks/hookRunner.ts`
+
+**Responsibilities:**
+
+- Execute hook processes
+- Manage stdin/stdout communication
+- Handle timeouts
+- Capture and format results
+- Enforce command whitelist
+
+**Command Whitelist (Line 128):**
+
+```typescript
+const WHITELISTED_COMMANDS = ['node', 'python', 'python3', 'bash', 'sh', 'npx', 'uvx'];
+```
+
+**Execution Flow:**
+
+```mermaid
+flowchart TD
+    Start[Start Execution] --> Validate[Validate Command]
+    Validate --> Whitelist{In Whitelist?}
+
+    Whitelist -->|No| Block[Block Execution]
+    Whitelist -->|Yes| Spawn[Spawn Process]
+
+    Spawn --> WriteStdin[Write Event to stdin]
+    WriteStdin --> Wait[Wait for Response]
+    Wait --> Timeout{Timeout?}
+
+    Timeout -->|Yes| Kill[Kill Process]
+    Timeout -->|No| ReadStdout[Read from stdout]
+
+    ReadStdout --> Parse[Parse JSON]
+    Parse --> Valid{Valid JSON?}
+
+    Valid -->|No| Error[Return Error]
+    Valid -->|Yes| Return[Return Result]
+
+    Kill --> Error
+    Block --> Error
+
+    style Start fill:#e1f5ff
+    style Whitelist fill:#fff4e1
+    style Block fill:#ffe1e1
+    style Return fill:#e8f5e9
+```
+
+### 5. Hook Translator
+
+**Location:** `packages/core/src/hooks/hookTranslator.ts`
+
+**Responsibilities:**
+
+- Translate legacy hook format to modern format
+- Convert between JSON and TypeScript types
+- Format hook input/output
+- Handle protocol versioning
+
+**Translation Flow:**
+
+```typescript
+// Legacy Format (JSON)
+{
+  "name": "Lint on Save",
+  "when": { "type": "fileEdited", "patterns": ["*.ts"] },
+  "then": { "type": "askAgent", "prompt": "Run linting" }
+}
+
+// Modern Format (TypeScript)
+{
+  id: "lint-on-save",
+  name: "Lint on Save",
+  eventType: "fileEdited",
+  filePatterns: ["*.ts"],
+  action: {
+    type: "askAgent",
+    prompt: "Run linting on {{file.path}}"
+  },
+  trusted: false,
+  enabled: true
+}
+```
+
+### 6. Trust Model
+
+**Location:** `packages/core/src/hooks/trustedHooks.ts`
+
+**Responsibilities:**
+
+- Verify hook trust level
+- Request user approval
+- Store approval decisions
+- Compute and verify hook hashes
+
+**Trust Levels:**
+
+```mermaid
+graph TD
+    Hook[Hook] --> CheckSource{Check Source}
+
+    CheckSource -->|Builtin| Trusted[Always Trusted]
+    CheckSource -->|User| CheckHash{Check Hash}
+    CheckSource -->|Workspace| CheckApproval{Check Approval}
+    CheckSource -->|Extension| CheckApproval
+
+    CheckHash -->|Match| Trusted
+    CheckHash -->|Mismatch| RequestApproval[Request Approval]
+
+    CheckApproval -->|Approved| Trusted
+    CheckApproval -->|Not Approved| RequestApproval
+
+    RequestApproval --> UserDecision{User Approves?}
+    UserDecision -->|Yes| StoreApproval[Store Approval]
+    UserDecision -->|No| Block[Block Execution]
+
+    StoreApproval --> Trusted
+    Trusted --> Execute[Execute Hook]
+
+    style Trusted fill:#e8f5e9
+    style Block fill:#ffe1e1
+    style Execute fill:#e1f5ff
+```
+
+### 7. Message Bus
+
+**Location:** `packages/core/src/hooks/messageBus.ts`
+
+**Responsibilities:**
+
+- Event-driven architecture
+- Decouple components
+- Enable parallel execution
+- Support complex workflows
+
+**Event Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Source as Event Source
+    participant Bus as Message Bus
+    participant Handler as Event Handler
+    participant Registry as Hook Registry
+    participant Runner as Hook Runner
+
+    Source->>Bus: emit(event, data)
+    Bus->>Handler: notify(event, data)
+    Handler->>Registry: getHooksForEvent(event)
+    Registry-->>Handler: hooks[]
+
+    loop For each hook
+        Handler->>Runner: execute(hook, data)
+        Runner-->>Handler: result
+    end
+
+    Handler-->>Bus: complete
+    Bus-->>Source: done
+```
+
+---
+
+## Data Flow
+
+### Hook Execution Flow
+
+```mermaid
+flowchart TD
+    Event[Event Occurs] --> Emit[MessageBus Emits]
+    Emit --> Handler[Event Handler]
+    Handler --> Registry[Get Hooks from Registry]
+    Registry --> Filter[Filter by Event Type]
+    Filter --> Planner[Hook Planner]
+
+    Planner --> Strategy[Determine Strategy]
+    Strategy --> RateLimit[Check Rate Limits]
+    RateLimit --> Trust[Check Trust]
+
+    Trust --> Approval{Needs Approval?}
+    Approval -->|Yes| RequestApproval[Request User Approval]
+    Approval -->|No| Execute[Execute Hook]
+
+    RequestApproval --> UserApproves{User Approves?}
+    UserApproves -->|Yes| Execute
+    UserApproves -->|No| Skip[Skip Hook]
+
+    Execute --> Runner[Hook Runner]
+    Runner --> Spawn[Spawn Process]
+    Spawn --> WriteStdin[Write Event Data]
+    WriteStdin --> ReadStdout[Read Response]
+    ReadStdout --> Parse[Parse JSON]
+    Parse --> Process[Process Result]
+
+    Process --> Continue{Continue Flag?}
+    Continue -->|Yes| NextHook[Next Hook]
+    Continue -->|No| Stop[Stop Execution]
+
+    NextHook --> Registry
+    Skip --> NextHook
+    Stop --> Done[Complete]
+
+    style Event fill:#e1f5ff
+    style Trust fill:#fff4e1
+    style Execute fill:#e8f5e9
+    style Done fill:#f3e5f5
+```
+
+### Hook Input/Output Flow
+
+```mermaid
+flowchart LR
+    EventData[Event Data] --> Format[Format Input]
+    Format --> JSON[JSON Object]
+    JSON --> Stdin[Write to stdin]
+    Stdin --> Hook[Hook Process]
+    Hook --> Stdout[Read from stdout]
+    Stdout --> ParseJSON[Parse JSON]
+    ParseJSON --> Validate[Validate Response]
+    Validate --> Result[Process Result]
+
+    style EventData fill:#e1f5ff
+    style Hook fill:#e8f5e9
+    style Result fill:#f3e5f5
+```
+
+---
+
+## Integration Points
+
+### 1. Tool System Integration
+
+Hooks can trigger tool execution through `askAgent` action:
+
+```typescript
+// Hook triggers agent to use tool
+{
+  action: {
+    type: 'askAgent',
+    prompt: 'Run linting on {{file.path}} using the shell tool'
+  }
+}
+```
+
+**Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Hook as Hook
+    participant Agent as Agent
+    participant Tool as Tool Registry
+    participant Shell as Shell Tool
+
+    Hook->>Agent: askAgent("Run linting...")
+    Agent->>Tool: selectTool("shell")
+    Tool-->>Agent: shell tool
+    Agent->>Shell: execute("eslint --fix file.ts")
+    Shell-->>Agent: result
+    Agent-->>Hook: complete
+```
+
+### 2. MCP Integration
+
+**Important:** MCP OAuth must be completed BEFORE hook execution.
+
+**Pre-Authentication Flow:**
+
+```mermaid
+flowchart TD
+    User[User] --> Panel[MCP Panel UI]
+    Panel --> OAuth[OAuth Flow]
+    OAuth --> Store[Store Tokens]
+    Store --> Ready[Ready for Hooks]
+
+    Ready --> HookTrigger[Hook Triggers]
+    HookTrigger --> UseToken[Use Existing Token]
+    UseToken --> MCPCall[MCP Tool Call]
+
+    style OAuth fill:#fff4e1
+    style Store fill:#e8f5e9
+    style MCPCall fill:#e1f5ff
+```
+
+**Why:** Hooks run automatically and cannot prompt for user authentication.
+
+**See:** `dev_MCPIntegration.md` for MCP OAuth details
+
+### 3. Extension System Integration
+
+Extensions can register hooks via manifest:
+
+```json
+{
+  "hooks": {
+    "before_model": [
+      {
+        "name": "validate-input",
+        "command": "node",
+        "args": ["hooks/validate.js"]
+      }
+    ]
+  }
+}
+```
+
+**Registration Flow:**
+
+```mermaid
+flowchart LR
+    Extension[Extension] --> Manager[Extension Manager]
+    Manager --> Parse[Parse Manifest]
+    Parse --> Register[Register Hooks]
+    Register --> Registry[Hook Registry]
+    Registry --> Available[Available to System]
+
+    style Extension fill:#e1f5ff
+    style Register fill:#e8f5e9
+    style Available fill:#f3e5f5
+```
+
+---
+
+## Design Decisions
+
+### 1. JSON stdin/stdout Protocol
+
+**Decision:** Use JSON over stdin/stdout for hook communication
+
+**Rationale:**
+
+- Language-agnostic (works with any language)
+- Simple to implement
+- Standard input/output (no special libraries needed)
+- Easy to debug and test
+
+**Trade-offs:**
+
+- ✅ Universal compatibility
+- ✅ Simple implementation
+- ❌ No streaming support
+- ❌ Limited to text data
+
+### 2. Command Whitelist
+
+**Decision:** Only allow whitelisted commands in `runCommand` hooks
+
+**Rationale:**
+
+- Security first approach
+- Prevent arbitrary command execution
+- Limit attack surface
+- User control over allowed commands
+
+**Whitelisted Commands:**
+
+- `node` - Node.js runtime
+- `python`, `python3` - Python runtime
+- `bash`, `sh` - Shell scripts
+- `npx` - npm package runner
+- `uvx` - uv package runner
+
+**Trade-offs:**
+
+- ✅ Enhanced security
+- ✅ Predictable behavior
+- ❌ Limited flexibility
+- ❌ May need updates for new tools
+
+### 3. Trust Model with Approval
+
+**Decision:** Require approval for untrusted hooks
+
+**Rationale:**
+
+- Security and safety
+- User control
+- Prevent malicious code execution
+- Hash verification for changes
+
+**Trust Levels:**
+
+1. **Builtin** - Always trusted
+2. **User** - Trusted by default
+3. **Workspace** - Requires approval
+4. **Downloaded** - Requires approval
+
+**Trade-offs:**
+
+- ✅ Enhanced security
+- ✅ User awareness
+- ❌ Additional friction
+- ❌ Approval fatigue risk
+
+### 4. Event-Driven Architecture
+
+**Decision:** Use MessageBus for event-driven architecture
+
+**Rationale:**
+
+- Decouples components
+- Enables parallel execution
+- Supports complex workflows
+- Easy to extend
+
+**Benefits:**
+
+- ✅ Loose coupling
+- ✅ Testability
+- ✅ Extensibility
+- ✅ Performance (parallel execution)
+
+### 5. Rate Limiting
+
+**Decision:** Implement per-hook and global rate limits
+
+**Rationale:**
+
+- Prevent hook spam
+- Protect system resources
+- Avoid infinite loops
+- Better user experience
+
+**Configuration:**
+
+- Per-hook max executions per minute
+- Global max executions per minute
+- Cooldown period between runs
+- Execution count tracking
+
+---
+
+## Security Model
+
+### 1. Command Injection Prevention
+
+**Threat:** Malicious hooks executing arbitrary commands
+
+**Mitigation:**
+
+- Command whitelist enforcement
+- Argument sanitization
+- No shell expansion
+- Safe process spawning
+
+**Implementation:**
+
+```typescript
+// Check command is whitelisted
+if (!WHITELISTED_COMMANDS.includes(command)) {
+  throw new Error(`Command not allowed: ${command}`);
+}
+
+// Spawn process safely (no shell)
+const process = spawn(command, args, {
+  shell: false, // Prevent shell injection
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+```
+
+### 2. Input Validation
+
+**Threat:** Malformed input causing crashes or exploits
+
+**Mitigation:**
+
+- JSON schema validation
+- Type checking
+- Required field verification
+- Value range validation
+
+**Implementation:**
+
+```typescript
+function validateHookInput(input: any): void {
+  if (!input.event) {
+    throw new Error('Missing required field: event');
+  }
+  if (!input.context) {
+    throw new Error('Missing required field: context');
+  }
+  // More validation...
+}
+```
+
+### 3. Output Sanitization
+
+**Threat:** Malicious output affecting system
+
+**Mitigation:**
+
+- JSON parsing with error handling
+- Output size limits
+- Special character escaping
+- Sensitive data redaction
+
+**Implementation:**
+
+```typescript
+function sanitizeHookOutput(output: string): any {
+  // Limit output size
+  if (output.length > MAX_OUTPUT_SIZE) {
+    output = output.substring(0, MAX_OUTPUT_SIZE);
+  }
+
+  // Parse JSON safely
+  try {
+    return JSON.parse(output);
+  } catch (error) {
+    throw new Error('Invalid JSON output');
+  }
+}
+```
+
+### 4. Resource Limits
+
+**Threat:** Hooks consuming excessive resources
+
+**Mitigation:**
+
+- Execution timeout (default: 5 seconds)
+- Memory limits
+- Process isolation
+- Rate limiting
+
+**Implementation:**
+
+```typescript
+// Set timeout
+const timeout = setTimeout(() => {
+  process.kill();
+  reject(new Error('Hook execution timeout'));
+}, HOOK_TIMEOUT);
+
+// Clear timeout on completion
+process.on('exit', () => {
+  clearTimeout(timeout);
+});
+```
+
+### 5. Privilege Separation
+
+**Threat:** Hooks accessing sensitive resources
+
+**Mitigation:**
+
+- Run with minimal privileges
+- File system access restrictions
+- Network access restrictions
+- Environment variable filtering
+
+---
+
+## Performance Considerations
+
+### 1. Parallel Execution
+
+**Optimization:** Execute independent hooks in parallel
+
+```mermaid
+graph LR
+    Start[Start] --> Analyze[Analyze Dependencies]
+    Analyze --> Independent{Independent?}
+
+    Independent -->|Yes| Parallel[Execute in Parallel]
+    Independent -->|No| Sequential[Execute Sequentially]
+
+    Parallel --> Hook1[Hook 1]
+    Parallel --> Hook2[Hook 2]
+    Parallel --> Hook3[Hook 3]
+
+    Hook1 --> Wait[Wait for All]
+    Hook2 --> Wait
+    Hook3 --> Wait
+
+    Sequential --> Hook1Seq[Hook 1]
+    Hook1Seq --> Hook2Seq[Hook 2]
+    Hook2Seq --> Hook3Seq[Hook 3]
+
+    Wait --> Done[Complete]
+    Hook3Seq --> Done
+
+    style Parallel fill:#e8f5e9
+    style Sequential fill:#fff4e1
+```
+
+### 2. Process Pooling
+
+**Optimization:** Reuse hook processes for multiple executions
+
+**Implementation:**
+
+- Keep processes alive
+- Reuse for multiple events
+- Close on idle timeout
+- Restart on failure
+
+### 3. Lazy Loading
+
+**Optimization:** Load hooks only when needed
+
+**Implementation:**
+
+- Load hook definitions on startup
+- Spawn processes only on execution
+- Cache hook metadata
+- Unload unused hooks
+
+---
+
+## File Locations
+
+| File                                           | Purpose                               |
+| ---------------------------------------------- | ------------------------------------- |
+| `packages/core/src/hooks/hookRegistry.ts`      | Hook storage and retrieval            |
+| `packages/core/src/hooks/hookEventHandler.ts`  | Event emission                        |
+| `packages/core/src/hooks/hookPlanner.ts`       | Execution planning                    |
+| `packages/core/src/hooks/hookRunner.ts`        | Hook execution (line 128: whitelist)  |
+| `packages/core/src/hooks/types.ts`             | Type definitions (line 30-42: events) |
+| `packages/core/src/hooks/hookDebugger.ts`      | Debugging and logging                 |
+| `packages/core/src/hooks/hookTranslator.ts`    | Legacy format translation             |
+| `packages/core/src/hooks/trustedHooks.ts`      | Trust management                      |
+| `packages/core/src/hooks/config.ts`            | Hook configuration                    |
+| `packages/core/src/hooks/messageBus.ts`        | Event bus                             |
+| `packages/cli/src/commands/hookCommands.ts`    | Hook management commands              |
+| `packages/core/src/services/hookService.ts`    | Hook service integration              |
+| `packages/cli/src/services/hookLoader.ts`      | Hook loading                          |
+| `packages/cli/src/services/hookFileService.ts` | Hook file operations                  |
+
+---
+
+## Further Reading
+
+### Documentation
+
+- [Hook User Guide](UserGuide.md) - Using hooks
+- [Hook Protocol](Protocol.md) - Technical protocol specification
+- [Keyboard Shortcuts](KeyboardShortcuts.md) - Hooks Panel UI shortcuts
+- [Visual Guide](VisualGuide.md) - Hooks Panel UI visual guide
+
+### Related Systems
+
+- [MCP Architecture](../MCP/MCP_Architecture.md) - MCP system architecture
+- [Tool Execution](../Tools/Architecture.md) - Tool system architecture
+- [Extension System](../Tools/GettingStarted.md) - Extension system
+
+### External References
+
+- JSON Specification (https://www.json.org/)
+- Process Management (https://nodejs.org/api/child_process.html)
+- Event-Driven Architecture (https://en.wikipedia.org/wiki/Event-driven_architecture)
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-01-26  
+**Status:** ✅ Complete