chati-dev 2.0.4 → 2.0.5

package/framework/hooks/model-governance.js

@@ -5,37 +5,57 @@
  * Validates that the model being used matches the agent's assignment.
  * Constitution Article XVI enforcement.
  *
- * Model assignments (from agent definitions):
- * - orchestrator: opus
- * - brief, detail, phases, tasks: sonnet
- * - architect, dev: sonnet | upgrade: opus if complex
- * - ux: sonnet
- * - qa-planning, qa-implementation: sonnet
- * - devops: sonnet
- * - greenfield-wu, brownfield-wu: sonnet
+ * Model assignments (from orchestrator spec — Model Map):
+ * - orchestrator: sonnet | upgrade: opus if complex routing
+ * - greenfield-wu: haiku | upgrade: sonnet if multi-stack
+ * - brownfield-wu: opus | no downgrade
+ * - brief: sonnet | upgrade: opus if 10+ integrations
+ * - detail: opus | no downgrade
+ * - architect: opus | no downgrade
+ * - ux: sonnet | upgrade: opus if design system from scratch
+ * - phases: sonnet | upgrade: opus if 20+ requirements
+ * - tasks: sonnet | upgrade: opus if 50+ tasks
+ * - qa-planning: opus | no downgrade
+ * - qa-implementation: opus | no downgrade
+ * - dev: opus | no downgrade
+ * - devops: sonnet | upgrade: opus if multi-env
  *
- * This hook is advisory — it warns but does not block.
+ * This hook is advisory in IDE mode — it warns but does not block.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 const AGENT_MODELS = {
-  orchestrator: 'opus',
-  'greenfield-wu': 'sonnet',
-  'brownfield-wu': 'sonnet',
+  orchestrator: 'sonnet',
+  'greenfield-wu': 'haiku',
+  'brownfield-wu': 'opus',
   brief: 'sonnet',
-  detail: 'sonnet',
-  architect: 'sonnet',
+  detail: 'opus',
+  architect: 'opus',
   ux: 'sonnet',
   phases: 'sonnet',
   tasks: 'sonnet',
-  'qa-planning': 'sonnet',
-  'qa-implementation': 'sonnet',
-  dev: 'sonnet',
+  'qa-planning': 'opus',
+  'qa-implementation': 'opus',
+  dev: 'opus',
   devops: 'sonnet',
 };
 
+/**
+ * Upgrade conditions per agent. When context matches, the model
+ * should be upgraded to the specified target.
+ */
+const UPGRADE_CONDITIONS = {
+  orchestrator: { to: 'opus', condition: 'complex routing or deviation handling' },
+  'greenfield-wu': { to: 'sonnet', condition: 'multi-stack or enterprise' },
+  brief: { to: 'opus', condition: '10+ integrations' },
+  ux: { to: 'opus', condition: 'design system from scratch' },
+  phases: { to: 'opus', condition: '20+ requirements' },
+  tasks: { to: 'opus', condition: '50+ tasks' },
+  devops: { to: 'opus', condition: 'multi-environment or IaC' },
+};
+
 function getCurrentAgent(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -71,6 +91,6 @@ async function main() {
   }
 }
 
-export { AGENT_MODELS, getCurrentAgent };
+export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
 
 main();

package/framework/orchestrator/chati.md

@@ -158,57 +158,137 @@ brownfield-wu -> Brief -> Architect -> Detail -> UX -> Phases -> Tasks -> QA-Pla
 | devops | chati.dev/agents/deploy/devops.md |
 
 ### Transition Logic
+
 ```
 When an agent completes (score >= 95%):
   1. Agent generates handoff at chati.dev/artifacts/handoffs/{agent-name}-handoff.md
   2. Agent updates session.yaml (status: completed, score, completed_at)
   3. Agent updates CLAUDE.md with current state
   4. Orchestrator identifies next agent from pipeline
+  5. Update session.yaml: current_agent = next_agent
+  6. Update project.state if crossing macro-phase boundary:
+     - WU through QA-Planning = clarity
+     - Dev + QA-Implementation = build
+     - Final validation = validate
+     - DevOps = deploy
+  7. Activate agent using Hybrid Activation Protocol (see below)
+```
+
+---
+
+## Hybrid Activation Protocol
+
+The orchestrator uses TWO activation modes depending on the agent type:
+
+### Interactive Agents (run IN-CONVERSATION)
+
+These agents require human interaction and run in the same terminal as the orchestrator:
+- **greenfield-wu** — needs user description of the project
+- **brownfield-wu** — needs user guidance on codebase
+- **brief** — needs iterative requirement extraction with user
+
+For interactive agents:
+```
+1. Read the agent's .md file from the Agent Location Map
+2. Display model recommendation (see Model Map below)
+3. Load agent context into the conversation
+4. User interacts with the agent directly
+5. Agent completes, generates handoff, orchestrator continues
+```
+
+### Autonomous Agents (run in SEPARATE TERMINALS)
+
+All other agents run in separate Claude Code processes with the correct model:
+- **detail**, **architect**, **ux**, **phases**, **tasks**
+- **qa-planning**, **dev**, **qa-implementation**, **devops**
+
+For autonomous agents:
+```
+1. Use the Bash tool to spawn the agent in a separate terminal:
+
+   node packages/chati-dev/src/terminal/run-agent.js \
+     --agent {agent_name} \
+     --task-id {primary_task_id} \
+     --project-dir {absolute_project_path} \
+     --previous-agent {previous_agent_name} \
+     --timeout 600000
+
+2. Wait for the JSON output
+
+3. Parse the result:
+   - If "status": "complete" → Save handoff, continue to next agent
+   - If "status": "needs_input" → Read "needs_input_question", ask the user,
+     then re-run with --additional-context "{user_response}"
+   - If "status": "error" → Apply Recovery Protocol (retry up to 2 times)
+   - If retries exhausted → Fall back to in-conversation activation
+
+4. Update session.yaml with completion data
+```
+
+### Parallel Group Execution
 
   ╔══════════════════════════════════════════════════════════════╗
