@kienntpixon/dieu-phoi 0.1.1 → 0.2.0

package/lib/aggregate.cjs

@@ -339,14 +339,80 @@ function buildSteers(tasks, steers, agents) {
   }).sort((a, b) => b.steer_rate - a.steer_rate || a.task_type.localeCompare(b.task_type));
 }
 
+function finiteNum(v) {
+  return typeof v === 'number' && isFinite(v) ? v : null;
+}
+
+/**
+ * Orchestration cost (CONTRACT "Thước đo" mục 6). Sessions = distinct non-empty `session_id` over
+ * dispatch events. Per session: ctx = max orch_ctx_tokens, usd = max orch_cum_usd, growth = max of
+ * max(0, orch_ctx_tokens - orch_ctx_baseline) over dispatches carrying both, comp = max orch_compactions
+ * (numbers only). compactions_total = sum of per-session comp, compactions_max = max.
+ * Each agent belongs to the session of its FIRST dispatch (file order); sub_usd_total sums the
+ * cost_usd of every complete of those agents (internal completes never have a dispatch, so never count).
+ */
+function orchestrationSummary(events) {
+  const sessions = new Map();
+  const agentSession = new Map();
+  for (const ev of events) {
+    if (!ev || ev.kind !== 'dispatch' || typeof ev.session_id !== 'string' || !ev.session_id) continue;
+    const sid = ev.session_id;
+    if (!sessions.has(sid)) sessions.set(sid, { ctx: null, usd: null, growth: null, comp: null });
+    const s = sessions.get(sid);
+    const c = finiteNum(ev.orch_ctx_tokens);
+    const u = finiteNum(ev.orch_cum_usd);
+    if (c !== null && (s.ctx === null || c > s.ctx)) s.ctx = c;
+    if (u !== null && (s.usd === null || u > s.usd)) s.usd = u;
+    const k = finiteNum(ev.orch_compactions);
+    if (k !== null && (s.comp === null || k > s.comp)) s.comp = k;
+    const b = finiteNum(ev.orch_ctx_baseline);
+    if (c !== null && b !== null) {
+      const g = Math.max(0, c - b);
+      if (s.growth === null || g > s.growth) s.growth = g;
+    }
+    if (typeof ev.agent_id === 'string' && ev.agent_id && !agentSession.has(ev.agent_id)) agentSession.set(ev.agent_id, sid);
+  }
+  let sub = 0;
+  for (const ev of events) {
+    if (!ev || ev.kind !== 'complete' || !agentSession.has(ev.agent_id)) continue;
+    const c = finiteNum(ev.cost_usd);
+    if (c !== null) sub += c;
+  }
+  const ctxs = [];
+  const growths = [];
+  const comps = [];
+  let orch = 0;
+  for (const s of sessions.values()) {
+    if (s.ctx !== null) ctxs.push(s.ctx);
+    if (s.growth !== null) growths.push(s.growth);
+    if (s.comp !== null) comps.push(s.comp);
+    if (s.usd !== null) orch += s.usd;
+  }
+  return {
+    sessions: sessions.size,
+    ctx_p50: round6(percentile(ctxs, 0.5)),
+    ctx_max: ctxs.length ? Math.max(...ctxs) : null,
+    growth_p50: round6(percentile(growths, 0.5)),
+    growth_max: growths.length ? Math.max(...growths) : null,
+    compactions_total: comps.reduce((x, y) => x + y, 0),
+    compactions_max: comps.length ? Math.max(...comps) : null,
+    orch_usd_total: round6(orch),
+    sub_usd_total: round6(sub),
+    orch_share: orch + sub > 0 ? round6(orch / (orch + sub)) : null,
+  };
+}
+
 function analyze(events, opts) {
   const { agents, userVerdicts, overrides, steers } = buildAgents(events);
   const tasks = buildTasks(agents, userVerdicts);
   const cells = buildCells(tasks, opts);
-  return { agents, tasks, cells, overrides, userVerdicts, steerEvents: steers, steers: buildSteers(tasks, steers, agents) };
+  return {
+    agents, tasks, cells, overrides, userVerdicts, steerEvents: steers, steers: buildSteers(tasks, steers, agents),
+    orchestration: orchestrationSummary(events),
+  };
 }
 
 module.exports = {
   MIN_N, FAIL_OUTCOMES, HEAVY_STEERS, CANONICAL_CELL_FIELDS, normalizeVerdict, isInternalComplete, buildAgents, buildTasks,
-  buildCells, buildSteers, canonicalCells, analyze, cellKey, mean, percentile, tsOf, steerIdOf,
+  buildCells, buildSteers, canonicalCells, orchestrationSummary, analyze, cellKey, mean, percentile, tsOf, steerIdOf,
 };

package/lib/args.cjs

@@ -3,7 +3,7 @@
 const path = require('path');
 const core = require('../hook.cjs');
 
