S2thend · Apr 3, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 3, 2026 · Apr 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -3,6 +3,8 @@
 Auto-generated from all feature plans. Last updated: 2026-04-01
 
 ## Active Technologies
+- TypeScript 5.x with strict mode enabled, running on Node.js 20+ + Commander.js (CLI framework), Node.js built-ins (`fs`, `path`, `readline`) (008-agent-session-linking)
+- Local Claude Code JSONL session files under `~/.claude/projects/`, including both flat `agent-*.jsonl` files and nested `<main-session>/subagents/agent-*.jsonl` files (008-agent-session-linking)
 
 - TypeScript 5.x with strict mode enabled + Commander.js (CLI framework), Node.js built-ins (`fs`, `path`, `readline`) (007-support-progress-messages)
 
@@ -22,6 +24,7 @@ npm test && npm run lint
 TypeScript 5.x with strict mode enabled: Follow standard conventions
 
 ## Recent Changes
+- 008-agent-session-linking: Added TypeScript 5.x with strict mode enabled, running on Node.js 20+ + Commander.js (CLI framework), Node.js built-ins (`fs`, `path`, `readline`)
 
 - 007-support-progress-messages: Added TypeScript 5.x with strict mode enabled + Commander.js (CLI framework), Node.js built-ins (`fs`, `path`, `readline`)
 

diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ A POSIX-style CLI tool that does one thing well: access your Claude Code chat hi
 
 - **List Sessions** - View all your Claude Code sessions with summaries, timestamps, and message counts
 - **View Conversations** - Read full session content with formatted messages and tool calls
+- **Linked Agent Sessions** - Discover nested subagent transcripts, expose linked agent IDs on parent sessions, and open agent transcripts directly by bare or prefixed agent ID
 - **Progress Messages** - Search, view, filter, and export `progress` session entries without falling back to raw JSONL files
 - **Token Statistics** - View complete token usage breakdown (input, output, cache read, cache creation) per session or aggregated across sessions
 - **Search** - Find specific content across all sessions or within a single session
@@ -58,6 +59,8 @@ cch list --stats
 cch list --json
 ```
 
+Human-readable `cch list` output remains main-session-only. `cch list --json` includes `agentIds` for discoverable child transcripts and `unresolvedAgentIds` for referenced child agents whose transcripts are not currently discoverable.
+
 **Output:**
 
 ```
@@ -96,13 +99,20 @@ cch view 0
 # View by UUID
 cch view abc123-def456-...
 
+# View a linked agent transcript directly
+cch view linked123
+cch view agent-linked123
+
 # View only progress messages
 cch view 0 --only progress
 
 # Output as JSON
 cch view 0 --json
+cch view linked123 --json
 ```
 
+`cch view` accepts a session index, full or partial main-session UUID, bare agent ID, or `agent-<id>`. Direct agent lookup is safe by default: ambiguous bare agent IDs fail instead of guessing. In JSON mode, ambiguous agent lookups return an `ambiguous-agent-id` error payload, and missing direct agent lookups return `session-not-found`.
+
 **Output:**
 
 ````
@@ -210,7 +220,11 @@ cch export --all --output all-sessions.json
 cch export --all --format markdown --output all-sessions.md
 ```
 
-Progress messages are preserved in JSON and Markdown exports, and `cch view --json` retains `type: "progress"` entries in the returned message list.
+Progress messages are preserved in JSON and Markdown exports, `cch view --json` retains `type: "progress"` entries in the returned message list, and exported session metadata preserves both `agentIds` and `unresolvedAgentIds`.
+
+## Platform Notes
+
+Nested subagent discovery is supported on macOS, Linux, and Windows Claude directory layouts. One existing Claude path caveat still applies: encoded project directory names do not round-trip perfectly when original workspace path segments contain literal hyphens, so decoded paths in those edge cases can normalize hyphens into path separators.
 
 ### Migrate Sessions
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "claude-code-history",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI and library for browsing, searching, exporting, and managing Claude Code chat history",
   "type": "module",
   "main": "./dist/lib/index.js",

