nubos-pilot 0.6.0 → 0.6.1

package/bin/install.js

@@ -683,6 +683,10 @@ async function main() {
       const doctor = require('./np-tools/doctor.cjs');
       return await doctor.run(rest.slice(1), { cwd, stdout: process.stdout });
     }
+    case 'install-hooks':
+      return await runInstallHooks({ cwd, args: rest.slice(1) });
+    case 'uninstall-hooks':
+      return await runUninstallHooks({ cwd, args: rest.slice(1) });
     default:
       process.stderr.write(
         red + 'Unbekanntes Subcommand: ' + sub + reset + '\n',
@@ -692,6 +696,70 @@ async function main() {
   }
 }
 
+function _parseHookFlags(args) {
+  const flags = { scope: null, which: 'both', force: false, dryRun: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--scope' || a === '-s') { flags.scope = args[++i] || null; continue; }
+    if (a.startsWith('--scope=')) { flags.scope = a.slice('--scope='.length); continue; }
+    if (a === '--statusline-only') { flags.which = 'statusline'; continue; }
+    if (a === '--ctx-monitor-only') { flags.which = 'ctx-monitor'; continue; }
+    if (a === '--force' || a === '-f') { flags.force = true; continue; }
+    if (a === '--dry-run') { flags.dryRun = true; continue; }
+  }
+  if (flags.scope && !VALID_SCOPES.includes(flags.scope)) {
+    throw new NubosPilotError('invalid-flag',
+      '--scope must be one of: ' + VALID_SCOPES.join(', '),
+      { flag: '--scope', got: flags.scope });
+  }
+  return flags;
+}
+
+async function runInstallHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || o.cwd || process.cwd();
+  const flags = _parseHookFlags(o.args || []);
+  const scope = flags.scope || _readExistingScope(projectRoot) || 'local';
+  const claudeHooks = require('../lib/install/claude-hooks.cjs');
+  const res = claudeHooks.installClaudeHooks({
+    projectRoot, scope, which: flags.which, force: flags.force, dryRun: flags.dryRun,
+  });
+  if (res.dryRun) {
+    process.stdout.write(JSON.stringify({ dryRun: true, path: res.path, results: res.results }, null, 2) + '\n');
+    return res;
+  }
+  console.error(green + '✓ Claude Code hooks geschrieben → ' + res.path + reset);
+  if (res.results.statusline) {
+    console.error(dim + '  statusline: ' + res.results.statusline.action
+      + (res.results.statusline.existingCommand ? ' (existing: ' + res.results.statusline.existingCommand + ')' : '')
+      + reset);
+  }
+  if (res.results.ctxMonitor) {
+    console.error(dim + '  ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+  }
+  if (res.results.statusline && res.results.statusline.action === 'skipped-existing') {
+    console.error(yellow + '  [statusline] existing non-nubos statusLine preserved. Pass --force to overwrite.' + reset);
+  }
+  return res;
+}
+
+async function runUninstallHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || o.cwd || process.cwd();
+  const flags = _parseHookFlags(o.args || []);
+  const scope = flags.scope || _readExistingScope(projectRoot) || 'local';
+  const claudeHooks = require('../lib/install/claude-hooks.cjs');
+  const res = claudeHooks.uninstallClaudeHooks({ projectRoot, scope, dryRun: flags.dryRun });
+  if (res.dryRun) {
+    process.stdout.write(JSON.stringify({ dryRun: true, path: res.path, results: res.results }, null, 2) + '\n');
+    return res;
+  }
+  console.error(green + '✓ Claude Code hooks entfernt ← ' + res.path + reset);
+  console.error(dim + '  statusline: ' + res.results.statusline.action + reset);
+  console.error(dim + '  ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+  return res;
+}
+
 if (require.main === module) {
   main().catch((err) => {
     if (err && err.code) {

package/bin/np-tools/discuss-phase.test.cjs

@@ -83,7 +83,7 @@ test('DP-1: run(["3"]) on valid milestone returns JSON payload with expected sha
   }
 });
 
-test('DP-1b: CLAUDECODE=1 sets text_mode=true with runtime source', () => {
+test('DP-1b: CLAUDECODE=1 no longer flips text_mode (Claude Code uses AskUserQuestion)', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';
@@ -92,8 +92,8 @@ test('DP-1b: CLAUDECODE=1 sets text_mode=true with runtime source', () => {
     const cap = _captureStdout();
     subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
     const payload = JSON.parse(cap.get().trim());
-    assert.equal(payload.text_mode, true);
-    assert.equal(payload.text_mode_source, 'runtime');
+    assert.equal(payload.text_mode, false);
+    assert.equal(payload.text_mode_source, 'default');
   } finally {
     restore();
   }

package/bin/np-tools/text-mode.test.cjs

@@ -56,7 +56,7 @@ test('text-mode CLI: default without config and without Claude env prints "false
   }
 });
 
-test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
+test('text-mode CLI: CLAUDECODE=1 no longer prints "true" (AskUserQuestion path)', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';
@@ -65,7 +65,7 @@ test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
       const io = _captureIO();
       const rc = subcmd.run([], { cwd: dir, stdout: io.stdout, stderr: io.stderr });
       assert.equal(rc, 0);
-      assert.equal(io.stdoutText().trim(), 'true');
+      assert.equal(io.stdoutText().trim(), 'false');
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
     }
@@ -74,18 +74,21 @@ test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
   }
 });
 
-test('text-mode CLI: --json emits detail object', () => {
+test('text-mode CLI: --json emits detail object with config source', () => {
   const restore = _clearClaudeEnv();
   try {
-    process.env.CLAUDECODE = '1';
     const dir = _mkSandbox();
     try {
+      fs.writeFileSync(
+        path.join(dir, '.nubos-pilot', 'config.json'),
+        JSON.stringify({ workflow: { text_mode: true } }),
+      );
       const io = _captureIO();
       const rc = subcmd.run(['--json'], { cwd: dir, stdout: io.stdout, stderr: io.stderr });
       assert.equal(rc, 0);
       const payload = JSON.parse(io.stdoutText().trim());
       assert.equal(payload.enabled, true);
-      assert.equal(payload.source, 'runtime');
+      assert.equal(payload.source, 'config');
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
     }
@@ -94,7 +97,7 @@ test('text-mode CLI: --json emits detail object', () => {
   }
 });
 
-test('text-mode CLI: config workflow.text_mode=false wins over CLAUDECODE', () => {
+test('text-mode CLI: config workflow.text_mode=false stays false even with CLAUDECODE', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';

package/lib/install/claude-hooks.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { atomicWriteFileSync, NubosPilotError } = require('../core.cjs');
+
+const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.js';
+const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.js';
+const NP_STATUSLINE_MARKER = 'np-statusline.js';
+const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.js';
+
+function _settingsPath(scope, projectRoot) {
+  if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
+  return path.join(projectRoot, '.claude', 'settings.local.json');
+}
+
+function _readJsonSafe(p) {
+  if (!fs.existsSync(p)) return {};
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf-8'); } catch { return {}; }
+  try { return JSON.parse(raw); } catch (err) {
+    throw new NubosPilotError(
+      'claude-settings-invalid-json',
+      'Cannot parse Claude settings: ' + p + ' — ' + err.message,
+      { path: p },
+    );
+  }
+}
+
+function _hookCommand(rel, scope, projectRoot) {
+  if (scope === 'global') {
+    return 'node "' + path.join('$HOME', rel) + '"';
+  }
+  return 'node "' + path.join(projectRoot, rel) + '"';
+}
+
+function _containsNpHook(entry, marker) {
+  if (!entry || typeof entry !== 'object') return false;
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  for (const h of hooks) {
+    if (h && typeof h.command === 'string' && h.command.includes(marker)) return true;
+  }
+  return false;
+}
+
+function _installStatusLine(settings, cmd, force) {
+  const existing = settings.statusLine;
+  if (existing && typeof existing === 'object' && existing.command) {
+    if (String(existing.command).includes(NP_STATUSLINE_MARKER)) {
+      settings.statusLine = { type: 'command', command: cmd };
+      return { action: 'updated', existed: true };
+    }
+    if (!force) {
+      return { action: 'skipped-existing', existed: true, existingCommand: existing.command };
+    }
+    settings.statusLine = { type: 'command', command: cmd };
+    return { action: 'overwrote', existed: true };
+  }
+  settings.statusLine = { type: 'command', command: cmd };
+  return { action: 'installed', existed: false };
+}
+
+function _installPostToolUse(settings, cmd) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+  const list = settings.hooks.PostToolUse;
+  for (const entry of list) {
+    if (_containsNpHook(entry, NP_CTX_MONITOR_MARKER)) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      for (const h of hooks) {
+        if (h && typeof h.command === 'string' && h.command.includes(NP_CTX_MONITOR_MARKER)) {
+          h.command = cmd;
+          h.type = 'command';
+        }
+      }
+      return { action: 'updated' };
+    }
+  }
+  list.push({
+    matcher: '.*',
+    hooks: [{ type: 'command', command: cmd }],
+  });
+  return { action: 'installed' };
+}
+
+function _removeStatusLine(settings) {
+  const existing = settings.statusLine;
+  if (existing && typeof existing === 'object'
+      && typeof existing.command === 'string'
+      && existing.command.includes(NP_STATUSLINE_MARKER)) {
+    delete settings.statusLine;
+    return { action: 'removed' };
+  }
+  return { action: 'not-ours' };
+}
+
+function _removePostToolUse(settings) {
+  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return { action: 'absent' };
+  const filtered = [];
+  for (const entry of settings.hooks.PostToolUse) {
+    if (_containsNpHook(entry, NP_CTX_MONITOR_MARKER)) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      const keptHooks = hooks.filter((h) => !(h && typeof h.command === 'string' && h.command.includes(NP_CTX_MONITOR_MARKER)));
+      if (keptHooks.length > 0) {
+        filtered.push(Object.assign({}, entry, { hooks: keptHooks }));
+      }
+      continue;
+    }
+    filtered.push(entry);
+  }
+  settings.hooks.PostToolUse = filtered;
+  if (filtered.length === 0) delete settings.hooks.PostToolUse;
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  return { action: 'removed' };
+}
+
+function installClaudeHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || process.cwd();
+  const scope = o.scope === 'global' ? 'global' : 'local';
+  const force = !!o.force;
+  const which = o.which || 'both';
+  const settingsPath = _settingsPath(scope, projectRoot);
+
+  const statuslineCmd = _hookCommand(STATUSLINE_REL, scope, projectRoot);
+  const ctxMonitorCmd = _hookCommand(CTX_MONITOR_REL, scope, projectRoot);
+
+  const statuslineAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, STATUSLINE_REL);
+  const ctxMonitorAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, CTX_MONITOR_REL);
+
+  if (which === 'statusline' || which === 'both') {
+    if (!fs.existsSync(statuslineAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Statusline hook script not found: ' + statuslineAbs + '. Run `npx nubos-pilot` install first.',
+        { script: statuslineAbs },
+      );
+    }
+  }
+  if (which === 'ctx-monitor' || which === 'both') {
+    if (!fs.existsSync(ctxMonitorAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Ctx-monitor hook script not found: ' + ctxMonitorAbs,
+        { script: ctxMonitorAbs },
+      );
+    }
+  }
+
+  const settings = _readJsonSafe(settingsPath);
+  const results = {};
+
+  if (which === 'statusline' || which === 'both') {
+    results.statusline = _installStatusLine(settings, statuslineCmd, force);
+  }
+  if (which === 'ctx-monitor' || which === 'both') {
+    results.ctxMonitor = _installPostToolUse(settings, ctxMonitorCmd);
+  }
+
+  if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
+
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { dryRun: false, path: settingsPath, results };
+}
+
+function uninstallClaudeHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || process.cwd();
+  const scope = o.scope === 'global' ? 'global' : 'local';
+  const settingsPath = _settingsPath(scope, projectRoot);
+  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' } } };
+
+  const settings = _readJsonSafe(settingsPath);
+  const results = {
+    statusline: _removeStatusLine(settings),
+    ctxMonitor: _removePostToolUse(settings),
+  };
+  if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { dryRun: false, path: settingsPath, results };
+}
+
+module.exports = {
+  installClaudeHooks,
+  uninstallClaudeHooks,
+  STATUSLINE_REL,
+  CTX_MONITOR_REL,
+  NP_STATUSLINE_MARKER,
+  NP_CTX_MONITOR_MARKER,
+  _settingsPath,
+  _hookCommand,
+};

package/lib/install/claude-hooks.test.cjs

@@ -0,0 +1,163 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const mod = require('./claude-hooks.cjs');
+
+function _mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-'));
+  fs.mkdirSync(path.join(dir, '.claude'), { recursive: true });
+  fs.mkdirSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-statusline.js'), '// stub\n');
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-ctx-monitor.js'), '// stub\n');
+  return dir;
+}
+
+test('claude-hooks: fresh install writes both hooks to local settings', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.dryRun, false);
+    assert.equal(res.results.statusline.action, 'installed');
+    assert.equal(res.results.ctxMonitor.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.type, 'command');
+    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+    assert.ok(Array.isArray(settings.hooks.PostToolUse));
+    assert.equal(settings.hooks.PostToolUse[0].matcher, '.*');
+    assert.ok(settings.hooks.PostToolUse[0].hooks[0].command.includes('np-ctx-monitor.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: existing foreign statusLine is preserved without force', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo my-custom-bar' },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.statusline.action, 'skipped-existing');
+    assert.equal(res.results.statusline.existingCommand, 'echo my-custom-bar');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.command, 'echo my-custom-bar');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: --force overwrites foreign statusLine', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo other' },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', force: true });
+    assert.equal(res.results.statusline.action, 'overwrote');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: re-install is idempotent (updates nubos-pilot hook path)', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    const res2 = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res2.results.statusline.action, 'updated');
+    assert.equal(res2.results.ctxMonitor.action, 'updated');
+    const settings = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
+    assert.equal(settings.hooks.PostToolUse.length, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: preserves unrelated PostToolUse hooks', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      hooks: {
+        PostToolUse: [
+          { matcher: 'Bash', hooks: [{ type: 'command', command: 'echo other-hook' }] },
+        ],
+      },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'ctx-monitor' });
+    assert.equal(res.results.ctxMonitor.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.hooks.PostToolUse.length, 2);
+    assert.equal(settings.hooks.PostToolUse[0].matcher, 'Bash');
+    assert.ok(settings.hooks.PostToolUse[1].hooks[0].command.includes('np-ctx-monitor.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: uninstall removes only our entries', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo custom' },
+      hooks: { PostToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'echo foreign' }] }] },
+    }));
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'ctx-monitor' });
+    const res = mod.uninstallClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.ctxMonitor.action, 'removed');
+    assert.equal(res.results.statusline.action, 'not-ours');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.command, 'echo custom');
+    assert.equal(settings.hooks.PostToolUse.length, 1);
+    assert.equal(settings.hooks.PostToolUse[0].matcher, 'Bash');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: missing hook script throws structured error', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-no-scripts-'));
+  try {
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local' }),
+      (err) => err && err.code === 'claude-hooks-script-missing',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: dryRun returns planned settings without writing', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', dryRun: true });
+    assert.equal(res.dryRun, true);
+    assert.ok(res.settings.statusLine);
+    assert.equal(fs.existsSync(res.path), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: invalid JSON in settings yields structured error', () => {
+  const dir = _mkSandbox();
+  try {
+    fs.writeFileSync(path.join(dir, '.claude', 'settings.local.json'), '{broken');
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local' }),
+      (err) => err && err.code === 'claude-settings-invalid-json',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/text-mode.cjs

@@ -5,7 +5,7 @@ const path = require('node:path');
 const { findProjectRoot, NubosPilotError } = require('./core.cjs');
 
 const DEFAULT_TEXT_MODE = false;
-const CLAUDE_ENV_KEYS = ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'];
+const CLAUDE_ENV_KEYS = [];
 
 function _coerceBool(raw) {
   if (raw === true || raw === false) return raw;

package/lib/text-mode.test.cjs

@@ -29,32 +29,21 @@ test('text-mode: default without config or runtime env is false', () => {
   }
 });
 
-test('text-mode: CLAUDECODE=1 in env flips default to true', () => {
+test('text-mode: CLAUDECODE=1 no longer flips to true (Claude Code uses AskUserQuestion)', () => {
   const dir = _mkSandbox();
   try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), true);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), false);
     const detail = tm.resolveTextModeDetail(dir, { CLAUDECODE: '1' });
-    assert.deepEqual(detail, { enabled: true, source: 'runtime' });
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('text-mode: CLAUDE_CODE_ENTRYPOINT non-empty flips to true', () => {
-  const dir = _mkSandbox();
-  try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDE_CODE_ENTRYPOINT: 'cli' }), true);
+    assert.deepEqual(detail, { enabled: false, source: 'default' });
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test('text-mode: env value "0" or "false" does not flip', () => {
+test('text-mode: CLAUDE_CODE_ENTRYPOINT no longer flips to true', () => {
   const dir = _mkSandbox();
   try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '0' }), false);
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: 'false' }), false);
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '' }), false);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDE_CODE_ENTRYPOINT: 'cli' }), false);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -71,7 +60,7 @@ test('text-mode: config workflow.text_mode=true wins over absent runtime', () =>
   }
 });
 
