chati-dev 4.2.1 → 4.2.2

package/framework/hooks/model-governance.js

@@ -80,24 +80,34 @@ async function main() {
       const assignment = AGENT_MODELS[agent];
       const expected = assignment.model || assignment;
       const provider = assignment.provider || 'claude';
-      // Advisory note — appended to context
+      // Advisory context injection via canonical UserPromptSubmit schema.
       process.stdout.write(JSON.stringify({
-        result: 'allow',
-        prefix: `<!-- [Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider}) -->`,
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: `[Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider})`,
+        },
       }));
     } else {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write('{}');
     }
   } catch (err) {
     process.stderr.write(`[chati] model-governance: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write('{}');
   }
 }
 
 export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/framework/hooks/prism-engine.js

@@ -65,8 +65,8 @@ async function main() {
     const session = readSessionState(projectDir);
 
     if (!session) {
-      // No active session — don't inject anything
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      // No active session — don't inject anything (empty output = allow)
+      process.stdout.write('{}');
       return;
     }
 
@@ -163,13 +163,19 @@ async function main() {
       '</chati-context>',
     ].filter(Boolean).join('\n');
 
+    // UserPromptSubmit context injection schema:
+    // hookSpecificOutput.additionalContext is the canonical field for
+    // injecting text into Claude's view of the current prompt.
     process.stdout.write(JSON.stringify({
-      result: 'allow',
-      prefix: contextBlock,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: contextBlock,
+      },
     }));
   } catch (err) {
     process.stderr.write(`[chati] prism-engine: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    // Silent allow on error — empty object = no injection, no block.
+    process.stdout.write('{}');
   }
 }
 
@@ -201,8 +207,16 @@ function detectFrustration(prompt) {
 
 export { readSessionState, detectFrustration };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/read-protection.js

@@ -93,24 +93,52 @@ async function main() {
     const result = isSensitivePath(filePath, cwd);
 
     if (result.sensitive) {
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Article IV] ${result.reason}. Use environment variables or secure vaults instead of reading sensitive files directly.`,
-      }));
+      process.stdout.write(JSON.stringify(denyOutput(
+        `[Article IV] ${result.reason}. Use environment variables or secure vaults instead of reading sensitive files directly.`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] read-protection: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Fail-open: a broken hook should not prevent reads. Real protection
+    // patterns are explicit above and run before this catch.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 export { isSensitivePath, SENSITIVE_PATTERNS, ALLOWED_EXCEPTIONS };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/session-digest.js

@@ -115,7 +115,9 @@ async function main() {
         process.stderr.write(`[chati] session-digest daily-append: ${err.message}\n`);
       }
 
-      // Auto memory consolidation: trigger when memories accumulate
+      // Auto memory consolidation: trigger when memories accumulate.
+      // CRITICAL: must be fully async (detached spawn) — PreCompact runs on the
+      // hot path and execSync would add up to 10s of latency to every compact.
       try {
         const memBase = join(projectDir, '.chati', 'memories');
         if (existsSync(memBase)) {
@@ -132,16 +134,19 @@ async function main() {
           // Consolidate when > 100 entries (50% of 200 cap)
           if (totalEntries > 100) {
             process.stderr.write(`[chati] auto-dream: ${totalEntries} entries, triggering consolidation\n`);
-            // Fire-and-forget: consolidation runs in background
-            // Import would fail in hook context, so we spawn a child process
-            const { execSync } = await import('child_process');
+            // Fire-and-forget detached spawn — returns immediately, child outlives parent.
+            const { spawn } = await import('child_process');
             try {
-              execSync(`node -e "import('./packages/chati-dev/src/memory/dream.js').then(m => m.runDreamConsolidation('${projectDir.replace(/'/g, "\\'")}'))"`, {
+              const child = spawn('node', [
+                '-e',
+                `import('./packages/chati-dev/src/memory/dream.js').then(m => m.runDreamConsolidation(${JSON.stringify(projectDir)}))`,
+              ], {
                 cwd: projectDir,
-                timeout: 10000,
+                detached: true,
                 stdio: 'ignore',
               });
-            } catch { /* expected: consolidation may timeout or fail */ }
+              child.unref();
+            } catch { /* expected: spawn may fail in restricted env */ }
           }
         }
       } catch (err) {
@@ -149,8 +154,9 @@ async function main() {
       }
     }
 
