Add comprehensive schema analysis report and update documentation

- Merge copilot/analyze-repository-core-flows branch with PR #7 docs
- Create SCHEMA_ANALYSIS_REPORT.md with consolidated schema definitions
- Update ARCHITECTURE_SUMMARY.md with complete SessionLogEntry schema
- Update ARCHITECTURE_ANALYSIS.md with sub-agent support clarification
- Add Task, TaskOutput, Read, Glob, Grep tool input schemas
- Add signature field to ThinkingBlock schema
- Expand entry types to include queue-operation and file-history-snapshot
- Update docs README with new document and version history

Co-authored-by: ShlomoStept <74121686+ShlomoStept@users.noreply.github.com>

Author: Copilot

docs/ARCHITECTURE_ANALYSIS.md

@@ -392,21 +392,29 @@ Generate HTML Files
 
 ## 2. Connecting the Main Agent to Sub-Agent Activity
 
-### 2.1 Current State: No Sub-Agent Tracking
+### 2.1 Current State: Sub-Agent Format Supported, Discovery Disabled
 
-**Important Finding:** The current codebase does **not** have explicit sub-agent tracking or hierarchical agent relationships.
+> **Update (2026-01-02):** Analysis of Claude Code artifacts reveals that sub-agent fields exist in the format. See [SCHEMA_ANALYSIS_REPORT.md](./SCHEMA_ANALYSIS_REPORT.md) for complete details.
 
-**Evidence:**
-1. Session filtering explicitly excludes agent files:
-   ```python
-   # Line 359 in find_local_sessions()
-   if f.name.startswith("agent-"):
-       continue
-   ```
+**Finding:** The artifact format **does support** sub-agent tracking via:
+- `agentId` field in session entries
+- `Task` tool for sub-agent invocation
+- `TaskOutput` tool for sub-agent result retrieval
+- `resume` parameter for resuming sub-agent context
 
-2. No agent ID or parent-child relationships in message schemas
+**Current Limitation:**
+The discovery code excludes agent files from listing:
+```python
+# Line 359 in find_local_sessions()
+if f.name.startswith("agent-"):
+    continue
+```
 
-3. All messages treated as single-agent conversation
+**To Enable Sub-Agent Support:**
+1. Add `--include-agents` flag to discovery functions
+2. Parse `agentId` field from session entries
+3. Link conversations via `parentUuid` relationship
+4. Add specialized renderer for `Task` tool
 
 ### 2.2 Tool Call and Tool Response Linking
 
