openairev 0.3.4 → 0.3.6

package/README.md

@@ -213,7 +213,7 @@ Restart your agent CLI after adding.
 | Tool | Description |
 |------|-------------|
 | `openairev_review` | Start a review in the background. Returns immediately. |
-| `openairev_status` | Check review progress and get the verdict when ready. |
+| `openairev_status` | Check review progress (prefer `openairev wait` instead). |
 | `openairev_run_tests` | Run project test suite |
 | `openairev_run_lint` | Run linter |
 | `openairev_get_diff` | Get current git diff |
@@ -223,10 +223,9 @@ Restart your agent CLI after adding.
 The review runs asynchronously so you can see progress:
 
 1. Call `openairev_review` → starts review in background, returns immediately
-2. Read `.openairev/progress.json` → shows live progress (files read, commands run, tokens)
-3. When `status` is `"completed"`, the verdict and feedback are in the same file
+2. Run `openairev wait` via Bash → streams progress (files read, commands run, tokens) and outputs the verdict when done
 
-The executor AI can read the progress file directly (no MCP round-trip needed), or use `openairev_status` as an alternative. The AI can also launch the review in a sub-agent and continue other work while it runs.
+One MCP call + one Bash call. No polling, no sleep loops. The AI can also launch the review in a sub-agent and continue other work while it runs.
 
 ## Config
 

package/bin/openairev.js

@@ -7,6 +7,7 @@ import { reviewCommand } from '../src/cli/review.js';
 import { resumeCommand } from '../src/cli/resume.js';
 import { statusCommand } from '../src/cli/status.js';
 import { historyCommand } from '../src/cli/history.js';
+import { waitCommand } from '../src/cli/wait.js';
 
 const program = new Command();
 
@@ -54,4 +55,10 @@ program
   .option('--chains', 'Show chains instead of sessions')
   .action(historyCommand);
 
+program
+  .command('wait')
+  .description('Wait for a background review to finish, streaming progress')
+  .option('--file <path>', 'Path to progress.json (auto-detected from .openairev/)')
+  .action(waitCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openairev",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Cross-model AI code reviewer — independent review for AI-assisted coding workflows",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
   ],
   "scripts": {
     "start": "node bin/openairev.js",
-    "test": "node --test src/**/*.test.js"
+    "test": "node --test src/**/*.test.js",
+    "smoke:mcp": "node scripts/mcp-smoke.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/src/agents/claude-code.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { exec } from './exec-helper.js';
+import { createClaudeSummarizer } from './stream-summarizer.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -16,8 +17,20 @@ export class ClaudeCodeAdapter {
     this.sessionName = id;
   }
 