-  ║ 4.5. PARALLELIZATION CHECK (MANDATORY — DO NOT SKIP)       ║
-  ║                                                             ║
-  ║ Before activating next agent, check parallel eligibility:   ║
+  ║ PARALLELIZATION CHECK (MANDATORY — DO NOT SKIP)             ║
   ║                                                             ║
   ║ GROUP 1 — Clarity Phase (after Brief completes):            ║
   ║   Agents: [detail, architect, ux]                           ║
-  ║   AUTONOMOUS: Spawn all 3 simultaneously (default)          ║
-  ║   HUMAN-IN-THE-LOOP: Offer parallel option (recommended)    ║
-  ║   Write scopes:                                             ║
-  ║     detail → chati.dev/artifacts/2-PRD/                     ║
-  ║     architect → chati.dev/artifacts/3-Architecture/         ║
-  ║     ux → chati.dev/artifacts/4-UX/                          ║
-  ║   → Merge ALL handoffs before proceeding to Phases          ║
+  ║   ALL run in parallel via separate terminals                ║
   ║                                                             ║
   ║ GROUP 2 — Build Phase (Dev agent tasks):                    ║
-  ║   ALL MODES: Independent tasks ALWAYS run in parallel       ║
-  ║   → Analyze task dependency graph from tasks.md             ║
-  ║   → Tasks with no shared file deps = parallel               ║
-  ║   → Tasks with deps = sequential within their chain         ║
-  ║   → Each terminal gets isolated write scope per task        ║
-  ║   → Merge results after each parallel batch                 ║
-  ║                                                             ║
-  ║ If next agent is NOT in a parallel group:                   ║
-  ║   → Continue with sequential activation (step 5)            ║
+  ║   Independent tasks ALWAYS run in parallel                  ║
+  ║   Tasks with dependencies = sequential within chain         ║
   ╚══════════════════════════════════════════════════════════════╝
 
-  5. Update session.yaml: current_agent = next_agent
-  6. Update project.state if crossing macro-phase boundary:
-     - WU through QA-Planning = clarity
-     - Dev + QA-Implementation = build
-     - Final validation = validate
-     - DevOps = deploy
-  7. Read next agent's command file -> Extract Model field from Identity section
-  8. Evaluate upgrade conditions against session context
-  9. Display model recommendation (see Model Selection Protocol below)
-  10. Activate agent
+When the next agent is part of a parallel group, use:
+
+```
+node packages/chati-dev/src/terminal/run-parallel.js \
+  --agents detail,architect,ux \
+  --task-ids {task_id_detail},{task_id_architect},{task_id_ux} \
+  --project-dir {absolute_project_path} \
+  --previous-agent brief \
+  --timeout 900000
+```
+
+Parse the consolidated JSON output:
+- If all agents completed → merged handoff ready, continue to next sequential agent
+- If partial failure → present failed agents to user with options:
+  1. Retry failed agents only
+  2. Continue with partial results
+  3. Fall back to sequential execution for failed agents
+
+### Sequential Fallback
+
+If terminal spawning fails (claude CLI not found, system error, etc.):
+```
+1. Log the failure
+2. Fall back to in-conversation activation (read agent .md file, become agent)
+3. Record in session.yaml:
+   terminal_fallback:
+     agent: {name}
+     reason: "{error_message}"
+     timestamp: "{now}"
+4. Continue pipeline normally
+```
+
+### Needs-Input Relay Pattern
+
+When a spawned agent needs user input:
+```
+1. Agent returns status: "needs_input" in JSON output
+2. Agent includes question in "needs_input_question" field
+3. Orchestrator reads the question
+4. Orchestrator presents question to user (in their language)
+5. User responds
+6. Orchestrator re-spawns agent with --additional-context "{user_response}"
+7. Repeat until agent completes or max 3 relay cycles
 ```
 
 ---
 
 ## Model Selection Protocol
 
-Before activating any agent, the orchestrator reads the agent's `Model` field and recommends the optimal model.
+Model selection is **enforced by construction**: the orchestrator passes `--model` to the spawned terminal. For interactive agents, the model is recommended to the user.
 
 ### Model Map (Quick Reference)
 
@@ -227,30 +307,19 @@ Before activating any agent, the orchestrator reads the agent's `Model` field an
 | qa-implementation | opus | no downgrade |
 | devops | sonnet | opus if multi-environment or IaC |
 
-### Evaluation Logic
-
-```
-1. Read agent's Model field from its .md file
-2. Extract default model and upgrade condition
-3. If upgrade condition exists:
-   a. Check session context (project.type, codebase_size, integrations_count, requirements_count)
-   b. Check previous agent signals (handoff complexity, discovered tech debt)
-   c. If condition matches -> recommend upgraded model
-   d. If condition does not match -> use default model
-4. If "no downgrade" -> always use the specified model
-```
-
-### Recommendation Message (IDE Mode)
-
-When the recommended model differs from the current model, display:
+### Enforcement
 
 ```
-💡 Model recommendation for {agent_name}: {recommended_model}
-   Reason: {justification}
-   Current: {current_model}
+For autonomous agents (spawned terminals):
+  → Model is AUTOMATICALLY selected and passed via --model flag
+  → No user intervention needed
+  → Correct model guaranteed by the prompt builder
 
-   To switch: /model {recommended_model}
-   Or continue with current model.
+For interactive agents (in-conversation):
+  → Display model recommendation to user:
+    💡 Model recommendation for {agent_name}: {recommended_model}
+       To switch: /model {recommended_model}
+  → Model governance hook provides defense-in-depth validation
 ```
 
 ### Session Logging