@@ -624,12 +632,30 @@ interface NormalizedJSONLSession {
 
 ### 3.3 LogLine Schema
 
+> **Note:** The complete, all-inclusive schema has been documented in [SCHEMA_ANALYSIS_REPORT.md](./SCHEMA_ANALYSIS_REPORT.md). The schema below represents the normalized parsing output, while the full artifact format includes additional fields.
+
 ```typescript
 interface LogLine {
-    type: "user" | "assistant";
+    // Core Identifiers (from raw artifacts)
+    uuid?: string;                // Unique event identifier
+    parentUuid?: string | null;   // Linked-list parent pointer
+    sessionId?: string;           // Session grouping ID
+    
+    // Entry Type (expanded)
+    type: "user" | "assistant" | "queue-operation" | "file-history-snapshot";
+    
     timestamp: string;  // ISO 8601 format, e.g., "2025-12-24T10:00:00.000Z"
     message: Message;
-    isCompactSummary?: boolean;  // Optional, indicates session continuation
+    
+    // Context Fields (optional)
+    cwd?: string;                 // Current working directory
+    gitBranch?: string;           // Active git branch
+    userType?: "external";        // User type indicator
+    isSidechain?: boolean;        // Parallel conversation flag
+    agentId?: string;             // Sub-agent identifier
+    slug?: string;                // Human-readable session ID
+    
+    isCompactSummary?: boolean;   // Session continuation indicator
 }
 ```
 
@@ -639,8 +665,11 @@ interface LogLine {
 
 **Field Details:**
 
-- **`type`**: Role of the message sender
-  - Values: `"user"` | `"assistant"`
+- **`type`**: Entry type
+  - Values: `"user"` | `"assistant"` | `"queue-operation"` | `"file-history-snapshot"`
+  - `user`/`assistant`: Standard message entries
+  - `queue-operation`: Background task queue operations
+  - `file-history-snapshot`: File backup state at message time
   - Determines rendering style and icon
 
 - **`timestamp`**: When the message was created
@@ -650,6 +679,11 @@ interface LogLine {
 
 - **`message`**: The actual message content (see Message schema)
 
+- **`agentId`**: Sub-agent identifier
+  - Type: string (optional)
+  - Present when message is from a sub-agent
+  - Can be used to link sub-agent sessions
+
 - **`isCompactSummary`**: Indicates session continuation/resume
   - Type: boolean (optional)
   - When true: Rendered as collapsible summary
@@ -729,22 +763,26 @@ interface TextBlock extends BaseContentBlock {
 ```typescript
 interface ThinkingBlock extends BaseContentBlock {
     type: "thinking";
-    thinking: string;  // Markdown-formatted internal reasoning
+    thinking: string;    // Markdown-formatted internal reasoning
+    signature: string;   // Cryptographic verification signature
 }
 ```
 
 **Example:**
 ```json
 {
     "type": "thinking",
-    "thinking": "The user wants a simple addition function. I should:\n1. Create the function\n2. Add a basic test"
+    "thinking": "The user wants a simple addition function. I should:\n1. Create the function\n2. Add a basic test",
+    "signature": "abc123..."
 }
 ```
 
 **Rendering:** Lines 946-948  
 **Renderer:** `_macros.thinking(content_html)`  
 **Styling:** Closed by default, yellow background
 
+> **Note:** The `signature` field was discovered during artifact analysis (see [SCHEMA_ANALYSIS_REPORT.md](./SCHEMA_ANALYSIS_REPORT.md)).
+
 ---
 
 #### 3.5.3 Tool Use Block
@@ -982,7 +1020,91 @@ interface TodoItem {
 
 ---
 
-#### 3.6.5 Generic Tool Input
+#### 3.6.5 Task Tool Input (Sub-Agent Invocation)
+
+> **Added (2026-01-02):** Documented based on artifact analysis. See [SCHEMA_ANALYSIS_REPORT.md](./SCHEMA_ANALYSIS_REPORT.md).
+
+```typescript
+interface TaskToolInput {
+    subagent_type: string;          // e.g., "Explore", "Plan", "general-purpose", "structured-engineering-agent"
+    prompt: string;                 // Detailed instructions for the sub-agent
+    description: string;            // Short human-readable summary
+    resume?: string;                // Optional agentId to resume existing context
+    model?: string;                 // Optional model override (e.g., "opus")
+    run_in_background?: boolean;    // Whether to run asynchronously
+}
+```
+
+**Known `subagent_type` Values:**
+- `"general-purpose"` - General task execution
+- `"Explore"` - Code/file exploration
+- `"Plan"` - Planning and strategy
+- `"structured-engineering-agent"` - Complex engineering tasks
+
+**Example:**
+```json
+{
+    "subagent_type": "Explore",
+    "prompt": "Find all Python files that contain database queries",
+    "description": "Finding database-related code",
+    "run_in_background": true
+}
+```
+
+**Rendering:** Currently uses generic tool renderer  
+**Recommendation:** Add specialized renderer with sub-agent type highlighting
+
+---
+
+#### 3.6.6 TaskOutput Tool Input
+
+```typescript
+interface TaskOutputToolInput {
+    task_id: string;    // ID of the Task to get output from
+    block: boolean;     // Whether to block waiting for output
+    timeout: number;    // Timeout in seconds
+}
+```
+
+---
+
+#### 3.6.7 Read Tool Input
+
+```typescript
+interface ReadToolInput {
+    file_path: string;   // Path to file to read
+    offset?: number;     // Starting line number
+    limit?: number;      // Number of lines to read
+}
+```
+
+---
+
+#### 3.6.8 Glob Tool Input
+
+```typescript
+interface GlobToolInput {
+    pattern: string;  // Glob pattern (e.g., "**/*.py")
+    path?: string;    // Base directory path
+}
+```
+
+---
+
+#### 3.6.9 Grep Tool Input
+
+```typescript
+interface GrepToolInput {
+    pattern: string;       // Search pattern (regex)
+    path: string;          // Directory or file to search
+    output_mode?: string;  // Output format mode
+    "-n"?: boolean;        // Show line numbers
+}
+```
+
+---
+
+#### 3.6.10 Generic Tool Input
 ```typescript
 interface GenericToolInput {
     description?: string;  // Optional description field
@@ -991,14 +1113,10 @@ interface GenericToolInput {
 ```
 
 **Used For:** Tools without specialized renderers:
-- Glob
-- Grep  
-- Read
 - WebFetch
 - WebSearch
 - Agent
 - Skill
-- Task
 
 **Rendering:** Lines 964-977  
 **Features:**

docs/ARCHITECTURE_SUMMARY.md

@@ -48,32 +48,68 @@
 **Session (Normalized):**
 ```typescript
 {
-    loglines: [
-        {
-            type: "user" | "assistant",
-            timestamp: string,  // ISO 8601
-            message: {
-                role: string,
-                content: string | ContentBlock[]
-            },
-            isCompactSummary?: boolean
-        }
-    ]
+    loglines: SessionLogEntry[]
+}
+
+interface SessionLogEntry {
+    // Core Identifiers
+    uuid: string;                // Unique event identifier
+    parentUuid: string | null;   // Linked-list parent pointer for ordering
+    sessionId: string;           // Conversation/session grouping ID
+    
+    // Entry Type (expanded from user/assistant)
+    type: "user" | "assistant" | "queue-operation" | "file-history-snapshot";
+    
+    timestamp: string;           // ISO 8601
+    
+    // Context Fields (optional)
+    cwd?: string;                // Current working directory
+    gitBranch?: string;          // Active git branch
+    userType?: "external";       // User type indicator
+    isSidechain?: boolean;       // Parallel/sidechain conversation flag
+    agentId?: string;            // Sub-agent identifier (e.g., "a85b54c")
+    slug?: string;               // Human-readable session identifier
+    
+    // Message Payload (for user/assistant types)
+    message?: {
+        role: "user" | "assistant";
+        content: ContentBlock[];
+        model?: string;          // e.g., "claude-opus-4-5-20251101"
+        id?: string;             // Message-specific ID
+    };
+    
+    // Snapshot Payload (for file-history-snapshot type)
+    snapshot?: {
+        messageId: string;
+        trackedFileBackups: Record<string, any>;
+        timestamp: string;
+    };
+    
+    // Queue Payload (for queue-operation type)
+    operation?: "enqueue" | "remove";
+    content?: string;            // Queue item content
+    
+    isCompactSummary?: boolean;  // Session continuation indicator
 }
 ```
 
 **Content Blocks:**
-- `text` - Markdown text
-- `thinking` - Internal reasoning
-- `tool_use` - Tool invocation
-- `tool_result` - Tool output
-- `image` - Base64 image
-
-**Tool Inputs:**
-- `Write`: `{file_path, content}`
-- `Edit`: `{file_path, old_string, new_string, replace_all?}`
-- `Bash`: `{command, description?}`
-- `TodoWrite`: `{todos: [{content, status, activeForm?}]}`
+- `text`: `{ type: "text", text: string }` - Markdown text
+- `thinking`: `{ type: "thinking", thinking: string, signature: string }` - Internal reasoning with verification signature
+- `tool_use`: `{ type: "tool_use", id: string, name: string, input: object }` - Tool invocation
+- `tool_result`: `{ type: "tool_result", tool_use_id: string, content: string | ContentBlock[], is_error?: boolean }` - Tool output
+- `image`: `{ type: "image", source: { type: "base64", media_type: string, data: string } }` - Base64 image
+
+**Tool Inputs (Complete List):**
+- `Write`: `{ file_path: string, content: string }`
+- `Edit`: `{ file_path: string, old_string: string, new_string: string, replace_all?: boolean }`
+- `Bash`: `{ command: string, description?: string }`
+- `TodoWrite`: `{ todos: [{ content: string, status: "pending" | "in_progress" | "completed", activeForm?: string }] }`
+- `Task` (Sub-Agent): `{ subagent_type: string, prompt: string, description: string, resume?: string, model?: string, run_in_background?: boolean }`
+- `TaskOutput`: `{ task_id: string, block: boolean, timeout: number }`
+- `Read`: `{ file_path: string, offset?: number, limit?: number }`
+- `Glob`: `{ pattern: string, path?: string }`
+- `Grep`: `{ pattern: string, path: string, output_mode?: string, "-n"?: boolean }`
 
 ### Module Boundaries (Current Monolith)
 
@@ -96,16 +132,18 @@ assets/       - CSS/JS
 - **Lines of Code:** 2994 (single file)
 - **Content Block Types:** 5 (text, thinking, tool_use, tool_result, image)
 - **Tool Renderers:** 4 specialized (Write, Edit, Bash, TodoWrite) + 1 generic
+- **Tool Input Types:** 9 documented (Write, Edit, Bash, TodoWrite, Task, TaskOutput, Read, Glob, Grep)
+- **Entry Types:** 4 (user, assistant, queue-operation, file-history-snapshot)
 - **Session Formats:** 2 (JSON, JSONL)
 - **CLI Commands:** 4 (local, web, json, all)
 
 ---
 
 ## Key Findings
 
-1. **No Sub-Agent Support:** Current code explicitly excludes agent files
-2. **Schemas Implicit:** No formal definitions, inferred from code
-3. **Tool Pairing Works:** Reliable ID-based system
+1. **Sub-Agent Format Supported:** Artifacts include `agentId` field and `Task` tool for sub-agent tracking. Discovery code excludes `agent-*` files from listing, but the format fully supports sub-agents.
+2. **Schemas Now Documented:** Complete specifications including SessionLogEntry, Content Blocks, and 9 Tool Input types (see [SCHEMA_ANALYSIS_REPORT.md](./SCHEMA_ANALYSIS_REPORT.md))
+3. **Tool Pairing Works:** Reliable ID-based system (`tool_use.id` ↔ `tool_result.tool_use_id`)
 4. **Componentization Needed:** Monolithic structure limits maintainability
 
 ## Next Steps