-  async run(prompt, { useSchema = false, schemaFile = 'verdict-schema.json', continueSession = false, sessionName = null } = {}) {
-    const args = ['-p', prompt, '--output-format', 'json'];
+  async run(prompt, {
+    useSchema = false,
+    schemaFile = 'verdict-schema.json',
+    continueSession = false,
+    sessionName = null,
+    stream = false,
+  } = {}) {
+    const args = ['-p', prompt];
+
+    if (stream) {
+      args.push('--output-format', 'stream-json', '--verbose', '--include-partial-messages');
+    } else {
+      args.push('--output-format', 'json');
+    }
 
     if (useSchema) {
       const schemaPath = join(__dirname, '../config', schemaFile);
@@ -32,7 +45,21 @@ export class ClaudeCodeAdapter {
       this.sessionName = sessionName;
     }
 
-    const result = await exec(this.cmd, args);
+    const summarizer = stream ? createClaudeSummarizer({
+      reviewerName: stream.reviewerName || 'claude_code',
+      tty: stream.tty !== false,
+      onProgress: stream.onProgress,
+    }) : undefined;
+
+    const result = await exec(this.cmd, args, { onData: summarizer, cwd: this.cwd });
+
+    if (stream) {
+      return parseClaudeStreamOutput(result.stdout, {
+        progress: summarizer?.getProgress() || [],
+        fallbackSessionId: this.sessionName,
+      });
+    }
+
     try {
       const parsed = JSON.parse(result.stdout);
       if (!this.sessionName && parsed.session_id) {
@@ -44,3 +71,93 @@ export class ClaudeCodeAdapter {
     }
   }
 }
+
+export function parseClaudeStreamOutput(stdout, { progress = [], fallbackSessionId = null } = {}) {
+  let sessionId = fallbackSessionId;
+  let assistantText = null;
+  let assistantStructuredOutput = null;
+  let resultText = null;
+  let structuredOutput = null;
+  let resultError = null;
+
+  for (const line of stdout.split('\n')) {
+    if (!line.trim()) continue;
+
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (!sessionId && event.session_id) {
+      sessionId = event.session_id;
+    }
+
+    if (event.type === 'assistant') {
+      const text = extractAssistantText(event);
+      if (text) assistantText = text;
+      const toolInput = extractStructuredToolInput(event);
+      if (toolInput) assistantStructuredOutput = toolInput;
+      if (event.error) resultError = event.error;
+    }
+
+    if (event.type === 'result') {
+      if (event.structured_output && typeof event.structured_output === 'object') {
+        structuredOutput = event.structured_output;
+      }
+      if (typeof event.result === 'string' && event.result.trim()) {
+        resultText = event.result;
+      }
+      if (event.is_error) {
+        resultError = event.result || resultError || 'Claude review failed';
+      }
+    }
+  }
+
+  const finalText = resultText || assistantText;
+  const parsed = tryParseJson(finalText);
+  const verdict = structuredOutput || assistantStructuredOutput || parsed;
+
+  if (resultError && !verdict) {
+    return {
+      raw: stdout,
+      raw_output: stdout,
+      progress,
+      session_id: sessionId,
+      error: resultError,
+    };
+  }
+
+  return {
+    result: verdict || finalText,
+    raw_output: stdout,
+    progress,
+    session_id: sessionId,
+  };
+}
+
+function extractAssistantText(event) {
+  const parts = event.message?.content;
+  if (!Array.isArray(parts)) return null;
+  return parts
+    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('');
+}
+
+function extractStructuredToolInput(event) {
+  const parts = event.message?.content;
+  if (!Array.isArray(parts)) return null;
+  const toolUse = parts.find((part) => part?.type === 'tool_use' && part.name === 'StructuredOutput');
+  return toolUse?.input && typeof toolUse.input === 'object' ? toolUse.input : null;
+}
+
+function tryParseJson(text) {
+  if (!text || typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

package/src/agents/claude-code.test.js

@@ -0,0 +1,100 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseClaudeStreamOutput } from './claude-code.js';
+
+describe('parseClaudeStreamOutput', () => {
+  it('parses a successful stream-json response into a verdict object', () => {
+    const stdout = [
+      JSON.stringify({
+        type: 'system',
+        subtype: 'init',
+        session_id: 'sess-123',
+      }),
+      JSON.stringify({
+        type: 'assistant',
+        session_id: 'sess-123',
+        message: {
+          content: [{
+            type: 'text',
+            text: '{"status":"approved","critical_issues":[],"test_gaps":[],"requirement_mismatches":[],"rule_violations":[],"risk_level":"low","confidence":0.99,"repair_instructions":[],"false_positives_reconsidered":[]}',
+          }],
+        },
+      }),
+      JSON.stringify({
+        type: 'result',
+        is_error: false,
+        session_id: 'sess-123',
+        result: '{"status":"approved","critical_issues":[],"test_gaps":[],"requirement_mismatches":[],"rule_violations":[],"risk_level":"low","confidence":0.99,"repair_instructions":[],"false_positives_reconsidered":[]}',
+      }),
+    ].join('\n');
+
+    const result = parseClaudeStreamOutput(stdout, { progress: ['reviewer: claude_code'] });
+
+    assert.equal(result.session_id, 'sess-123');
+    assert.equal(result.result.status, 'approved');
+    assert.deepEqual(result.progress, ['reviewer: claude_code']);
+  });
+
+  it('prefers structured_output from the final result event', () => {
+    const stdout = [
+      JSON.stringify({
+        type: 'system',
+        subtype: 'init',
+        session_id: 'sess-789',
+      }),
+      JSON.stringify({
+        type: 'result',
+        is_error: false,
+        session_id: 'sess-789',
+        result: '',
+        structured_output: {
+          status: 'approved',
+          critical_issues: [],
+          test_gaps: [],
+          requirement_mismatches: [],
+          rule_violations: [],
+          risk_level: 'low',
+          confidence: 0.98,
+          repair_instructions: [],
+          false_positives_reconsidered: [],
+        },
+      }),
+    ].join('\n');
+
+    const result = parseClaudeStreamOutput(stdout);
+
+    assert.equal(result.session_id, 'sess-789');
+    assert.equal(result.result.status, 'approved');
+    assert.equal(result.result.confidence, 0.98);
+  });
+
+  it('returns an error when the stream reports failure without a verdict payload', () => {
+    const stdout = [
+      JSON.stringify({
+        type: 'system',
+        subtype: 'init',
+        session_id: 'sess-456',
+      }),
+      JSON.stringify({
+        type: 'assistant',
+        session_id: 'sess-456',
+        error: 'authentication_failed',
+        message: {
+          content: [{ type: 'text', text: 'Not logged in' }],
+        },
+      }),
+      JSON.stringify({
+        type: 'result',
+        is_error: true,
+        session_id: 'sess-456',
+        result: 'Not logged in',
+      }),
+    ].join('\n');
+
+    const result = parseClaudeStreamOutput(stdout);
+
+    assert.equal(result.session_id, 'sess-456');
+    assert.equal(result.error, 'Not logged in');
+    assert.ok(result.raw_output.includes('authentication_failed'));
+  });
+});

package/src/agents/exec-helper.js

@@ -2,10 +2,11 @@ import { spawn } from 'child_process';
 
 const MAX_BUFFER = 10 * 1024 * 1024;
 
-export function exec(cmd, args, { onData } = {}) {
+export function exec(cmd, args, { onData, cwd } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, {
       timeout: 300_000,
+      cwd,
     });
 
     const stdoutChunks = [];

package/src/agents/mock-reviewer.js

@@ -0,0 +1,80 @@
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function buildVerdict(schemaFile, status) {
+  if (schemaFile === 'plan-verdict-schema.json') {
+    return {
+      status,
+      critical_issues: [],
+      missing_requirements: [],
+      sequencing_issues: [],
+      risks: [],
+      risk_level: 'low',
+      confidence: 0.99,
+      repair_instructions: [],
+      false_positives_reconsidered: [
+        'Mock reviewer found no plan issues in smoke-test mode.',
+      ],
+    };
+  }
+
+  return {
+    status,
+    critical_issues: [],
+    test_gaps: [],
+    requirement_mismatches: [],
+    rule_violations: [],
+    risk_level: 'low',
+    confidence: 0.99,
+    repair_instructions: [],
+    false_positives_reconsidered: [
+      'Mock reviewer found no code issues in smoke-test mode.',
+    ],
+  };
+}
+
+export class MockReviewerAdapter {
+  constructor(options = {}) {
+    this.cmd = options.cmd || 'mock';
+    this.cwd = options.cwd || process.cwd();
+    this.sessionId = null;
+  }
+
+  restoreSession(id) {
+    this.sessionId = id;
+  }
+
+  async run(_prompt, {
+    schemaFile = 'verdict-schema.json',
+    sessionName = null,
+    stream = false,
+  } = {}) {
+    const status = process.env.OPENAIREV_MOCK_REVIEW_STATUS || 'approved';
+    const delayMs = Number.parseInt(process.env.OPENAIREV_MOCK_PROGRESS_DELAY_MS || '40', 10);
+    const sessionId = this.sessionId || sessionName || `mock-session-${Date.now()}`;
+    this.sessionId = sessionId;
+
+    const progress = [
+      'reviewer: mock',
+      `session: ${sessionId}`,
+      'reading diff',
+      'verdict ready',
+    ];
+
+    if (stream?.onProgress) {
+      for (let i = 0; i < progress.length; i++) {
+        await delay(delayMs);
+        stream.onProgress(progress.slice(0, i + 1));
+      }
+    }
+
+    const verdict = buildVerdict(schemaFile, status);
+    return {
+      result: verdict,
+      raw_output: JSON.stringify(verdict, null, 2),
+      progress,
+      session_id: sessionId,
+    };
+  }
+}

package/src/agents/mock-reviewer.test.js

@@ -0,0 +1,36 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { MockReviewerAdapter } from './mock-reviewer.js';
+
+describe('MockReviewerAdapter', () => {
+  it('returns a code-review verdict with progress updates', async () => {
+    const adapter = new MockReviewerAdapter();
+    const snapshots = [];
+
+    const result = await adapter.run('review this', {
+      stream: {
+        onProgress(lines) {
+          snapshots.push([...lines]);
+        },
+      },
+    });
+
+    assert.equal(result.result.status, 'approved');
+    assert.equal(result.progress.at(-1), 'verdict ready');
+    assert.equal(snapshots.length, 4);
+    assert.equal(snapshots.at(-1).at(-1), 'verdict ready');
+    assert.equal(result.session_id, adapter.sessionId);
+  });
+
+  it('returns the plan-review shape when plan schema is requested', async () => {
+    const adapter = new MockReviewerAdapter();
+    const result = await adapter.run('review this plan', {
+      schemaFile: 'plan-verdict-schema.json',
+    });
+
+    assert.equal(result.result.status, 'approved');
+    assert.deepEqual(result.result.missing_requirements, []);
+    assert.deepEqual(result.result.sequencing_issues, []);
+    assert.deepEqual(result.result.risks, []);
+  });
+});

package/src/agents/registry.js

@@ -1,9 +1,11 @@
 import { ClaudeCodeAdapter } from './claude-code.js';
 import { CodexAdapter } from './codex.js';
+import { MockReviewerAdapter } from './mock-reviewer.js';
 
 const ADAPTERS = {
   claude_code: ClaudeCodeAdapter,
   codex: CodexAdapter,
+  mock: MockReviewerAdapter,
 };
 
 export function createAdapter(agentName, config, { cwd } = {}) {

package/src/agents/stream-summarizer.js

@@ -1,13 +1,20 @@
 import chalk from 'chalk';
 
+const MAX_PROGRESS_LINES = 200;
+
+const COLORS = {
+  cyan: chalk.cyan,
+  green: chalk.green,
+  yellow: chalk.yellow,
+  red: chalk.red,
+};
+
 /**
- * Creates a summarizer callback for Codex NDJSON event streams.
- * tty=true: prints colored progress to stderr.
- * tty=false: collects plain-text progress lines silently.
- * Both modes always collect lines for the final summary.
+ * Shared factory for NDJSON stream summarizers.
+ * Handles buffering, line splitting, progress collection, and TTY output.
+ * Each adapter provides its own handleEvent callback.
  */
-export function createCodexSummarizer({ reviewerName, tty = true, onProgress } = {}) {
-  const seenFiles = new Set();
+function createSummarizer({ reviewerName, tty = true, onProgress, handleEvent }) {
   const progressLines = [];
   let buffer = '';
   let started = false;
@@ -15,36 +22,42 @@ export function createCodexSummarizer({ reviewerName, tty = true, onProgress } =
   const summarizer = (chunk) => {
     if (!started) {
       started = true;
-      if (reviewerName) emit(`reviewer: ${reviewerName}`, 'cyan');
+      if (reviewerName) emit(reviewerName, 'cyan');
     }
     buffer += chunk;
+    processLines();
+  };
+
+  summarizer.getProgress = () => {
+    processLines(true);
+    return progressLines;
+  };
+
+  function processLines(flush = false) {
     const lines = buffer.split('\n');
     buffer = lines.pop();
+    if (flush && buffer.trim()) {
+      lines.push(buffer);
+      buffer = '';
+    }
 
     for (const line of lines) {
       if (!line.trim()) continue;
       try {
-        const event = JSON.parse(line);
-        summarizeCodexEvent(event, seenFiles, { emit });
+        handleEvent(JSON.parse(line), emit);
       } catch {
         // skip non-JSON
       }
     }
-  };
-
-  summarizer.getProgress = () => progressLines;
+  }
 
   function emit(msg, color) {
-    if (progressLines.length < 200) {
+    if (progressLines.length < MAX_PROGRESS_LINES && progressLines.at(-1) !== msg) {
       progressLines.push(msg);
       if (onProgress) onProgress(progressLines);
     }
     if (tty) {
-      const colorFn = color === 'cyan' ? chalk.cyan
-        : color === 'green' ? chalk.green
-        : color === 'yellow' ? chalk.yellow
-        : color === 'red' ? chalk.red
-        : chalk.dim;
+      const colorFn = COLORS[color] || chalk.dim;
       process.stderr.write(`  ${colorFn(msg)}\n`);
     }
   }
@@ -52,6 +65,33 @@ export function createCodexSummarizer({ reviewerName, tty = true, onProgress } =
   return summarizer;
 }
 
+/**
+ * Creates a summarizer callback for Codex NDJSON event streams.
+ */
+export function createCodexSummarizer({ reviewerName, tty, onProgress } = {}) {
+  const seenFiles = new Set();
+  return createSummarizer({
+    reviewerName: reviewerName && `reviewer: ${reviewerName}`,
+    tty,
+    onProgress,
+    handleEvent: (event, emit) => summarizeCodexEvent(event, seenFiles, { emit }),
+  });
+}
+
+/**
+ * Creates a summarizer callback for Claude stream-json event streams.
+ */
+export function createClaudeSummarizer({ reviewerName, tty, onProgress } = {}) {
+  const seenFiles = new Set();
+  const state = { sawMessageStart: false, sawDraft: false, currentToolUse: null };
+  return createSummarizer({
+    reviewerName: reviewerName && `reviewer: ${reviewerName}`,
+    tty,
+    onProgress,
+    handleEvent: (event, emit) => summarizeClaudeEvent(event, { emit, seenFiles, state }),
+  });
+}
+
 function summarizeCodexEvent(event, seenFiles, { emit }) {
   const type = event.type;
 
@@ -112,6 +152,152 @@ function summarizeCodexEvent(event, seenFiles, { emit }) {
   }
 }
 
+function summarizeClaudeEvent(wrapper, { emit, seenFiles, state }) {
+  if (wrapper.type === 'system' && wrapper.subtype === 'init') {
+    emit(`session: ${wrapper.session_id}`);
+    return;
+  }
+
+  if (wrapper.type === 'assistant' && wrapper.error) {
+    emit(`error: ${wrapper.error}`, 'red');
+    return;
+  }
+
+  if (wrapper.type === 'stream_event') {
+    const event = wrapper.event;
+
+    if (event?.type === 'message_start' && !state.sawMessageStart) {
+      state.sawMessageStart = true;
+      emit('analyzing diff...', 'cyan');
+      return;
+    }
+
+    if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
+      state.currentToolUse = {
+        name: event.content_block.name || 'tool',
+        index: event.index,
+        input: '',
+      };
+      return;
+    }
+
+    if (event?.type === 'content_block_delta' && event.delta?.type === 'input_json_delta' && state.currentToolUse) {
+      state.currentToolUse.input += event.delta.partial_json || '';
+      return;
+    }
+
+    if (event?.type === 'content_block_stop' && state.currentToolUse) {
+      const tool = state.currentToolUse;
+      state.currentToolUse = null;
+      emitToolSummary(tool, { emit, seenFiles });
+      return;
+    }
+
+    if (
+      event?.type === 'content_block_delta' &&
+      event.delta?.type === 'text_delta' &&
+      event.delta.text &&
+      !state.sawDraft
+    ) {
+      state.sawDraft = true;
+      emit('drafting verdict...', 'cyan');
+      return;
+    }
+
+    if (event?.type === 'message_delta' && event.usage?.output_tokens != null) {
+      emit(`output: ${fmt(event.usage.output_tokens)} tokens`);
+      return;
+    }
+  }
+
+  if (wrapper.type === 'tool_result') {
+    if (wrapper.is_error) {
+      const name = wrapper.tool_name || 'tool';
+      emit(`${name} failed: ${truncate(wrapper.error || 'unknown error', 80)}`, 'yellow');
+    }
+    return;
+  }
+
+  if (wrapper.type === 'result') {
+    if (wrapper.is_error) {
+      emit(`error: ${wrapper.result || 'unknown error'}`, 'red');
+      return;
+    }
+    emit('verdict ready', 'green');
+    if (wrapper.usage) {
+      const input = (wrapper.usage.input_tokens || 0) +
+        (wrapper.usage.cache_creation_input_tokens || 0) +
+        (wrapper.usage.cache_read_input_tokens || 0);
+      const output = wrapper.usage.output_tokens || 0;
+      emit(`tokens: ${fmt(input + output)} total (${fmt(input)} in / ${fmt(output)} out)`);
+    }
+  }
+}
+
+function emitToolSummary(tool, { emit, seenFiles }) {
+  let input;
+  try {
+    input = tool.input ? JSON.parse(tool.input) : {};
+  } catch {
+    emit(`running tool: ${tool.name}`);
+    return;
+  }
+
+  const name = tool.name;
+
+  if (name === 'Read') {
+    const file = shortPath(input.file_path);
+    if (file && !seenFiles.has(file)) {
+      seenFiles.add(file);
+      emit(`reading: ${file}`);
+    }
+    return;
+  }
+
+  if (name === 'Glob') {
+    emit(`searching: ${input.pattern || 'files'}`);
+    return;
+  }
+
+  if (name === 'Grep') {
+    const target = input.path ? shortPath(input.path) : 'codebase';
+    emit(`grep: ${truncate(input.pattern || '', 50)} in ${target}`);
+    return;
+  }
+
+  if (name === 'Bash') {
+    const cmd = input.command || '';
+    if (isInternalCmd(cmd)) return;
+    const file = extractFileFromCmd(cmd);
+    if (file && !seenFiles.has(file)) {
+      seenFiles.add(file);
+      emit(`reading: ${file}`);
+    } else if (!file) {
+      const short = summarizeCmd(cmd);
+      if (short) emit(`running: ${short}`);
+    }
+    return;
+  }
+
+  if (name === 'Edit' || name === 'Write') {
+    const file = shortPath(input.file_path);
+    if (file) emit(`writing: ${file}`);
+    return;
+  }
+
+  emit(`running tool: ${name}`);
+}
+
+function shortPath(filePath) {
+  if (!filePath) return null;
+  return filePath.replace(/^.*\/(?=src\/|lib\/|bin\/|test\/|config\/|packages\/)/, '')
+    || filePath.split('/').slice(-2).join('/');
+}
+
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max - 3) + '...' : str;
+}
+
 function isInternalCmd(cmd) {
   return /node\s+-e\s/.test(cmd) ||
     /require\(['"]child_process['"]\)/.test(cmd) ||

package/src/agents/stream-summarizer.test.js

@@ -0,0 +1,143 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createClaudeSummarizer } from './stream-summarizer.js';
+
+function feed(summarizer, events) {
+  summarizer(events.map(e => JSON.stringify(e)).join('\n') + '\n');
+}
+
+describe('createClaudeSummarizer', () => {
+  it('collects useful progress lines from Claude stream-json events', () => {
+    const snapshots = [];
+    const summarizer = createClaudeSummarizer({
+      reviewerName: 'claude_code',
+      tty: false,
+      onProgress(lines) {
+        snapshots.push([...lines]);
+      },
+    });
+
+    feed(summarizer, [
+      { type: 'system', subtype: 'init', session_id: 'sess-123' },
+      { type: 'stream_event', event: { type: 'message_start' } },
+      { type: 'stream_event', event: {
+        type: 'content_block_delta',
+        delta: { type: 'text_delta', text: '{"status":"approved"' },
+      }},
+      { type: 'result', is_error: false, usage: { input_tokens: 10, output_tokens: 5 } },
+    ]);
+
+    const progress = summarizer.getProgress();
+
+    assert.deepEqual(progress, [
+      'reviewer: claude_code',
+      'session: sess-123',
+      'analyzing diff...',
+      'drafting verdict...',
+      'verdict ready',
+      'tokens: 15 total (10 in / 5 out)',
+    ]);
+    assert.equal(snapshots.at(-1).at(-1), 'tokens: 15 total (10 in / 5 out)');
+  });
+
+  it('tracks tool usage with file dedup', () => {
+    const summarizer = createClaudeSummarizer({ tty: false });
+
+    feed(summarizer, [
+      { type: 'system', subtype: 'init', session_id: 's1' },
+      { type: 'stream_event', event: { type: 'message_start' } },
+      // Read tool
+      { type: 'stream_event', event: {
+        type: 'content_block_start', index: 1,
+        content_block: { type: 'tool_use', name: 'Read' },
+      }},
+      { type: 'stream_event', event: {
+        type: 'content_block_delta', index: 1,
+        delta: { type: 'input_json_delta', partial_json: '{"file_path":"/home/user/src/version.js"}' },
+      }},
+      { type: 'stream_event', event: { type: 'content_block_stop', index: 1 } },
+      // Second Read of same file — should be deduped
+      { type: 'stream_event', event: {
+        type: 'content_block_start', index: 2,
+        content_block: { type: 'tool_use', name: 'Read' },
+      }},
+      { type: 'stream_event', event: {
+        type: 'content_block_delta', index: 2,
+        delta: { type: 'input_json_delta', partial_json: '{"file_path":"/home/user/src/version.js"}' },
+      }},
+      { type: 'stream_event', event: { type: 'content_block_stop', index: 2 } },
+      // Grep tool
+      { type: 'stream_event', event: {
+        type: 'content_block_start', index: 3,
+        content_block: { type: 'tool_use', name: 'Grep' },
+      }},
+      { type: 'stream_event', event: {
+        type: 'content_block_delta', index: 3,
+        delta: { type: 'input_json_delta', partial_json: '{"pattern":"VERSION","path":"src/"}' },
+      }},
+      { type: 'stream_event', event: { type: 'content_block_stop', index: 3 } },
+    ]);
+
+    const progress = summarizer.getProgress();
+
+    assert.ok(progress.includes('reading: src/version.js'));
+    // Only one "reading" for the same file
+    assert.equal(progress.filter(l => l.includes('reading: src/version.js')).length, 1);
+    assert.ok(progress.some(l => l.startsWith('grep: VERSION')));
+  });
+
+  it('tracks Bash commands and Glob searches', () => {
+    const summarizer = createClaudeSummarizer({ tty: false });
+
+    feed(summarizer, [
+      { type: 'system', subtype: 'init', session_id: 's2' },
+      // Bash tool
+      { type: 'stream_event', event: {
+        type: 'content_block_start', index: 1,
+        content_block: { type: 'tool_use', name: 'Bash' },
+      }},
+      { type: 'stream_event', event: {
+        type: 'content_block_delta', index: 1,
+        delta: { type: 'input_json_delta', partial_json: '{"command":"git diff HEAD~1"}' },
+      }},
+      { type: 'stream_event', event: { type: 'content_block_stop', index: 1 } },
+      // Glob tool
+      { type: 'stream_event', event: {
+        type: 'content_block_start', index: 2,
+        content_block: { type: 'tool_use', name: 'Glob' },
+      }},
+      { type: 'stream_event', event: {
+        type: 'content_block_delta', index: 2,
+        delta: { type: 'input_json_delta', partial_json: '{"pattern":"**/*.test.js"}' },
+      }},
+      { type: 'stream_event', event: { type: 'content_block_stop', index: 2 } },
+    ]);
+
+    const progress = summarizer.getProgress();
+
+    assert.ok(progress.some(l => l.startsWith('running: git diff')));
+    assert.ok(progress.some(l => l === 'searching: **/*.test.js'));
+  });
+
+  it('reports tool errors', () => {
+    const summarizer = createClaudeSummarizer({ tty: false });
+
+    feed(summarizer, [
+      { type: 'tool_result', is_error: true, tool_name: 'Bash', error: 'command not found' },
+    ]);
+
+    const progress = summarizer.getProgress();
+    assert.ok(progress.some(l => l.includes('Bash failed') && l.includes('command not found')));
+  });
+
+  it('handles result errors', () => {
+    const summarizer = createClaudeSummarizer({ tty: false });
+
+    feed(summarizer, [
+      { type: 'result', is_error: true, result: 'rate limited' },
+    ]);
+
+    const progress = summarizer.getProgress();
+    assert.ok(progress.some(l => l === 'error: rate limited'));
+  });
+});

package/src/cli/init.js

@@ -258,8 +258,7 @@ ${marker}
 This project uses OpenAIRev for independent AI code review. When the user asks to "review", "get a review", or "check my changes":
 
 1. Call \`openairev_review\` with \`executor: "claude_code"\` and \`diff_cmd\` scoped to the files you changed (e.g. \`"git diff HEAD -- src/auth.ts src/routes.ts"\`). The review starts in the background and returns immediately.
-2. To check progress, read \`.openairev/progress.json\` — it updates in real-time showing what the reviewer is reading and doing.
-3. When \`progress.json\` shows \`"status": "completed"\`, the verdict and feedback are in the same file.
+2. Run \`openairev wait\` via Bash to stream progress and get the verdict when done. This is a single blocking call — no polling needed.
 
 **Tips**:
 - Always use \`diff_cmd\` to scope the diff to your changed files. Do NOT let it auto-detect — the full repo diff may be too large.
@@ -313,8 +312,7 @@ ${marker}
 This project uses OpenAIRev for independent AI code review. When the user asks to "review", "get a review", or "check my changes":
 
 1. Call \`openairev_review\` with \`executor: "codex"\` and \`diff_cmd\` scoped to the files you changed (e.g. \`"git diff HEAD -- src/auth.ts src/routes.ts"\`). The review starts in the background and returns immediately.
-2. To check progress, read \`.openairev/progress.json\` — it updates in real-time showing what the reviewer is reading and doing.
-3. When \`progress.json\` shows \`"status": "completed"\`, the verdict and feedback are in the same file.
+2. Run \`openairev wait\` to stream progress and get the verdict when done. This is a single blocking call — no polling needed.
 
 **Tips**:
 - Always use \`diff_cmd\` to scope the diff to your changed files. Do NOT let it auto-detect — the full repo diff may be too large.

package/src/cli/wait.js

@@ -0,0 +1,55 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from '../config/config-loader.js';
+
+export async function waitCommand(options) {
+  const progressFile = options.file || join(getConfigDir(), 'progress.json');
+
+  if (!existsSync(progressFile)) {
+    console.log('No review in progress. Call openairev_review first.');
+    process.exit(1);
+  }
+
+  let lastLen = 0;
+
+  return new Promise((resolve) => {
+    const timer = setInterval(() => {
+      const data = readProgress(progressFile);
+      if (!data) return;
+
+      const lines = data.progress || [];
+      for (let i = lastLen; i < lines.length; i++) {
+        console.log(`  ${lines[i]}`);
+      }
+      lastLen = lines.length;
+
+      if (data.status === 'completed' || data.status === 'error') {
+        clearInterval(timer);
+        printResult(data);
+        resolve();
+      }
+    }, 2000);
+  });
+}
+
+function readProgress(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function printResult(data) {
+  if (data.status === 'error') {
+    console.log(`\nReview failed: ${data.error}`);
+    process.exit(1);
+  }
+
+  console.log('');
+  if (data.executor_feedback) {
+    console.log(data.executor_feedback);
+  } else if (data.verdict) {
+    console.log(JSON.stringify(data.verdict, null, 2));
+  }
+}

package/src/mcp/mcp-server.js

@@ -25,7 +25,7 @@ const server = new McpServer({
 
 server.tool(
   'openairev_review',
-  'TRIGGER: Use this tool when the user says "review", "review my code", "get a review", "check my changes", "openairev", or asks for independent/cross-model code review. Sends current code changes to a DIFFERENT AI model for independent review. The review runs in the background and returns immediately. To check progress, read .openairev/progress.json — it updates in real-time. When status is "completed", the verdict is in the same file.',
+  'TRIGGER: Use this tool when the user says "review", "review my code", "get a review", "check my changes", "openairev", or asks for independent/cross-model code review. Sends current code changes to a DIFFERENT AI model for independent review. The review starts in the background and returns immediately. After calling this, run `openairev wait` via Bash to stream progress and get the verdict — one blocking call, no polling needed.',
   {
     executor: z.string().optional().describe('Which agent wrote the code (claude_code or codex). If you are Claude Code, set this to "claude_code". If you are Codex, set this to "codex".'),
     diff: z.string().optional().describe('The diff to review. IMPORTANT: Pass only the diff for files YOU changed, not the entire repo. Use `git diff HEAD -- file1 file2` to scope it. If omitted, auto-detects from git which may be too large.'),
@@ -90,7 +90,7 @@ server.tool(
     return {
       content: [{
         type: 'text',
-        text: `Review started. Reviewer: ${reviewerName}\n\nCall openairev_status to check progress and get the verdict when ready.`,
+        text: `Review started. Reviewer: ${reviewerName}\nProgress file: ${PROGRESS_FILE}\n\nRun \`openairev wait\` from ${cwd} or read ${PROGRESS_FILE} directly to stream progress and get the verdict.`,
       }],
     };
   }
@@ -98,7 +98,7 @@ server.tool(
 
 server.tool(
   'openairev_status',
-  'Check the progress and result of the current or most recent OpenAIRev review. Alternative to reading .openairev/progress.json directly.',
+  'Check the progress and result of the current or most recent OpenAIRev review. Prefer running `openairev wait` via Bash instead — it streams progress and blocks until done.',
   {},
   async () => {
     const progress = readProgress();
@@ -109,8 +109,8 @@ server.tool(
     if (progress.status === 'running') {
       const lines = progress.progress || [];
       const text = lines.length > 0
-        ? `Review in progress (reviewer: ${progress.reviewer}):\n${lines.map(l => `  ${l}`).join('\n')}\n\nStill running... Call openairev_status again in a few seconds.`
-        : `Review in progress (reviewer: ${progress.reviewer}). Started: ${progress.started}\n\nCall openairev_status again in a few seconds.`;
+        ? `Review in progress (reviewer: ${progress.reviewer}):\n${lines.map(l => `  ${l}`).join('\n')}\n\nStill running. Run \`openairev wait\` via Bash to stream progress until done.`
+        : `Review in progress (reviewer: ${progress.reviewer}). Started: ${progress.started}\n\nRun \`openairev wait\` via Bash to stream progress until done.`;
       return { content: [{ type: 'text', text }] };
     }
 
@@ -164,6 +164,8 @@ server.tool(
 
 function writeProgress(data) {
   try {
+    data.cwd = cwd;
+    data.progress_file = PROGRESS_FILE;
     writeFileSync(PROGRESS_FILE, JSON.stringify(data, null, 2));
   } catch { /* non-critical */ }
 }