@@ -258,10 +327,11 @@ When the recommended model differs from the current model, display:
 ```yaml
 # Appended to session.yaml on each agent activation
 model_selections:
-  - agent: brief
-    recommended: sonnet
-    actual: opus          # What the user actually used
-    reason: "default"
+  - agent: detail
+    recommended: opus
+    actual: opus
+    mode: terminal          # terminal | in-conversation
+    reason: "no downgrade"
     timestamp: "2026-..."
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "AI-Powered Multi-Agent Orchestration System — 13 agents, 6 IDEs, 4 languages",
   "type": "module",
   "bin": {

package/src/terminal/handoff-parser.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Parse structured handoff data from spawned agent output.
+ *
+ * Agents running in separate `claude -p` terminals include a
+ * <chati-handoff> block in their output. This module extracts
+ * and parses that block so the orchestrator can read the results.
+ */
+
+/**
+ * Parse the <chati-handoff> block from agent stdout.
+ *
+ * @param {string} output - Full stdout from the agent process
+ * @returns {{ found: boolean, handoff: object|null, rawOutput: string }}
+ */
+export function parseAgentOutput(output) {
+  if (!output || typeof output !== 'string') {
+    return { found: false, handoff: null, rawOutput: '' };
+  }
+
+  const match = output.match(/<chati-handoff>([\s\S]*?)<\/chati-handoff>/);
+  if (!match) {
+    return { found: false, handoff: null, rawOutput: output };
+  }
+
+  const content = match[1].trim();
+  const handoff = parseHandoffFields(content);
+
+  return { found: true, handoff, rawOutput: output };
+}
+
+/**
+ * Parse YAML-like key-value fields from the handoff block content.
+ *
+ * Supports:
+ *   scalar: value
+ *   list:
+ *     - item1
+ *     - item2
+ *   map:
+ *     key1: value1
+ *     key2: value2
+ *
+ * @param {string} content - Content inside <chati-handoff> tags
+ * @returns {object} Parsed handoff data
+ */
+function parseHandoffFields(content) {
+  const result = {
+    status: 'unknown',
+    score: null,
+    summary: '',
+    outputs: [],
+    decisions: {},
+    blockers: [],
+    needs_input_question: null,
+  };
+
+  const lines = content.split('\n');
+  let currentKey = null;
+  let currentType = null; // 'list' | 'map'
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Check if this is a list item (  - value)
+    const listMatch = trimmed.match(/^-\s+(.+)/);
+    if (listMatch && currentKey && currentType === 'list') {
+      if (Array.isArray(result[currentKey])) {
+        result[currentKey].push(listMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Check if this is a map item (  key: value) under a map key
+    const mapMatch = trimmed.match(/^(\w[\w_-]*):\s+(.+)/);
+    if (mapMatch && currentKey && currentType === 'map') {
+      if (typeof result[currentKey] === 'object' && !Array.isArray(result[currentKey])) {
+        result[currentKey][mapMatch[1]] = mapMatch[2].trim();
+      }
+      continue;
+    }
+
+    // Top-level key: value
+    const kvMatch = trimmed.match(/^(\w[\w_-]*):\s*(.*)/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim();
+
+      // Known list keys
+      if (['outputs', 'blockers'].includes(key)) {
+        currentKey = key;
+        currentType = 'list';
+        // If value is inline (not empty), treat as single item
+        if (value && value !== '') {
+          result[key] = [value];
+          currentKey = null;
+          currentType = null;
+        }
+        continue;
+      }
+
+      // Known map keys
+      if (['decisions'].includes(key)) {
+        currentKey = key;
+        currentType = 'map';
+        continue;
+      }
+
+      // Scalar keys
+      currentKey = null;
+      currentType = null;
+
+      if (key === 'status') {
+        result.status = value || 'unknown';
+      } else if (key === 'score') {
+        const num = parseInt(value, 10);
+        result.score = isNaN(num) ? null : num;
+      } else if (key === 'summary') {
+        result.summary = value || '';
+      } else if (key === 'needs_input_question') {
+        result.needs_input_question = value === 'null' || value === '' ? null : value;
+      }
+    }
+  }
+
+  return result;
+}

package/src/terminal/index.js

@@ -28,3 +28,12 @@ export {
   getReadScope,
   buildIsolationEnv,
 } from './isolation.js';
+
+export {
+  buildAgentPrompt,
+  AGENT_FILE_MAP,
+} from './prompt-builder.js';
+
+export {
+  parseAgentOutput,
+} from './handoff-parser.js';

package/src/terminal/prompt-builder.js

@@ -0,0 +1,313 @@
+/**
+ * @fileoverview Prompt builder for multi-terminal agent execution.
+ *
+ * Builds a complete, self-contained prompt for spawned agent terminals.
+ * When an agent runs in a separate `claude -p` process, it has zero
+ * conversation history — the prompt must contain everything: PRISM
+ * context, agent definition, previous handoff, write scope, and
+ * output format instructions.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { runPrism } from '../context/engine.js';
+import { loadHandoff, formatHandoff } from '../tasks/handoff.js';
+import { getWriteScope } from './isolation.js';
+
+// Re-read at import time so the prompt builder always uses the correct map
+// without circular dependency issues (the hook file runs main() on import
+// which writes to stdout — we only need the data, so we inline the map).
+const AGENT_MODELS = {
+  orchestrator: 'sonnet',
+  'greenfield-wu': 'haiku',
+  'brownfield-wu': 'opus',
+  brief: 'sonnet',
+  detail: 'opus',
+  architect: 'opus',
+  ux: 'sonnet',
+  phases: 'sonnet',
+  tasks: 'sonnet',
+  'qa-planning': 'opus',
+  'qa-implementation': 'opus',
+  dev: 'opus',
+  devops: 'sonnet',
+};
+
+/**
+ * Map of agent names to their definition file paths (relative to project root).
+ */
+export const AGENT_FILE_MAP = {
+  'greenfield-wu': 'chati.dev/agents/clarity/greenfield-wu.md',
+  'brownfield-wu': 'chati.dev/agents/clarity/brownfield-wu.md',
+  brief: 'chati.dev/agents/clarity/brief.md',
+  detail: 'chati.dev/agents/clarity/detail.md',
+  architect: 'chati.dev/agents/clarity/architect.md',
+  ux: 'chati.dev/agents/clarity/ux.md',
+  phases: 'chati.dev/agents/clarity/phases.md',
+  tasks: 'chati.dev/agents/clarity/tasks.md',
+  'qa-planning': 'chati.dev/agents/quality/qa-planning.md',
+  dev: 'chati.dev/agents/build/dev.md',
+  'qa-implementation': 'chati.dev/agents/quality/qa-implementation.md',
+  devops: 'chati.dev/agents/deploy/devops.md',
+};
+
+/**
+ * @typedef {object} PromptBuildConfig
+ * @property {string} agent           - Agent name (e.g. 'detail')
+ * @property {string} taskId          - Task identifier
+ * @property {string} projectDir      - Project root (absolute path)
+ * @property {string} [previousAgent] - Agent that produced the handoff
+ * @property {string} [workflow]      - Active workflow name
+ * @property {object} [sessionState]  - Parsed session.yaml fields
+ * @property {string[]} [writeScope]  - Override write scope
+ * @property {string} [additionalContext] - Extra context (e.g. user answer to needs_input)
+ */
+
+/**
+ * Build a complete, self-contained prompt for a spawned agent terminal.
+ *
+ * @param {PromptBuildConfig} config
+ * @returns {{ prompt: string, model: string, metadata: { agent: string, layers: number, promptSize: number } }}
+ */
+export function buildAgentPrompt(config) {
+  if (!config || !config.agent) {
+    throw new Error('buildAgentPrompt requires config.agent');
+  }
+  if (!config.projectDir) {
+    throw new Error('buildAgentPrompt requires config.projectDir');
+  }
+
+  const sections = [];
+
+  // 1. PRISM Context (L0-L4) — spawned terminals always start FRESH
+  const prismResult = buildPrismSection(config);
+  if (prismResult.xml) {
+    sections.push(prismResult.xml);
+  }
+
+  // 2. Agent definition (.md file)
+  const agentDef = loadAgentDefinition(config.agent, config.projectDir);
+  if (agentDef) {
+    sections.push('<!-- AGENT DEFINITION -->\n' + agentDef);
+  }
+
+  // 3. Previous handoff
+  const handoffSection = buildHandoffSection(config);
+  if (handoffSection) {
+    sections.push(handoffSection);
+  }
+
+  // 4. Additional context (user input relay for needs_input)
+  if (config.additionalContext) {
+    sections.push(
+      '<!-- ADDITIONAL CONTEXT -->\n' +
+      '## Additional Context from User\n\n' +
+      config.additionalContext
+    );
+  }
+
+  // 5. Write scope instructions
+  sections.push(buildWriteScopeSection(config));
+
+  // 6. Session context
+  sections.push(buildSessionSection(config));
+
+  // 7. Output format instructions (handoff template)
+  sections.push(buildOutputInstructions());
+
+  const prompt = sections.join('\n\n---\n\n');
+  const model = AGENT_MODELS[config.agent] || 'sonnet';
+
+  return {
+    prompt,
+    model,
+    metadata: {
+      agent: config.agent,
+      layers: prismResult.layerCount || 0,
+      promptSize: prompt.length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the PRISM context engine for the agent.
+ * Spawned terminals always start FRESH (remainingPercent: 100).
+ */
+function buildPrismSection(config) {
+  const domainsDir = join(config.projectDir, 'chati.dev', 'domains');
+
+  if (!existsSync(domainsDir)) {
+    return { xml: null, layerCount: 0 };
+  }
+
+  const state = config.sessionState || {};
+
+  // Load handoff data for PRISM L3
+  let handoff = {};
+  if (config.previousAgent) {
+    const loaded = loadHandoff(config.projectDir, config.previousAgent);
+    if (loaded.loaded && loaded.handoff) {
+      handoff = loaded.handoff;
+    }
+  }
+
+  const result = runPrism({
+    domainsDir,
+    remainingPercent: 100, // Spawned terminals are always FRESH
+    mode: state.project?.state || 'clarity',
+    agent: config.agent,
+    workflow: config.workflow || null,
+    pipelinePosition: config.agent,
+    taskId: config.taskId || null,
+    handoff,
+    artifacts: state.artifacts || [],
+    taskCriteria: [],
+  });
+
+  return {
+    xml: result.xml || null,
+    layerCount: result.layerCount || 0,
+  };
+}
+
+/**
+ * Load the agent's full .md definition file.
+ */
+function loadAgentDefinition(agent, projectDir) {
+  const relativePath = AGENT_FILE_MAP[agent];
+  if (!relativePath) return null;
+
+  const fullPath = join(projectDir, relativePath);
+  if (!existsSync(fullPath)) return null;
+
+  return readFileSync(fullPath, 'utf-8');
+}
+
+/**
+ * Build the previous handoff section for the prompt.
+ */
+function buildHandoffSection(config) {
+  if (!config.previousAgent) return null;
+
+  const result = loadHandoff(config.projectDir, config.previousAgent);
+  if (!result.loaded || !result.handoff) return null;
+
+  return (
+    '<!-- PREVIOUS HANDOFF -->\n' +
+    `## Handoff from ${config.previousAgent}\n\n` +
+    formatHandoff({
+      from: {
+        agent: result.handoff.from_agent || config.previousAgent,
+        task_id: result.handoff.from_task || 'unknown',
+        phase: result.handoff.from_phase || 'unknown',
+      },
+      to: config.agent,
+      timestamp: result.handoff.timestamp || new Date().toISOString(),
+      status: result.handoff.status || 'unknown',
+      score: result.handoff.score,
+      summary: result.handoff.summary || '',
+      outputs: result.handoff.outputs || [],
+      decisions: result.handoff.decisions || {},
+      blockers: result.handoff.blockers || [],
+      criteria_met: result.handoff.criteria_met || [],
+      criteria_unmet: result.handoff.criteria_unmet || [],
+    })
+  );
+}
+
+/**
+ * Build write scope instructions embedded in the prompt.
+ * This is the primary enforcement mechanism — env vars alone are not
+ * respected by the spawned Claude process.
+ */
+function buildWriteScopeSection(config) {
+  const scope = config.writeScope || getWriteScope(config.agent);
+
+  if (scope.length === 0) {
+    return (
+      '<!-- WRITE SCOPE -->\n' +
+      '## Write Scope (MANDATORY)\n\n' +
+      'You have NO write access. This is a read-only execution.\n' +
+      'Do NOT use Write, Edit, or any file-modifying tool.'
+    );
+  }
+
+  const paths = scope.map(p => `- \`${p}\``).join('\n');
+
+  return (
+    '<!-- WRITE SCOPE -->\n' +
+    '## Write Scope (MANDATORY)\n\n' +
+    'You may ONLY write to these paths:\n' +
+    paths + '\n\n' +
+    '**All other write operations are BLOCKED.** Do NOT attempt to write, edit, or create files outside these paths. ' +
+    'Read access is unrestricted — you may read any file in the project.'
+  );
+}
+
+/**
+ * Build session context section.
+ */
+function buildSessionSection(config) {
+  const state = config.sessionState || {};
+  const project = state.project || {};
+
+  const lines = [
+    '<!-- SESSION CONTEXT -->',
+    '## Session Context',
+    '',
+    `- **Project**: ${project.name || '(unnamed)'}`,
+    `- **Type**: ${project.type || 'greenfield'}`,
+    `- **Mode**: ${project.state || 'clarity'}`,
+    `- **Language**: ${state.language || 'en'} (interaction) / English (artifacts)`,
+    `- **User Level**: ${state.user_level || 'auto'}`,
+    `- **Execution Mode**: ${state.execution_mode || 'autonomous'}`,
+    `- **Your Agent**: ${config.agent}`,
+    `- **Your Model**: ${AGENT_MODELS[config.agent] || 'sonnet'}`,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Build output format instructions so the agent produces a parseable handoff.
+ */
+function buildOutputInstructions() {
+  return `<!-- OUTPUT INSTRUCTIONS -->
+## Output Instructions (MANDATORY)
+
+When you complete your work, you MUST include a structured handoff block at the END of your response.
+This block is how the orchestrator reads your results. Without it, your work cannot be collected.
+
+\`\`\`
+<chati-handoff>
+status: complete
+score: 95
+summary: One to three sentence summary of what was accomplished.
+outputs:
+  - path/to/artifact1.md
+  - path/to/artifact2.md
+decisions:
+  key1: value1
+  key2: value2
+blockers:
+  - Description of any unresolved blocker
+needs_input_question: null
+</chati-handoff>
+\`\`\`
+
+### Status values:
+- **complete**: All work finished successfully (score >= 95 required)
+- **partial**: Some work done but not all criteria met
+- **needs_input**: You need information from the user to continue. Set \`needs_input_question\` to your question.
+- **error**: Something went wrong that you cannot recover from
+
+### Important:
+- The \`<chati-handoff>\` block MUST appear in your response
+- Score must be 0-100 (95+ to pass quality gate)
+- List ALL artifacts you created/modified in outputs
+- If you need user input, set status to "needs_input" and write your question in needs_input_question`;
+}

package/src/terminal/run-agent.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * CLI runner for single-agent terminal execution.
+ *
+ * Called by the orchestrator via the Bash tool to spawn an agent
+ * in a separate Claude Code process with the correct model.
+ *
+ * Usage:
+ *   node run-agent.js --agent detail --task-id expand-prd \
+ *     --project-dir /path/to/project --previous-agent brief \
+ *     --timeout 600000
+ *
+ * Outputs JSON to stdout for the orchestrator to parse.
+ */
+
+import { fileURLToPath } from 'url';
+import { buildAgentPrompt } from './prompt-builder.js';
+import { spawnTerminal } from './spawner.js';
+import { parseAgentOutput } from './handoff-parser.js';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing (no external deps)
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = 'true';
+      }
+    }
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  // Validate required args
+  if (!args.agent) {
+    outputError('Missing required argument: --agent');
+    process.exit(1);
+  }
+  if (!args['task-id']) {
+    outputError('Missing required argument: --task-id');
+    process.exit(1);
+  }
+
+  const projectDir = args['project-dir'] || process.cwd();
+  const timeout = parseInt(args.timeout, 10) || 600_000; // default 10 minutes
+
+  // Load session state if available
+  let sessionState = {};
+  try {
+    const { existsSync, readFileSync } = await import('fs');
+    const { join } = await import('path');
+    const sessionPath = join(projectDir, '.chati', 'session.yaml');
+    if (existsSync(sessionPath)) {
+      const raw = readFileSync(sessionPath, 'utf-8');
+      sessionState = parseSimpleYaml(raw);
+    }
+  } catch {
+    // Session state is optional — continue without it
+  }
+
+  // Build the agent prompt
+  let promptResult;
+  try {
+    promptResult = buildAgentPrompt({
+      agent: args.agent,
+      taskId: args['task-id'],
+      projectDir,
+      previousAgent: args['previous-agent'] || null,
+      workflow: args.workflow || null,
+      sessionState,
+      additionalContext: args['additional-context'] || null,
+    });
+  } catch (err) {
+    outputError(`Failed to build prompt: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Spawn the agent terminal
+  const startTime = Date.now();
+  let handle;
+
+  try {
+    handle = spawnTerminal({
+      agent: args.agent,
+      taskId: args['task-id'],
+      model: promptResult.model,
+      prompt: promptResult.prompt,
+      workingDir: projectDir,
+      timeout,
+    });
+  } catch (err) {
+    outputError(`Failed to spawn terminal: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Wait for the process to complete
+  try {
+    await waitForExit(handle, timeout);
+  } catch (err) {
+    outputError(`Terminal execution failed: ${err.message}`);
+    process.exit(2);
+  }
+
+  const elapsed = Date.now() - startTime;
+  const stdout = handle.stdout.join('');
+  const stderr = handle.stderr.join('');
+
+  // Parse the handoff from stdout
+  const parsed = parseAgentOutput(stdout);
+
+  if (parsed.found) {
+    outputResult({
+      status: parsed.handoff.status,
+      agent: args.agent,
+      model: promptResult.model,
+      exitCode: handle.exitCode,
+      handoff: parsed.handoff,
+      elapsed,
+    });
+  } else {
+    // No handoff block found — return raw output
+    outputResult({
+      status: handle.exitCode === 0 ? 'partial' : 'error',
+      agent: args.agent,
+      model: promptResult.model,
+      exitCode: handle.exitCode,
+      handoff: null,
+      rawOutput: stdout.slice(0, 5000), // Truncate to avoid huge JSON
+      stderr: stderr.slice(0, 2000),
+      elapsed,
+    });
+  }
+
+  process.exit(handle.exitCode === 0 ? 0 : 1);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for a terminal handle's process to exit.
+ */
+function waitForExit(handle, timeout) {
+  return new Promise((resolve, reject) => {
+    if (handle.status === 'exited') {
+      return resolve();
+    }
+
+    const timer = setTimeout(() => {
+      if (handle.process && typeof handle.process.kill === 'function') {
+        try { handle.process.kill('SIGKILL'); } catch { /* ignore */ }
+      }
+      handle.status = 'exited';
+      handle.exitCode = -2;
+      reject(new Error(`Terminal timed out after ${Math.round(timeout / 1000)}s`));
+    }, timeout);
+
+    handle.process.once('exit', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+
+    handle.process.once('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Output a structured JSON result to stdout.
+ */
+function outputResult(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Output an error as JSON to stdout (so orchestrator can parse it).
+ */
+function outputError(message) {
+  process.stdout.write(JSON.stringify({ status: 'error', error: message }) + '\n');
+}
+
+/**
+ * Minimal YAML parser for session.yaml (handles flat and one-level nested keys).
+ */
+function parseSimpleYaml(content) {
+  const result = {};
+  let currentSection = null;
+
+  for (const line of content.split('\n')) {
+    if (line.trim() === '' || line.trim().startsWith('#')) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+    const kvMatch = trimmed.match(/^([\w_-]+):\s*(.*)/);
+
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim().replace(/^["']|["']$/g, '');
+
+      if (indent === 0) {
+        if (value === '' || value === undefined) {
+          // Section header
+          currentSection = key;
+          result[key] = result[key] || {};
+        } else {
+          result[key] = value;
+          currentSection = null;
+        }
+      } else if (currentSection && indent > 0) {
+        if (typeof result[currentSection] !== 'object') {
+          result[currentSection] = {};
+        }
+        result[currentSection][key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+// Guard pattern (per project convention)
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    outputError(err.message);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, waitForExit, parseSimpleYaml };

package/src/terminal/run-parallel.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * CLI runner for parallel agent terminal execution.
+ *
+ * Called by the orchestrator via the Bash tool to spawn multiple agents
+ * simultaneously in separate Claude Code processes.
+ *
+ * Usage:
+ *   node run-parallel.js --agents detail,architect,ux \
+ *     --task-ids expand-prd,architect-design,ux-wireframe \
+ *     --project-dir /path/to/project --previous-agent brief \
+ *     --timeout 900000
+ *
+ * Outputs consolidated JSON to stdout for the orchestrator to parse.
+ */
+
+import { fileURLToPath } from 'url';
+import { buildAgentPrompt } from './prompt-builder.js';
+import { spawnParallelGroup } from './spawner.js';
+import { TerminalMonitor } from './monitor.js';
+import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
+import { parseAgentOutput } from './handoff-parser.js';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = 'true';
+      }
+    }
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (!args.agents) {
+    outputError('Missing required argument: --agents (comma-separated)');
+    process.exit(1);
+  }
+  if (!args['task-ids']) {
+    outputError('Missing required argument: --task-ids (comma-separated)');
+    process.exit(1);
+  }
+
+  const agents = args.agents.split(',').map(s => s.trim());
+  const taskIds = args['task-ids'].split(',').map(s => s.trim());
+
+  if (agents.length !== taskIds.length) {
+    outputError(`Agent count (${agents.length}) must match task-id count (${taskIds.length})`);
+    process.exit(1);
+  }
+
+  const projectDir = args['project-dir'] || process.cwd();
+  const previousAgent = args['previous-agent'] || null;
+  const timeout = parseInt(args.timeout, 10) || 900_000; // default 15 minutes
+
+  // Load session state
+  let sessionState = {};
+  try {
+    const { existsSync, readFileSync } = await import('fs');
+    const { join } = await import('path');
+    const sessionPath = join(projectDir, '.chati', 'session.yaml');
+    if (existsSync(sessionPath)) {
+      const raw = readFileSync(sessionPath, 'utf-8');
+      // Minimal parse
+      sessionState = {};
+      for (const line of raw.split('\n')) {
+        const m = line.trim().match(/^([\w_-]+):\s*(.+)/);
+        if (m) sessionState[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+      }
+    }
+  } catch { /* optional */ }
+
+  // Build prompts for all agents
+  const configs = [];
+  const startTime = Date.now();
+
+  for (let i = 0; i < agents.length; i++) {
+    try {
+      const promptResult = buildAgentPrompt({
+        agent: agents[i],
+        taskId: taskIds[i],
+        projectDir,
+        previousAgent,
+        sessionState,
+      });
+
+      configs.push({
+        agent: agents[i],
+        taskId: taskIds[i],
+        model: promptResult.model,
+        prompt: promptResult.prompt,
+        workingDir: projectDir,
+        timeout,
+      });
+    } catch (err) {
+      outputError(`Failed to build prompt for ${agents[i]}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Spawn all terminals in parallel
+  let group;
+  try {
+    group = spawnParallelGroup(configs);
+  } catch (err) {
+    outputError(`Failed to spawn parallel group: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Monitor until completion
+  const monitor = new TerminalMonitor({ pollInterval: 2000, timeout });
+
+  for (const terminal of group.terminals) {
+    monitor.addTerminal(terminal);
+  }
+
+  await new Promise((resolve) => {
+    monitor.onComplete(() => {
+      monitor.stopMonitoring();
+      resolve();
+    });
+
+    // Safety timeout
+    const safetyTimer = setTimeout(() => {
+      monitor.stopMonitoring();
+      resolve();
+    }, timeout + 10_000);
+
+    monitor.onComplete(() => clearTimeout(safetyTimer));
+    monitor.startMonitoring();
+  });
+
+  const elapsed = Date.now() - startTime;
+
+  // Collect and merge results
+  const rawResults = collectResults(group.groupId, group.terminals);
+
+  // Parse handoffs from each terminal's stdout
+  const agentResults = rawResults.results.map(r => {
+    const parsed = parseAgentOutput(r.stdout);
+    return {
+      ...r,
+      handoff: parsed.found ? parsed.handoff : null,
+      handoffFound: parsed.found,
+    };
+  });
+
+  // Merge handoffs
+  const mergeInput = agentResults.map(r => ({
+    agent: r.agent,
+    status: r.handoff?.status || (r.exitCode === 0 ? 'complete' : 'failed'),
+    outputs: r.handoff?.outputs || [],
+    decisions: r.handoff?.decisions || {},
+    blockers: r.handoff?.blockers || [],
+    summary: r.handoff?.summary || '',
+  }));
+
+  const merged = mergeHandoffs(mergeInput);
+  const nextAgent = determineNextAgent(agents);
+  const consolidated = buildConsolidatedHandoff(merged, nextAgent);
+
+  // Output consolidated result
+  const output = {
+    status: rawResults.summary.failed === 0 ? 'complete' : 'partial',
+    groupId: group.groupId,
+    agents: agents.map((a, i) => ({
+      agent: a,
+      model: configs[i].model,
+      status: agentResults[i].handoff?.status || (agentResults[i].exitCode === 0 ? 'complete' : 'failed'),
+      score: agentResults[i].handoff?.score || null,
+      exitCode: agentResults[i].exitCode,
+      handoffFound: agentResults[i].handoffFound,
+    })),
+    mergedHandoff: consolidated,
+    summary: rawResults.summary,
+    elapsed,
+    performance: {
+      sequentialEstimate: elapsed * agents.length,
+      parallelActual: elapsed,
+      timeSaved: elapsed * (agents.length - 1),
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+  process.exit(rawResults.summary.failed > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine the next sequential agent after a parallel group.
+ * GROUP 1 (detail+architect+ux) → phases
+ * GROUP 2 (dev tasks) → qa-implementation
+ */
+function determineNextAgent(agents) {
+  const groupKey = agents.sort().join(',');
+  if (groupKey.includes('architect') && groupKey.includes('detail') && groupKey.includes('ux')) {
+    return 'phases';
+  }
+  if (agents.every(a => a === 'dev')) {
+    return 'qa-implementation';
+  }
+  return null;
+}
+
+function outputError(message) {
+  process.stdout.write(JSON.stringify({ status: 'error', error: message }) + '\n');
+}
+
+// Guard pattern
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    outputError(err.message);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, determineNextAgent };

package/src/terminal/spawner.js

@@ -40,8 +40,10 @@ export function _resetCounter() {
 
 /**
  * @typedef {object} SpawnConfig
- * @property {string} agent       - Agent name (e.g. "architect")
- * @property {string} taskId      - Task identifier
+ * @property {string} agent           - Agent name (e.g. "architect")
+ * @property {string} taskId          - Task identifier
+ * @property {string} [model]         - LLM model (haiku/sonnet/opus)
+ * @property {string} [prompt]        - Full prompt string (from prompt-builder, piped via stdin)
  * @property {object} [contextPayload] - Context to inject via env var
  * @property {string[]} [writeScope]   - Override write scope
  * @property {string} [workingDir]     - Working directory for the process
@@ -54,6 +56,7 @@ export function _resetCounter() {
  * @property {object|null} process - child_process.ChildProcess (null when dry)
  * @property {string} agent      - Agent name
  * @property {string} taskId     - Task identifier
+ * @property {string} model      - Model used for this terminal
  * @property {string} startedAt  - ISO timestamp
  * @property {string} status     - "running" | "exited" | "killed"
  * @property {number|null} exitCode - Process exit code (null while running)
@@ -68,7 +71,7 @@ export function _resetCounter() {
  * perform any I/O and is therefore fully testable in isolation.
  *
  * @param {SpawnConfig} config
- * @returns {{ command: string, args: string[], env: Record<string, string> }}
+ * @returns {{ command: string, args: string[], env: Record<string, string>, terminalId: string, prompt: string|null }}
  */
 export function buildSpawnCommand(config) {
   if (!config || typeof config !== 'object') {
@@ -89,6 +92,7 @@ export function buildSpawnCommand(config) {
     CHATI_TERMINAL_ID: terminalId,
     CHATI_AGENT: config.agent,
     CHATI_TASK_ID: config.taskId,
+    CHATI_SPAWNED: 'true',
   };
 
   if (config.contextPayload) {
@@ -99,19 +103,18 @@ export function buildSpawnCommand(config) {
     }
   }
 
-  // Build the prompt that will be sent to claude CLI
-  const prompt = `Execute task ${config.taskId} as agent ${config.agent}. ` +
-    `Write scope: ${isolationEnv.CHATI_WRITE_SCOPE || 'none'}. ` +
-    `Terminal ID: ${terminalId}.`;
-
+  // Build CLI args — prompt is piped via stdin, NOT as a CLI argument
   const command = 'claude';
-  const args = [
-    '--print',
-    '--dangerously-skip-permissions',
-    prompt,
-  ];
+  const args = ['--print', '--dangerously-skip-permissions'];
+
+  if (config.model) {
+    args.push('--model', config.model);
+  }
 
-  return { command, args, env, terminalId };
+  // Prompt is returned separately for stdin piping (avoids ARG_MAX limits)
+  const prompt = config.prompt || null;
+
+  return { command, args, env, terminalId, prompt };
 }
 
 /**
@@ -121,7 +124,7 @@ export function buildSpawnCommand(config) {
  * @returns {TerminalHandle}
  */
 export function spawnTerminal(config) {
-  const { command, args, env, terminalId } = buildSpawnCommand(config);
+  const { command, args, env, terminalId, prompt } = buildSpawnCommand(config);
 
   const cwd = config.workingDir || process.cwd();
   const timeout = config.timeout || 300_000; // default 5 minutes
@@ -129,15 +132,22 @@ export function spawnTerminal(config) {
   const child = spawn(command, args, {
     cwd,
     env: { ...process.env, ...env },
-    stdio: ['ignore', 'pipe', 'pipe'],
+    stdio: ['pipe', 'pipe', 'pipe'],
   });
 
+  // Pipe prompt via stdin (avoids shell argument length limits)
+  if (prompt) {
+    child.stdin.write(prompt);
+  }
+  child.stdin.end();
+
   /** @type {TerminalHandle} */
   const handle = {
     id: terminalId,
     process: child,
     agent: config.agent,
     taskId: config.taskId,
+    model: config.model || 'sonnet',
     startedAt: new Date().toISOString(),
     status: 'running',
     exitCode: null,
@@ -250,11 +260,11 @@ export function killTerminal(handle) {
  * Return the current status snapshot of a terminal.
  *
  * @param {TerminalHandle} handle
- * @returns {{ id: string, agent: string, status: string, elapsed: number, exitCode: number|null }}
+ * @returns {{ id: string, agent: string, model: string, status: string, elapsed: number, exitCode: number|null }}
  */
 export function getTerminalStatus(handle) {
   if (!handle) {
-    return { id: 'unknown', agent: 'unknown', status: 'unknown', elapsed: 0, exitCode: null };
+    return { id: 'unknown', agent: 'unknown', model: 'unknown', status: 'unknown', elapsed: 0, exitCode: null };
   }
 
   const elapsed = Date.now() - new Date(handle.startedAt).getTime();
@@ -262,6 +272,7 @@ export function getTerminalStatus(handle) {
   return {
     id: handle.id,
     agent: handle.agent,
+    model: handle.model || 'unknown',
     status: handle.status,
     elapsed,
     exitCode: handle.exitCode,