chati-dev 4.2.1 → 4.2.2

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.2.1"
+version: "4.2.2"
 installed_at: "2026-02-07T10:00:00Z"
 updated_at: "2026-04-11T00:00:00Z"
-installer_version: "4.2.1"
+installer_version: "4.2.2"
 project_type: greenfield
 language: en
 ides: [claude-code]
@@ -54,7 +54,7 @@ features:
   frustration_detection: true       # Detect user frustration and adapt response style
   bash_security_checks: true        # 23-point shell injection defense system
   # Agent Teams (v4.2.0 — Article XXI)
-  agent_teams: false                  # Enable Claude Code native Agent Teams (requires claude provider)
+  agent_teams: true                   # Enable Claude Code native Agent Teams. Gated to claude provider; Gemini/Codex fall back silently.
   team_planning_size: 3               # Planning Team max teammates: detail + architect + ux
   team_build_size: 2                  # Build Team max teammates: dev + qa-implementation
   team_echo_threshold: 0.92           # Content similarity ratio to trigger Echo Detection (Article XXII)

package/framework/constitution.md

@@ -755,7 +755,8 @@ If any check is NO, the compliance block itself is an ERROR and the report canno
 
 ---
 
-*Chati.dev Constitution v4.2.1 — 22 Articles + Preamble*
+*Chati.dev Constitution v4.2.2 — 22 Articles + Preamble*
 *v4.2.0 Amendments: Article V amended (Team Communication); Article VIII amended (Team Handoff Envelope); Article XII amended (PRISM L6 Team Roster); Article XXI added (Agent Teams Governance); Article XXII added (Fault Vector Protocol)*
 *v4.2.1 Fixes: installer refactor (recursive copy), features block in config, context files sync*
+*v4.2.2 Fixes: 10 hooks rewritten to canonical hookSpecificOutput schema; .claude/settings.json now actually written by installer (CRITICAL — hooks were dormant before); license enforcement extended to Gemini and Codex per-turn; Agent Teams default ON; orchestrator jargon removed from user-facing output*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/context/root.md

@@ -1,11 +1,11 @@
 # Chati.dev System Context
 
 ## Framework
-- **Version**: 4.2.1
+- **Version**: 4.2.2
 - **Agents**: Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases
 - **Constitution**: 22 Articles + Preamble
 - **Quality**: 5 pipeline gates + 3-tier verdicts + Fault Vector Protocol (Article XXII)
-- **Agent Teams**: Native Claude Code teams with peer communication (Article XXI, feature-flagged)
+- **Agent Teams**: Native Claude Code teams with peer communication (Article XXI, default ON in v4.2.2 for Claude provider)
 
 ## Key References
 - **Session State**: `.chati/session.yaml` (runtime — not committed)

package/framework/hooks/constitution-guard.js

@@ -81,10 +81,9 @@ async function main() {
       const secrets = containsSecrets(content);
 
       if (secrets.length > 0) {
-        process.stdout.write(JSON.stringify({
-          decision: 'block',
-          reason: `[Article IV] Potential secret detected in file content. Pattern: ${secrets[0]}. Use environment variables instead.`,
-        }));
+        process.stdout.write(JSON.stringify(denyOutput(
+          `[Article IV] Potential secret detected in file content. Pattern: ${secrets[0]}. Use environment variables instead.`
+        )));
         return;
       }
     }