-    // Session telemetry ping (moved from license-guard to reduce per-prompt overhead)
-    // 5-minute throttle with phase/agent change detection
+    // Session telemetry ping (owned by session-digest, was moved here from license-guard).
+    // 5-minute throttle with phase/agent change detection.
+    // Pings.yaml format: '/path/to/project': '<ISO8601>|<phase>|<agent>'
     try {
       const homedir = process.env.HOME || '';
       const pingsPath = join(homedir, '.chati-dev', 'pings.yaml');
@@ -163,15 +169,17 @@ async function main() {
 
         if (licenseKey && digest) {
           let shouldPing = false;
-          const now = Date.now();
+          const nowIso = new Date().toISOString();
           const currentState = `${digest.mode}|${digest.currentAgent}`;
 
           if (existsSync(pingsPath)) {
             const pingsRaw = readFileSync(pingsPath, 'utf-8');
-            const entryMatch = pingsRaw.match(new RegExp(`${projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*?'([^']+)'`));
+            const escaped = projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const entryMatch = pingsRaw.match(new RegExp(`^${escaped}:\\s*'([^']+)'`, 'm'));
             if (entryMatch) {
               const [ts, phase, agent] = entryMatch[1].split('|');
-              const elapsed = now - parseInt(ts);
+              const lastTime = new Date(ts).getTime();
+              const elapsed = isNaN(lastTime) ? Infinity : Date.now() - lastTime;
               const stateChanged = `${phase}|${agent}` !== currentState;
               shouldPing = elapsed > 300000 || stateChanged; // 5 min or state change
             } else {
@@ -182,16 +190,24 @@ async function main() {
           }
 
           if (shouldPing) {
-            // Update ping timestamp
+            // Update ping entry — preserve other projects in the file.
             mkdirSync(join(homedir, '.chati-dev'), { recursive: true });
-            writeFileSync(pingsPath, `'${projectDir}': '${now}|${currentState}'\n`, 'utf-8');
+            const newEntry = `${projectDir}: '${nowIso}|${currentState}'\n`;
+            let content = existsSync(pingsPath) ? readFileSync(pingsPath, 'utf-8') : '';
+            const escaped = projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            if (new RegExp(`^${escaped}:`, 'm').test(content)) {
+              content = content.replace(new RegExp(`^${escaped}:.*$`, 'm'), newEntry.trim());
+            } else {
+              content += newEntry;
+            }
+            writeFileSync(pingsPath, content, 'utf-8');
 
             // Fire-and-forget telemetry (3s timeout, never blocks)
             try {
               const body = JSON.stringify({
                 license_key: licenseKey,
                 project_name: digest.currentAgent || 'unknown',
-                events: [{ type: 'session_active', timestamp: new Date().toISOString(), properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
+                events: [{ type: 'session_active', timestamp: nowIso, properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
               });
               fetch('https://chati.dev/api/telemetry', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(3000) }).catch(() => {});
             } catch { /* expected: network may be unavailable */ }
@@ -202,15 +218,24 @@ async function main() {
       process.stderr.write(`[chati] session-digest telemetry-ping: ${err.message}\n`);
     }
 
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    // PreCompact is observational only — empty output is the canonical "no-op".
+    process.stdout.write('{}');
   } catch (err) {
     process.stderr.write(`[chati] session-digest: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write('{}');
   }
 }
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/style-guard.js

@@ -97,7 +97,7 @@ async function main() {
     // Skip exempt paths
     const filePath = toolInput.file_path || '';
     if (isExemptPath(filePath, projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -112,24 +112,44 @@ async function main() {
     }
 
     if (result.violations.length > 0) {
-      // Block all style violations — agent must rewrite
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Style Guard] ${result.violations.join(' ')} Rewrite without em-dashes and emojis.`,
-      }));
+      // Advisory: surface as reason but allow. Style is a soft preference,
+      // not a security boundary — hard-blocking blocks legitimate markdown.
+      process.stdout.write(JSON.stringify(allowOutput(
+        `[Style Guard] ${result.violations.join(' ')} Consider rewriting without em-dashes and emojis (Article V).`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati] style-guard: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
 export { checkStyle, checkBashStyle, isExemptPath, EM_DASH_PATTERN, EMOJI_PATTERN };
 
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/team-quality-gate.js

@@ -79,7 +79,7 @@ async function main() {
     // Quick exit: no team active → allow everything
     const teamId = process.env.CHATI_TEAM_ID;
     if (!teamId) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -87,14 +87,14 @@ async function main() {
     const currentAgent = process.env.CHATI_TEAM_MEMBER || detectAgentFromSession(projectDir);
     if (!currentAgent) {
       // Cannot determine agent → allow (fail-open for safety)
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     // Get the file path being written
     const filePath = event.tool_input?.file_path || '';
     if (!filePath) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -103,7 +103,7 @@ async function main() {
 
     // Check shared paths first — always allowed
     if (SHARED_PATHS.some(sp => relativePath.startsWith(sp))) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -112,24 +112,42 @@ async function main() {
       if (agent === currentAgent) continue;
       for (const scope of scopes) {
         if (relativePath.startsWith(scope) || (!scope.includes('/') && relativePath.endsWith(scope))) {
-          process.stdout.write(JSON.stringify({
-            result: 'block',
-            reason: `[Team Quality Gate] ${currentAgent} cannot write to ${relativePath} — this path belongs to ${agent}. Use the team mailbox to coordinate changes (Article XXI).`,
-          }));
+          process.stdout.write(JSON.stringify(denyOutput(
+            `[Team Quality Gate] ${currentAgent} cannot write to ${relativePath} — this path belongs to ${agent}. Use the team mailbox to coordinate changes (Article XXI).`
+          )));
           return;
         }
       }
     }
 
     // Path not owned by anyone specific → allow
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     // Fail-open: hook errors should not block execution
     process.stderr.write(`[chati] team-quality-gate: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 function detectAgentFromSession(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -138,8 +156,16 @@ function detectAgentFromSession(projectDir) {
   return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
 }
 
-// Only run main when executed directly
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/undercover-guard.js

@@ -173,14 +173,14 @@ async function main() {
 
     // Check if undercover mode is enabled
     if (!isUndercoverEnabled(projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     // Skip framework-internal files
     const filePath = toolInput.file_path || '';
     if (isExemptPath(filePath, projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -196,25 +196,44 @@ async function main() {
 
     if (scan.found) {
       const terms = scan.matches.map(m => `"${m.term}" → "${m.replacement}"`).join(', ');
-      process.stdout.write(JSON.stringify({
-        decision: 'allow',  // Advisory — don't block, just warn
-        reason: `[Undercover] Internal references detected in output: ${terms}. Please sanitize before shipping to production. Replace internal terms with their generic equivalents.`,
-      }));
+      // Advisory only — surface findings as reason, allow operation.
+      process.stdout.write(JSON.stringify(allowOutput(
+        `[Undercover] Internal references detected: ${terms}. Sanitize before shipping. Replace internal terms with their generic equivalents.`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] undercover-guard: ${err?.message || 'unknown'}\n`);
     // Fail-open: undercover is advisory, not security-critical
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
 export { scanForInternals, scanBashForInternals, isExemptPath, isUndercoverEnabled, UNDERCOVER_RULES };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/orchestrator/chati.md

@@ -83,13 +83,20 @@ Parse the JSON output. The `action` field tells you what to do:
 | `complete` | Action: Complete |
 | `error` | Display error, suggest `/chati status` |
 
-**After every action**, display context bracket from JSON `context_bracket`:
-```
-FRESH    → "Context: FRESH ({remaining}%) — Proceeding to {agent}"
-MODERATE → "Context: MODERATE ({remaining}%) — Proceeding (context layers reduced)"
-DEPLETED → "Context: DEPLETED ({remaining}%) — Warning: context running low"
-CRITICAL → "Context: CRITICAL ({remaining}%) — Initiating handoff protocol"
-```
+**Internal: track context bracket from JSON `context_bracket` but DO NOT display it to the user.** The bracket is internal telemetry — users should never see "Context: FRESH (90%)" or framework jargon like "Initiating handoff protocol". Speak in natural language about what you are doing, not the internal state.
+
+Only mention the bracket when it reaches CRITICAL, and only in plain language. Example: "I'm running low on memory — let me wrap up the current step before continuing." Never say "CRITICAL bracket", "PRISM", "L0-L5", "deviation protocol", or other internal framework terms.
+
+**Never reveal agent technical names** to the user. Refer to phases naturally:
+- `greenfield-wu` / `brownfield-wu` → "let's understand your goals"
+- `brief` → "let's confirm what we're building"
+- `detail` → "let's expand the requirements"
+- `architect` → "let's design the architecture"
+- `ux` → "let's design the user experience"
+- `phases` / `tasks` → "let's break this down into phases"
+- `qa-planning` / `qa-implementation` → "let's review what we have"
+- `dev` → "let's build it"
+- `devops` → "let's deploy it"
 
 ---
 
@@ -135,11 +142,7 @@ The user should experience a smooth start: they describe their project, the orch
 
 These agents (greenfield-wu, brownfield-wu, brief) run in the same conversation.
 
-1. Display model recommendation from JSON `model_info`:
-   ```
-   Model recommendation for {agent}: {model} ({upgrade condition})
-   To switch: /model {model}
-   ```
+1. Track model recommendation from JSON `model_info` internally. Do NOT display "Model recommendation for {agent}" or expose internal agent names. If the recommended model is materially different from the current one and the difference will affect quality, mention it briefly in plain language: e.g., "This step works best on Opus — switch with /model opus if you want stronger reasoning." Otherwise stay silent.
 2. Read the agent file from `agent_file` in the JSON response
 3. Load its full content and **become** that agent
 4. Follow the agent's instructions — the user interacts with you directly
@@ -206,17 +209,17 @@ Quality gate passed: {score}%.
 
 These agents run in separate Claude Code processes.
 
-1. Display context bracket status from JSON
+1. Track context bracket internally — do NOT display it.
 2. Check `handoff_status.valid` from JSON:
-   - If `false` with missing fields:
+   - If `false` with missing fields, present user-facing options in plain language:
      ```
-     Context check: FAILED — missing: {missing_fields}
-     1. Re-run previous agent to regenerate handoff (Recommended)
-     2. Continue anyway (risk: missing context)
-     3. Manual context injection (provide missing info)
+     I noticed some context from the previous step is missing. How should I proceed?
+     1. Redo the previous step to regenerate the missing information (Recommended)
+     2. Continue anyway, with the missing context
+     3. Provide the missing details manually
      ```
-   - If warnings only: display warnings, proceed
-   - If `true`: display "Context check: OK — handoff verified"
+   - If warnings only: proceed silently. Only mention the warning if it directly affects what the user just asked for.
+   - If `true`: proceed silently. Do NOT announce "Context check: OK".
 3. Execute `spawn_command` via Bash tool (the full command is in the JSON)
 4. Wait for JSON output from the spawned process. Handle `status`:
    - `"complete"` → Present **Completion Options** (see above) → on approval, run `orchestrate advance --agent {name} --score {score}`
@@ -240,7 +243,7 @@ Planning phase agents (detail, architect, ux) run simultaneously.
 
 **NOTE (Article XXI):** When `features.agent_teams: true` in config.yaml, the orchestrator MUST attempt `spawn_team` FIRST for GROUP 1 agents (detail, architect, ux) and BUILD pair (dev, qa-implementation). Only fall back to `spawn_parallel` if team spawning is unavailable or fails. The CLI `orchestrate next` command handles this automatically — when teams are enabled, it returns `spawn_team` instead of `spawn_parallel`.
 
-1. Display: "Spawning parallel group: {agents}"
+1. Display naturally what is happening using user-facing language. Examples (pick one that fits the phase): "Working on the planning phase now." / "Reviewing the architecture and UX in parallel." NEVER say "spawning parallel group", "spawn_parallel", or list internal agent names like "detail, architect, ux".
 2. Execute `parallel_spawn_command` via Bash tool
 3. Parse consolidated JSON output
 4. Present **Completion Options** (Parallel Group variant) — wait for user choice
@@ -271,7 +274,7 @@ node packages/chati-dev/bin/chati.js orchestrate spawn-team --team-type {plannin
 ```
 Parse JSON. If `fallback_required: true` → fall back silently to `spawn_parallel`. Do NOT display error messages.
 
-Display: "Forming {team_type} team: {members}"
+Display naturally what the team is doing using user-facing language. For Planning Team: "Working on the planning — designing the requirements, architecture, and user experience together." For Build Team: "Building this with continuous quality review." NEVER say "team", "spawn_team", "Article XXI", "mailbox", "Planning Team", or list internal agent names.
 
 ### Step 2: Spawn Teammates via Agent Tool
 
@@ -413,13 +416,13 @@ If the Agent tool is unavailable or any sub-agent spawn fails:
 
 The user is returning to an active session.
 
-1. Present `status_summary` from JSON in the user's language
-2. Display context bracket
-3. Offer options:
+1. Present a natural-language summary of where we are in the user's language. Translate the internal `status_summary` into user-friendly terms — never say "qa-planning completed" or expose internal agent names.
+2. Track context bracket internally — do NOT display.
+3. Offer options in plain language (translate internal agent names to user-facing phase descriptions):
    ```
-   1. Continue with {next_agent} (Recommended)
-   2. Review last output
-   3. View full status (/chati status)
+   1. Continue (Recommended)
+   2. Review what we just produced
+   3. Show me the full project status
    ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {