@simonren/quorum 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +91 -48
  2. package/commands/multi-consult.md +47 -72
  3. package/commands/multi-review.md +68 -99
  4. package/dist/adapters/base.d.ts +53 -70
  5. package/dist/adapters/base.js +21 -79
  6. package/dist/adapters/claude.d.ts +38 -17
  7. package/dist/adapters/claude.js +93 -185
  8. package/dist/adapters/cli-adapter.d.ts +78 -0
  9. package/dist/adapters/cli-adapter.js +217 -0
  10. package/dist/adapters/codex.d.ts +18 -13
  11. package/dist/adapters/codex.js +64 -200
  12. package/dist/adapters/gemini.d.ts +30 -20
  13. package/dist/adapters/gemini.js +56 -148
  14. package/dist/adapters/index.d.ts +8 -5
  15. package/dist/adapters/index.js +7 -8
  16. package/dist/config.d.ts +116 -28
  17. package/dist/config.js +50 -28
  18. package/dist/consult-prompt.d.ts +6 -5
  19. package/dist/consult-prompt.js +48 -23
  20. package/dist/decoders/claude.d.ts +6 -0
  21. package/dist/decoders/claude.js +10 -1
  22. package/dist/doctor.d.ts +20 -0
  23. package/dist/doctor.js +91 -0
  24. package/dist/executor.d.ts +58 -46
  25. package/dist/executor.js +218 -129
  26. package/dist/guards.d.ts +29 -0
  27. package/dist/guards.js +72 -0
  28. package/dist/handoff.d.ts +79 -229
  29. package/dist/handoff.js +411 -402
  30. package/dist/index.d.ts +8 -12
  31. package/dist/index.js +81 -106
  32. package/dist/integrity.d.ts +16 -0
  33. package/dist/integrity.js +49 -0
  34. package/dist/sections.d.ts +22 -0
  35. package/dist/sections.js +31 -0
  36. package/dist/server.d.ts +9 -0
  37. package/dist/server.js +36 -0
  38. package/dist/tools/consult.d.ts +17 -76
  39. package/dist/tools/consult.js +72 -188
  40. package/dist/tools/format.d.ts +35 -0
  41. package/dist/tools/format.js +85 -0
  42. package/dist/tools/review.d.ts +55 -0
  43. package/dist/tools/review.js +120 -0
  44. package/dist/types.d.ts +20 -103
  45. package/dist/types.js +18 -29
  46. package/package.json +7 -4
  47. package/dist/cli/check.d.ts +0 -20
  48. package/dist/cli/check.js +0 -78
  49. package/dist/cli/codex.d.ts +0 -11
  50. package/dist/cli/codex.js +0 -255
  51. package/dist/cli/gemini.d.ts +0 -12
  52. package/dist/cli/gemini.js +0 -253
  53. package/dist/context.d.ts +0 -1538
  54. package/dist/context.js +0 -383
  55. package/dist/decoders/gemini.d.ts +0 -33
  56. package/dist/decoders/gemini.js +0 -58
  57. package/dist/errors.d.ts +0 -46
  58. package/dist/errors.js +0 -198
  59. package/dist/pipeline.d.ts +0 -135
  60. package/dist/pipeline.js +0 -462
  61. package/dist/prompt-v2.d.ts +0 -38
  62. package/dist/prompt-v2.js +0 -391
  63. package/dist/prompt.d.ts +0 -71
  64. package/dist/prompt.js +0 -309
  65. package/dist/schema.d.ts +0 -660
  66. package/dist/schema.js +0 -536
  67. package/dist/tools/feedback.d.ts +0 -91
  68. package/dist/tools/feedback.js +0 -117
@@ -1,122 +1,49 @@
1
1
  /**
2
- * MCP Tool — multi_consult
2
+ * MCP tool — multi_consult
3
3
  *
4
- * Asks Codex, Gemini, and Claude (Opus) the same question in parallel.
5
- * Returns each model's structured 5-section response to CC for synthesis.
4
+ * Asks every available adapter the same question in parallel and returns each
5
+ * model's 5-section response to CC for synthesis.
6
6
  */
7
7
  import { z } from 'zod';
8
- import { realpathSync } from 'fs';
9
- import { resolve, sep } from 'path';
10
- import { homedir } from 'os';
11
8
  import { getAvailableAdapters } from '../adapters/index.js';
12
- // =============================================================================
13
- // SENSITIVE PATH GUARD
14
- // =============================================================================
15
- /**
16
- * Returns the directory's *canonical* absolute path if it's safe to use as a
17
- * workingDir, or null if it resolves to a sensitive system location. We deny
18
- * roots like `/`, `/etc`, `~`, `~/.ssh`, etc. — paths *inside* a project root
19
- * are fine. The check resolves symlinks via realpath so a symlinked alias of
20
- * a sensitive directory is also caught.
21
- */
22
- export function checkSensitiveWorkingDir(input) {
23
- let resolved;
24
- try {
25
- // realpath if it exists; otherwise fall back to resolve() so the standard
26
- // adapter cwd-existence check produces the user-visible error.
27
- resolved = realpathSync(input);
28
- }
29
- catch {
30
- resolved = resolve(input);
31
- }
32
- const home = homedir();
33
- const rawDenylist = [
34
- '/',
35
- '/etc',
36
- '/var',
37
- '/usr',
38
- '/bin',
39
- '/sbin',
40
- '/boot',
41
- '/root',
42
- home,
43
- `${home}${sep}.ssh`,
44
- `${home}${sep}.aws`,
45
- `${home}${sep}.config`,
46
- `${home}${sep}.gnupg`,
47
- ];
48
- // Resolve denylist symlinks too (e.g. macOS /etc -> /private/etc) so the
49
- // resolved-path comparison hits regardless of symlink direction.
50
- const denylist = new Set();
51
- for (const path of rawDenylist) {
52
- denylist.add(path);
53
- try {
54
- denylist.add(realpathSync(path));
55
- }
56
- catch { /* ignore — path doesn't exist */ }
57
- }
58
- if (denylist.has(resolved)) {
59
- return { ok: false, reason: `workingDir resolves to a sensitive path: ${resolved}` };
60
- }
61
- return { ok: true, resolved };
62
- }
9
+ import { CONSULT_RESPONSE_SECTIONS } from '../consult-prompt.js';
10
+ import { checkSensitiveWorkingDir, containsSteeringTag, refusalText, STEERING_TAG_MESSAGE } from '../guards.js';
11
+ import { changedPaths, snapshotWorkingTree, tamperWarning } from '../integrity.js';
12
+ import { validateSections } from '../sections.js';
13
+ import { REASONING_EFFORTS, SERVICE_TIERS } from '../types.js';
14
+ import { clampOutput, fromSettled, NO_CLIS_TEXT, renderBlock, renderFailure, seconds, statusHeading, toolText, } from './format.js';
15
+ export { checkSensitiveWorkingDir } from '../guards.js';
63
16
  // =============================================================================
64
17
  // SECTION VALIDATION
65
18
  // =============================================================================
66
- const REQUIRED_SECTIONS = [
67
- 'Recommendation',
68
- 'Reasoning',
69
- 'Tradeoffs',
70
- 'Risks',
71
- 'Open questions for the asker',
72
- ];
73
- /**
74
- * Lightweight check for the 5 expected `## …` headers in a model's consult
75
- * response. Behaviors:
76
- * - Strips fenced code blocks first so a quoted format-example skeleton
77
- * doesn't falsely satisfy the check.
78
- * - Requires the section name as a word boundary at the start of an H2 line,
79
- * but tolerates trailing decoration (colon, em-dash continuation, etc.).
80
- * - Case-sensitive on the section name. Bare bold (`**Recommendation**`),
81
- * wrong level (`### Recommendation`), and ALL-CAPS variants all count as
82
- * missing — that's the signal we want CC to see when models drift.
83
- */
19
+ /** Check a consult response for the five required `## …` headers. */
84
20
  export function validateConsultSections(output) {
85
- // Remove fenced code blocks so headers inside them don't satisfy the regex.
86
- const stripped = output.replace(/```[\s\S]*?```/g, '');
87
- const missing = [];
88
- for (const section of REQUIRED_SECTIONS) {
89
- // Match the exact section name at the start of an H2 header line.
90
- // `\b` after the name allows `:`, `—`, `-`, whitespace+more — but not
91
- // suffixed letters/digits (which would change the section name itself).
92
- const pattern = new RegExp(`^##\\s+${escapeRegex(section)}\\b[^\\n]*$`, 'm');
93
- if (!pattern.test(stripped)) {
94
- missing.push(section);
95
- }
96
- }
97
- return { missing };
98
- }
99
- function escapeRegex(s) {
100
- return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
21
+ return validateSections(output, CONSULT_RESPONSE_SECTIONS);
101
22
  }
102
23
  // =============================================================================
103
- // INPUT SCHEMA
24
+ // INPUT SCHEMA — single source for validation AND the advertised JSON schema
104
25
  // =============================================================================
