karajan-code 1.11.0 → 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/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.11.0",
+  "version": "1.11.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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({