@@ -93,10 +92,9 @@ async function main() {
     if (toolName === 'Bash') {
       const command = toolInput.command || '';
       if (isDestructiveCommand(command)) {
-        process.stdout.write(JSON.stringify({
-          decision: 'block',
-          reason: `[Article IV] Destructive command detected: "${command.slice(0, 60)}...". This requires explicit user confirmation.`,
-        }));
+        process.stdout.write(JSON.stringify(denyOutput(
+          `[Article IV] Destructive command detected: "${command.slice(0, 60)}...". This requires explicit user confirmation.`
+        )));
         return;
       }
 
@@ -105,28 +103,49 @@ async function main() {
       if (injectionFindings.length > 0) {
         const critical = injectionFindings.filter(f => f.severity === 'critical');
         if (critical.length > 0) {
-          process.stdout.write(JSON.stringify({
-            decision: 'block',
-            reason: `[Article IV] Shell injection risk detected (${critical.length} critical): ${critical.map(f => f.id).join(', ')}. Command: "${command.slice(0, 60)}..."`,
-          }));
+          process.stdout.write(JSON.stringify(denyOutput(
+            `[Article IV] Shell injection risk detected (${critical.length} critical): ${critical.map(f => f.id).join(', ')}. Command: "${command.slice(0, 60)}..."`
+          )));
           return;
         }
-        // High/medium findings: allow with warning (advisory)
-        process.stdout.write(JSON.stringify({
-          decision: 'allow',
-          reason: `[Security Advisory] ${injectionFindings.length} shell security finding(s): ${injectionFindings.map(f => f.id).join(', ')}`,
-        }));
+        // High/medium findings: allow (advisory only, surfaced via reason)
+        process.stdout.write(JSON.stringify(allowOutput(
+          `[Security Advisory] ${injectionFindings.length} shell security finding(s): ${injectionFindings.map(f => f.id).join(', ')}`
+        )));
         return;
       }
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] constitution-guard: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Fail-open on hook errors: a broken hook should not block legitimate work.
+    // Real security checks above are explicit and run before this catch.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 /**
  * 23-point shell injection security checks.
  * Inline implementation (hooks are standalone — no imports from src/).
@@ -135,15 +154,24 @@ async function main() {
 // SYNC: These 23 check IDs MUST match packages/chati-dev/src/security/bash-security.js
 // Hooks are standalone (no imports from src/), so duplication is necessary.
 // If you update here, update bash-security.js too. Run: npm test to verify both.
+// Severity tiers:
+// - critical = block immediately (clearly malicious, no legitimate use)
+// - high/medium = advisory only (surfaced as reason, allowed). Used to be
+//   blocking, but several patterns produced too many false positives
+//   (e.g. SHELL_METACHARACTERS firing on every $(date), GIT_COMMIT_SUBSTITUTION
+//   firing on git commit -m "$(date)"). Critical patterns below are narrowly
+//   scoped to actually-dangerous shell injection vectors.
 const SHELL_INJECTION_CHECKS = [
-  { id: 'INCOMPLETE_COMMANDS', pattern: /[|&;]\s*$/, severity: 'high' },
+  { id: 'INCOMPLETE_COMMANDS', pattern: /[|&;]\s*$/, severity: 'medium' },
   { id: 'JQ_SYSTEM_FUNCTION', pattern: /jq\b.*\bsystem\s*\(/i, severity: 'critical' },
-  { id: 'JQ_FILE_ARGUMENTS', pattern: /jq\b.*--from-file|jq\b.*-f\s+[^|&;]+/i, severity: 'high' },
-  { id: 'OBFUSCATED_FLAGS', pattern: /\$[({].*[)}].*-/, severity: 'high' },
-  { id: 'SHELL_METACHARACTERS', pattern: /[`]|\$\(/, severity: 'critical' },
-  { id: 'DANGEROUS_VARIABLES', pattern: /(?:^|\s)(?:PATH|LD_PRELOAD|LD_LIBRARY_PATH|DYLD_INSERT_LIBRARIES|PYTHONPATH|NODE_PATH|RUBYLIB|PERL5LIB)\s*=/, severity: 'critical' },
-  { id: 'NEWLINES', pattern: /(?<!\\)\n.*(?:rm|curl|wget|chmod|chown|sudo|eval|exec)/, severity: 'high' },
-  { id: 'BACKSLASH_ESCAPED_WHITESPACE', pattern: /\\\s+(?:-|\/)/,severity: 'medium' },
+  { id: 'JQ_FILE_ARGUMENTS', pattern: /jq\b.*--from-file|jq\b.*-f\s+[^|&;]+/i, severity: 'medium' },
+  { id: 'OBFUSCATED_FLAGS', pattern: /\$[({].*[)}].*-/, severity: 'medium' },
+  // SHELL_METACHARACTERS removed: $() and backticks are normal substitution.
+  // Genuinely dangerous substitutions are caught by DANGEROUS_PATTERNS_COMMAND_SUBSTITUTION below.
+  { id: 'DANGEROUS_VARIABLES', pattern: /(?:^|\s)(?:LD_PRELOAD|LD_LIBRARY_PATH|DYLD_INSERT_LIBRARIES|PYTHONPATH|NODE_PATH|RUBYLIB|PERL5LIB)\s*=/, severity: 'critical' },
+  // PATH= removed from critical (legitimate `PATH=/foo:$PATH cmd` exists).
+  { id: 'NEWLINES', pattern: /(?<!\\)\n.*(?:rm|curl|wget|chmod|chown|sudo|eval|exec)/, severity: 'medium' },
+  { id: 'BACKSLASH_ESCAPED_WHITESPACE', pattern: /\\\s+(?:-|\/)/, severity: 'medium' },
   // eslint-disable-next-line no-control-regex
   { id: 'CONTROL_CHARACTERS', pattern: /[\x00-\x08\x0e-\x1f\x7f]/, severity: 'critical' },
   { id: 'UNICODE_WHITESPACE', pattern: /[\u200B-\u200F\u2028-\u202F\uFEFF\u00A0\u2060\u180E]/, severity: 'critical' },
@@ -151,13 +179,13 @@ const SHELL_INJECTION_CHECKS = [
   { id: 'DANGEROUS_PATTERNS_INPUT_REDIRECTION', pattern: /<\s*(?:\/etc\/(?:passwd|shadow|sudoers)|\/proc\/|~\/\.ssh\/|~\/\.aws\/)/, severity: 'critical' },
   { id: 'DANGEROUS_PATTERNS_OUTPUT_REDIRECTION', pattern: />\s*(?:\/etc\/|~\/\.ssh\/|~\/\.bashrc|~\/\.zshrc|~\/\.profile|~\/\.gitconfig)/, severity: 'critical' },
   { id: 'IFS_INJECTION', pattern: /\bIFS\s*=/, severity: 'critical' },
-  { id: 'BRACE_EXPANSION', pattern: /\{.*(?:rm|curl|wget|chmod|eval|exec|sudo).*[,}]/, severity: 'high' },
-  { id: 'GIT_COMMIT_SUBSTITUTION', pattern: /git\s+(?:commit|push|tag).*\$[({]/, severity: 'high' },
+  { id: 'BRACE_EXPANSION', pattern: /\{.*(?:rm|curl|wget|chmod|eval|exec|sudo).*[,}]/, severity: 'medium' },
+  // GIT_COMMIT_SUBSTITUTION removed: `git commit -m "$(date)"` is legitimate.
   { id: 'PROC_ENVIRON_ACCESS', pattern: /\/proc\/(?:self|\d+)\/(?:environ|cmdline|maps|mem)/, severity: 'critical' },
-  { id: 'MALFORMED_TOKEN_INJECTION', pattern: /\\x[0-9a-f]{2}|\\u[0-9a-f]{4}|\\[0-7]{3}/i, severity: 'high' },
+  { id: 'MALFORMED_TOKEN_INJECTION', pattern: /\\x[0-9a-f]{2}|\\u[0-9a-f]{4}|\\[0-7]{3}/i, severity: 'medium' },
   { id: 'MID_WORD_HASH', pattern: /\w#\w/, severity: 'medium' },
   { id: 'COMMENT_QUOTE_DESYNC', pattern: /#.*['"][^'"]*$/, severity: 'medium' },
-  { id: 'QUOTED_NEWLINE', pattern: /["'][^"']*\n[^"']*["']/, severity: 'high' },
+  { id: 'QUOTED_NEWLINE', pattern: /["'][^"']*\n[^"']*["']/, severity: 'medium' },
   { id: 'ZSH_DANGEROUS_COMMANDS', pattern: /\b(?:zmodload|sysopen|sysread|syswrite|zsystem|zselect|ztcp)\b/, severity: 'critical' },
   { id: 'BACKSLASH_ESCAPED_OPERATORS', pattern: /\\[|;&]/, severity: 'medium' },
 ];
@@ -176,8 +204,16 @@ function runShellInjectionChecks(command) {
 
 export { containsSecrets, isDestructiveCommand, runShellInjectionChecks, SECRET_PATTERNS, DESTRUCTIVE_COMMANDS, SHELL_INJECTION_CHECKS };
 
-// 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/license-guard.js

@@ -3,217 +3,110 @@
  * License Guard Hook — UserPromptSubmit
  *
  * Validates license status before each user prompt turn.
- * Uses a 24h cache stored in ~/.chati-dev/license.yaml (global, all projects).
+ * Uses a 4-hour cache stored in ~/.chati-dev/license.yaml (global, all projects).
  *
  * Behavior:
- * - No key configured  → allow (orchestrator handles inline activation)
- * - Cache VALID < 24h  → allow silently + session ping (once/day/project)
- * - Cache EXPIRED/INVALID < 24h → block with renewal message
- * - Cache stale (> 24h) → call API, refresh cache, then allow or block
- * - API unreachable    → fail open (allow), never block work
+ * - No license file        → block with activation instructions
+ * - Cache VALID < 4h       → allow silently
+ * - Cache EXPIRED/INVALID  → block with renewal message
+ * - Cache stale (> 4h)     → call API, refresh cache, then allow or block
+ * - API unreachable + cache VALID < 24h → grace allow
+ * - API unreachable + cache stale       → block (cannot verify)
+ *
+ * Telemetry pings are owned by session-digest.js (PreCompact event), not here.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join, basename } from 'path';
+import { join } from 'path';
 import { homedir } from 'os';
 
 const API_BASE = 'https://chati.dev/api';
-const TELEMETRY_ENDPOINT = 'https://chati.dev/api/telemetry';
-const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours — shorter window to catch expirations faster
-const PING_THROTTLE_MS = 5 * 60 * 1000; // 5 minutes
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 
 const GLOBAL_DIR = join(homedir(), '.chati-dev');
 const LICENSE_PATH = join(GLOBAL_DIR, 'license.yaml');
-const PINGS_PATH = join(GLOBAL_DIR, 'pings.yaml');
-
-async function main() {
-  let input = '';
-  for await (const chunk of process.stdin) input += chunk;
-
-  try {
-    // Read global license file — REQUIRED for operation
-    if (!existsSync(LICENSE_PATH)) {
-      block('No license found. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
-      return;
-    }
 
-    const licenseRaw = readFileSync(LICENSE_PATH, 'utf-8');
-    const licenseKey = readYamlField(licenseRaw, 'key');
-
-    if (!licenseKey || licenseKey === 'null') {
-      block('No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
-      return;
-    }
-
-    // Check cache validity
-    const status = readYamlField(licenseRaw, 'status');
-    const checkedAt = readYamlField(licenseRaw, 'checked_at');
-    const age = checkedAt ? Date.now() - new Date(checkedAt).getTime() : Infinity;
-
-    if (age < CACHE_TTL_MS) {
-      if (status === 'VALID') {
-        await allowWithPing(licenseKey);
-        return;
-      }
-      if (status === 'EXPIRED' || status === 'INVALID') {
-        block(buildMessage(status, readYamlField(licenseRaw, 'reason')));
-        return;
-      }
-    }
-
-    // Cache stale — call API
-    try {
-      const machineId = await computeMachineId();
-      const res = await fetch(
-        `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
-        { signal: AbortSignal.timeout(5000) }
-      );
-      const data = await res.json();
+/**
+ * Pure license validation function — provider-agnostic.
+ * Returns a verdict object that hook wrappers can translate to their
+ * provider's blocking schema (Claude UserPromptSubmit, Gemini BeforeModel,
+ * Codex UserPromptSubmit).
+ *
+ * @returns {Promise<{valid: boolean, reason?: string, status?: string}>}
+ */
+export async function checkLicense() {
+  // Read global license file — REQUIRED for operation
+  if (!existsSync(LICENSE_PATH)) {
+    return { valid: false, reason: 'No license found. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing', status: 'MISSING' };
+  }
 
-      // Persist updated status (keep existing key)
-      const existing = parseYaml(licenseRaw);
-      const updated = {
-        ...existing,
-        status: data.status,
-        plan: data.plan ?? '',
-        days_remaining: data.days_remaining ?? '',
-        expires_at: data.expires_at ?? '',
-        reason: data.reason ?? '',
-        checked_at: new Date().toISOString(),
-      };
-      mkdirSync(GLOBAL_DIR, { recursive: true });
-      writeFileSync(LICENSE_PATH, dumpYaml(updated));
+  const licenseRaw = readFileSync(LICENSE_PATH, 'utf-8');
+  const licenseKey = readYamlField(licenseRaw, 'key');
 
-      if (data.status === 'VALID') {
-        await allowWithPing(licenseKey);
-        return;
-      }
-      block(buildMessage(data.status, data.reason));
-    } catch {
-      // API unreachable — check if we have a recent VALID cache to fall back on
-      // If cache is less than 24h old AND was VALID, allow (grace period for network issues)
-      // Otherwise block — we cannot verify the license
-      if (age < 24 * 60 * 60 * 1000 && status === 'VALID') {
-        allow(); // grace: last check was recent and valid, allow despite network issue
-      } else {
-        block('Unable to verify license (network issue). If this persists, check your connection.\nRun: npx chati-dev activate --key=YOUR-KEY');
-      }
-    }
-  } catch { /* expected: stdin parse may fail — fail open */
-    allow();
+  if (!licenseKey || licenseKey === 'null') {
+    return { valid: false, reason: 'No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing', status: 'MISSING' };
   }
-}
 
-// ---------------------------------------------------------------------------
-// Session Ping (5-min throttle with phase-change detection)
-// ---------------------------------------------------------------------------
-
-async function allowWithPing(licenseKey) {
-  const projectPath = process.cwd();
-  const projectName = basename(projectPath) || 'unknown';
-  const session = readSessionContext();
+  // Check cache validity
+  const status = readYamlField(licenseRaw, 'status');
+  const checkedAt = readYamlField(licenseRaw, 'checked_at');
+  const age = checkedAt ? Date.now() - new Date(checkedAt).getTime() : Infinity;
 
-  if (shouldPing(projectPath, session)) {
-    recordPing(projectPath, session); // sync — prevents duplicate pings even if fetch fails
-    const pingPromise = sendSessionPing(licenseKey, projectName, session);
-    allow();
-    await pingPromise; // keep process alive until ping completes (max 3s)
-  } else {
-    allow();
+  if (age < CACHE_TTL_MS) {
+    if (status === 'VALID') return { valid: true, status: 'VALID' };
+    if (status === 'EXPIRED' || status === 'INVALID') {
+      return { valid: false, reason: buildMessage(status, readYamlField(licenseRaw, 'reason')), status };
+    }
   }
-}
 
-/**
- * Reads .chati/session.yaml from cwd to extract pipeline phase, agent, and project type.
- * Returns {} on any error (fail silently — this is optional enrichment).
- */
-function readSessionContext() {
+  // Cache stale — call API
   try {
-    const sessionPath = join(process.cwd(), '.chati', 'session.yaml');
-    if (!existsSync(sessionPath)) return {};
-    const raw = readFileSync(sessionPath, 'utf-8');
-
-    // project.state → pipeline_phase
-    const stateMatch = raw.match(/^\s+state:\s*(.+)$/m);
-    const pipeline_phase = stateMatch ? stateMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    // current_agent (top-level)
-    const agentMatch = raw.match(/^current_agent:\s*(.+)$/m);
-    const current_agent = agentMatch ? agentMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    // project.type → project_type
-    const typeMatch = raw.match(/^\s+type:\s*(.+)$/m);
-    const project_type = typeMatch ? typeMatch[1].trim().replace(/^["']|["']$/g, '') : null;
-
-    return { pipeline_phase, current_agent, project_type };
-  } catch { return {}; }
+    const machineId = await computeMachineId();
+    const res = await fetch(
+      `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
+      { signal: AbortSignal.timeout(5000) }
+    );
+    const data = await res.json();
+
+    // Persist updated status (keep existing key)
+    const existing = parseYaml(licenseRaw);
+    const updated = {
+      ...existing,
+      status: data.status,
+      plan: data.plan ?? '',
+      days_remaining: data.days_remaining ?? '',
+      expires_at: data.expires_at ?? '',
+      reason: data.reason ?? '',
+      checked_at: new Date().toISOString(),
+    };
+    mkdirSync(GLOBAL_DIR, { recursive: true });
+    writeFileSync(LICENSE_PATH, dumpYaml(updated));
+
+    if (data.status === 'VALID') return { valid: true, status: 'VALID' };
+    return { valid: false, reason: buildMessage(data.status, data.reason), status: data.status };
+  } catch {
+    // API unreachable — grace period if cache is recent and was VALID
+    if (age < 24 * 60 * 60 * 1000 && status === 'VALID') {
+      return { valid: true, status: 'VALID', graced: true };
+    }
+    return { valid: false, reason: 'Unable to verify license (network issue). If this persists, check your connection.\nRun: npx chati-dev activate --key=YOUR-KEY', status: 'NETWORK_ERROR' };
+  }
 }
 
-/**
- * Pings.yaml format: '/path/to/project': '2026-03-22T21:00:00.000Z|discover|greenfield-wu'
- * Ping if: (1) no entry, (2) >5 min ago, OR (3) phase/agent changed
- */
-function shouldPing(projectPath, session = {}) {
-  try {
-    if (!existsSync(PINGS_PATH)) return true;
-    const content = readFileSync(PINGS_PATH, 'utf-8');
-    const escaped = projectPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const match = content.match(new RegExp(`^${escaped}:\\s*'?([^'\\n]+)'?$`, 'm'));
-    if (!match) return true;
-
-    const [timestamp, lastPhase, lastAgent] = match[1].trim().split('|');
-    const age = Date.now() - new Date(timestamp).getTime();
-    if (age > PING_THROTTLE_MS) return true;
-
-    // Phase or agent changed → ping immediately
-    if (session.pipeline_phase && session.pipeline_phase !== lastPhase) return true;
-    if (session.current_agent && session.current_agent !== lastAgent) return true;
-
-    return false;
-  } catch { return false; } // fail closed — don't add latency on parse error
-}
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
 
-function recordPing(projectPath, session = {}) {
   try {
-    mkdirSync(GLOBAL_DIR, { recursive: true });
-    const timestamp = new Date().toISOString();
-    const phase = session.pipeline_phase ?? '';
-    const agent = session.current_agent ?? '';
-    const value = `${timestamp}|${phase}|${agent}`;
-
-    let content = existsSync(PINGS_PATH) ? readFileSync(PINGS_PATH, 'utf-8') : '';
-    const escaped = projectPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    if (new RegExp(`^${escaped}:`, 'm').test(content)) {
-      content = content.replace(new RegExp(`^(${escaped}:).*$`, 'm'), `$1 '${value}'`);
+    const result = await checkLicense();
+    if (result.valid) {
+      allow();
     } else {
-      content += `${projectPath}: '${value}'\n`;
+      block(result.reason);
     }
-    writeFileSync(PINGS_PATH, content);
-  } catch {} // fail silently
-}
-
-async function sendSessionPing(licenseKey, projectName, session = {}) {
-  try {
-    const properties = {};
-    if (session.pipeline_phase) properties.pipeline_phase = session.pipeline_phase;
-    if (session.current_agent) properties.current_agent = session.current_agent;
-    if (session.project_type) properties.project_type = session.project_type;
-
-    await fetch(TELEMETRY_ENDPOINT, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        license_key: licenseKey,
-        project_name: projectName,
-        events: [{
-          type: 'session_active',
-          timestamp: new Date().toISOString(),
-          properties,
-        }],
-      }),
-      signal: AbortSignal.timeout(3000),
-    });
-  } catch {} // fire-and-forget, always fail silently
+  } catch { /* expected: stdin parse may fail — fail open */
+    allow();
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -221,10 +114,12 @@ async function sendSessionPing(licenseKey, projectName, session = {}) {
 // ---------------------------------------------------------------------------
 
 function allow() {
-  process.stdout.write(JSON.stringify({ decision: 'allow' }));
+  // UserPromptSubmit canonical "allow" is empty object — omit decision.
+  process.stdout.write('{}');
 }
 
 function block(reason) {
+  // UserPromptSubmit blocking schema: decision + reason at top level.
   process.stdout.write(JSON.stringify({ decision: 'block', reason }));
 }
 
@@ -274,7 +169,16 @@ async function computeMachineId() {
   return createHash('sha256').update(raw).digest('hex').substring(0, 16);
 }
 
+// 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/mode-governance.js

@@ -41,12 +41,25 @@ const STATE_TO_GOVERNANCE_MODE = {
 
 function getCurrentMode(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
-  if (!existsSync(sessionPath)) return 'planning'; // Default to most restrictive
+  // No session = no enforcement yet (orchestrator will set mode on first run).
+  // Defaulting to planning here would deadlock fresh installs (planning blocks
+  // session.yaml writes, so the orchestrator could never bootstrap).
+  if (!existsSync(sessionPath)) return 'build';
 
   const raw = readFileSync(sessionPath, 'utf-8');
-  const match = raw.match(/^\s*mode:\s*(.+)$/m);
-  const state = match ? match[1].trim().replace(/^["']|["']$/g, '') : 'discover';
-  return STATE_TO_GOVERNANCE_MODE[state] || 'planning';
+  // Prefer explicit mode field; fall back to project.state mapping.
+  const modeMatch = raw.match(/^\s*mode:\s*(.+)$/m);
+  if (modeMatch) {
+    const mode = modeMatch[1].trim().replace(/^["']|["']$/g, '');
+    if (MODE_SCOPES[mode]) return mode;
+  }
+  const stateMatch = raw.match(/^\s+state:\s*(.+)$/m);
+  if (stateMatch) {
+    const state = stateMatch[1].trim().replace(/^["']|["']$/g, '');
+    return STATE_TO_GOVERNANCE_MODE[state] || 'build';
+  }
+  // Session exists but no mode/state field — be permissive.
+  return 'build';
 }
 
 function isPathAllowed(filePath, projectDir, mode) {
@@ -74,31 +87,59 @@ async function main() {
     const filePath = toolInput.file_path || toolInput.path || '';
 
     if (!filePath) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     const mode = getCurrentMode(projectDir);
 
     if (isPathAllowed(filePath, projectDir, mode)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
     } else {
       const scope = MODE_SCOPES[mode];
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`,
-      }));
+      process.stdout.write(JSON.stringify(denyOutput(
+        `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`
+      )));
     }
   } catch (err) {
     process.stderr.write(`[chati-hook-error] mode-governance: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Hook errors are fail-OPEN: a broken hook should not block the user.
+    // Security-critical denials are handled by explicit logic above.
+    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 { getCurrentMode, isPathAllowed, MODE_SCOPES, STATE_TO_GOVERNANCE_MODE };
 
-// 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 */ }
 }