inter-agent-bridge-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inter-Agent Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,65 @@
+# Inter-Agent Bridge Protocol v0.2.0
+
+## Purpose
+Define a lightweight, local-first standard for reading and coordinating cross-agent session evidence across Codex, Gemini, and Claude.
+
+## Tenets
+1. Local-first: read local session logs only by default.
+2. Evidence-based: every claim must map to source sessions.
+3. Context-light: return concise structured output first.
+4. Dual implementation parity: Node and Rust must follow the same command and JSON contract.
+
+## Canonical Modes
+- `verify`
+- `steer`
+- `analyze`
+- `feedback`
+
+## CLI Contract (v0.2)
+Both implementations must support:
+
+```bash
+bridge read --agent <codex|gemini|claude> [--id=<substring>] [--cwd=<path>] [--chats-dir=<path>] [--json]
+bridge compare --source <agent[:session-substring]>... [--cwd=<path>] [--json]
+bridge report --handoff <path-to-handoff.json> [--cwd=<path>] [--json]
+```
+
+Rules:
+1. `--cwd` defaults to current working directory when not provided.
+2. If `--id` is provided, select the most recently modified session file whose path contains the substring.
+3. If `--id` is not provided, select newest session scoped by cwd when possible.
+4. If cwd-scoped session is missing for Codex/Claude, warn and fall back to latest global session.
+5. Hard failures must exit non-zero and print a concise error.
+
+## JSON Output Contract (`bridge read --json`)
+
+```json
+{
+  "agent": "codex",
+  "source": "/absolute/path/to/session-file",
+  "content": "last assistant/model turn or fallback text",
+  "warnings": [
+    "Warning: no Codex session matched cwd /path; falling back to latest session."
+  ]
+}
+```
+
+Schema is defined in `schemas/read-output.schema.json`.
+
+`bridge report --json` outputs the coordinator report object defined by `schemas/report.schema.json`.
+`bridge report --handoff` consumes packets defined by `schemas/handoff.schema.json`.
+
+## Redaction Rules
+Implementations must redact likely secrets from returned content before printing:
+- `sk-...` style API keys
+- `AKIA...` style AWS access key IDs
+- `Bearer <token>` headers
+- `api_key|token|secret|password` key-value pairs
+
+## Environment Overrides (for testing and controlled installs)
+- `BRIDGE_CODEX_SESSIONS_DIR`
+- `BRIDGE_GEMINI_TMP_DIR`
+- `BRIDGE_CLAUDE_PROJECTS_DIR`
+
+## Conformance
+Any release must pass `scripts/conformance.sh`, which runs both implementations against shared fixtures and verifies equivalent JSON output.

package/README.md