diff --git a/specs/008-agent-session-linking/checklists/requirements.md b/specs/008-agent-session-linking/checklists/requirements.md
@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Agent Session Linking
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-02
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validated against `spec.md` on 2026-04-02.
+- No clarification markers remain; the spec is ready for `/speckit.plan`.
diff --git a/specs/008-agent-session-linking/contracts/cli-interface.md b/specs/008-agent-session-linking/contracts/cli-interface.md
@@ -0,0 +1,158 @@
+# CLI Interface Contract: Agent Session Linking
+
+**Feature**: 008-agent-session-linking  
+**Date**: 2026-04-02
+
+## Overview
+
+This contract defines the user-facing CLI behavior changes needed so `cch` can navigate directly from main-session metadata to nested or flat agent transcripts without polluting top-level session lists.
+
+## Command: `list`
+
+### Syntax
+
+```bash
+cch list [options]
+```
+
+No new flags are introduced.
+
+### Updated Result Semantics
+
+- Human-readable list output continues to show only main sessions as top-level rows.
+- JSON list output includes both `agentIds` and `unresolvedAgentIds` for each main-session summary.
+- Linked agent IDs are derived from explicit main-session evidence first and nested fallback path ownership second.
+
+### JSON Example
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "index": 0,
+      "id": "11111111-1111-1111-1111-111111111111",
+      "projectPath": "/tmp/project",
+      "summary": "Nested agent example",
+      "agentIds": ["abc123"],
+      "unresolvedAgentIds": ["missing456"]
+    }
+  ]
+}
+```
+
+## Command: `view`
+
+### Updated Syntax
+
+```bash
+cch view <session>
+```
+
+### Accepted Identifier Forms
+
+- Numeric session index
+- Main-session UUID
+- Partial main-session UUID prefix
+- Bare linked agent identifier
+- `agent-<id>` form of a linked agent identifier
+
+### Updated Usage Text
+
+```text
+Usage: cch view <session>
+
+Provide a session index, session UUID, or agent ID.
+```
+
+## View Output Behavior
+
+### Main Session Detail
+
+- Human-readable output may show:
+  - linked agent IDs that are directly usable in follow-up lookup
+  - unresolved referenced agent IDs that are not currently retrievable
+- JSON output includes both `agentIds` and `unresolvedAgentIds`.
+
+### Direct Agent Transcript View
+
+- `cch view abc123` opens the matching agent transcript when exactly one discoverable transcript matches.
+- `cch view agent-abc123` behaves the same as the bare form.
+- The agent transcript remains a separate session view rather than being merged into the parent main-session transcript.
+
+### Ambiguity Handling
+
+```bash
+$ cch view abc123
+```
+
+```text
+Error: Agent ID is ambiguous: abc123
+Multiple matching agent transcripts were found. Use a more specific session identifier.
+```
+
+Exit code: non-zero
+
+### JSON Ambiguity Handling
+
+```bash
+$ cch view abc123 --json
+```
+
+```json
+{
+  "success": false,
+  "error": {
+    "type": "ambiguous-agent-id",
+    "agentId": "abc123",
+    "message": "Agent ID is ambiguous: abc123"
+  }
+}
+```
+
+### Missing Agent Handling
+
+```bash
+$ cch view missing456
+```
+
+```text
+Error: Session not found: missing456
+Try 'cch list --json' or inspect the parent session's unresolved agent references.
+```
+
+Exit code: non-zero
+
+### JSON Missing Agent Handling
+
+```bash
+$ cch view missing456 --json
+```
+
+```json
+{
+  "success": false,
+  "error": {
+    "type": "session-not-found",
+    "agentId": "missing456",
+    "message": "Session not found: missing456"
+  }
+}
+```
+
+## Option Interactions
+
+| Command | Behavior |
+|---------|----------|
+| `cch list` | Shows only main-session rows |
+| `cch list --json` | Includes `agentIds` and `unresolvedAgentIds` in each summary |
+| `cch view <uuid>` | Shows main-session detail with linked and unresolved agent metadata |
+| `cch view <agent-id>` | Opens matching child-agent transcript when unique |
+| `cch view agent-<id>` | Same lookup behavior as bare agent ID |
+
+## Help Text Impact
+
+- `cch view --help` MUST describe accepted identifier forms beyond index/UUID only.
+- User-facing ambiguity errors MUST be distinct from not-found errors.
+- `cch view --json` MUST return structured error results for ambiguity and not-found outcomes instead of plain strings.
+- No new flags are required for `list` or `view`.