karajan-code 1.10.1 → 1.11.1

package/README.md

@@ -30,7 +30,7 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 **Key features:**
 - **Multi-agent pipeline** with 11 configurable roles
 - **4 AI agents supported**: Claude, Codex, Gemini, Aider
-- **MCP server** with 11 tools — use `kj` from Claude, Codex, or any MCP-compatible host without leaving your agent. [See MCP setup](#mcp-server)
+- **MCP server** with 15 tools — use `kj` from Claude, Codex, or any MCP-compatible host without leaving your agent. [See MCP setup](#mcp-server)
 - **TDD enforcement** — test changes required when source files change
 - **SonarQube integration** — static analysis with quality gate enforcement (requires [Docker](#requirements))
 - **Review profiles** — standard, strict, relaxed, paranoid
@@ -44,6 +44,9 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
 - **Pipeline stage tracker** — cumulative progress view during `kj_run` showing which stages are done, running, or pending — both in CLI and via MCP events for real-time host rendering
 - **Planner observability guardrails** — continuous heartbeat/stall telemetry, configurable max-silence protection (`session.max_agent_silence_minutes`), and hard runtime cap (`session.max_planner_minutes`) to avoid long stuck planner runs
+- **Rate-limit standby** — when agents hit rate limits, Karajan parses cooldown times, waits with exponential backoff, and auto-resumes instead of failing
+- **Preflight handshake** — `kj_preflight` requires human confirmation of agent assignments before execution, preventing AI from silently overriding your config
+- **3-tier config** — session > project > global config layering with `kj_agents` scoping
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -62,16 +65,16 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 
 | Role | Description | Default |
 |------|-------------|---------|
-| **triage** | Classifies task complexity (trivial/simple/medium/complex) and activates only necessary roles | Off |
+| **triage** | Pipeline director — analyzes task complexity and activates roles dynamically | **On** |
 | **researcher** | Investigates codebase context before planning | Off |
 | **planner** | Generates structured implementation plans | Off |
 | **coder** | Writes code and tests following TDD methodology | **Always on** |
 | **refactorer** | Improves code clarity without changing behavior | Off |
 | **sonar** | Runs SonarQube static analysis and quality gate checks | On (if configured) |
 | **reviewer** | Code review with configurable strictness profiles | **Always on** |
-| **tester** | Test quality gate and coverage verification | Off |
-| **security** | OWASP security audit | Off |
-| **solomon** | Conflict resolver when coder and reviewer disagree | Off |
+| **tester** | Test quality gate and coverage verification | **On** |
+| **security** | OWASP security audit | **On** |
+| **solomon** | Session supervisor — monitors iteration health with 4 rules, escalates on anomalies | **On** |
 | **commiter** | Git commit, push, and PR automation after approval | Off |
 
 Roles marked with `?` are optional and can be enabled per-run or via config.
@@ -272,6 +275,16 @@ Resume a paused session (e.g., after fail-fast).
 kj resume s_2026-02-28T20-47-24-270Z --answer "yes, proceed with the fix"
 ```
 
+### `kj agents`
+
+List or change AI agent assignments per role.
+
+```bash
+kj agents                       # List current agents (with scope column)
+kj agents set coder gemini      # Set coder to gemini (project scope)
+kj agents set reviewer claude --global  # Set reviewer globally
+```
+
 ### `kj roles`
 
 Inspect pipeline roles and their template instructions.
@@ -416,9 +429,12 @@ After `npm install -g karajan-code`, the MCP server is auto-registered in Claude
 | `kj_resume` | Resume a paused session |
 | `kj_report` | Read session reports (supports `--trace`) |
 | `kj_roles` | List roles or show role templates |
-| `kj_code` | Run coder-only mode |
-| `kj_review` | Run reviewer-only mode |
-| `kj_plan` | Generate implementation plan with heartbeat/stall telemetry and clearer diagnostics |
+| `kj_agents` | List or change agent assignments (session/project/global scope) |
+| `kj_preflight` | Human confirms agent config before kj_run/kj_code executes |
+| `kj_code` | Run coder-only mode (with progress notifications) |
+| `kj_review` | Run reviewer-only mode (with progress notifications) |
+| `kj_plan` | Generate implementation plan (with progress notifications) |
+| `kj_status` | Live parsed status of current run (stage, agent, iteration, errors) |
 
 ### MCP restart after version updates
 
@@ -461,7 +477,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1040+ tests with Vitest
+npm test              # Run 1180+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/bin/kj-tail

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# kj-tail — Colorized, filtered tail for Karajan run logs
+# Usage: kj-tail [project-dir] [-v|--verbose]
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+GRAY='\033[0;90m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+VERBOSE=false
+PROJECT_DIR=""
+
+for arg in "$@"; do
+  case "$arg" in
+    -v|--verbose) VERBOSE=true ;;
+    *) PROJECT_DIR="$arg" ;;
+  esac
+done
+
+PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
+LOG_FILE="${PROJECT_DIR}/.kj/run.log"
+
+if [[ ! -f "$LOG_FILE" ]]; then
+  echo -e "${RED}No run.log found at ${LOG_FILE}${RESET}"
+  echo "Usage: kj-tail [project-dir] [-v|--verbose]"
+  exit 1
+fi
+
+echo -e "${BOLD}${CYAN}Karajan tail${RESET} ${GRAY}— ${LOG_FILE}${RESET}"
+echo -e "${GRAY}Ctrl+C to stop. Use -v to include agent output.${RESET}"
+echo ""
+
+tail -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+  # Strip timestamp (HH:MM:SS.mmm)
+  clean="${line#[0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9][0-9] }"
+
+  # Strip [agent:output] tag — it's the default, no need to show it
+  clean="${clean/\[agent:output\] /}"
+
+  # Colorize by content
+  if [[ "$clean" == *"[coder:start]"* ]] || [[ "$clean" == *"[coder:done]"* ]] || [[ "$clean" == *"[coder]"* ]]; then
+    echo -e "${GREEN}${clean}${RESET}"
+  elif [[ "$clean" == *"[reviewer"* ]]; then
+    echo -e "${YELLOW}${clean}${RESET}"
+  elif [[ "$clean" == *"[sonar"* ]]; then
+    echo -e "${BLUE}${clean}${RESET}"
+  elif [[ "$clean" == *"[solomon"* ]]; then
+    echo -e "${MAGENTA}${clean}${RESET}"
+  elif [[ "$clean" == *"[iteration"* ]] || [[ "$clean" == *"[session"* ]] || [[ "$clean" == *"[kj_run]"* ]] || [[ "$clean" == *"[kj_code]"* ]]; then
+    echo -e "${BOLD}${CYAN}${clean}${RESET}"
+  elif [[ "$clean" == *"fail"* ]] || [[ "$clean" == *"error"* ]] || [[ "$clean" == *"FAIL"* ]] || [[ "$clean" == *"ERROR"* ]]; then
+    echo -e "${RED}${clean}${RESET}"
+  elif [[ "$clean" == *"[agent:heartbeat]"* ]]; then
+    echo -e "${GRAY}${clean}${RESET}"
+  elif [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]]; then
+    echo -e "${YELLOW}${clean}${RESET}"
+  elif [[ "$clean" == "---"* ]]; then
+    echo -e "${BOLD}${clean}${RESET}"
+  else
+    echo "$clean"
+  fi
+done

package/docs/README.es.md

@@ -30,7 +30,7 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 **Caracteristicas principales:**
 - **Pipeline multi-agente** con 11 roles configurables
 - **4 agentes de IA soportados**: Claude, Codex, Gemini, Aider
-- **Servidor MCP** con 11 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **Servidor MCP** con 15 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
 - **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
 - **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
@@ -43,6 +43,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
 - **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
 - **Guardarrailes de observabilidad del planner** — telemetria continua de heartbeat/stall, proteccion configurable por silencio maximo (`session.max_agent_silence_minutes`) y limite duro de ejecucion (`session.max_planner_minutes`) para evitar bloqueos prolongados en `kj_plan`/planner
+- **Standby por rate-limit** — cuando un agente alcanza limites de uso, Karajan parsea el tiempo de espera, espera con backoff exponencial y reanuda automaticamente en vez de fallar
+- **Preflight handshake** — `kj_preflight` requiere confirmacion humana de la configuracion de agentes antes de ejecutar, previniendo que la IA cambie asignaciones silenciosamente
+- **Config de 3 niveles** — sesion > proyecto > global con scoping de `kj_agents`
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -61,16 +64,16 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 
 | Rol | Descripcion | Por defecto |
 |-----|-------------|-------------|
-| **triage** | Clasifica la complejidad de la tarea (trivial/simple/media/compleja) y activa solo los roles necesarios | Off |
+| **triage** | Director de pipeline — analiza la complejidad y activa roles dinamicamente | **On** |
 | **researcher** | Investiga el contexto del codebase antes de planificar | Off |
 | **planner** | Genera planes de implementacion estructurados | Off |
 | **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre activo** |
 | **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
 | **sonar** | Ejecuta analisis estatico SonarQube y quality gates | On (si configurado) |
 | **reviewer** | Revision de codigo con perfiles de exigencia configurables | **Siempre activo** |
-| **tester** | Quality gate de tests y verificacion de cobertura | Off |
-| **security** | Auditoria de seguridad OWASP | Off |
-| **solomon** | Resolutor de conflictos cuando coder y reviewer discrepan | Off |
+| **tester** | Quality gate de tests y verificacion de cobertura | **On** |
+| **security** | Auditoria de seguridad OWASP | **On** |
+| **solomon** | Supervisor de sesion — monitoriza salud de iteraciones con 4 reglas, escala ante anomalias | **On** |
 | **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
 
 Los roles marcados con `?` son opcionales y se pueden activar por ejecucion o via config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -28,6 +28,7 @@
   },
   "files": [
     "src/",
+    "bin/",
     "templates/",
     "scripts/",
     "docs/karajan-code-logo-small.png",

package/src/agents/claude-agent.js

@@ -101,10 +101,20 @@ function pickOutput(res) {
   return res.stdout || res.stderr || "";
 }
 
+/**
+ * Default tools to allow for Claude subprocess.
+ * Since claude -p runs non-interactively (stdin: "ignore"), it cannot ask for
+ * permission approval.  Without --allowedTools, it blocks waiting for approval
+ * that never comes.
+ */
+const ALLOWED_TOOLS = [
+  "Read", "Write", "Edit", "Bash", "Glob", "Grep"
+];
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt];
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     const model = this.getRoleModel(role);
     if (model) args.push("--model", model);
 
@@ -131,7 +141,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async reviewTask(task) {
-    const args = ["-p", task.prompt, "--output-format", "stream-json"];
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json"];
     const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({

package/src/cli.js

@@ -165,9 +165,10 @@ program
 program
   .command("agents [subcommand] [role] [provider]")
   .description("List or change AI agent assignments per role (e.g. kj agents set coder gemini)")
-  .action(async (subcommand, role, provider) => {
+  .option("--global", "Persist change to kj.config.yml (default for CLI)")
+  .action(async (subcommand, role, provider, flags) => {
     await withConfig("agents", {}, async ({ config }) => {
-      await agentsCommand({ config, subcommand: subcommand || "list", role, provider });
+      await agentsCommand({ config, subcommand: subcommand || "list", role, provider, global: flags.global });
     });
   });
 

package/src/commands/agents.js

@@ -1,4 +1,4 @@
-import { loadConfig, writeConfig, getConfigPath, resolveRole } from "../config.js";
+import { loadConfig, writeConfig, getConfigPath, getProjectConfigPath, loadProjectConfig, resolveRole } from "../config.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 
 const ASSIGNABLE_ROLES = [
@@ -8,18 +8,24 @@ const ASSIGNABLE_ROLES = [
 
 const VALID_PROVIDERS = KNOWN_AGENTS.map((a) => a.name);
 
-export function listAgents(config) {
+export function listAgents(config, sessionOverrides = {}, projectConfig = null) {
   return ASSIGNABLE_ROLES.map((role) => {
     const resolved = resolveRole(config, role);
+    const sessionProvider = sessionOverrides[role];
+    const projectProvider = projectConfig?.roles?.[role]?.provider;
+    let scope = "global";
+    if (sessionProvider) scope = "session";
+    else if (projectProvider) scope = "project";
     return {
       role,
-      provider: resolved.provider || "-",
-      model: resolved.model || "-"
+      provider: sessionProvider || resolved.provider || "-",
+      model: resolved.model || "-",
+      scope
     };
   });
 }
 
-export async function setAgent(role, provider) {
+export async function setAgent(role, provider, { global: isGlobal = false } = {}) {
   if (!ASSIGNABLE_ROLES.includes(role)) {
     throw new Error(`Unknown role "${role}". Valid roles: ${ASSIGNABLE_ROLES.join(", ")}`);
   }
@@ -30,37 +36,55 @@ export async function setAgent(role, provider) {
     }
   }
 
-  const { config } = await loadConfig();
-  config.roles = config.roles || {};
-  config.roles[role] = config.roles[role] || {};
-  config.roles[role].provider = provider;
-
-  const configPath = getConfigPath();
-  await writeConfig(configPath, config);
+  if (isGlobal) {
+    const { config } = await loadConfig();
+    config.roles = config.roles || {};
+    config.roles[role] = config.roles[role] || {};
+    config.roles[role].provider = provider;
+    const configPath = getConfigPath();
+    await writeConfig(configPath, config);
+    return { role, provider, scope: "global", configPath };
+  }
 
-  return { role, provider, configPath };
+  // Session scope — try MCP session override first
+  try {
+    const { setSessionOverride } = await import("../mcp/preflight.js");
+    setSessionOverride(role, provider);
+    return { role, provider, scope: "session" };
+  } catch {
+    // preflight module not available (CLI mode) — write to project config
+    const projectConfigPath = getProjectConfigPath();
+    const projectConfig = (await loadProjectConfig()) || {};
+    projectConfig.roles = projectConfig.roles || {};
+    projectConfig.roles[role] = projectConfig.roles[role] || {};
+    projectConfig.roles[role].provider = provider;
+    await writeConfig(projectConfigPath, projectConfig);
+    return { role, provider, scope: "project", configPath: projectConfigPath };
+  }
 }
 
-export async function agentsCommand({ config, subcommand, role, provider }) {
+export async function agentsCommand({ config, subcommand, role, provider, global: isGlobal }) {
   if (subcommand === "set") {
     if (!role || !provider) {
-      console.log("Usage: kj agents set <role> <provider>");
+      console.log("Usage: kj agents set <role> <provider> [--global]");
       console.log(`Roles: ${ASSIGNABLE_ROLES.join(", ")}`);
       console.log(`Providers: ${VALID_PROVIDERS.join(", ")}`);
       return;
     }
-    const result = await setAgent(role, provider);
-    console.log(`Set ${result.role} -> ${result.provider} (saved to ${result.configPath})`);
+    const result = await setAgent(role, provider, { global: isGlobal ?? true });
+    console.log(`Set ${result.role} -> ${result.provider} (scope: ${result.scope})`);
     return result;
   }
 
-  const agents = listAgents(config);
+  const projectConfig = await loadProjectConfig();
+  const agents = listAgents(config, {}, projectConfig);
   const roleWidth = Math.max(...agents.map((a) => a.role.length), 4);
   const provWidth = Math.max(...agents.map((a) => a.provider.length), 8);
-  console.log(`${"Role".padEnd(roleWidth)}  ${"Provider".padEnd(provWidth)}  Model`);
-  console.log("-".repeat(roleWidth + provWidth + 10));
+  const scopeWidth = Math.max(...agents.map((a) => a.scope.length), 5);
+  console.log(`${"Role".padEnd(roleWidth)}  ${"Provider".padEnd(provWidth)}  ${"Scope".padEnd(scopeWidth)}  Model`);
+  console.log("-".repeat(roleWidth + provWidth + scopeWidth + 14));
   for (const a of agents) {
-    console.log(`${a.role.padEnd(roleWidth)}  ${a.provider.padEnd(provWidth)}  ${a.model}`);
+    console.log(`${a.role.padEnd(roleWidth)}  ${a.provider.padEnd(provWidth)}  ${a.scope.padEnd(scopeWidth)}  ${a.model}`);
   }
   return agents;
 }

package/src/config.js

@@ -21,11 +21,11 @@ const DEFAULTS = {
   pipeline: {
     planner: { enabled: false },
     refactorer: { enabled: false },
-    solomon: { enabled: false },
+    solomon: { enabled: true },
     researcher: { enabled: false },
-    tester: { enabled: false },
-    security: { enabled: false },
-    triage: { enabled: false }
+    tester: { enabled: true },
+    security: { enabled: true },
+    triage: { enabled: true }
   },
   review_mode: "standard",
   max_iterations: 5,
@@ -155,6 +155,19 @@ export function getConfigPath() {
   return path.join(getKarajanHome(), "kj.config.yml");
 }
 
+export function getProjectConfigPath(projectDir = process.cwd()) {
+  return path.join(projectDir, ".karajan", "kj.config.yml");
+}
+
+export async function loadProjectConfig(projectDir = process.cwd()) {
+  const projectConfigPath = getProjectConfigPath(projectDir);
+  if (!(await exists(projectConfigPath))) {
+    return null;
+  }
+  const raw = await fs.readFile(projectConfigPath, "utf8");
+  return yaml.load(raw) || {};
+}
+
 async function loadProjectPricingOverrides(projectDir = process.cwd()) {
   const projectConfigPath = path.join(projectDir, ".karajan.yml");
   if (!(await exists(projectConfigPath))) {
@@ -171,24 +184,32 @@ async function loadProjectPricingOverrides(projectDir = process.cwd()) {
   return pricing;
 }
 
-export async function loadConfig() {
+export async function loadConfig(projectDir) {
   const configPath = getConfigPath();
-  const projectPricing = await loadProjectPricingOverrides();
-  if (!(await exists(configPath))) {
-    const baseDefaults = mergeDeep(DEFAULTS, {});
-    if (projectPricing) {
-      baseDefaults.budget = mergeDeep(baseDefaults.budget || {}, { pricing: projectPricing });
-    }
-    return { config: baseDefaults, path: configPath, exists: false };
+  const projectPricing = await loadProjectPricingOverrides(projectDir);
+
+  // Load global config
+  let globalConfig = {};
+  const globalExists = await exists(configPath);
+  if (globalExists) {
+    const raw = await fs.readFile(configPath, "utf8");
+    globalConfig = yaml.load(raw) || {};
+  }
+
+  // Load project config (.karajan/kj.config.yml)
+  const projectConfig = await loadProjectConfig(projectDir);
+
+  // Merge: DEFAULTS < global < project
+  let merged = mergeDeep(DEFAULTS, globalConfig);
+  if (projectConfig) {
+    merged = mergeDeep(merged, projectConfig);
   }
 
-  const raw = await fs.readFile(configPath, "utf8");
-  const parsed = yaml.load(raw) || {};
-  const merged = mergeDeep(DEFAULTS, parsed);
   if (projectPricing) {
     merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
   }
-  return { config: merged, path: configPath, exists: true };
+
+  return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
 export async function writeConfig(configPath, config) {

package/src/mcp/preflight.js

@@ -0,0 +1,28 @@
+/**
+ * Session-scoped preflight state.
+ * Lives in memory — dies when the MCP server restarts.
+ */
+let preflightAcked = false;
+let sessionOverrides = {};
+
+export function isPreflightAcked() {
+  return preflightAcked;
+}
+
+export function ackPreflight(overrides = {}) {
+  preflightAcked = true;
+  sessionOverrides = { ...overrides };
+}
+
+export function getSessionOverrides() {
+  return { ...sessionOverrides };
+}
+
+export function setSessionOverride(key, value) {
+  sessionOverrides[key] = value;
+}
+
+export function resetPreflight() {
+  preflightAcked = false;
+  sessionOverrides = {};
+}

package/src/mcp/server-handlers.js

@@ -22,6 +22,7 @@ import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
 import { resolveReviewProfile } from "../review/profiles.js";
 import { createRunLog, readRunLog } from "../utils/run-log.js";
 import { currentBranch } from "../utils/git.js";
+import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
 
 /**
  * Resolve the user's project directory via MCP roots.
@@ -249,7 +250,7 @@ export async function handleResumeDirect(a, server, extra) {
   return { ok: true, ...result };
 }
 
-function buildDirectEmitter(server, runLog) {
+function buildDirectEmitter(server, runLog, extra) {
   const emitter = new EventEmitter();
   emitter.on("progress", (event) => {
     try {
@@ -260,6 +261,8 @@ function buildDirectEmitter(server, runLog) {
     } catch { /* best-effort */ }
     if (runLog) runLog.logEvent(event);
   });
+  const progressNotifier = buildProgressNotifier(extra);
+  if (progressNotifier) emitter.on("progress", progressNotifier);
   return emitter;
 }
 
@@ -282,7 +285,7 @@ export async function handlePlanDirect(a, server, extra) {
   runLog.logText(
     `[kj_plan] started — provider=${plannerRole.provider}, max_silence=${silenceTimeoutMs ? `${Math.round(silenceTimeoutMs / 1000)}s` : "disabled"}, max_runtime=${plannerTimeoutMs ? `${Math.round(plannerTimeoutMs / 1000)}s` : "disabled"}`
   );
-  const emitter = buildDirectEmitter(server, runLog);
+  const emitter = buildDirectEmitter(server, runLog, extra);
   const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
   const onOutput = ({ stream, line }) => {
     emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
@@ -339,7 +342,7 @@ export async function handleCodeDirect(a, server, extra) {
   const projectDir = await resolveProjectDir(server);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
-  const emitter = buildDirectEmitter(server, runLog);
+  const emitter = buildDirectEmitter(server, runLog, extra);
   const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
   const onOutput = ({ stream, line }) => {
     emitter.emit("progress", { type: "agent:output", stage: "coder", message: line, detail: { stream, agent: coderRole.provider } });
@@ -388,7 +391,7 @@ export async function handleReviewDirect(a, server, extra) {
   const projectDir = await resolveProjectDir(server);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
-  const emitter = buildDirectEmitter(server, runLog);
+  const emitter = buildDirectEmitter(server, runLog, extra);
   const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
   const onOutput = ({ stream, line }) => {
     emitter.emit("progress", { type: "agent:output", stage: "reviewer", message: line, detail: { stream, agent: reviewerRole.provider } });
@@ -449,12 +452,68 @@ export async function handleToolCall(name, args, server, extra) {
         return failPayload("Missing required fields: role and provider");
       }
       const { setAgent } = await import("../commands/agents.js");
-      const result = await setAgent(a.role, a.provider);
-      return { ok: true, ...result, message: `${result.role} now uses ${result.provider}` };
+      const result = await setAgent(a.role, a.provider, { global: false });
+      return { ok: true, ...result, message: `${result.role} now uses ${result.provider} (scope: ${result.scope})` };
     }
     const config = await buildConfig(a);
     const { listAgents } = await import("../commands/agents.js");
-    return { ok: true, agents: listAgents(config) };
+    const sessionOvr = getSessionOverrides();
+    return { ok: true, agents: listAgents(config, sessionOvr) };
+  }
+
+  if (name === "kj_preflight") {
+    const overrides = {};
+    const AGENT_ROLES = ["coder", "reviewer", "tester", "security", "solomon"];
+
+    // Apply explicit param overrides
+    for (const role of AGENT_ROLES) {
+      if (a[role]) overrides[role] = a[role];
+    }
+    if (a.enableTester !== undefined) overrides.enableTester = a.enableTester;
+    if (a.enableSecurity !== undefined) overrides.enableSecurity = a.enableSecurity;
+
+    // Parse natural-language humanResponse for agent changes
+    const resp = (a.humanResponse || "").toLowerCase();
+    if (resp !== "ok") {
+      // Match patterns like "use gemini as coder", "coder: claude", "set reviewer to codex"
+      for (const role of AGENT_ROLES) {
+        const patterns = [
+          new RegExp(`use\\s+(\\w+)\\s+(?:as|for)\\s+${role}`, "i"),
+          new RegExp(`${role}\\s*[:=]\\s*(\\w+)`, "i"),
+          new RegExp(`set\\s+${role}\\s+(?:to|=)\\s*(\\w+)`, "i")
+        ];
+        for (const pat of patterns) {
+          const m = (a.humanResponse || "").match(pat);
+          if (m && !overrides[role]) {
+            overrides[role] = m[1];
+            break;
+          }
+        }
+      }
+    }
+
+    ackPreflight(overrides);
+
+    const config = await buildConfig(a);
+    const { listAgents } = await import("../commands/agents.js");
+    const agents = listAgents(config);
+    const lines = agents
+      .filter(ag => ag.provider !== "-")
+      .map(ag => {
+        const ovr = overrides[ag.role] ? ` -> ${overrides[ag.role]} (session override)` : "";
+        return `  ${ag.role}: ${ag.provider}${ag.model !== "-" ? ` (${ag.model})` : ""}${ovr}`;
+      });
+    const overrideLines = Object.entries(overrides)
+      .filter(([k]) => !AGENT_ROLES.includes(k))
+      .map(([k, v]) => `  ${k}: ${v}`);
+    const allLines = [...lines, ...overrideLines];
+
+    return {
+      ok: true,
+      message: `Preflight acknowledged. Agent configuration confirmed.`,
+      config: allLines.join("\n"),
+      overrides
+    };
   }
 
   if (name === "kj_config") {
@@ -506,6 +565,29 @@ export async function handleToolCall(name, args, server, extra) {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
+    if (!isPreflightAcked()) {
+      const { config } = await loadConfig();
+      const { listAgents } = await import("../commands/agents.js");
+      const agents = listAgents(config);
+      const agentSummary = agents
+        .filter(ag => ag.provider !== "-")
+        .map(ag => `  ${ag.role}: ${ag.provider}${ag.model !== "-" ? ` (${ag.model})` : ""}`)
+        .join("\n");
+      return responseText({
+        ok: false,
+        preflightRequired: true,
+        message: `PREFLIGHT REQUIRED\n\nCurrent agent configuration:\n${agentSummary}\n\nAsk the human to confirm or adjust this configuration, then call kj_preflight with their response.\n\nDo NOT pass coder/reviewer parameters to kj_run — use kj_preflight to set them.`
+      });
+    }
+    // Apply session overrides, ignoring agent params from tool call
+    const sessionOvr = getSessionOverrides();
+    if (sessionOvr.coder) { a.coder = sessionOvr.coder; }
+    if (sessionOvr.reviewer) { a.reviewer = sessionOvr.reviewer; }
+    if (sessionOvr.tester) { a.tester = sessionOvr.tester; }
+    if (sessionOvr.security) { a.security = sessionOvr.security; }
+    if (sessionOvr.solomon) { a.solomon = sessionOvr.solomon; }
+    if (sessionOvr.enableTester !== undefined) { a.enableTester = sessionOvr.enableTester; }
+    if (sessionOvr.enableSecurity !== undefined) { a.enableSecurity = sessionOvr.enableSecurity; }
     return handleRunDirect(a, server, extra);
   }
 
@@ -513,6 +595,23 @@ export async function handleToolCall(name, args, server, extra) {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
+    if (!isPreflightAcked()) {
+      const { config } = await loadConfig();
+      const { listAgents } = await import("../commands/agents.js");
+      const agents = listAgents(config);
+      const agentSummary = agents
+        .filter(ag => ag.provider !== "-")
+        .map(ag => `  ${ag.role}: ${ag.provider}${ag.model !== "-" ? ` (${ag.model})` : ""}`)
+        .join("\n");
+      return responseText({
+        ok: false,
+        preflightRequired: true,
+        message: `PREFLIGHT REQUIRED\n\nCurrent agent configuration:\n${agentSummary}\n\nAsk the human to confirm or adjust this configuration, then call kj_preflight with their response.\n\nDo NOT pass coder/reviewer parameters to kj_code — use kj_preflight to set them.`
+      });
+    }
+    // Apply session overrides, ignoring agent params from tool call
+    const sessionOvr = getSessionOverrides();
+    if (sessionOvr.coder) { a.coder = sessionOvr.coder; }
     return handleCodeDirect(a, server, extra);
   }