105
- export const ConsultInputSchema = z.object({
106
- workingDir: z.string().describe('Working directory for the CLI to operate in'),
107
- question: z.string().describe('CC-composed self-contained question for the panel'),
108
- relevantFiles: z.array(z.string()).optional().describe('CC-triaged file subset for code-grounded questions'),
109
- customPrompt: z.string()
110
- .optional()
111
- // Reject any literal `<user-steering` or `</user-steering` so a steering
112
- // value cannot escape the prompt envelope and inject instructions.
113
- .refine(v => !v || !/<\/?user-steering/i.test(v), {
114
- message: 'customPrompt must not contain <user-steering> tags',
115
- })
116
- .describe('Free-form steering from $ARGUMENTS'),
117
- reasoningEffort: z.enum(['high', 'xhigh']).optional().describe("Codex reasoning effort (default: 'xhigh' for consult)"),
118
- serviceTier: z.enum(['default', 'fast', 'flex']).optional().describe("Codex service tier (default: 'fast')"),
119
- });
26
+ export const ConsultInputShape = {
27
+ workingDir: z.string().min(1)
28
+ .describe('Absolute path of the project root. Always required, even for general questions. Never a home directory or system path.'),
29
+ question: z.string().min(1).max(100_000)
30
+ .describe('CC-composed, self-contained question, ending with a CRITERIA block (priority-ordered, each tagged [stated] or [assumed]).'),
31
+ relevantFiles: z.array(z.string().min(1)).max(100).optional()
32
+ .describe('For code-grounded questions: the minimal file subset (typically 3–10) the panel must read. Omit for general questions so the panel answers from expertise without reading the filesystem.'),
33
+ customPrompt: z.string().max(20_000).optional()
34
+ .refine((v) => !containsSteeringTag(v), { message: STEERING_TAG_MESSAGE })
35
+ .describe('Free-form steering from the user (e.g. "focus on rollback safety"). Omit when the question already carries it.'),
36
+ reasoningEffort: z.enum(REASONING_EFFORTS).optional()
37
+ .describe("Codex reasoning effort. Default 'xhigh' for consult; 'high' is faster and cheaper."),
38
+ serviceTier: z.enum(SERVICE_TIERS).optional()
39
+ .describe("Codex service tier. Omit for the config default ('fast'); 'flex' = cheaper and slower; 'default' = API default tier."),
40
+ };
41
+ export const ConsultInputSchema = z.object(ConsultInputShape);
42
+ export const MULTI_CONSULT_DESCRIPTION = "Ask the panel (Codex, Gemini, Claude with fresh context) the same question in parallel and get each model's " +
43
+ "structured answer (Recommendation / Reasoning / Tradeoffs / Risks / Open questions) back for CC to synthesize. " +
44
+ "Input shape: 'question' only — no 'ccOutput'. Use for guidance, recommendations, or choosing an approach when there is " +
45
+ "no prior CC-produced work to review; to review such work use 'multi_review'. The discriminator is the shape of the " +
46
+ "input, not the user's phrasing. Calls take minutes.";
120
47
  function toConsultRequest(input) {
121
48
  return {
122
49
  workingDir: input.workingDir,
@@ -127,94 +54,51 @@ function toConsultRequest(input) {
127
54
  serviceTier: input.serviceTier,
128
55
  };
129
56
  }
130
- function formatOutcome(outcome) {
57
+ function renderOutcome(outcome) {
131
58
  const { adapter, result } = outcome;
132
- const name = adapter.getCapabilities().name;
59
+ const model = adapter.getCapabilities().name;
133
60
  if (!result.success) {
134
- const emoji = {
135
- cli_not_found: '❌', timeout: '⏱️', rate_limit: '🚫', auth_error: '🔐', cli_error: '❌',
136
- };
137
- let msg = `## ${name}\n${emoji[result.error.type] || '❌'} **${result.error.type}**: ${result.error.message}`;
138
- if (result.suggestion)
139
- msg += `\n\n💡 ${result.suggestion}`;
140
- return msg;
61
+ return renderBlock('answer', { model, status: 'failed', error: result.error.type, seconds: seconds(result.executionTimeMs) }, renderFailure(result));
141
62
  }
142
- const drift = validateConsultSections(result.output);
63
+ // Validate what CC will actually see: a section cut off by the cap is missing.
64
+ const shown = clampOutput(result.output);
65
+ const drift = validateConsultSections(shown);
143
66
  const driftLine = drift.missing.length > 0
144
- ? `⚠️ Format drift: missing sections [${drift.missing.join(', ')}]\n\n`
67
+ ? `⚠️ Format drift: missing sections [${drift.missing.join(', ')}] — weight this answer accordingly.\n\n`
145
68
  : '';
146
- return `## ${name}\n**Execution Time:** ${(result.executionTimeMs / 1000).toFixed(1)}s\n\n${driftLine}${result.output}`;
69
+ return renderBlock('answer', {
70
+ model,
71
+ status: 'ok',
72
+ seconds: seconds(result.executionTimeMs),
73
+ drift: drift.missing.length > 0 ? drift.missing.join(',') : undefined,
74
+ truncated: result.truncated ? 'true' : undefined,
75
+ }, driftLine + shown);
147
76
  }
148
77
  export async function handleMultiConsult(input) {
149
- // Sensitive-cwd guard runs before any adapter dispatch — direct MCP callers
150
- // can't bypass the slash-command body's refusal by skipping CC.
78
+ // Guard runs before any adapter dispatch so direct MCP callers cannot skip
79
+ // the slash command's refusal.
151
80
  const guard = checkSensitiveWorkingDir(input.workingDir);
152
- if (!guard.ok) {
153
- return {
154
- content: [{
155
- type: 'text',
156
- text: `❌ Refused: ${guard.reason}\n\nInvoke /multi-consult from a project root, not a sensitive system path.`,
157
- }],
158
- };
159
- }
160
- const request = toConsultRequest(input);
81
+ if (!guard.ok)
82
+ return toolText(refusalText(guard.reason, '/multi-consult'));
161
83
  const adapters = await getAvailableAdapters();
162
- if (adapters.length === 0) {
163
- return {
164
- content: [{
165
- type: 'text',
166
- text: '❌ No AI CLIs found.\n\nInstall at least one:\n - Codex: npm install -g @openai/codex-cli\n - Gemini (agy): curl -fsSL https://antigravity.google/cli/install.sh | bash',
167
- }],
168
- };
169
- }
170
- // Promise.allSettled — a rejected adapter must NOT collapse the whole call.
171
- const settled = await Promise.allSettled(adapters.map((adapter) => adapter.runConsult(request).then((result) => ({ adapter, result }))));
172
- const outcomes = settled.map((s, i) => {
173
- if (s.status === 'fulfilled')
174
- return s.value;
175
- const message = s.reason instanceof Error ? s.reason.message : String(s.reason);
176
- return {
177
- adapter: adapters[i],
178
- result: {
179
- success: false,
180
- error: { type: 'cli_error', message },
181
- suggestion: 'Adapter rejected — see error above',
182
- executionTimeMs: 0,
183
- },
184
- };
185
- });
186
- const allFailed = outcomes.every((o) => !o.result.success);
187
- const someFailed = outcomes.some((o) => !o.result.success);
188
- const lines = [];
189
- if (allFailed)
190
- lines.push('## Multi-Consult ❌ All Failed\n');
191
- else if (someFailed)
192
- lines.push('## Multi-Consult ⚠️ Partial Success\n');
193
- else
194
- lines.push('## Multi-Consult ✓\n');
195
- lines.push(`**Models:** ${adapters.map((a) => a.id).join(', ')}\n`);
196
- for (const outcome of outcomes) {
197
- lines.push(formatOutcome(outcome));
198
- lines.push('');
199
- }
200
- return { content: [{ type: 'text', text: lines.join('\n') }] };
84
+ if (adapters.length === 0)
85
+ return toolText(NO_CLIS_TEXT);
86
+ const request = toConsultRequest(input);
87
+ const treeBefore = snapshotWorkingTree(guard.resolved);
88
+ // allSettled: a thrown adapter must not collapse the other answers.
89
+ const settled = await Promise.allSettled(adapters.map((adapter) => adapter.runConsult(request)));
90
+ const outcomes = adapters.map((adapter, i) => ({ adapter, result: fromSettled(settled[i]) }));
91
+ const failed = outcomes.filter((o) => !o.result.success).length;
92
+ const tampered = changedPaths(treeBefore, snapshotWorkingTree(guard.resolved));
93
+ const lines = [
94
+ statusHeading('Multi-Consult', outcomes.length, failed),
95
+ '',
96
+ ...(tampered.length > 0 ? [tamperWarning(tampered), ''] : []),
97
+ `**Models:** ${adapters.map((a) => a.id).join(', ')} (${outcomes.length - failed}/${outcomes.length} answered)`,
98
+ '',
99
+ 'Each `<answer>` block is one model\'s raw response.',
100
+ '',
101
+ ...outcomes.map((o) => renderOutcome(o) + '\n'),
102
+ ];
103
+ return toolText(lines.join('\n'));
201
104
  }
202
- // =============================================================================
203
- // TOOL DEFINITION
204
- // =============================================================================
205
- export const MULTI_CONSULT_TOOL_DEFINITION = {
206
- name: 'multi_consult',
207
- description: "Use when asking the panel for guidance, recommendation, or approach (no prior CC-produced work to review). Input shape: 'question' only — no 'ccOutput'. For reviewing existing CC-produced work (plan, findings, code), use 'multi_review' (which requires 'ccOutput'). The discriminator is the shape of the input, not the user's phrasing.",
208
- inputSchema: {
209
- type: 'object',
210
- properties: {
211
- workingDir: { type: 'string', description: 'Working directory for the CLI to operate in' },
212
- question: { type: 'string', description: 'CC-composed self-contained question for the panel' },
213
- relevantFiles: { type: 'array', items: { type: 'string' }, description: 'CC-triaged file subset for code-grounded questions' },
214
- customPrompt: { type: 'string', description: 'Free-form steering from $ARGUMENTS' },
215
- reasoningEffort: { type: 'string', enum: ['high', 'xhigh'], description: "Codex reasoning effort (default: 'xhigh' for consult)" },
216
- serviceTier: { type: 'string', enum: ['default', 'fast', 'flex'], description: "Codex service tier (default: 'fast')" },
217
- },
218
- required: ['workingDir', 'question'],
219
- },
220
- };
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Shared formatting for tool results.
3
+ *
4
+ * Both tools hand CC a single text block. Each model's raw output is wrapped
5
+ * in an XML-style element (`<review …>` / `<answer …>`) whose attributes carry
6
+ * the metadata CC needs to cross-reference — model, pass, status, timing —
7
+ * because the raw output is free markdown and cannot be relied on for
8
+ * delimiters.
9
+ */
10
+ import { ReviewFailure, ReviewResult } from '../adapters/base.js';
11
+ /** Per-model output cap so one runaway reviewer cannot crowd out the others. */
12
+ export declare const MAX_OUTPUT_CHARS = 60000;
13
+ export declare const NO_CLIS_TEXT: string;
14
+ export interface ToolText {
15
+ [key: string]: unknown;
16
+ content: Array<{
17
+ type: 'text';
18
+ text: string;
19
+ }>;
20
+ isError?: boolean;
21
+ }
22
+ export declare function toolText(text: string, isError?: boolean): ToolText;
23
+ /** Top-level status line: ✓ / ⚠️ Partial Success / ❌ All Failed. */
24
+ export declare function statusHeading(title: string, total: number, failed: number): string;
25
+ /** Collapse a settled promise into a ReviewResult so a thrown adapter reads as a failure. */
26
+ export declare function fromSettled(settled: PromiseSettledResult<ReviewResult>): ReviewResult;
27
+ export declare function seconds(ms: number): string;
28
+ export declare function renderFailure(result: ReviewFailure): string;
29
+ /** Cap a model's output; append a notice when it was cut. */
30
+ export declare function clampOutput(text: string, max?: number): string;
31
+ /**
32
+ * Wrap a body in an XML-style element with the given attributes. Attribute
33
+ * values are escaped; undefined/empty attributes are omitted.
34
+ */
35
+ export declare function renderBlock(tag: string, attrs: Record<string, string | number | undefined>, body: string): string;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Shared formatting for tool results.
3
+ *
4
+ * Both tools hand CC a single text block. Each model's raw output is wrapped
5
+ * in an XML-style element (`<review …>` / `<answer …>`) whose attributes carry
6
+ * the metadata CC needs to cross-reference — model, pass, status, timing —
7
+ * because the raw output is free markdown and cannot be relied on for
8
+ * delimiters.
9
+ */
10
+ /** Per-model output cap so one runaway reviewer cannot crowd out the others. */
11
+ export const MAX_OUTPUT_CHARS = 60_000;
12
+ const ERROR_EMOJI = {
13
+ cli_not_found: '❌',
14
+ timeout: '⏱️',
15
+ rate_limit: '🚫',
16
+ auth_error: '🔐',
17
+ cli_error: '❌',
18
+ };
19
+ export const NO_CLIS_TEXT = [
20
+ '❌ No AI CLIs available.',
21
+ '',
22
+ 'Install at least one and make sure it is on PATH:',
23
+ ' - Codex: npm install -g @openai/codex-cli && codex login',
24
+ ' - Gemini: curl -fsSL https://antigravity.google/cli/install.sh | bash && agy',
25
+ ' - Claude: https://docs.anthropic.com/en/docs/claude-code',
26
+ '',
27
+ 'Adapters can also be switched off with `"enabled": false` in ~/.config/quorum/config.json.',
28
+ 'Run `npx -y @simonren/quorum doctor` to see what quorum detects.',
29
+ ].join('\n');
30
+ export function toolText(text, isError = false) {
31
+ return isError ? { content: [{ type: 'text', text }], isError: true } : { content: [{ type: 'text', text }] };
32
+ }
33
+ /** Top-level status line: ✓ / ⚠️ Partial Success / ❌ All Failed. */
34
+ export function statusHeading(title, total, failed) {
35
+ if (total === 0 || failed >= total)
36
+ return `# ${title} ❌ All Failed`;
37
+ if (failed > 0)
38
+ return `# ${title} ⚠️ Partial Success`;
39
+ return `# ${title} ✓`;
40
+ }
41
+ /** Collapse a settled promise into a ReviewResult so a thrown adapter reads as a failure. */
42
+ export function fromSettled(settled) {
43
+ if (settled.status === 'fulfilled')
44
+ return settled.value;
45
+ const message = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
46
+ // The stack only exists here — keep it on stderr for diagnosis.
47
+ console.error('[quorum] adapter threw instead of returning a result:', settled.reason instanceof Error ? settled.reason.stack ?? message : message);
48
+ return {
49
+ success: false,
50
+ error: { type: 'cli_error', message },
51
+ suggestion: 'Adapter threw instead of returning a result — see error above',
52
+ executionTimeMs: 0,
53
+ };
54
+ }
55
+ export function seconds(ms) {
56
+ return (ms / 1000).toFixed(1);
57
+ }
58
+ export function renderFailure(result) {
59
+ const emoji = ERROR_EMOJI[result.error.type] ?? '❌';
60
+ let msg = `${emoji} **${result.error.type}**: ${result.error.message}`;
61
+ if (result.suggestion)
62
+ msg += `\n\n💡 ${result.suggestion}`;
63
+ return msg;
64
+ }
65
+ /** Cap a model's output; append a notice when it was cut. */
66
+ export function clampOutput(text, max = MAX_OUTPUT_CHARS) {
67
+ if (text.length <= max)
68
+ return text;
69
+ const dropped = text.length - max;
70
+ return `${text.slice(0, max)}\n\n[… truncated ${dropped} chars — the model exceeded the ${max}-char per-response cap]`;
71
+ }
72
+ /**
73
+ * Wrap a body in an XML-style element with the given attributes. Attribute
74
+ * values are escaped; undefined/empty attributes are omitted.
75
+ */
76
+ export function renderBlock(tag, attrs, body) {
77
+ const attrText = Object.entries(attrs)
78
+ .filter(([, v]) => v !== undefined && v !== '')
79
+ .map(([k, v]) => `${k}="${escapeAttr(String(v))}"`)
80
+ .join(' ');
81
+ return `<${tag}${attrText ? ' ' + attrText : ''}>\n${body}\n</${tag}>`;
82
+ }
83
+ function escapeAttr(value) {
84
+ return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
85
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * MCP tool — multi_review
3
+ *
4
+ * Runs every available adapter twice in parallel — a standard pass (bugs,
5
+ * gaps, is the bar met) and an adversarial pass (assumptions, decisions,
6
+ * failure paths) — and returns each model's raw response to CC, which
7
+ * verifies the findings against the code and synthesizes a verdict.
8
+ */
9
+ import { z } from 'zod';
10
+ import { ToolText } from './format.js';
11
+ export declare const ReviewInputShape: {
12
+ workingDir: z.ZodString;
13
+ ccOutput: z.ZodString;
14
+ outputType: z.ZodEnum<["implementation", "plan", "findings", "analysis", "proposal"]>;
15
+ baseRef: z.ZodOptional<z.ZodString>;
16
+ analyzedFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
17
+ focusAreas: z.ZodOptional<z.ZodArray<z.ZodEnum<["security", "performance", "architecture", "correctness", "maintainability", "scalability", "testing", "documentation"]>, "many">>;
18
+ customPrompt: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
19
+ reasoningEffort: z.ZodOptional<z.ZodEnum<["high", "xhigh"]>>;
20
+ serviceTier: z.ZodOptional<z.ZodEnum<["default", "fast", "flex"]>>;
21
+ };
22
+ export declare const ReviewInputSchema: z.ZodObject<{
23
+ workingDir: z.ZodString;
24
+ ccOutput: z.ZodString;
25
+ outputType: z.ZodEnum<["implementation", "plan", "findings", "analysis", "proposal"]>;
26
+ baseRef: z.ZodOptional<z.ZodString>;
27
+ analyzedFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
28
+ focusAreas: z.ZodOptional<z.ZodArray<z.ZodEnum<["security", "performance", "architecture", "correctness", "maintainability", "scalability", "testing", "documentation"]>, "many">>;
29
+ customPrompt: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
30
+ reasoningEffort: z.ZodOptional<z.ZodEnum<["high", "xhigh"]>>;
31
+ serviceTier: z.ZodOptional<z.ZodEnum<["default", "fast", "flex"]>>;
32
+ }, "strip", z.ZodTypeAny, {
33
+ workingDir: string;
34
+ outputType: "implementation" | "plan" | "findings" | "analysis" | "proposal";
35
+ ccOutput: string;
36
+ reasoningEffort?: "high" | "xhigh" | undefined;
37
+ serviceTier?: "default" | "fast" | "flex" | undefined;
38
+ customPrompt?: string | undefined;
39
+ baseRef?: string | undefined;
40
+ focusAreas?: ("security" | "performance" | "architecture" | "correctness" | "maintainability" | "scalability" | "testing" | "documentation")[] | undefined;
41
+ analyzedFiles?: string[] | undefined;
42
+ }, {
43
+ workingDir: string;
44
+ outputType: "implementation" | "plan" | "findings" | "analysis" | "proposal";
45
+ ccOutput: string;
46
+ reasoningEffort?: "high" | "xhigh" | undefined;
47
+ serviceTier?: "default" | "fast" | "flex" | undefined;
48
+ customPrompt?: string | undefined;
49
+ baseRef?: string | undefined;
50
+ focusAreas?: ("security" | "performance" | "architecture" | "correctness" | "maintainability" | "scalability" | "testing" | "documentation")[] | undefined;
51
+ analyzedFiles?: string[] | undefined;
52
+ }>;
53
+ export type ReviewInput = z.infer<typeof ReviewInputSchema>;
54
+ export declare const MULTI_REVIEW_DESCRIPTION: string;
55
+ export declare function handleMultiReview(input: ReviewInput): Promise<ToolText>;
@@ -0,0 +1,120 @@
1
+ /**
2
+ * MCP tool — multi_review
3
+ *
4
+ * Runs every available adapter twice in parallel — a standard pass (bugs,
5
+ * gaps, is the bar met) and an adversarial pass (assumptions, decisions,
6
+ * failure paths) — and returns each model's raw response to CC, which
7
+ * verifies the findings against the code and synthesizes a verdict.
8
+ */
9
+ import { z } from 'zod';
10
+ import { getAvailableAdapters } from '../adapters/index.js';
11
+ import { REQUIRED_REVIEW_SECTIONS } from '../handoff.js';
12
+ import { checkSensitiveWorkingDir, containsSteeringTag, refusalText, STEERING_TAG_MESSAGE } from '../guards.js';
13
+ import { changedPaths, snapshotWorkingTree, tamperWarning } from '../integrity.js';
14
+ import { validateSections } from '../sections.js';
15
+ import { FOCUS_AREAS, OUTPUT_TYPES, REASONING_EFFORTS, SERVICE_TIERS } from '../types.js';
16
+ import { clampOutput, fromSettled, NO_CLIS_TEXT, renderBlock, renderFailure, seconds, statusHeading, toolText, } from './format.js';
17
+ // =============================================================================
18
+ // INPUT SCHEMA — single source for validation AND the advertised JSON schema
19
+ // =============================================================================
20
+ export const ReviewInputShape = {
21
+ workingDir: z.string().min(1)
22
+ .describe('Absolute path of the project root the reviewers may read. Never a home directory or system path.'),
23
+ ccOutput: z.string().min(1).max(100_000)
24
+ .describe("CC's brief: SUMMARY (with a Bar: line), UNCERTAINTIES tagged [load-bearing]/[incidental], QUESTIONS, DECISIONS (with Rationale:), KNOWN GAPS, PRIORITY FILES. Reviewers have the filesystem but not the conversation — put what only CC knows here. Keep it short: no diffs or file contents (agy takes the whole prompt on argv, ~120 KB max)."),
25
+ outputType: z.enum(OUTPUT_TYPES)
26
+ .describe("What the brief describes: 'implementation' for code CC changed, 'plan' before implementing, 'findings' from an investigation, 'analysis', or 'proposal'."),
27
+ baseRef: z.string().max(200).regex(/^[A-Za-z0-9._\/@^~-]+$/, 'baseRef must be a git ref or SHA').optional()
28
+ .describe("Git ref the change is relative to, e.g. 'main' or a merge-base SHA. Give it when the working tree is clean (a checked-out branch or PR) so reviewers can run `git diff <baseRef>...HEAD` instead of finding an empty diff."),
29
+ analyzedFiles: z.array(z.string().min(1)).max(200).optional()
30
+ .describe('Files CC created or modified (relative to workingDir). Reviewers read these first.'),
31
+ focusAreas: z.array(z.enum(FOCUS_AREAS)).max(FOCUS_AREAS.length).optional()
32
+ .describe('Areas to weight. Only when the user asked for a focus; omit for a comprehensive review.'),
33
+ customPrompt: z.string().max(20_000).optional()
34
+ .refine((v) => !containsSteeringTag(v), { message: STEERING_TAG_MESSAGE })
35
+ .describe('Free-form steering from the user, passed to both passes (e.g. "focus the challenge on rollback safety").'),
36
+ reasoningEffort: z.enum(REASONING_EFFORTS).optional()
37
+ .describe("Codex reasoning effort. Default 'high'; use 'xhigh' for deeper analysis at higher cost."),
38
+ serviceTier: z.enum(SERVICE_TIERS).optional()
39
+ .describe("Codex service tier. Omit for the config default ('fast' = priority, ~2x cost); 'flex' = cheaper and slower; 'default' = API default tier."),
40
+ };
41
+ export const ReviewInputSchema = z.object(ReviewInputShape);
42
+ export const MULTI_REVIEW_DESCRIPTION = "Review work Claude Code (CC) already produced — code changes, a plan, findings, an analysis, or a proposal. " +
43
+ "Requires 'ccOutput', CC's brief about that work. Every available model (Codex, Gemini, Claude with fresh context) " +
44
+ "runs a standard pass and an adversarial pass in parallel; the raw responses come back for CC to verify against the code " +
45
+ "and synthesize. For an open question with no prior CC work to review, use 'multi_consult' instead — the discriminator " +
46
+ "is the shape of the input, not the user's phrasing. Calls take minutes.";
47
+ function toReviewRequest(input) {
48
+ return {
49
+ workingDir: input.workingDir,
50
+ ccOutput: input.ccOutput,
51
+ outputType: input.outputType,
52
+ analyzedFiles: input.analyzedFiles,
53
+ focusAreas: input.focusAreas,
54
+ customPrompt: input.customPrompt,
55
+ baseRef: input.baseRef,
56
+ reasoningEffort: input.reasoningEffort,
57
+ serviceTier: input.serviceTier,
58
+ };
59
+ }
60
+ function renderPass(outcome) {
61
+ const { adapter, mode, result } = outcome;
62
+ const model = adapter.getCapabilities().name;
63
+ if (!result.success) {
64
+ return renderBlock('review', { model, pass: mode, status: 'failed', error: result.error.type, seconds: seconds(result.executionTimeMs) }, renderFailure(result));
65
+ }
66
+ // Validate what CC will actually see: a verdict cut off by the cap is missing.
67
+ const shown = clampOutput(result.output);
68
+ const drift = validateSections(shown, REQUIRED_REVIEW_SECTIONS);
69
+ const driftLine = drift.missing.length > 0
70
+ ? `⚠️ Format drift: missing sections [${drift.missing.join(', ')}] — read with care.\n\n`
71
+ : '';
72
+ return renderBlock('review', {
73
+ model,
74
+ pass: mode,
75
+ status: 'ok',
76
+ seconds: seconds(result.executionTimeMs),
77
+ drift: drift.missing.length > 0 ? drift.missing.join(',') : undefined,
78
+ truncated: result.truncated ? 'true' : undefined,
79
+ }, driftLine + shown);
80
+ }
81
+ export async function handleMultiReview(input) {
82
+ // Guard runs before any adapter dispatch so direct MCP callers cannot skip
83
+ // the slash command's refusal.
84
+ const guard = checkSensitiveWorkingDir(input.workingDir);
85
+ if (!guard.ok)
86
+ return toolText(refusalText(guard.reason, '/multi-review'));
87
+ const adapters = await getAvailableAdapters();
88
+ if (adapters.length === 0)
89
+ return toolText(NO_CLIS_TEXT);
90
+ const request = toReviewRequest(input);
91
+ const modes = ['standard', 'adversarial'];
92
+ const treeBefore = snapshotWorkingTree(guard.resolved);
93
+ // Both passes for every adapter, all in parallel. allSettled: a thrown
94
+ // adapter must not collapse the other five results.
95
+ const jobs = adapters.flatMap((adapter) => modes.map((mode) => ({ adapter, mode, promise: adapter.runReview({ ...request, reviewMode: mode }) })));
96
+ const settled = await Promise.allSettled(jobs.map((j) => j.promise));
97
+ const outcomes = jobs.map((job, i) => ({
98
+ adapter: job.adapter,
99
+ mode: job.mode,
100
+ result: fromSettled(settled[i]),
101
+ }));
102
+ const failed = outcomes.filter((o) => !o.result.success).length;
103
+ const tampered = changedPaths(treeBefore, snapshotWorkingTree(guard.resolved));
104
+ const lines = [
105
+ statusHeading('Multi-Model Review', outcomes.length, failed),
106
+ '',
107
+ ...(tampered.length > 0 ? [tamperWarning(tampered), ''] : []),
108
+ `**Models:** ${adapters.map((a) => a.id).join(', ')} — standard + adversarial pass each (${outcomes.length - failed}/${outcomes.length} passes succeeded)`,
109
+ '',
110
+ 'Each `<review>` block is one model\'s raw response. Verify every finding against the code before acting on it.',
111
+ '',
112
+ '## Standard review',
113
+ '',
114
+ ...outcomes.filter((o) => o.mode === 'standard').map((o) => renderPass(o) + '\n'),
115
+ '## Adversarial review',
116
+ '',
117
+ ...outcomes.filter((o) => o.mode === 'adversarial').map((o) => renderPass(o) + '\n'),
118
+ ];
119
+ return toolText(lines.join('\n'));
120
+ }