karajan-code 1.10.0 → 1.11.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "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/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/commands/run.js

@@ -4,7 +4,7 @@ import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
 import { printHeader, printEvent } from "../utils/display.js";
 import { resolveRole } from "../config.js";
-import { parseCardId, buildTaskFromCard, buildCompletionUpdates } from "../planning-game/adapter.js";
+import { parseCardId } from "../planning-game/adapter.js";
 
 export async function runCommandHandler({ task, config, logger, flags }) {
   const requiredProviders = [
@@ -22,24 +22,10 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
   await assertAgentsAvailable(requiredProviders);
 
-  // --- Planning Game: resolve card context ---
+  // --- Planning Game: resolve card ID ---
   const pgCardId = flags?.pgTask || parseCardId(task);
   const pgProject = flags?.pgProject || config.planning_game?.project_id || null;
-  let pgCard = null;
-  let enrichedTask = task;
-
-  if (pgCardId && pgProject && config.planning_game?.enabled !== false) {
-    try {
-      const { fetchCard, updateCard } = await import("../planning-game/client.js");
-      pgCard = await fetchCard({ projectId: pgProject, cardId: pgCardId });
-      if (pgCard) {
-        enrichedTask = buildTaskFromCard(pgCard);
-        logger.info(`Planning Game: loaded card ${pgCardId} from project ${pgProject}`);
-      }
-    } catch (err) {
-      logger.warn(`Planning Game: could not load card ${pgCardId}: ${err.message}`);
-    }
-  }
+  const enrichedTask = task;
 
   const jsonMode = flags?.json;
 
@@ -65,26 +51,8 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     printHeader({ task: enrichedTask, config });
   }
 
-  const startDate = new Date().toISOString();
   const result = await runFlow({ task: enrichedTask, config, logger, flags, emitter, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
-  // --- Planning Game: update card on completion ---
-  if (pgCard && pgProject && result?.approved) {
-    try {
-      const { updateCard } = await import("../planning-game/client.js");
-      const updates = buildCompletionUpdates({
-        approved: true,
-        commits: result.git?.commits || [],
-        startDate,
-        codeveloper: config.planning_game?.codeveloper || null
-      });
-      await updateCard({ projectId: pgProject, cardId: pgCardId, firebaseId: pgCard.firebaseId, updates });
-      logger.info(`Planning Game: updated ${pgCardId} to "${updates.status}"`);
-    } catch (err) {
-      logger.warn(`Planning Game: could not update card ${pgCardId}: ${err.message}`);
-    }
-  }
-
   if (jsonMode) {
     console.log(JSON.stringify(result, null, 2));
   }

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);
   }
 

package/src/mcp/tools.js

@@ -149,6 +149,24 @@ export const tools = [
       }
     }
   },
+  {
+    name: "kj_preflight",
+    description: "Confirm or adjust agent configuration before first kj_run/kj_code. REQUIRED before running any task via MCP. Show the config to the human, get their confirmation or adjustments, then call this tool with their response.",
+    inputSchema: {
+      type: "object",
+      required: ["humanResponse"],
+      properties: {
+        humanResponse: { type: "string", description: "The human's response: 'ok' to confirm defaults, or specific changes like 'use gemini as coder'" },
+        coder: { type: "string", description: "Override coder for this session" },
+        reviewer: { type: "string", description: "Override reviewer for this session" },
+        tester: { type: "string", description: "Override tester for this session" },
+        security: { type: "string", description: "Override security for this session" },
+        solomon: { type: "string", description: "Override solomon for this session" },
+        enableTester: { type: "boolean", description: "Enable/disable tester for this session" },
+        enableSecurity: { type: "boolean", description: "Enable/disable security for this session" }
+      }
+    }
+  },
   {
     name: "kj_code",
     description: "Run coder-only mode",
@@ -180,7 +198,7 @@ export const tools = [
   },
   {
     name: "kj_status",
-    description: "Show real-time log of the current or last Karajan run. Use this to monitor progress while kj_run/kj_plan/kj_code is executing. Reads from .kj/run.log in the project directory.",
+    description: "Show real-time status and log of the current or last Karajan run. Returns a parsed status (current stage, agent, iteration, errors) plus recent log lines. Use this to monitor progress while kj_run/kj_plan/kj_code is executing.",
     inputSchema: {
       type: "object",
       properties: {