-const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync']);
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync', 'approve']);
 
 /** Minimal argv parser: positionals, --k v, --k=v, boolean flags. */
 function parseArgs(argv) {

package/lib/choose.cjs

@@ -50,6 +50,9 @@ const DEFAULT_TIME_CAP_MIN = {
 };
 const DEFAULT_LAMBDA = { relaxed: 0.02, normal: 0.1, urgent: 1.0 };
 const DEFAULT_EXPLORE = 0.1;
+// Orchestrator context soft cap = allowed GROWTH in tokens over the session's first request (baseline:
+// system prompt + tools, ~60-70k). Core default = ceiling: a profile may only lower it.
+const DEFAULT_ORCH_CTX_SOFT_CAP = 60000;
 
 function tierName(i) {
   return `${LADDER[i].model}/${LADDER[i].effort}`;
@@ -121,7 +124,15 @@ function loadProfile(skillDir) {
   const timeCap = Object.assign({}, DEFAULT_TIME_CAP_MIN,
     r.time_cap_min && typeof r.time_cap_min === 'object' ? r.time_cap_min : {});
   const extra = Array.isArray(r.extra_task_types) ? r.extra_task_types.map(String) : [];
-  return { source, dept: r.dept || null, priors, lambda, explore_rate: explore, time_cap_min: timeCap, extra_task_types: extra };
+  let softCap = DEFAULT_ORCH_CTX_SOFT_CAP;
+  if (r.orch_ctx_soft_cap !== undefined && r.orch_ctx_soft_cap !== null) {
+    const v = Number(r.orch_ctx_soft_cap);
+    if (isFinite(v) && v > 0) softCap = Math.min(DEFAULT_ORCH_CTX_SOFT_CAP, Math.floor(v));
+  }
+  return {
+    source, dept: r.dept || null, priors, lambda, explore_rate: explore, time_cap_min: timeCap, extra_task_types: extra,
+    orch_ctx_soft_cap: softCap,
+  };
 }
 
 // ------------------------------------------------------------------ seeded RNG
@@ -461,6 +472,7 @@ function choose(opts) {
 }
 
 module.exports = {
+  DEFAULT_ORCH_CTX_SOFT_CAP,
   LADDER, DEFAULT_PRIORS, DEFAULT_LAMBDA, DEFAULT_TIME_CAP_MIN, ROUGH, tierIndex, tierName, parsePrior,
   parseTier, loadProfile, makeRng, betaSample, escalation, overridePrior, roughEstimate, choose, shortModel,
 };

package/lib/commands.cjs

@@ -55,8 +55,9 @@ function cmdSetup(opts) {
   const lines = [
     `Đã cài hook: ${res.hook}`,
     res.settings_changed
-      ? `Đã đăng ký PostToolUse(Agent) + SubagentStop trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
+      ? `Đã đăng ký PostToolUse(Agent) + SubagentStop + SessionStart(compact) trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
       : `settings.json đã có hook, không đổi gì (${res.settings})`,
+    `Thư mục báo cáo subagent: ${res.runs_dir} (quyền: ${res.permissions.allow.join(', ')} + additionalDirectories)`,
     `Phòng ban: ${res.config.dept || '(chưa đặt, dùng --dept)'}`,
     `Sink: ${res.config.sink_url ? res.config.sink_url : '(chưa có — log chỉ lưu cục bộ)'}`,
     `Skill: ${res.config.skill_dir || '(không thấy; dùng --skill-dir)'}${res.config.skill_version ? ` v${res.config.skill_version}` : ''}`,
@@ -87,8 +88,12 @@ async function cmdDoctor(opts) {
   add(major >= 18, 'node', `v${process.versions.node}${major >= 18 ? '' : ' (cần ≥ 18)'}`);
   add(fs.existsSync(ctx.paths.hook), 'hook', ctx.paths.hook);
   const reg = setupLib.registration(claudeDir);
-  add(reg.PostToolUse && reg.SubagentStop, 'settings',
-    `PostToolUse(Agent)=${reg.PostToolUse ? 'có' : 'thiếu'}, SubagentStop=${reg.SubagentStop ? 'có' : 'thiếu'} (${reg.file})`);
+  add(reg.PostToolUse && reg.SubagentStop && reg.SessionStart, 'settings',
+    `PostToolUse(Agent)=${reg.PostToolUse ? 'có' : 'thiếu'}, SubagentStop=${reg.SubagentStop ? 'có' : 'thiếu'}, SessionStart(compact)=${reg.SessionStart ? 'có' : 'thiếu'} (${reg.file})`);
+  const permOk = reg.permissions && reg.runs_dir_exists && !reg.legacy_permissions;
+  add(permOk, 'run-permissions', permOk
+    ? `${reg.permission_entries.allow.join(', ')} + additionalDirectories ${reg.permission_entries.dir}`
+    : `${!reg.permissions ? `thiếu quyền cho thư mục báo cáo ${reg.permission_entries.dir} (subagent nền sẽ không ghi được)` : (!reg.runs_dir_exists ? `chưa có thư mục ${reg.runs_dir}` : 'còn quyền cũ cho ~/.claude/dieu-phoi/runs (đường dẫn được bảo vệ, không dùng được)')} — chạy dieu-phoi setup`, 'CẢNH BÁO');
   const hasCfg = fs.existsSync(ctx.paths.config);
   add(hasCfg, 'config', hasCfg ? `${ctx.paths.config} dept=${ctx.config.dept || '-'}` : 'chưa có — chạy `dieu-phoi setup`');
   const sd = ctx.config.skill_dir;
@@ -124,6 +129,10 @@ async function cmdDoctor(opts) {
   add(true, 'internal-subagents', skipped && skipped.count
     ? `bỏ qua ${skipped.count} SubagentStop của subagent nội bộ Claude Code (lần cuối ${skipped.last_ts})`
     : 'chưa bỏ qua SubagentStop nội bộ nào');
+  const orch = measureOrch(opts, ctx, profileOrNull(opts, ctx));
+  if (orch.ctx_tokens !== null) {
+    add(!orch.over, 'orch-ctx', `session ${orch.session_id}: ${orch.ctx_tokens} token, tăng ${orch.ctx_growth}/${orch.soft_cap}, ≈ ${fmtUsd(orch.cum_usd)} — ${orch.advice}`, 'CẢNH BÁO');
+  }
   if (ctx.config.sink_url && ctx.config.sink_token) {
     try {
       const u = new URL(ctx.config.sink_url);
@@ -141,7 +150,7 @@ async function cmdDoctor(opts) {
     add(true, 'sink', 'chưa cấu hình (chỉ lưu cục bộ)');
   }
   const failed = checks.some((c) => c.level === 'LỖI');
-  if (opts.json) return { code: failed ? 1 : 0, out: JSON.stringify({ ok: !failed, checks }, null, 2) };
+  if (opts.json) return { code: failed ? 1 : 0, out: JSON.stringify({ ok: !failed, runs_dir: reg.runs_dir, checks }, null, 2) };
   const out = checks.map((c) => `[${c.level}] ${c.name}: ${c.detail}`).join('\n');
   return { code: failed ? 1 : 0, out };
 }
@@ -150,8 +159,9 @@ async function cmdDoctor(opts) {
 
 function cmdHook(opts) {
   const home = typeof opts['claude-dir'] === 'string' ? path.join(path.resolve(opts['claude-dir']), 'dieu-phoi') : undefined;
-  core.runHook({ home });
-  return { code: 0, out: null };
+  const r = core.runHook({ home });
+  // SessionStart(compact) returns the JSON to print; every other hook event prints nothing.
+  return { code: 0, out: r && typeof r.stdout === 'string' ? r.stdout : null };
 }
 
 async function cmdSync(opts) {
@@ -326,6 +336,76 @@ function cmdSteer(opts) {
   return { code: 0, out: `Đã ghi steer ${kind} (${steerId}) cho ${target}.` };
 }
 
+// ------------------------------------------------------------------ ctx (orchestrator context)
+
+/**
+ * Measure the orchestrating session: --session, else env CLAUDE_CODE_SESSION_ID; transcript found under
+ * <claude dir>/projects/<project>/<id>.jsonl. Never throws; ctx_tokens null when it cannot measure.
+ */
+function measureOrch(opts, ctx, prof) {
+  const sid = typeof opts.session === 'string' && opts.session ? opts.session
+    : (process.env.CLAUDE_CODE_SESSION_ID || null);
+  const softCap = (prof && prof.orch_ctx_soft_cap) || chooser.DEFAULT_ORCH_CTX_SOFT_CAP;
+  let u = { ctx_tokens: null, ctx_baseline: null, ctx_growth: null, cum_usd: null, compactions: null };
+  try {
+    const file = sid ? core.findSessionTranscript(claudeDirOf(opts), sid) : null;
+    if (file) {
+      u = core.orchestratorUsage(file, core.loadPricing(ctx), { cacheFile: core.orchCacheFile(ctx.paths, sid, file) });
+    }
+  } catch (_) { /* measurement never fails the caller */ }
+  const over = typeof u.ctx_growth === 'number' && u.ctx_growth > softCap;
+  let advice;
+  if (!sid) advice = 'Không đo được: không có session (thiếu CLAUDE_CODE_SESSION_ID, dùng --session <id>).';
+  else if (u.ctx_tokens === null) advice = 'Không đo được: không thấy transcript của session này.';
+  else if (over) advice = `Context điều phối đã tăng ${u.ctx_growth} token (nền ${u.ctx_baseline}, nay ${u.ctx_tokens}) vượt trần mềm ${softCap}: gõ /compact để nén phiên — trạng thái điều phối sẽ được nạp lại tự động.`;
+  else advice = `Context điều phối tăng ${u.ctx_growth}/${softCap} token so với nền ${u.ctx_baseline}, còn trong trần mềm.`;
+  return {
+    session_id: sid, ctx_tokens: u.ctx_tokens, ctx_baseline: u.ctx_baseline, ctx_growth: u.ctx_growth,
+    cum_usd: u.cum_usd, compactions: u.compactions, soft_cap: softCap, over, advice,
+  };
+}
+
+function profileOrNull(opts, ctx) {
+  try { return chooser.loadProfile(skillDirOf(opts, ctx)); } catch (_) { return null; }
+}
+
+function cmdCtx(opts) {
+  const ctx = ctxOf(opts);
+  const m = measureOrch(opts, ctx, profileOrNull(opts, ctx));
+  if (opts.json) return { code: 0, out: JSON.stringify(m) };
+  if (m.ctx_tokens === null) return { code: 0, out: m.advice };
+  return {
+    code: 0,
+    out: `session ${m.session_id}: context ${m.ctx_tokens} token, nền ${m.ctx_baseline}, tăng ${m.ctx_growth} (trần mềm ${m.soft_cap})${m.over ? ' — VƯỢT' : ''}, `
+      + `chi phí điều phối ≈ ${fmtUsd(m.cum_usd)}, đã nén ${m.compactions === null ? '?' : m.compactions} lần\n${m.advice}`,
+  };
+}
+
+function orchLine(o) {
+  if (!o || !o.sessions) return 'Điều phối: chưa có dispatch nào ghi session_id (cần core ≥ 0.2.0).';
+  return `Điều phối: ${o.sessions} phiên, context p50 ${o.ctx_p50 === null ? '-' : Math.round(o.ctx_p50)} / max ${o.ctx_max === null ? '-' : o.ctx_max} token (tăng so với nền p50 ${o.growth_p50 === null ? '-' : Math.round(o.growth_p50)} / max ${o.growth_max === null ? '-' : o.growth_max}), `
+    + `chi phí điều phối ${fmtUsd(o.orch_usd_total)} vs subagent ${fmtUsd(o.sub_usd_total)} (điều phối chiếm ${pct(o.orch_share)}); nén context ${o.compactions_total} lần (tối đa ${o.compactions_max === null ? '-' : o.compactions_max}/phiên).`;
+}
+
+// ------------------------------------------------------------------ state (re-injected after /compact)
+
+/**
+ * Orchestration state of one session rebuilt purely from events.jsonl (same builder the SessionStart(compact)
+ * hook uses). Session = --session, else env CLAUDE_CODE_SESSION_ID. Run dirs are pointed to, never read.
+ */
+function cmdState(opts) {
+  const ctx = ctxOf(opts);
+  const sid = typeof opts.session === 'string' && opts.session ? opts.session
+    : (process.env.CLAUDE_CODE_SESSION_ID || null);
+  if (!sid) {
+    if (opts.json) return { code: 0, out: JSON.stringify({ session_id: null, generated_at: core.nowIso(), runs_dir: null, plans: [], tasks: [] }) };
+    return { code: 0, out: 'Không có session (thiếu CLAUDE_CODE_SESSION_ID, dùng --session <id>).' };
+  }
+  const state = core.buildSessionState(core.readEvents(ctx), sid, { plansDir: ctx.paths.plans });
+  if (opts.json) return { code: 0, out: JSON.stringify(state, null, 2) };
+  return { code: 0, out: core.formatSessionState(state, core.STATE_TEXT_CAP) };
+}
+
 // ------------------------------------------------------------------ stats / retro
 
 function lambdaOf(opts, ctx) {
@@ -340,14 +420,16 @@ function pct(v) {
 function cmdStats(opts) {
   const ctx = ctxOf(opts);
   const { lambda } = lambdaOf(opts, ctx);
-  const { cells, steers } = agg.analyze(core.readEvents(ctx), { lambda });
+  const { cells, steers, orchestration } = agg.analyze(core.readEvents(ctx), { lambda });
   const type = typeof opts.type === 'string' ? opts.type : null;
   const rows = type ? cells.filter((c) => c.task_type === type) : cells;
   const steerRows = type ? steers.filter((s) => s.task_type === type) : steers;
   if (opts.json) {
-    return { code: 0, out: JSON.stringify({ lambda_usd_per_min: lambda, min_n: agg.MIN_N, cells: rows, steers: steerRows }, null, 2) };
+    return { code: 0, out: JSON.stringify({ lambda_usd_per_min: lambda, min_n: agg.MIN_N, cells: rows, steers: steerRows, orchestration }, null, 2) };
+  }
+  if (!rows.length) {
+    return { code: 0, out: orchestration.sessions ? `Chưa có dữ liệu theo ô.\n${orchLine(orchestration)}` : 'Chưa có dữ liệu.' };
   }
-  if (!rows.length) return { code: 0, out: 'Chưa có dữ liệu.' };
   const t = [['task_type', 'model/effort', 'n', 'accept%', 'agent_pass%', 'E[cost]', 'E[time]', 'p50', 'p75', 'score', '']];
   for (const c of rows) {
     t.push([
@@ -370,7 +452,7 @@ function cmdStats(opts) {
   }
   return {
     code: 0,
-    out: `${table(t)}\n\n${table(s)}\n\n`
+    out: `${table(t)}\n\n${table(s)}\n\n${orchLine(orchestration)}\n\n`
       + 'n = task tính tỉ lệ (/số đã giao, (-k) = bị loại: reject-scope hoặc lượt exec đầu bị steer plan/redirect). '
       + 'accept% = thành công theo verdict người dùng đầu tiên, chưa có thì verdict agent; agent_pass% = chỉ tầng agent. '
       + `E[cost], E[time] tính trọn mọi lượt + review của task. score = E[cost] + λ·E[time], λ=${lambda} USD/phút.`,
@@ -384,7 +466,7 @@ function cmdRetro(opts) {
   const ctx = ctxOf(opts);
   const { prof, lambda } = lambdaOf(opts, ctx);
   const events = core.readEvents(ctx);
-  const { agents, tasks, cells, steers, userVerdicts, overrides } = agg.analyze(events, { lambda });
+  const { agents, tasks, cells, steers, userVerdicts, overrides, orchestration } = agg.analyze(events, { lambda });
   const reasons = {};
   const outcomes = {};
   const userOutcomes = {};
@@ -433,6 +515,7 @@ function cmdRetro(opts) {
     steers,
     high_steer_task_types: highSteer,
     overrides: overrides.map((o) => ({ ts: o.ts, task_type: o.task_type, suggested_tier: o.suggested_tier, chosen_tier: o.chosen_tier })),
+    orchestration,
     cells,
   };
   if (opts.json) return { code: 0, out: JSON.stringify(summary, null, 2) };
@@ -443,6 +526,7 @@ function cmdRetro(opts) {
     `Lý do hay gặp: ${summary.reason_codes.slice(0, 8).map((r) => `${r.code}×${r.count}`).join(', ') || '-'}`,
     `Loại task: ${summary.task_types.map((t) => `${t.task_type}(${t.n})`).join(', ') || '-'}`,
     `Steer nhiều (brainstorm hỏi quá ít): ${highSteer.map((s) => `${s.task_type} ${pct(s.steer_rate)}`).join(', ') || '-'}`,
+    orchLine(orchestration),
     'Chi tiết theo ô: `dieu-phoi stats`; đưa cho LLM: `dieu-phoi retro --json`.',
   ];
   return { code: 0, out: lines.join('\n') };
@@ -475,6 +559,10 @@ function cmdChoose(opts) {
   }
   const input = chooseInput(opts, ctx, core.readEvents(ctx));
   const res = chooser.choose(input);
+  const orch = measureOrch(opts, ctx, input.profile);
+  res.orch_ctx_tokens = orch.ctx_tokens;
+  res.orch_ctx_growth = orch.ctx_growth;
+  res.orch_ctx_over = orch.over;
   if (res.overridden) {
     const tid = input.taskId;
     core.appendEvent(ctx, Object.assign({
@@ -489,13 +577,14 @@ function cmdChoose(opts) {
     }, core.commonFields(ctx)));
   }
   if (opts.json) return { code: 0, out: JSON.stringify(res) };
-  const est = `~${fmtUsd(res.est_cost_usd)} · ~${fmtNum(res.est_time_min)} phút (${res.est_source === 'data' ? 'dữ liệu' : 'ước lượng thô'})`;
+  const warn = orch.over ? `\nCẢNH BÁO: ${orch.advice}` : '';
+  const est =`~${fmtUsd(res.est_cost_usd)} · ~${fmtNum(res.est_time_min)} phút (${res.est_source === 'data' ? 'dữ liệu' : 'ước lượng thô'})`;
   if (res.action === 'ask_user') {
-    return { code: 0, out: `HỎI NGƯỜI DÙNG — ${res.reason}` };
+    return { code: 0, out: `HỎI NGƯỜI DÙNG — ${res.reason}${warn}` };
   }
   return {
     code: 0,
-    out: `model=${res.model} effort=${res.effort}${res.explored ? ' (thăm dò)' : ''}${res.overridden ? ' (override)' : ''}${res.deviation ? ' (LỆCH khỏi tier đã duyệt)' : ''} ${est} — ${res.reason}`,
+    out: `model=${res.model} effort=${res.effort}${res.explored ? ' (thăm dò)' : ''}${res.overridden ? ' (override)' : ''}${res.deviation ? ' (LỆCH khỏi tier đã duyệt)' : ''} ${est} — ${res.reason}${warn}`,
   };
 }
 
@@ -563,7 +652,11 @@ function buildPlanTable(rawSteps, base) {
       role: s.role || base.role,
       seed: base.seed === undefined || base.seed === null ? `plan:${s.step}` : `${base.seed}:${s.step}`,
     }));
-    const head = { step: s.step, title: s.title, type: s.type, score: Number(s.score), depends_on: s.deps };
+    // Rubric inputs that drive the safety floors: shown to the user at gate 1 so mis-scoring is caught.
+    const head = {
+      step: s.step, title: s.title, type: s.type, task_id: s.task || null, score: Number(s.score),
+      verifiable: s.verifiable, reversible: s.reversible, depends_on: s.deps,
+    };
     try {
       return Object.assign(head, call());
     } catch (e) {
@@ -589,12 +682,71 @@ function buildPlanTable(rawSteps, base) {
   };
 }
 
+const ROOT_RE = /^[A-Za-z0-9_-]{1,32}$/;
+
+/**
+ * Record the plan the user approved at gate 1: <data>/plans/<root>.json (local only — not an event, never
+ * synced). Each re-approval increments `approval` (number of approvals for this root) and overwrites the
+ * record; earlier approvals move to `history`. Not the user-verdict `round`.
+ * tier = exactly what the approved table shows (override applied); refused steps -> null.
+ */
+function prevApproval(prev) {
+  if (!prev || typeof prev !== 'object') return 0;
+  const n = Number.isInteger(prev.approval) ? prev.approval : prev.round; // `round`: 0.2.0 dev records
+  return Number.isInteger(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Steps that cannot be matched to dispatches once approved: missing task_id, a task_id used twice, or a
+ * task_id equal to the root. Returns Vietnamese problem strings (empty = ok).
+ */
+function planTaskIdProblems(plan, root) {
+  const problems = [];
+  const missing = plan.steps.filter((r) => !r.task_id).map((r) => r.step);
+  if (missing.length) problems.push(`thiếu task_id ở bước ${missing.join(', ')}`);
+  const by = new Map();
+  for (const r of plan.steps) if (r.task_id) by.set(r.task_id, (by.get(r.task_id) || []).concat(r.step));
+  for (const [id, steps] of by) if (steps.length > 1) problems.push(`task_id "${id}" bị dùng lại ở các bước ${steps.join(', ')}`);
+  if (root) {
+    const same = plan.steps.filter((r) => r.task_id === root).map((r) => r.step);
+    if (same.length) problems.push(`task_id của bước ${same.join(', ')} trùng --root "${root}" (root dành cho scout/planner)`);
+  }
+  return problems;
+}
+
+function recordApprovedPlan(ctx, root, stepsFile, plan) {
+  const file = path.join(ctx.paths.plans, `${root}.json`);
+  const prev = core.readJsonFile(file, null);
+  let history = [];
+  if (prev && typeof prev === 'object' && !Array.isArray(prev)) {
+    const old = Object.assign({}, prev);
+    delete old.history;
+    history = (Array.isArray(prev.history) ? prev.history : []).concat([old]);
+  }
+  const rec = {
+    root_task_id: root,
+    steps_file: stepsFile.split(path.sep).join('/'),
+    approved_at: core.nowIso(),
+    approval: prevApproval(prev) + 1,
+    steps: plan.steps.map((r) => ({
+      id: r.step, task_id: r.task_id || null, title: r.title === undefined ? null : r.title, type: r.type || null,
+      tier: r.action === 'refused' ? null : (r.tier || null), depends_on: r.depends_on,
+    })),
+    history,
+  };
+  core.writeFileAtomic(file, `${JSON.stringify(rec, null, 2)}\n`);
+  return Object.assign({ file }, rec);
+}
+
 function mdCell(s) {
   return String(s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
 }
 
 function cmdPlanTable(opts) {
-  if (typeof opts.file !== 'string') throw new Error('Cú pháp: dieu-phoi plan-table --file <steps.json> [--json]');
+  if (typeof opts.file !== 'string') throw new Error('Cú pháp: dieu-phoi plan-table --file <steps.json> [--json] [--approve --root <root_task_id>]');
+  if (opts.approve && (typeof opts.root !== 'string' || !ROOT_RE.test(opts.root))) {
+    throw new Error('--approve cần --root <root_task_id> (chữ, số, - _; tối đa 32 ký tự)');
+  }
   let raw;
   try {
     raw = JSON.parse(fs.readFileSync(path.resolve(opts.file), 'utf8').replace(/^/, ''));
@@ -605,13 +757,24 @@ function cmdPlanTable(opts) {
   const base = chooseInput(Object.assign({}, opts, { type: 'x', score: 0, override: undefined }), ctx, core.readEvents(ctx));
   delete base.override;
   const plan = buildPlanTable(raw, base);
-  if (opts.json) return { code: 0, out: JSON.stringify(plan, null, 2) };
-  const lines = ['| Bước | Model/effort | Lý do | Ước tính |', '|---|---|---|---|'];
+  const problems = planTaskIdProblems(plan, opts.approve ? String(opts.root) : null);
+  if (opts.approve && problems.length) {
+    throw new Error(`plan-table --approve: không ghi kế hoạch — ${problems.join('; ')}. Mỗi bước cần task_id riêng, khác --root.`);
+  }
+  if (problems.length) process.stderr.write(`dieu-phoi plan-table: cảnh báo — ${problems.join('; ')} (cần sửa trước khi --approve)\n`);
+  const rec = opts.approve ? recordApprovedPlan(ctx, String(opts.root), path.resolve(opts.file), plan) : null;
+  if (opts.json) {
+    const out = rec ? Object.assign({}, plan, { approved: { root_task_id: rec.root_task_id, approval: rec.approval, record: rec.file } }) : plan;
+    return { code: 0, out: JSON.stringify(out, null, 2) };
+  }
+  const lines = ['| Bước | Model/effort | Rubric (điểm · kiểm chứng · đảo ngược) | Lý do | Ước tính |', '|---|---|---|---|---|'];
   for (const r of plan.steps) {
     const tierCell = r.action === 'refused' ? '—' : (r.action === 'ask_user' ? `${r.tier} (hỏi người dùng)` : r.tier);
-    const why = `${r.type}, điểm ${r.score}${r.depends_on.length ? `, sau ${r.depends_on.join(', ')}` : ''} — ${r.reason.replace(/; profile: .*$/, '')}`;
+    const yn = (v) => (v ? 'y' : 'n');
+    const rubric = `${Number.isFinite(r.score) ? r.score : '?'} · ${yn(r.verifiable)} · ${yn(r.reversible)}`;
+    const why = `${r.type}${r.depends_on.length ? `, sau ${r.depends_on.join(', ')}` : ''} — ${r.reason.replace(/; profile: .*$/, '')}`;
     const est = r.action === 'refused' ? '-' : `~${fmtUsd(r.est_cost_usd)} · ~${fmtNum(r.est_time_min)} phút${r.est_source === 'rough' ? ' (thô)' : ''}`;
-    lines.push(`| ${mdCell(r.title ? `${r.step}. ${r.title}` : r.step)} | ${mdCell(tierCell)} | ${mdCell(why)} | ${mdCell(est)} |`);
+    lines.push(`| ${mdCell(r.title ? `${r.step}. ${r.title}` : r.step)} | ${mdCell(tierCell)} | ${mdCell(rubric)} | ${mdCell(why)} | ${mdCell(est)} |`);
   }
   lines.push('');
   lines.push(`**Tổng chi phí ước tính:** ~${fmtUsd(plan.total_cost_usd)} · **Thời gian (đường găng, chạy song song khi không phụ thuộc):** ~${fmtNum(plan.critical_path_min)} phút (cộng dồn ${fmtNum(plan.sum_time_min)} phút)`);
@@ -621,10 +784,11 @@ function cmdPlanTable(opts) {
     process.stderr.write(`dieu-phoi plan-table: cảnh báo — ${plan.refused.length} bước bị từ chối
 `);
   }
+  if (rec) lines.push('', `Đã ghi kế hoạch đã duyệt (root ${rec.root_task_id}, lần duyệt ${rec.approval})`);
   return { code: 0, out: lines.join('\n') };
 }
 
 module.exports = {
-  cmdSetup, cmdUninstall, cmdDoctor, cmdHook, cmdSync, cmdVerdict, cmdSteer, cmdStats, cmdRetro, cmdChoose,
-  cmdPlanTable, buildPlanTable, criticalPath, resolveAgentId, AGENT_OUTCOMES, USER_OUTCOMES, VERIFY,
+  cmdSetup, cmdUninstall, cmdDoctor, cmdHook, cmdSync, cmdVerdict, cmdSteer, cmdStats, cmdRetro, cmdChoose, cmdCtx, cmdState, measureOrch,
+  cmdPlanTable, buildPlanTable, recordApprovedPlan, planTaskIdProblems, criticalPath, resolveAgentId, AGENT_OUTCOMES, USER_OUTCOMES, VERIFY,
 };

package/lib/setup.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const core = require('../hook.cjs');
 
@@ -70,10 +71,11 @@ function alreadyRegistered(settings, cmd) {
         if (h.command !== cmd) continue;
         if (event === 'PostToolUse' && g.matcher === 'Agent') good++;
         else if (event === 'SubagentStop') good++;
+        else if (event === 'SessionStart' && g.matcher === 'compact') good++;
       }
     }
   }
-  return ours === 2 && good === 2;
+  return ours === 3 && good === 3;
 }
 
 function addOurHooks(settings, hookPath) {
@@ -84,6 +86,84 @@ function addOurHooks(settings, hookPath) {
   h.PostToolUse.push({ matcher: 'Agent', hooks: [{ type: 'command', command: cmd, timeout: 10 }] });
   if (!Array.isArray(h.SubagentStop)) h.SubagentStop = [];
   h.SubagentStop.push({ hooks: [{ type: 'command', command: cmd, timeout: 10 }] });
+  // after /compact or auto-compact: re-inject the orchestration state rebuilt from the log
+  if (!Array.isArray(h.SessionStart)) h.SessionStart = [];
+  h.SessionStart.push({ matcher: 'compact', hooks: [{ type: 'command', command: cmd, timeout: 10 }] });
+}
+
+// ------------------------------------------------------------------ run-dir permissions
+
+/**
+ * Run directory for subagent reports: ~/.dieu-phoi/runs (override: DIEU_PHOI_RUNS_DIR, absolute).
+ * Deliberately OUTSIDE ~/.claude: `.claude` is a Claude Code protected path, where allow rules never
+ * pre-approve writes, so background agents could not write their reports there.
+ */
+function runsDir() {
+  return core.runsDir();
+}
+
+/** Run dir used by 0.2.0 dev builds (<claudeDir>/dieu-phoi/runs); its rules are removed by setup/uninstall. */
+function legacyRunsDirOf(claudeDir) {
+  return path.join(path.resolve(claudeDir), 'dieu-phoi', 'runs');
+}
+
+/**
+ * Permission entries that let background subagents (default permission mode) read and write reports in
+ * `runs`: Read(<p>/**) + Edit(<p>/**) allow rules (Edit rules cover every file-writing tool; Claude
+ * Code ignores path rules on Write and warns about them, so no Write(...) rule) and the dir itself in
+ * permissions.additionalDirectories. <p> = ~/<rel> under the home dir, else //<abs> (Windows: //c/...).
+ */
+function permissionEntries(runs, homeDir) {
+  const home = path.resolve(homeDir || os.homedir());
+  const rel = path.relative(home, runs);
+  let pat;
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+    pat = `~/${toSlash(rel)}/**`;
+  } else {
+    const abs = toSlash(runs);
+    const m = /^([A-Za-z]):\/(.*)$/.exec(abs);
+    pat = m ? `//${m[1].toLowerCase()}/${m[2]}/**` : `/${abs}/**`;
+  }
+  return { allow: [`Read(${pat})`, `Edit(${pat})`], dir: toSlash(runs) };
+}
+
+/** Add our permission entries (idempotent). Returns true when settings changed. */
+function addOurPermissions(settings, entries) {
+  let changed = false;
+  if (!settings.permissions || typeof settings.permissions !== 'object' || Array.isArray(settings.permissions)) {
+    settings.permissions = {};
+    changed = true;
+  }
+  const p = settings.permissions;
+  if (!Array.isArray(p.allow)) { p.allow = []; changed = true; }
+  for (const r of entries.allow) if (!p.allow.includes(r)) { p.allow.push(r); changed = true; }
+  if (!Array.isArray(p.additionalDirectories)) { p.additionalDirectories = []; changed = true; }
+  if (!p.additionalDirectories.includes(entries.dir)) { p.additionalDirectories.push(entries.dir); changed = true; }
+  return changed;
+}
+
+/** Remove exactly our permission entries; a list we emptied is deleted. Returns number removed. */
+function stripOurPermissions(settings, entries) {
+  const p = settings.permissions;
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return 0;
+  let removed = 0;
+  const strip = (key, items) => {
+    if (!Array.isArray(p[key])) return;
+    const kept = p[key].filter((x) => !items.includes(x));
+    if (kept.length === p[key].length) return;
+    removed += p[key].length - kept.length;
+    if (kept.length) p[key] = kept; else delete p[key];
+  };
+  strip('allow', entries.allow);
+  strip('additionalDirectories', [entries.dir]);
+  return removed;
+}
+
+function hasOurPermissions(settings, entries) {
+  const p = settings && settings.permissions;
+  if (!p || typeof p !== 'object') return false;
+  return entries.allow.every((r) => Array.isArray(p.allow) && p.allow.includes(r))
+    && Array.isArray(p.additionalDirectories) && p.additionalDirectories.includes(entries.dir);
 }
 
 function readSettings(file) {
@@ -204,11 +284,20 @@ function setup(opts) {
   const cmd = hookCommand(paths.hook);
   let removed = 0;
   let res = { changed: false, backup: null };
+  let dirty = false;
   if (!(before.exists && alreadyRegistered(obj, cmd))) {
     removed = stripOurHooks(obj);
     addOurHooks(obj, paths.hook);
-    res = writeSettings(settingsFile, before, obj);
+    dirty = true;
   }
+  // 4. run dir + permissions so background subagents can write their reports there
+  const perms = permissionEntries(runsDir());
+  fs.mkdirSync(perms.dir, { recursive: true });
+  // rules a 0.2.0 dev build added for <claudeDir>/dieu-phoi/runs (protected path, never worked) go away
+  const legacyRemoved = stripOurPermissions(obj, permissionEntries(legacyRunsDirOf(claudeDir)));
+  if (legacyRemoved) dirty = true;
+  if (addOurPermissions(obj, perms)) dirty = true;
+  if (dirty) res = writeSettings(settingsFile, before, obj);
 
   return {
     home,
@@ -218,6 +307,9 @@ function setup(opts) {
     settings_changed: res.changed,
     backup: res.backup,
     replaced_entries: removed,
+    runs_dir: perms.dir,
+    permissions: perms,
+    legacy_permissions_removed: legacyRemoved,
     config: cfg,
   };
 }
@@ -229,29 +321,41 @@ function uninstall(opts) {
   const before = readSettings(settingsFile);
   const obj = JSON.parse(JSON.stringify(before.obj));
   const removed = stripOurHooks(obj);
+  const permsRemoved = stripOurPermissions(obj, permissionEntries(runsDir()))
+    + stripOurPermissions(obj, permissionEntries(legacyRunsDirOf(claudeDir)));
   let res = { changed: false, backup: null };
-  if (removed) res = writeSettings(settingsFile, before, obj);
+  if (removed || permsRemoved) res = writeSettings(settingsFile, before, obj);
   const hookFile = core.pathsFor(home).hook;
   let hookRemoved = false;
   if (opts.purge && fs.existsSync(hookFile)) {
     fs.unlinkSync(hookFile);
     hookRemoved = true;
   }
-  return { removed, settings: settingsFile, backup: res.backup, hook_removed: hookRemoved, data_kept: core.pathsFor(home).data };
+  return { removed, permissions_removed: permsRemoved, settings: settingsFile, backup: res.backup, hook_removed: hookRemoved, data_kept: core.pathsFor(home).data };
 }
 
 /** Inspect settings for our registration. */
 function registration(claudeDir) {
   const file = path.join(path.resolve(claudeDir), 'settings.json');
-  const out = { file, PostToolUse: false, SubagentStop: false, commands: [] };
+  const perms = permissionEntries(runsDir());
+  const legacy = permissionEntries(legacyRunsDirOf(claudeDir));
+  const out = {
+    file, PostToolUse: false, SubagentStop: false, SessionStart: false, commands: [], permissions: false, permission_entries: perms,
+    runs_dir: perms.dir, runs_dir_exists: fs.existsSync(perms.dir), legacy_permissions: false,
+  };
   let obj;
   try { obj = readSettings(file).obj; } catch (_) { return out; }
+  out.permissions = hasOurPermissions(obj, perms);
+  const lp = obj.permissions || {};
+  out.legacy_permissions = legacy.allow.some((r) => Array.isArray(lp.allow) && lp.allow.includes(r))
+    || (Array.isArray(lp.additionalDirectories) && lp.additionalDirectories.includes(legacy.dir));
   const hooks = obj.hooks || {};
-  for (const ev of ['PostToolUse', 'SubagentStop']) {
+  for (const ev of ['PostToolUse', 'SubagentStop', 'SessionStart']) {
     for (const g of Array.isArray(hooks[ev]) ? hooks[ev] : []) {
       for (const h of (g && Array.isArray(g.hooks) ? g.hooks : [])) {
         if (!isOurs(h)) continue;
         if (ev === 'PostToolUse' && g.matcher && !/\bAgent\b/.test(g.matcher)) continue;
+        if (ev === 'SessionStart' && g.matcher !== 'compact') continue;
         out[ev] = true;
         out.commands.push(h.command);
       }
@@ -262,5 +366,5 @@ function registration(claudeDir) {
 
 module.exports = {
   MARKER, setup, uninstall, registration, stripOurHooks, addOurHooks, alreadyRegistered, hookCommand,
-  skillVersionOf, findSkillDir, tsStamp,
+  skillVersionOf, findSkillDir, tsStamp, runsDir, legacyRunsDirOf, permissionEntries, addOurPermissions, stripOurPermissions, hasOurPermissions,
 };