-test('text-mode: config workflow.text_mode=false overrides CLAUDECODE runtime', () => {
+test('text-mode: config workflow.text_mode=false stays false under CLAUDECODE env', () => {
   const dir = _mkSandbox();
   try {
     _writeConfig(dir, { workflow: { text_mode: false } });
@@ -97,11 +86,11 @@ test('text-mode: config workflow.text_mode="true" string coerced to boolean', ()
   }
 });
 
-test('text-mode: config missing workflow.text_mode falls through to runtime detection', () => {
+test('text-mode: config missing workflow.text_mode falls through to default (false)', () => {
   const dir = _mkSandbox();
   try {
     _writeConfig(dir, { response_language: 'de' });
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), true);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), false);
     assert.equal(tm.resolveTextMode(dir, {}), false);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -131,9 +120,9 @@ test('text-mode: readConfigTextMode throws on invalid JSON', () => {
   }
 });
 
-test('text-mode: detectRuntimeTextMode honors multiple env keys', () => {
-  assert.equal(tm.detectRuntimeTextMode({ CLAUDECODE: '1' }), true);
-  assert.equal(tm.detectRuntimeTextMode({ CLAUDE_CODE_ENTRYPOINT: 'cli' }), true);
+test('text-mode: detectRuntimeTextMode returns false for all envs (no runtime auto-flip anymore)', () => {
+  assert.equal(tm.detectRuntimeTextMode({ CLAUDECODE: '1' }), false);
+  assert.equal(tm.detectRuntimeTextMode({ CLAUDE_CODE_ENTRYPOINT: 'cli' }), false);
   assert.equal(tm.detectRuntimeTextMode({ OTHER: '1' }), false);
   assert.equal(tm.detectRuntimeTextMode({}), false);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "AI-driven planning and execution tool for code projects",
   "homepage": "https://github.com/Nubos-AI/nubos-pilot",
   "repository": {

package/templates/claude/payload/hooks/np-ctx-monitor.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const WARN_THRESHOLD = 35;
+const CRITICAL_THRESHOLD = 25;
+const DEBOUNCE_TOOLS = 5;
+
+function readStdinJson() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve({});
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    const timer = setTimeout(() => {
+      try { process.stdin.removeAllListeners(); } catch {}
+      resolve(safeParse(buf));
+    }, 500);
+    process.stdin.on('data', (c) => { buf += c; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+  });
+}
+
+function safeParse(s) {
+  try { return s ? JSON.parse(s) : {}; } catch { return {}; }
+}
+
+function severityFor(remaining) {
+  if (remaining <= CRITICAL_THRESHOLD) return 'critical';
+  if (remaining <= WARN_THRESHOLD) return 'warning';
+  return 'normal';
+}
+
+function sanitizeSid(sid) {
+  return String(sid || '').replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+(async () => {
+  let payload = {};
+  try { payload = await readStdinJson(); } catch { payload = {}; }
+  const sid = payload && payload.session_id;
+  if (!sid) { process.exit(0); return; }
+  const safeSid = sanitizeSid(sid);
+  const bridgePath = path.join(os.tmpdir(), 'claude-ctx-' + safeSid + '.json');
+  if (!fs.existsSync(bridgePath)) { process.exit(0); return; }
+
+  let bridge;
+  try { bridge = JSON.parse(fs.readFileSync(bridgePath, 'utf-8')); } catch { process.exit(0); return; }
+  const remaining = Number(bridge && bridge.usable_remaining_pct);
+  if (!Number.isFinite(remaining)) { process.exit(0); return; }
+
+  const statePath = path.join(os.tmpdir(), 'claude-ctx-warn-' + safeSid + '.json');
+  let state = { tool_count: 0, last_warn_at: -999, last_severity: 'normal' };
+  try {
+    const existing = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    state = Object.assign(state, existing);
+  } catch {}
+  state.tool_count = Number(state.tool_count || 0) + 1;
+
+  const sev = severityFor(remaining);
+  const escalated = sev !== 'normal' && sev !== state.last_severity && state.last_severity !== 'critical';
+  const firstWarn = state.last_severity === 'normal' && sev !== 'normal';
+  const enoughGap = (state.tool_count - Number(state.last_warn_at || -999)) >= DEBOUNCE_TOOLS;
+
+  if (sev === 'normal') {
+    state.last_severity = 'normal';
+    try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+    process.exit(0); return;
+  }
+
+  if (!firstWarn && !escalated && !enoughGap) {
+    try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+    process.exit(0); return;
+  }
+
+  state.last_warn_at = state.tool_count;
+  state.last_severity = sev;
+  try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+
+  const msg = sev === 'critical'
+    ? 'CONTEXT CRITICAL: only ' + remaining + '% of usable context remaining. Stop taking new work — save state now with /np:pause-work before autocompact triggers.'
+    : 'CONTEXT LOW: ' + remaining + '% of usable context remaining. Wrap up the current task and consider /np:pause-work soon.';
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: '[nubos-pilot ctx-monitor] ' + msg,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+})().catch(() => { process.exit(0); });

package/templates/claude/payload/hooks/np-statusline.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const BAR_WIDTH = 10;
+const AUTOCOMPACT_BUFFER = 0.835;
+const DEFAULT_WINDOW = 200_000;
+const EXTENDED_WINDOW = 1_000_000;
+
+function readStdinJson() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve({});
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    const timer = setTimeout(() => {
+      try { process.stdin.removeAllListeners(); } catch {}
+      resolve(safeParse(buf));
+    }, 500);
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+  });
+}
+
+function safeParse(s) {
+  try { return s ? JSON.parse(s) : {}; } catch { return {}; }
+}
+
+function modelWindow(payload) {
+  const id = String((payload && payload.model && payload.model.id) || '');
+  const name = String((payload && payload.model && payload.model.display_name) || '');
+  const s = (id + ' ' + name).toLowerCase();
+  if (s.includes('[1m]') || /\b1m\b/.test(s) || s.includes('1-m') || s.includes('1000k')) {
+    return EXTENDED_WINDOW;
+  }
+  return DEFAULT_WINDOW;
+}
+
+function lastUsage(transcriptPath) {
+  if (!transcriptPath) return null;
+  let raw;
+  try { raw = fs.readFileSync(transcriptPath, 'utf-8'); } catch { return null; }
+  const lines = raw.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    const usage = obj && obj.message && obj.message.usage;
+    if (!usage || typeof usage !== 'object') continue;
+    const input = Number(usage.input_tokens || 0);
+    const cacheCreation = Number(usage.cache_creation_input_tokens || 0);
+    const cacheRead = Number(usage.cache_read_input_tokens || 0);
+    const output = Number(usage.output_tokens || 0);
+    const total = input + cacheCreation + cacheRead + output;
+    if (!Number.isFinite(total) || total <= 0) continue;
+    return { input, cacheCreation, cacheRead, output, total };
+  }
+  return null;
+}
+
+function renderBar(used, limit) {
+  const fraction = Math.max(0, Math.min(1, used / limit));
+  const ofUsable = Math.max(0, Math.min(1, fraction / AUTOCOMPACT_BUFFER));
+  const pct = Math.round(ofUsable * 100);
+  const filled = Math.round(ofUsable * BAR_WIDTH);
+  const bar = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+  let color = '\x1b[32m';
+  let suffix = '';
+  if (pct >= 80) { color = '\x1b[31m'; suffix = ' 💀'; }
+  else if (pct >= 65) { color = '\x1b[38;5;208m'; }
+  else if (pct >= 50) { color = '\x1b[33m'; }
+  return color + bar + '\x1b[0m ' + pct + '%' + suffix;
+}
+
+function writeBridge(payload, usage, limit) {
+  const sid = payload && payload.session_id;
+  if (!sid) return;
+  const bridgePath = path.join(os.tmpdir(), 'claude-ctx-' + String(sid).replace(/[^a-zA-Z0-9._-]/g, '_') + '.json');
+  const data = {
+    session_id: sid,
+    used: usage.total,
+    limit: limit,
+    usable_remaining_pct: Math.max(0, Math.round(((AUTOCOMPACT_BUFFER * limit) - usage.total) / (AUTOCOMPACT_BUFFER * limit) * 100)),
+    updated_at: new Date().toISOString(),
+  };
+  try { fs.writeFileSync(bridgePath, JSON.stringify(data)); } catch {}
+}
+
+(async () => {
+  let payload = {};
+  try { payload = await readStdinJson(); } catch { payload = {}; }
+  const limit = modelWindow(payload);
+  const usage = lastUsage(payload && payload.transcript_path);
+  const prefix = '\x1b[38;5;33mnubos-pilot\x1b[0m';
+  if (!usage) {
+    process.stdout.write(prefix);
+    return;
+  }
+  writeBridge(payload, usage, limit);
+  const bar = renderBar(usage.total, limit);
+  const modelName = (payload && payload.model && payload.model.display_name) || '';
+  const tail = modelName ? '  \x1b[2m' + modelName + '\x1b[0m' : '';
+  process.stdout.write(prefix + '  ctx ' + bar + tail);
+})().catch(() => {
+  process.stdout.write('\x1b[38;5;33mnubos-pilot\x1b[0m');
+});

package/workflows/add-todo.md

@@ -47,10 +47,10 @@ through `lib/layout.cjs.slugify` (strips to `[a-z0-9-]` only;
 filename-injection mitigation) and validates the description length
 (<= 500 chars) before any filesystem write occurs.
 
-**Text-mode routing.** If `text_mode == true`, skip every `np-tools.cjs askuser`
-call below and render questions as plain-text numbered lists in the main
-chat. Auto-enabled in Claude Code (CLAUDECODE=1); opt-in via
-`.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ## Create Pending Dir
 

package/workflows/discuss-phase.md

@@ -34,22 +34,20 @@ Parse JSON for: `milestone`, `milestone_id`, `milestone_dir`, `milestone_name`,
 `milestone_context_path`, `has_context`, `has_milestone_dir`, `goal`,
 `requirements`, `agent_skills`, `mode`, `text_mode`, `text_mode_source`.
 
-**Text-mode routing (SSOT = INIT payload).** If `text_mode` is `true`, do
-**not** shell out to `np-tools.cjs askuser` for any prompt in this workflow.
-Present every question inline as a plain-text numbered list and wait for the
-user's reply in the main chat. This is the correct path whenever:
-
-- `text_mode_source == "runtime"` → Claude Code Bash has no TTY and cannot
-  forward interactive menu selections; the askuser marker-block protocol
-  never completes.
-- `text_mode_source == "config"` → the user explicitly opted into text mode
-  via `.nubos-pilot/config.json` → `workflow.text_mode`.
-
-When text mode is active, skip every `node .nubos-pilot/bin/np-tools.cjs
-askuser …` block below and substitute the plain-text equivalent. Collect the
-answers from the user's reply, then proceed to the next step as normal. The
-rest of the workflow (validation, canonical-ref accumulation, template
-render, commit) is unchanged.
+**Askuser routing (SSOT = INIT payload).** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a **spec**, not a literal command. Pick the path once at Initialize:
+
+- **Claude Code runtime** (you are running inside Claude Code — the `AskUserQuestion` tool is available to you): **do not** shell out to `np-tools.cjs askuser`. Parse the JSON spec inside each askuser block and call the native `AskUserQuestion` tool directly with one question entry:
+  - `type: "select"` → `{ question, header, multiSelect: false, options: [{label, description}...] }`
+  - `type: "multiselect"` → `{ question, header, multiSelect: true, options: [{label, description}...] }`
+  - `type: "confirm"` → single question with `options: [{label: "Yes"}, {label: "No"}]`, `multiSelect: false`
+  - `type: "input"` → ask as a plain free-form question in the chat; the user replies inline
+  Use a short `header` (≤12 chars) that labels the category, e.g. `"Discuss"`, `"Scope"`, `"Overwrite?"`. This is the default path and gives the user a real selection menu.
+
+- **`text_mode == true`** (INIT payload): skip every askuser block and render every question inline as a plain-text numbered list; the user replies with the number. This path is opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+
+- **Other runtime with TTY** (Codex, Gemini, …): run the shell `node .nubos-pilot/bin/np-tools.cjs askuser --json '…'` block verbatim.
+
+`text_mode_source` in the INIT payload (`config` / `default`) is informational only — it does not change the routing above.
 
 If the user passed `--assumptions`, route to
 `workflows/discuss-phase-assumptions.md` and exit this workflow.
@@ -142,33 +140,19 @@ Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
 ## Answer Validation
 
 <answer_validation>
-**Routing decision (made once at Initialize):** If INIT payload
-`text_mode == true`, skip every `np-tools.cjs askuser` call in this workflow
-and use plain-text numbered lists in the main chat instead. The
-`text_mode_source` field (`runtime` / `config` / `default`) tells you why
-text mode is active — it is informational only and does not change behavior.
-
-**When text_mode is false and askuser is used — per-prompt validation:**
-1. If `askuser` exits with structured error `askuser-no-tty` (exit code 1,
-   stderr JSON with `"code":"askuser-no-tty"`), that means the runtime
-   detection missed something; **skip retry** and treat the remainder of the
-   workflow as text-mode (plain-text numbered lists).
-2. If the response is empty or whitespace-only (exit 0 but no value), retry
-   the question once with the same parameters.
-3. If still empty, present the options as a plain-text numbered list and ask
-   the user to type their choice number.
+**Routing was decided at Initialize** (see "Askuser routing" section above). This section documents per-prompt validation only.
+
+**Claude Code path (`AskUserQuestion` tool):** the tool guarantees a non-empty selection; no validation needed.
+
+**Shell askuser path (other runtimes with TTY):**
+1. If `askuser` exits with structured error `askuser-no-tty` (exit code 1, stderr JSON with `"code":"askuser-no-tty"`), that means the runtime detection missed something; **skip retry** and treat the remainder of the workflow as text-mode (plain-text numbered lists).
+2. If the response is empty or whitespace-only (exit 0 but no value), retry the question once with the same parameters.
+3. If still empty, present the options as a plain-text numbered list and ask the user to type their choice number.
 Never proceed with an empty answer.
 
-**Enable text mode:**
-- Auto-detected: any Claude Code session (`CLAUDECODE=1` /
-  `CLAUDE_CODE_ENTRYPOINT` set) — default behavior, no user action needed.
-- Opt-in per project: set `workflow.text_mode: true` in
-  `.nubos-pilot/config.json`.
-- Opt-out per project: set `workflow.text_mode: false` in
-  `.nubos-pilot/config.json` (overrides runtime detection).
+**Text-mode (numbered-list path):** user reply must parse as a valid index (1-N) for select/multiselect, `y/n` for confirm, or any non-empty string for input. Re-ask on invalid input.
 
-Text mode applies to ALL workflows that emit `text_mode` in their INIT
-payload, not just discuss-phase.
+**Enable text mode** (force the numbered-list path regardless of runtime): set `workflow.text_mode: true` in `.nubos-pilot/config.json`. Useful for remote-control setups or runtimes where neither `AskUserQuestion` nor TTY stdin are reliable.
 </answer_validation>
 
 ## Process

package/workflows/discuss-project.md

@@ -61,6 +61,11 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 narrative status updates, and the prose written into PROJECT.md sections.
 Supersedes CLAUDE.md managed block.
 
+**Askuser routing.** The "Use `np-tools.cjs askuser` for every prompt" rule below is SC-5 gateway enforcement — the JSON spec must pass through np-tools for logging/validation. Pick the presentation path:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip shell askuser calls and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute `node .nubos-pilot/bin/np-tools.cjs askuser --json '…'` directly.
+
 Parse: `mode`, `sub_mode` (`bootstrap` or `refresh`), `project_md_exists`,
 `scan_context`, `questions[]`, `required_fields[]`.
 

package/workflows/execute-phase.md

@@ -32,11 +32,10 @@ directive in CLAUDE.md managed block.
 
 Parse JSON for: `milestone`, `milestone_id`, `milestone_dir`, `waves[]` (each with `wave` (= slice number), `slice_id`, `slice_full_id`, `slice_dir`, `tasks[]`), `total_tasks`, `slice_count`, `executor_tier`, `text_mode`, `text_mode_source`, `agent_skills`.
 
-**Text-mode routing.** If `text_mode == true`, skip every `np-tools.cjs askuser`
-call below (including the orphan-checkpoint and empty-milestone prompts)
-and render the options as a plain-text numbered list in the main chat.
-Auto-enabled in Claude Code (CLAUDECODE=1); opt-in via
-`.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below (including the orphan-checkpoint and empty-milestone prompts) is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 `PLAN_ID` is iterated per slice as `${milestone_id}-${slice_id}` (e.g. `M001-S001`). `TASK_ID` is iterated from each slice's `tasks[]` (e.g. `M001-S001-T0001`).
 

package/workflows/new-milestone.md

@@ -62,11 +62,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 user-facing output, and any prose written into milestone artefacts (YAML
 keys, IDs, and identifiers stay canonical English). Supersedes CLAUDE.md.
 
-**Text-mode routing.** If INIT payload `text_mode == true`, skip every
-`np-tools.cjs askuser` call below and render each question as a plain-text
-prompt in the main chat; collect the answer inline. Auto-enabled in Claude
-Code (CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` →
-`workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 Payload: three questions — `milestone_name`, `milestone_goal`, `create_req_prefix` (confirm).
 

package/workflows/new-project.md

@@ -126,11 +126,10 @@ user-facing output, and any narrative prose written into PROJECT.md /
 REQUIREMENTS.md (field names and YAML keys stay canonical English).
 Supersedes CLAUDE.md.
 
-**Text-mode routing.** If INIT payload `text_mode == true`, skip every
-`np-tools.cjs askuser` call below and render each question as a plain-text
-prompt in the main chat; collect the user's answer inline and move on.
-Auto-enabled in Claude Code (CLAUDECODE=1); opt-in via
-`.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ```bash
 ANS_PROJECT_NAME=$(node .nubos-pilot/bin/np-tools.cjs askuser --json '{"type":"input","prompt":"Project name?"}')

package/workflows/note.md

@@ -52,16 +52,16 @@ into `$TEXT`. Empty text after stripping is an error — there is no
 `list` or `promote` subcommand here (deferred to a future
 capture-management plan).
 
-**Text-mode routing.** Resolve once at the start:
+**Askuser routing.** Resolve once at the start:
 
 ```bash
 TEXT_MODE=$(node .nubos-pilot/bin/np-tools.cjs text-mode 2>/dev/null || echo false)
 ```
 
-If `$TEXT_MODE == "true"`, skip every `np-tools.cjs askuser` call below and
-render questions as plain-text numbered lists in the main chat. Auto-enabled
-in Claude Code (CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` →
-`workflow.text_mode`.
+Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`$TEXT_MODE == "true"`**: skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ## Compute Paths
 

package/workflows/plan-phase.md

@@ -88,10 +88,10 @@ prompts as a system-level rule. This supersedes any directive in CLAUDE.md.
 
 Parse JSON for: `milestone`, `milestone_id`, `milestone_dir`, `milestone_context_path`, `milestone_roadmap_path`, `milestone_meta_path`, `name`, `goal`, `requirements`, `success_criteria`, `has_context`, `has_roadmap`, `has_meta`, `existing_slices[]`, `planner_tier`, `checker_tier`, `text_mode`, `text_mode_source`, `agent_skills`.
 
-**Text-mode routing.** If `text_mode == true`, skip every `np-tools.cjs askuser`
-call below and present questions as plain-text numbered lists in the main
-chat. Auto-enabled in Claude Code (CLAUDECODE=1); opt-in per-project via
-`.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 `PLAN_ID` and `TASK_ID` default to `${milestone_id}-plan` / `${milestone_id}-planner-run` for the metrics records.
 

package/workflows/propose-milestones.md

@@ -70,7 +70,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Language (SSOT = `.nubos-pilot/config.json` → `response_language`).**
 `$LANG_DIRECTIVE` is authoritative. Obey it for askuser prompt texts, AI-facing reasoning shown to the user, and any narrative prose. YAML keys, milestone IDs, and status strings stay canonical English.
 
-**Text-mode routing.** If INIT payload `text_mode == true`, skip every `np-tools.cjs askuser` call below and render each question as a plain-text prompt in the main chat; collect the answer inline. Auto-enabled in Claude Code (CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 Parse INIT for: `milestones[]` (each with `id`, `name`, `goal`, `status`, `classification`, `slice_count`, `context`, `touchable`, `modification_requires_confirm`), `project_md`, `requirements_md`, `project_has_tbd`, `current_state_milestone`, `next_milestone_number`, `guidance`.
 

package/workflows/research-phase.md

@@ -107,10 +107,10 @@ project language. This supersedes CLAUDE.md.
 `RUNTIME` is resolved once here and reused by the metrics-record call at the
 researcher spawn site (Step 4) per D-06 workflow-writer pattern.
 
-**Text-mode routing.** If `text_mode == true` in the payload below, skip every
-`np-tools.cjs askuser` call in this workflow and render questions as
-plain-text numbered lists in the main chat. Auto-enabled in Claude Code
-(CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 The payload shape:
 

package/workflows/resume-work.md

@@ -24,10 +24,10 @@ askuser prompts. When spawning the np-executor to continue a checkpoint,
 pass `$LANG_DIRECTIVE` into the spawn prompt so resumed task summaries
 follow the project language. Supersedes CLAUDE.md.
 
-**Text-mode routing.** If INIT payload `text_mode == true`, skip every
-`np-tools.cjs askuser` call below and render prompts as plain-text numbered
-lists in the main chat. Auto-enabled in Claude Code (CLAUDECODE=1); opt-in
-via `.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ## Execution
 

package/workflows/session-report.md

@@ -62,10 +62,10 @@ canonical English. Supersedes CLAUDE.md.
 TEXT_MODE=$(node .nubos-pilot/bin/np-tools.cjs text-mode 2>/dev/null || echo false)
 ```
 
-If `$TEXT_MODE == "true"`, skip every `np-tools.cjs askuser` call below and
-render questions as plain-text numbered lists in the main chat. Auto-enabled
-in Claude Code (CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` →
-`workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`$TEXT_MODE == "true"`** (from the check above, or INIT payload `text_mode == true`): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 The filename format is `YYYY-MM-DDTHHMM-session-report.md` (D-17 —
 4-char HHMM, no seconds, local time) so reports sort

package/workflows/validate-phase.md

@@ -33,10 +33,10 @@ field names stay English. Supersedes CLAUDE.md.
 
 Parse JSON for: `milestone`, `milestone_id`, `milestone_dir`, `milestone_name`, `slice_uat`, `text_mode`, `text_mode_source`.
 
-**Text-mode routing.** If `text_mode == true`, skip every `np-tools.cjs askuser`
-call in this workflow and render options as plain-text numbered lists in
-the main chat. Auto-enabled in Claude Code (CLAUDECODE=1); opt-in via
-`.nubos-pilot/config.json` → `workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ```bash
 MILESTONE_ID=$(echo "$INIT" | jq -r '.milestone_id')

package/workflows/verify-work.md

@@ -31,11 +31,10 @@ CLAUDE.md.
 
 Parse: `milestone`, `milestone_id`, `milestone_dir`, `milestone_name`, `success_criteria`, `draft_results`, `verification_path`, `slice_uat`, `verifier_tier`, `text_mode`, `text_mode_source`, `agent_skills`.
 
-**Text-mode routing.** If `text_mode == true`, skip every `np-tools.cjs askuser`
-call below (including the Pass-2 `needs_user_confirm` gate) and render the
-options as a plain-text numbered list in the main chat. Auto-enabled in
-Claude Code (CLAUDECODE=1); opt-in via `.nubos-pilot/config.json` →
-`workflow.text_mode`.
+**Askuser routing.** Every `node .nubos-pilot/bin/np-tools.cjs askuser …` block below (including the Pass-2 `needs_user_confirm` gate) is a spec, not a literal command. Pick the path once at Initialize:
+- **Claude Code** (native `AskUserQuestion` tool is available): parse the JSON spec and call `AskUserQuestion` directly. `select` → `multiSelect: false`; `multiselect` → `multiSelect: true`; `confirm` → `options: [{label: "Yes"}, {label: "No"}]`; `input` → ask free-form in chat. Use a short `header` (≤12 chars).
+- **`text_mode == true`** (INIT payload): skip every askuser block and render questions as plain-text numbered lists. Opt-in via `.nubos-pilot/config.json` → `workflow.text_mode`.
+- **Other runtime with TTY** (Codex, Gemini, …): execute the shell `askuser` block verbatim.
 
 ## Pass 1 — verifier agent