@@ -0,0 +1,183 @@
+# Inter-Agent Bridge
+
+![CI Status](https://github.com/cote-star/agent-bridge/actions/workflows/ci.yml/badge.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Version](https://img.shields.io/badge/version-0.2.0-green.svg)
+
+**Inter-Agent Bridge** is a lightweight local protocol and reference implementation for reading cross-agent session context. It enables AI agents (Codex, Gemini, Claude) to read each other's recent session outputs from local storage, facilitating coordination, verification, and steering without a centralized cloud service.
+
+## 🌟 Key Tenets
+
+1.  **Local-First**: Reads directly from local session logs (`~/.codex/sessions`, etc.) by default and does not call external services for `read`, `compare`, or `report`.
+2.  **Evidence-Based**: Every claim or summary must track back to a specific source session file.
+3.  **Privacy-Focused**: Automatically redacts sensitive keys (API keys, AWS tokens) before output.
+4.  **Dual Parity**: Ships with both **Node.js** and **Rust** CLIs that are conformance-tested against the same output contract.
+
+## 🎥 Demo
+
+![Inter-Agent Bridge Demo](docs/demo.webp)
+
+## 🏗️ Architecture
+
+The bridge acts as a universal translator for agent session formats.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant BridgeCLI
+    participant Codex as ~/.codex/sessions
+    participant Gemini as ~/.gemini/tmp
+    participant Claude as ~/.claude/projects
+
+    User->>BridgeCLI: bridge read --agent codex --id "fix-bug"
+    BridgeCLI->>Codex: Scan & Parse JSONL
+    Codex-->>BridgeCLI: Raw Session Data
+    BridgeCLI->>BridgeCLI: Redact Secrets (sk-..., AKIA...)
+    BridgeCLI->>BridgeCLI: Format via Schema
+    BridgeCLI-->>User: Structured JSON Output
+```
+
+## 🚀 Feature Matrix
+
+| Feature            | Codex | Gemini | Claude |
+| :----------------- | :---: | :----: | :----: |
+| **Read Content**   |  ✅   |   ✅   |   ✅   |
+| **Auto-Discovery** |  ✅   |   ✅   |   ✅   |
+| **CWD Scoping**    |  ✅   |   ⚠️   |   ✅   |
+| **Comparisons**    |  ✅   |   ✅   |   ✅   |
+
+> ⚠️ Gemini resolves sessions by hashing the working directory path (SHA256) to locate chat files, rather than extracting CWD metadata from session content like Codex and Claude.
+
+## 📦 Installation
+
+### Consumers (After Release)
+
+> Available after v0.2.0 is published to npm / crates.io.
+
+**Node.js**:
+
+```bash
+npm install -g inter-agent-bridge-cli
+bridge-node read --agent=codex --json
+```
+
+**Rust**:
+
+```bash
+cargo install bridge-cli
+bridge read --agent codex --json
+```
+
+### Contributors (Developers)
+
+Clone the repository to build from source.
+
+**Node**:
+
+```bash
+npm install
+node scripts/read_session.cjs read --agent=codex
+```
+
+**Rust**:
+
+```bash
+cargo run --manifest-path cli/Cargo.toml -- read --agent codex
+```
+
+## 📖 Usage
+
+> **Note**: The examples below use the `bridge` command. If you installed via Node.js (`npm`), use `bridge-node` instead.
+
+### Reading a Session
+
+Get the last assistant/model output from a specific agent context.
+
+```bash
+# Read from Codex (defaults to latest session)
+bridge read --agent codex
+
+# Read from Claude, scoped to current working directory
+bridge read --agent claude --cwd /path/to/project
+
+# Get machine-readable JSON output
+bridge read --agent gemini --json
+```
+
+### Comparing Agents (`analyze` mode)
+
+Compare outputs from multiple agents to detect divergence.
+
+```bash
+bridge compare --source codex --source gemini --source claude --json
+```
+
+### Reporting
+
+Generate a full coordination report from a handoff packet.
+
+```bash
+bridge report --handoff ./handoff_packet.json --json
+```
+
+### Protocol-Accurate Command Contract
+
+```bash
+bridge read --agent <codex|gemini|claude> [--id=<substring>] [--cwd=<path>] [--chats-dir=<path>] [--json]
+bridge compare --source <agent[:session-substring]>... [--cwd=<path>] [--json]
+bridge report --handoff <handoff.json> [--cwd=<path>] [--json]
+```
+
+- `read` returns the latest assistant/model output found in the selected session (or fallback raw lines when structured extraction fails).
+- `compare` parses each `--source` as `<agent>` (current session) or `<agent>:<session-substring>`.
+- `report` consumes a handoff packet and emits structured findings/recommendations.
+
+## ⚙️ Configuration
+
+Override default paths using environment variables.
+
+| Variable                     | Description               | Default              |
+| :--------------------------- | :------------------------ | :------------------- |
+| `BRIDGE_CODEX_SESSIONS_DIR`  | Path to Codex sessions    | `~/.codex/sessions`  |
+| `BRIDGE_GEMINI_TMP_DIR`      | Path to Gemini temp chats | `~/.gemini/tmp`      |
+| `BRIDGE_CLAUDE_PROJECTS_DIR` | Path to Claude projects   | `~/.claude/projects` |
+
+## 🛠️ Development
+
+- **Protocol**: See [PROTOCOL.md](./PROTOCOL.md) for the CLI and JSON specification.
+- **Skills**: See [SKILL.md](./SKILL.md) for agentic capabilities.
+- **Release**: See [docs/release.md](./docs/release.md) for publishing workflows.
+
+### Conformance Testing
+
+Ensure both Node and Rust implementations return identical output for the same fixtures.
+
+```bash
+bash scripts/conformance.sh
+```
+
+### README Command Checks
+
+Run fixture-backed checks for command examples documented in this README.
+
+```bash
+bash scripts/check_readme_examples.sh
+```
+
+### Schema Validation
+
+Validate that generated reports match the JSON schema.
+
+```bash
+bash scripts/validate_schemas.sh
+```
+
+If your environment is offline, use:
+
+```bash
+BRIDGE_SKIP_AJV=1 bash scripts/validate_schemas.sh
+```
+
+---
+
+_Maintained by the Agent Bridge Team._

package/fixtures/handoff-report.json

@@ -0,0 +1,32 @@
+{
+  "mode": "verify",
+  "task": "Validate fixture implementation parity",
+  "success_criteria": [
+    "All sources readable",
+    "No divergence in fixture outputs"
+  ],
+  "sources": [
+    {
+      "agent": "codex",
+      "session_id": "codex-fixture",
+      "current_session": false,
+      "cwd": "/workspace/demo"
+    },
+    {
+      "agent": "gemini",
+      "session_id": "gemini-fixture",
+      "current_session": false,
+      "cwd": "/workspace/demo"
+    },
+    {
+      "agent": "claude",
+      "session_id": "claude-fixture",
+      "current_session": false,
+      "cwd": "/workspace/demo"
+    }
+  ],
+  "constraints": [
+    "No cloud dependencies",
+    "Keep output concise"
+  ]
+}

package/fixtures/session-store/claude/projects/sample/session-claude-fixture-0001.jsonl

@@ -0,0 +1,2 @@
+{"cwd":"/workspace/demo"}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Claude fixture assistant output."}]}}

package/fixtures/session-store/codex/sessions/2026/01/01/session-codex-fixture-0001.jsonl

@@ -0,0 +1,2 @@
+{"type":"session_meta","payload":{"cwd":"/workspace/demo"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":"Codex fixture assistant output."}}

package/fixtures/session-store/gemini/tmp/demo/chats/session-gemini-fixture-0001.json

@@ -0,0 +1,7 @@
+{
+  "sessionId": "gemini-fixture-0001",
+  "messages": [
+    {"type": "user", "content": "hello"},
+    {"type": "gemini", "content": "Gemini fixture assistant output."}
+  ]
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "inter-agent-bridge-cli",
+  "version": "0.2.0",
+  "private": false,
+  "type": "commonjs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cote-star/agent-bridge.git"
+  },
+  "homepage": "https://github.com/cote-star/agent-bridge",
+  "bugs": {
+    "url": "https://github.com/cote-star/agent-bridge/issues"
+  },
+  "bin": {
+    "bridge-node": "scripts/read_session.cjs"
+  },
+  "files": [
+    "scripts/read_session.cjs",
+    "PROTOCOL.md",
+    "README.md",
+    "schemas",
+    "fixtures"
+  ],
+  "scripts": {
+    "conformance": "bash scripts/conformance.sh",
+    "check:readme": "bash scripts/check_readme_examples.sh",
+    "validate:schemas": "bash scripts/validate_schemas.sh",
+    "check": "npm run conformance && npm run check:readme && npm run validate:schemas"
+  }
+}

package/schemas/handoff.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://inter-agent-bridge.dev/schemas/handoff.schema.json",
+  "title": "Coordinator Handoff Packet",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mode", "task", "success_criteria", "sources"],
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["verify", "steer", "analyze", "feedback"]
+    },
+    "task": {
+      "type": "string",
+      "minLength": 1
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["agent"],
+        "anyOf": [
+          {
+            "required": ["session_id"],
+            "properties": {
+              "session_id": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          {
+            "required": ["current_session"],
+            "properties": {
+              "current_session": {
+                "const": true
+              }
+            }
+          }
+        ],
+        "properties": {
+          "agent": {
+            "type": "string",
+            "enum": ["codex", "gemini", "claude"]
+          },
+          "session_id": { "type": ["string", "null"] },
+          "current_session": { "type": "boolean" },
+          "cwd": { "type": "string" }
+        }
+      }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/read-output.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://inter-agent-bridge.dev/schemas/read-output.schema.json",
+  "title": "Bridge Read Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["agent", "source", "content", "warnings"],
+  "properties": {
+    "agent": {
+      "type": "string",
+      "enum": ["codex", "gemini", "claude"]
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "content": {
+      "type": "string"
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/report.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://inter-agent-bridge.dev/schemas/report.schema.json",
+  "title": "Coordinator Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mode", "task", "sources_used", "verdict", "findings", "recommended_next_actions"],
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["verify", "steer", "analyze", "feedback"]
+    },
+    "task": {
+      "type": "string"
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "sources_used": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "verdict": {
+      "type": "string"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "summary", "evidence", "confidence"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"]
+          },
+          "summary": { "type": "string" },
+          "evidence": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          }
+        }
+      }
+    },
+    "recommended_next_actions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/scripts/read_session.cjs

@@ -0,0 +1,794 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const rawArgs = process.argv.slice(2);
+const commandNames = new Set(['read', 'compare', 'report']);
+const command = commandNames.has(rawArgs[0]) ? rawArgs[0] : 'read';
+const args = commandNames.has(rawArgs[0]) ? rawArgs.slice(1) : rawArgs;
+
+const codexSessionsBase = normalizePath(process.env.BRIDGE_CODEX_SESSIONS_DIR || '~/.codex/sessions');
+const claudeProjectsBase = normalizePath(process.env.BRIDGE_CLAUDE_PROJECTS_DIR || '~/.claude/projects');
+const geminiTmpBase = normalizePath(process.env.BRIDGE_GEMINI_TMP_DIR || '~/.gemini/tmp');
+
+function expandHome(filepath) {
+  if (!filepath) return filepath;
+  if (filepath === '~') return os.homedir();
+  if (filepath.startsWith('~/')) {
+    return path.join(os.homedir(), filepath.slice(2));
+  }
+  return filepath;
+}
+
+function normalizePath(filepath) {
+  return path.resolve(expandHome(filepath));
+}
+
+function hashPath(filepath) {
+  return crypto.createHash('sha256').update(normalizePath(filepath)).digest('hex');
+}
+
+function getOptionValues(inputArgs, name) {
+  const values = [];
+  for (let i = 0; i < inputArgs.length; i += 1) {
+    const arg = inputArgs[i];
+    if (arg === name && i + 1 < inputArgs.length) {
+      values.push(inputArgs[i + 1]);
+      i += 1;
+      continue;
+    }
+
+    const prefix = `${name}=`;
+    if (arg.startsWith(prefix)) {
+      values.push(arg.slice(prefix.length));
+    }
+  }
+  return values;
+}
+
+function getOptionValue(inputArgs, name, fallback = null) {
+  const values = getOptionValues(inputArgs, name);
+  return values.length > 0 ? values[values.length - 1] : fallback;
+}
+
+function hasFlag(inputArgs, name) {
+  return inputArgs.includes(name);
+}
+
+function collectMatchingFiles(dirPath, predicate, recursive = false) {
+  if (!dirPath || !fs.existsSync(dirPath)) return [];
+
+  const matches = [];
+
+  function search(currentDir) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (error) {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive) search(fullPath);
+        continue;
+      }
+
+      if (!predicate(fullPath, entry.name)) continue;
+
+      try {
+        const stat = fs.statSync(fullPath);
+        matches.push({ path: fullPath, mtimeMs: stat.mtimeMs });
+      } catch (error) {
+        // Ignore entries that disappear while scanning.
+      }
+    }
+  }
+
+  search(dirPath);
+  matches.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return matches;
+}
+
+function readJsonlLines(filePath) {
+  return fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+}
+
+function findLatestByCwd(files, cwdExtractor, expectedCwd) {
+  for (const file of files) {
+    const fileCwd = cwdExtractor(file.path);
+    if (fileCwd && fileCwd === expectedCwd) {
+      return file.path;
+    }
+  }
+  return null;
+}
+
+function getCodexSessionCwd(filePath) {
+  try {
+    const firstLine = readJsonlLines(filePath)[0];
+    if (!firstLine) return null;
+
+    const json = JSON.parse(firstLine);
+    if (json.type === 'session_meta' && json.payload && typeof json.payload.cwd === 'string') {
+      return normalizePath(json.payload.cwd);
+    }
+  } catch (error) {
+    return null;
+  }
+  return null;
+}
+
+function getClaudeSessionCwd(filePath) {
+  try {
+    const lines = readJsonlLines(filePath);
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (typeof json.cwd === 'string') {
+          return normalizePath(json.cwd);
+        }
+      } catch (error) {
+        // Ignore unparseable line.
+      }
+    }
+  } catch (error) {
+    return null;
+  }
+  return null;
+}
+
+function listGeminiChatDirs() {
+  if (!fs.existsSync(geminiTmpBase)) return [];
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(geminiTmpBase, { withFileTypes: true });
+  } catch (error) {
+    return [];
+  }
+
+  const dirs = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const chatsDir = path.join(geminiTmpBase, entry.name, 'chats');
+    if (fs.existsSync(chatsDir)) {
+      dirs.push(chatsDir);
+    }
+  }
+  return dirs;
+}
+
+function resolveGeminiChatDirs(chatsDir, cwd) {
+  if (chatsDir) {
+    const expanded = normalizePath(chatsDir);
+    return fs.existsSync(expanded) ? [expanded] : [];
+  }
+
+  const ordered = [];
+  const seen = new Set();
+
+  function addDir(dirPath) {
+    if (!dirPath || seen.has(dirPath) || !fs.existsSync(dirPath)) return;
+    ordered.push(dirPath);
+    seen.add(dirPath);
+  }
+
+  const scopedHash = hashPath(cwd);
+  addDir(path.join(geminiTmpBase, scopedHash, 'chats'));
+
+  for (const dir of listGeminiChatDirs()) {
+    addDir(dir);
+  }
+
+  return ordered;
+}
+
+function resolveCodexTargetFile(id, cwd, warnings) {
+  if (!fs.existsSync(codexSessionsBase)) return null;
+
+  if (id) {
+    const files = collectMatchingFiles(
+      codexSessionsBase,
+      (fullPath, name) => name.endsWith('.jsonl') && fullPath.includes(id),
+      true
+    );
+    return files.length > 0 ? files[0].path : null;
+  }
+
+  const files = collectMatchingFiles(codexSessionsBase, (fullPath, name) => name.endsWith('.jsonl'), true);
+  if (files.length === 0) return null;
+
+  const scoped = findLatestByCwd(files, getCodexSessionCwd, cwd);
+  if (scoped) return scoped;
+
+  warnings.push(`Warning: no Codex session matched cwd ${cwd}; falling back to latest session.`);
+  return files[0].path;
+}
+
+function resolveClaudeTargetFile(id, cwd, warnings) {
+  if (!fs.existsSync(claudeProjectsBase)) return null;
+
+  if (id) {
+    const files = collectMatchingFiles(
+      claudeProjectsBase,
+      (fullPath, name) => name.endsWith('.jsonl') && fullPath.includes(id),
+      true
+    );
+    return files.length > 0 ? files[0].path : null;
+  }
+
+  const files = collectMatchingFiles(claudeProjectsBase, (fullPath, name) => name.endsWith('.jsonl'), true);
+  if (files.length === 0) return null;
+
+  const scoped = findLatestByCwd(files, getClaudeSessionCwd, cwd);
+  if (scoped) return scoped;
+
+  warnings.push(`Warning: no Claude session matched cwd ${cwd}; falling back to latest session.`);
+  return files[0].path;
+}
+
+function resolveGeminiTargetFile(id, chatsDir, cwd) {
+  const dirs = resolveGeminiChatDirs(chatsDir, cwd);
+  if (dirs.length === 0) return { targetFile: null, searchedDirs: [] };
+
+  const candidates = [];
+  for (const dir of dirs) {
+    const files = collectMatchingFiles(
+      dir,
+      (fullPath, name) => {
+        if (!name.endsWith('.json')) return false;
+        if (id) return fullPath.includes(id);
+        return name.startsWith('session-');
+      },
+      false
+    );
+
+    for (const file of files) {
+      candidates.push(file);
+    }
+  }
+
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return {
+    targetFile: candidates.length > 0 ? candidates[0].path : null,
+    searchedDirs: dirs,
+  };
+}
+
+function extractText(value) {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return '';
+
+  return value
+    .map(part => {
+      if (typeof part === 'string') return part;
+      if (part && typeof part.text === 'string') return part.text;
+      return '';
+    })
+    .join('');
+}
+
+function extractClaudeText(value) {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return '';
+
+  return value
+    .filter(part => part && part.type === 'text')
+    .map(part => part.text || '')
+    .join('');
+}
+
+function redactSensitiveText(input) {
+  let output = String(input || '');
+  output = output.replace(/\bsk-[A-Za-z0-9]{20,}\b/g, 'sk-[REDACTED]');
+  output = output.replace(/\bAKIA[0-9A-Z]{16}\b/g, 'AKIA[REDACTED]');
+  output = output.replace(/\bBearer\s+[A-Za-z0-9._-]{10,}\b/gi, 'Bearer [REDACTED]');
+  output = output.replace(
+    /\b(api[_-]?key|token|secret|password)\b\s*[:=]\s*["']?[^"'\s]+["']?/gi,
+    (_, key) => `${key}=[REDACTED]`
+  );
+  return output;
+}
+
+function readCodexSession(id, cwd) {
+  const warnings = [];
+  const targetFile = resolveCodexTargetFile(id, cwd, warnings);
+  if (!targetFile) {
+    throw new Error('No Codex session found.');
+  }
+
+  const lines = readJsonlLines(targetFile);
+  const messages = [];
+  let skipped = 0;
+
+  for (const line of lines) {
+    try {
+      const json = JSON.parse(line);
+      if (json.type === 'response_item' && json.payload && json.payload.type === 'message') {
+        messages.push(json.payload);
+      } else if (json.type === 'event_msg' && json.payload && json.payload.type === 'agent_message') {
+        messages.push({ role: 'assistant', content: json.payload.message });
+      }
+    } catch (error) {
+      skipped += 1;
+    }
+  }
+
+  if (skipped > 0) {
+    warnings.push(`Warning: skipped ${skipped} unparseable line(s) in ${targetFile}`);
+  }
+
+  let content = '';
+  if (messages.length > 0) {
+    const assistantMsgs = messages.filter(message => (message.role || '').toLowerCase() === 'assistant');
+    const selected = assistantMsgs.length > 0 ? assistantMsgs[assistantMsgs.length - 1] : messages[messages.length - 1];
+    content = extractText(selected.content) || '[No text content]';
+  } else {
+    content = `Could not extract structured messages. Showing last 20 raw lines:\n${lines.slice(-20).join('\n')}`;
+  }
+
+  return {
+    agent: 'codex',
+    source: targetFile,
+    content: redactSensitiveText(content),
+    warnings,
+  };
+}
+
+function readGeminiSession(id, chatsDir, cwd) {
+  const resolved = resolveGeminiTargetFile(id, chatsDir, cwd);
+  const targetFile = resolved.targetFile;
+  if (!targetFile) {
+    if (chatsDir) {
+      throw new Error(`No Gemini session found in ${normalizePath(chatsDir)}`);
+    }
+
+    const lines = ['No Gemini session found. Searched chats directories:'];
+    for (const dir of resolved.searchedDirs) {
+      lines.push(` - ${dir}`);
+    }
+    throw new Error(lines.join('\n'));
+  }
+
+  let session;
+  try {
+    session = JSON.parse(fs.readFileSync(targetFile, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Failed to parse Gemini JSON: ${error.message}`);
+  }
+
+  let content = '';
+  if (Array.isArray(session.messages)) {
+    const selected =
+      [...session.messages].reverse().find(message => {
+        const type = (message.type || '').toLowerCase();
+        return type === 'gemini' || type === 'assistant' || type === 'model';
+      }) || session.messages[session.messages.length - 1];
+
+    if (!selected) {
+      throw new Error('Gemini session has no messages.');
+    }
+
+    content = typeof selected.content === 'string'
+      ? selected.content
+      : extractText(selected.content) || '[No text content]';
+  } else if (Array.isArray(session.history)) {
+    const selected =
+      [...session.history].reverse().find(turn => (turn.role || '').toLowerCase() !== 'user') ||
+      session.history[session.history.length - 1];
+
+    if (!selected) {
+      throw new Error('Gemini history is empty.');
+    }
+
+    if (Array.isArray(selected.parts)) {
+      content = selected.parts.map(part => part.text || '').join('\n');
+    } else if (typeof selected.parts === 'string') {
+      content = selected.parts;
+    } else {
+      content = '[No text content]';
+    }
+  } else {
+    throw new Error('Unknown Gemini session schema. Supported fields: messages, history.');
+  }
+
+  return {
+    agent: 'gemini',
+    source: targetFile,
+    content: redactSensitiveText(content),
+    warnings: [],
+  };
+}
+
+function readClaudeSession(id, cwd) {
+  if (!fs.existsSync(claudeProjectsBase)) {
+    throw new Error(`Claude projects directory not found: ${claudeProjectsBase}`);
+  }
+
+  const warnings = [];
+  const targetFile = resolveClaudeTargetFile(id, cwd, warnings);
+  if (!targetFile) {
+    throw new Error('No Claude session found.');
+  }
+
+  const lines = readJsonlLines(targetFile);
+  const messages = [];
+  let skipped = 0;
+
+  for (const line of lines) {
+    try {
+      const json = JSON.parse(line);
+      const message = json.message || json;
+      if (json.type === 'assistant' || message.role === 'assistant') {
+        const content = message.content !== undefined ? message.content : json.content;
+        const text = extractClaudeText(content);
+        if (text) {
+          messages.push(text);
+        }
+      }
+    } catch (error) {
+      skipped += 1;
+    }
+  }
+
+  if (skipped > 0) {
+    warnings.push(`Warning: skipped ${skipped} unparseable line(s) in ${targetFile}`);
+  }
+
+  const content = messages.length > 0
+    ? messages[messages.length - 1]
+    : `Could not extract assistant messages. Showing last 20 raw lines:\n${lines.slice(-20).join('\n')}`;
+
+  return {
+    agent: 'claude',
+    source: targetFile,
+    content: redactSensitiveText(content),
+    warnings,
+  };
+}
+
+function readSource(sourceSpec, defaultCwd) {
+  const effectiveCwd = normalizePath(sourceSpec.cwd || defaultCwd);
+  if (sourceSpec.agent === 'codex') {
+    return readCodexSession(sourceSpec.session_id || null, effectiveCwd);
+  }
+  if (sourceSpec.agent === 'gemini') {
+    return readGeminiSession(sourceSpec.session_id || null, sourceSpec.chats_dir || null, effectiveCwd);
+  }
+  if (sourceSpec.agent === 'claude') {
+    return readClaudeSession(sourceSpec.session_id || null, effectiveCwd);
+  }
+
+  throw new Error(`Unsupported agent: ${sourceSpec.agent}`);
+}
+
+function parseSourceArg(raw) {
+  const firstColon = raw.indexOf(':');
+  const agent = (firstColon === -1 ? raw : raw.slice(0, firstColon)).trim().toLowerCase();
+  const session = firstColon === -1 ? null : raw.slice(firstColon + 1).trim();
+
+  if (!['codex', 'gemini', 'claude'].includes(agent)) {
+    throw new Error(`Unsupported agent: ${agent}`);
+  }
+
+  return {
+    agent,
+    session_id: session ? session : null,
+    current_session: !session,
+    cwd: null,
+    chats_dir: null,
+  };
+}
+
+function evidenceTag(sourceSpec) {
+  const id = sourceSpec.session_id ? sourceSpec.session_id.slice(0, 8) : 'latest';
+  return `[${sourceSpec.agent}:${id}]`;
+}
+
+function computeVerdict(mode, missingCount, uniqueCount, successCount) {
+  if (successCount === 0) return 'INCOMPLETE';
+
+  if (mode === 'verify') {
+    if (missingCount === 0 && uniqueCount <= 1) return 'PASS';
+    return 'FAIL';
+  }
+
+  if (mode === 'steer') return 'STEERING_PLAN_READY';
+  if (mode === 'analyze') return 'ANALYSIS_COMPLETE';
+  if (mode === 'feedback') return 'FEEDBACK_COMPLETE';
+  return 'INCOMPLETE';
+}
+
+function buildReport(request, defaultCwd) {
+  const successful = [];
+  const missing = [];
+
+  for (const sourceSpec of request.sources) {
+    const evidence = evidenceTag(sourceSpec);
+    try {
+      const session = readSource(sourceSpec, defaultCwd);
+      successful.push({ sourceSpec, session, evidence });
+    } catch (error) {
+      missing.push({ sourceSpec, error: error.message || String(error), evidence });
+    }
+  }
+
+  const findings = [];
+
+  for (const item of missing) {
+    findings.push({
+      severity: 'P1',
+      summary: `Source unavailable: ${item.sourceSpec.agent} (${item.error})`,
+      evidence: [item.evidence],
+      confidence: 0.9,
+    });
+  }
+
+  for (const item of successful) {
+    for (const warning of item.session.warnings || []) {
+      findings.push({
+        severity: 'P2',
+        summary: `Source warning: ${warning}`,
+        evidence: [item.evidence],
+        confidence: 0.75,
+      });
+    }
+  }
+
+  const uniqueContents = new Set(successful.map(item => (item.session.content || '').trim()));
+
+  if (successful.length >= 2) {
+    if (uniqueContents.size > 1) {
+      findings.push({
+        severity: 'P1',
+        summary: 'Divergent agent outputs detected',
+        evidence: successful.map(item => item.evidence),
+        confidence: 0.75,
+      });
+    } else {
+      findings.push({
+        severity: 'P3',
+        summary: 'All available agent outputs are aligned',
+        evidence: successful.map(item => item.evidence),
+        confidence: 0.9,
+      });
+    }
+  } else {
+    findings.push({
+      severity: 'P2',
+      summary: 'Insufficient comparable sources',
+      evidence: successful.map(item => item.evidence),
+      confidence: 0.5,
+    });
+  }
+
+  const recommendedNextActions = [];
+  if (missing.length > 0) {
+    recommendedNextActions.push('Provide valid session identifiers or cwd values for unavailable sources.');
+  }
+  if (uniqueContents.size > 1) {
+    recommendedNextActions.push('Inspect full transcripts for diverging sources before final decisions.');
+  }
+  if (Array.isArray(request.constraints) && request.constraints.length > 0) {
+    recommendedNextActions.push(`Verify recommendations against constraints: ${request.constraints.join('; ')}.`);
+  }
+  if (recommendedNextActions.length === 0) {
+    recommendedNextActions.push('No immediate action required.');
+  }
+
+  const openQuestions = missing.map(item => `Missing source ${item.sourceSpec.agent}: ${item.error}`);
+
+  return {
+    mode: request.mode,
+    task: request.task,
+    success_criteria: request.success_criteria,
+    sources_used: successful.map(item => `${item.evidence} ${item.session.source}`),
+    verdict: computeVerdict(request.mode, missing.length, uniqueContents.size, successful.length),
+    findings: findings,
+    recommended_next_actions: recommendedNextActions,
+    open_questions: openQuestions,
+  };
+}
+
+function renderReadResult(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  for (const warning of result.warnings || []) {
+    console.error(warning);
+  }
+
+  const label = result.agent.charAt(0).toUpperCase() + result.agent.slice(1);
+  console.log(`SOURCE: ${label} Session (${result.source})`);
+  console.log('---');
+  console.log(result.content);
+}
+
+function renderReport(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const lines = [];
+  lines.push('### Inter-Agent Coordinator Report');
+  lines.push('');
+  lines.push(`**Mode:** ${result.mode}`);
+  lines.push(`**Task:** ${result.task}`);
+  lines.push('**Success Criteria:**');
+  for (const criterion of result.success_criteria || []) {
+    lines.push(`- ${criterion}`);
+  }
+  lines.push('');
+  lines.push('**Sources Used:**');
+  for (const source of result.sources_used || []) {
+    lines.push(`- ${source}`);
+  }
+  lines.push('');
+  lines.push(`**Verdict:** ${result.verdict}`);
+  lines.push('');
+  lines.push('**Findings:**');
+  for (const finding of result.findings || []) {
+    lines.push(
+      `- **${finding.severity}:** ${finding.summary} (evidence: ${(finding.evidence || []).join(', ')}; confidence: ${Number(finding.confidence || 0).toFixed(2)})`
+    );
+  }
+  lines.push('');
+  lines.push('**Recommended Next Actions:**');
+  (result.recommended_next_actions || []).forEach((action, index) => {
+    lines.push(`${index + 1}. ${action}`);
+  });
+  if ((result.open_questions || []).length > 0) {
+    lines.push('');
+    lines.push('**Open Questions:**');
+    for (const question of result.open_questions) {
+      lines.push(`- ${question}`);
+    }
+  }
+
+  console.log(lines.join('\n'));
+}
+
+function validateMode(mode) {
+  const allowed = new Set(['verify', 'steer', 'analyze', 'feedback']);
+  if (!allowed.has(mode)) {
+    throw new Error(`Unsupported mode: ${mode}`);
+  }
+}
+
+function runRead(inputArgs) {
+  const agent = getOptionValue(inputArgs, '--agent', 'codex');
+  const id = getOptionValue(inputArgs, '--id', null);
+  const chatsDir = getOptionValue(inputArgs, '--chats-dir', null);
+  const cwd = normalizePath(getOptionValue(inputArgs, '--cwd', process.cwd()));
+  const asJson = hasFlag(inputArgs, '--json');
+
+  let result;
+  if (agent === 'codex') {
+    result = readCodexSession(id, cwd);
+  } else if (agent === 'gemini') {
+    result = readGeminiSession(id, chatsDir, cwd);
+  } else if (agent === 'claude') {
+    result = readClaudeSession(id, cwd);
+  } else {
+    throw new Error(`Unknown agent: ${agent}. Supported: codex, gemini, claude`);
+  }
+
+  renderReadResult(result, asJson);
+}
+
+function runCompare(inputArgs) {
+  const sourcesRaw = getOptionValues(inputArgs, '--source');
+  if (sourcesRaw.length === 0) {
+    throw new Error('compare requires at least one --source option');
+  }
+
+  const cwd = normalizePath(getOptionValue(inputArgs, '--cwd', process.cwd()));
+  const asJson = hasFlag(inputArgs, '--json');
+  const sourceSpecs = sourcesRaw.map(parseSourceArg);
+
+  const report = buildReport(
+    {
+      mode: 'analyze',
+      task: 'Compare agent outputs',
+      success_criteria: [
+        'Identify agreements and contradictions',
+        'Highlight unavailable sources',
+      ],
+      sources: sourceSpecs,
+      constraints: [],
+    },
+    cwd
+  );
+
+  renderReport(report, asJson);
+}
+
+function runReport(inputArgs) {
+  const handoffPath = getOptionValue(inputArgs, '--handoff', null);
+  if (!handoffPath) {
+    throw new Error('report requires --handoff=<path>');
+  }
+
+  const cwd = normalizePath(getOptionValue(inputArgs, '--cwd', process.cwd()));
+  const asJson = hasFlag(inputArgs, '--json');
+
+  let handoff;
+  try {
+    handoff = JSON.parse(fs.readFileSync(normalizePath(handoffPath), 'utf-8'));
+  } catch (error) {
+    throw new Error(`Failed to read handoff JSON: ${error.message}`);
+  }
+
+  const mode = String(handoff.mode || '').toLowerCase();
+  validateMode(mode);
+
+  if (typeof handoff.task !== 'string' || !handoff.task.trim()) {
+    throw new Error('Handoff is missing required string field: task');
+  }
+  if (!Array.isArray(handoff.success_criteria) || handoff.success_criteria.length === 0) {
+    throw new Error('Handoff is missing required array field: success_criteria');
+  }
+  if (!Array.isArray(handoff.sources) || handoff.sources.length === 0) {
+    throw new Error('Handoff is missing required array field: sources');
+  }
+
+  const sourceSpecs = handoff.sources.map(source => {
+    const agent = String(source.agent || '').toLowerCase();
+    if (!['codex', 'gemini', 'claude'].includes(agent)) {
+      throw new Error(`Unsupported agent: ${agent}`);
+    }
+
+    const sessionId = typeof source.session_id === 'string' && source.session_id.trim()
+      ? source.session_id.trim()
+      : null;
+    const currentSession = source.current_session === true;
+
+    if (!sessionId && !currentSession) {
+      throw new Error('Each source must provide session_id or set current_session=true');
+    }
+
+    return {
+      agent,
+      session_id: sessionId,
+      current_session: currentSession,
+      cwd: typeof source.cwd === 'string' && source.cwd.trim() ? source.cwd : null,
+      chats_dir: null,
+    };
+  });
+
+  const report = buildReport(
+    {
+      mode,
+      task: handoff.task,
+      success_criteria: handoff.success_criteria.map(String),
+      sources: sourceSpecs,
+      constraints: Array.isArray(handoff.constraints) ? handoff.constraints.map(String) : [],
+    },
+    cwd
+  );
+
+  renderReport(report, asJson);
+}
+
+try {
+  if (command === 'read') {
+    runRead(args);
+  } else if (command === 'compare') {
+    runCompare(args);
+  } else if (command === 'report') {
+    runReport(args);
+  } else {
+    throw new Error(`Unknown command: ${command}`);
+  }
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exit(1);
+}