@kienntpixon/dieu-phoi 0.3.0 → 0.5.0

package/hook.cjs

@@ -4,7 +4,9 @@
  * dieu-phoi hook + core helpers.
  *
  * This file is copied verbatim to ~/.claude/dieu-phoi/bin/hook.cjs by `dieu-phoi setup`
- * and run by Claude Code on PostToolUse(Agent), SubagentStop, SessionStart(compact) and UserPromptSubmit. It must stay
+ * and run by Claude Code on PostToolUse(Agent), SubagentStop, SessionStart(compact) and UserPromptSubmit; the dp-* agent
+ * files (`dieu-phoi setup` -> ~/.claude/agents) also run it inside those subagents as `--watch` (PostToolUse, context
+ * handoff watchdog), `--gate` (PreToolUse(Agent), gen-2 helper rules) and `--gate-release`. It must stay
  * self-contained: Node built-ins only, no requires of other package files.
  *
  * Hook rules: stdout only for the JSON of SessionStart(compact) / UserPromptSubmit, always exit 0,
@@ -13,6 +15,9 @@
  *
  *   node hook.cjs            -> read hook payload from stdin, append event
  *   node hook.cjs --sync     -> push unsynced events to the sink (spawned detached)
+ *   node hook.cjs --watch    -> dp subagent PostToolUse: context watchdog (additionalContext JSON or nothing)
+ *   node hook.cjs --gate     -> dp-exec PreToolUse(Agent): allow / deny a gen-2 helper spawn
+ *   node hook.cjs --gate-release -> dp-exec PostToolUseFailure(Agent): give a failed spawn's helper slot back
  */
 
 const fs = require('fs');
@@ -20,14 +25,14 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.3.0';
+const CORE_VERSION = '0.5.0';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
   'test-write', 'review', 'research-synth', 'content-write', 'plan-design', 'data-analysis',
 ];
 const URGENCIES = ['relaxed', 'normal', 'urgent'];
-const ROLES = ['exec', 'verify', 'plan'];
+const ROLES = ['exec', 'verify', 'plan', 'helper'];
 const MODEL_ALIASES = {
   opus: 'claude-opus-5-5',
   sonnet: 'claude-sonnet-5-5',
@@ -200,7 +205,7 @@ const UNTAGGED = Object.freeze({
   task_type: 'untagged', score: null, urgency: null, try: null, task_id: null, role: 'exec',
 });
 
-/** Parse `[dp:<type>|s<n>|<urgency>|try<n>|task=<id>|role=<r>]` from the first line. */
+/** Parse `[dp:<type>|s<n>|<urgency>|try<n>|task=<id>|role=<r>|parent=<id>]` from the first line. */
 function parseTag(text) {
   if (typeof text !== 'string') return null;
   const first = text.replace(/^/, '').split(/\r?\n/, 1)[0].trim();
@@ -223,6 +228,8 @@ function parseTag(text) {
       tag.task_id = mm[1];
     } else if ((mm = /^role=([a-z]+)$/.exec(p)) && ROLES.includes(mm[1])) {
       tag.role = mm[1];
+    } else if ((mm = /^parent=([A-Za-z0-9_-]{1,32})$/.exec(p))) {
+      tag.parent_task_id = mm[1]; // core 0.5.0: gen-2 helper -> the dp-exec step that spawned it
     }
   }
   return tag;
@@ -366,23 +373,26 @@ function lastUuidOf(lines) {
   return null;
 }
 
-/** Tag from the first user message of the transcript (the original prompt). */
-function tagFromTranscript(lines) {
+/** Text of the first user message of the transcript (the original prompt / brief), or null. */
+function firstPromptText(lines) {
   for (const l of lines) {
     if (!l || l.type !== 'user' || !l.message) continue;
     const c = l.message.content;
-    let text = null;
-    if (typeof c === 'string') text = c;
-    else if (Array.isArray(c)) {
+    if (typeof c === 'string') return c;
+    if (Array.isArray(c)) {
       const b = c.find((x) => x && x.type === 'text' && typeof x.text === 'string');
-      if (b) text = b.text;
+      if (b) return b.text;
     }
-    if (text === null) continue;
-    return parseTag(text);
   }
   return null;
 }
 
+/** Tag from the first user message of the transcript (the original prompt). */
+function tagFromTranscript(lines) {
+  const text = firstPromptText(lines);
+  return text === null ? null : parseTag(text);
+}
+
 /**
  * Summarize a transcript segment. Usage counted once per requestId (last line wins).
  * opts.afterUuids: uuids already counted by earlier segments; the segment starts after
@@ -737,10 +747,30 @@ function findSessionTranscript(claudeDir, sessionId) {
 
 // ------------------------------------------------------------------ events (append-only)
 
-/** Append one event. events.jsonl is append-only: never rewritten, sync progress lives elsewhere. */
+/**
+ * Append one event. events.jsonl is append-only: never rewritten, sync progress lives elsewhere.
+ * Core 0.4.0: one O_APPEND write of the whole line (hooks of parallel agents may append at the same time:
+ * an O_APPEND write lands as one unit, so lines never interleave). If the file does not
+ * end with '\n' (a writer died mid-line), a '\n' is written first so the torn fragment cannot swallow this
+ * event — readers skip the fragment as one unparsable line. Withdrawing a task = `dieu-phoi discard`, never an
+ * edit of this file.
+ */
 function appendEvent(ctx, ev) {
   fs.mkdirSync(ctx.paths.data, { recursive: true });
-  fs.appendFileSync(ctx.paths.events, `${JSON.stringify(ev)}\n`);
+  const fd = fs.openSync(ctx.paths.events, 'a+');
+  try {
+    let lead = '';
+    const size = fs.fstatSync(fd).size;
+    if (size > 0) {
+      const last = Buffer.alloc(1);
+      if (fs.readSync(fd, last, 0, 1, size - 1) === 1 && last[0] !== 0x0a) lead = '\n';
+    }
+    const buf = Buffer.from(`${lead}${JSON.stringify(ev)}\n`, 'utf8');
+    let off = 0;
+    while (off < buf.length) off += fs.writeSync(fd, buf, off, buf.length - off);
+  } finally {
+    fs.closeSync(fd);
+  }
 }
 
 function readEventsBuffer(ctx) {
@@ -859,7 +889,10 @@ function verdictLayer(ev) {
   const by = ev.by === 'user' ? 'user' : 'agent';
   let cause = ev.cause || null;
   if (by === 'user' && ev.outcome === 'reject' && cause !== 'scope') cause = 'quality';
-  return { by, outcome: ev.outcome, cause };
+  // legacy quota pause recorded as timeout → aborted (same reading as the stats)
+  const outcome = by === 'agent' && ev.outcome === 'timeout' && /^(?:quota-pause|usage-limit|auto-quota-pause|auto-usage-limit|paused-for-quota)(?:-|$)/.test(String(ev.reason_code || ''))
+    ? 'aborted' : ev.outcome;
+  return { by, outcome, cause };
 }
 
 function dispatchInSession(ev, sessionId) {
@@ -893,7 +926,9 @@ function buildSessionState(events, sessionId, opts) {
   const runs = toPosix(o.runsDir || runsDir());
   const taskIds = [];
   const seenTask = new Set();
+  const discarded = new Set(events.filter((ev) => ev && ev.kind === 'discard' && ev.task_id).map((ev) => ev.task_id));
   for (const ev of events) {
+    if (ev && discarded.has(ev.task_id)) continue;
     if (dispatchInSession(ev, sessionId) && typeof ev.task_id === 'string' && ev.task_id && !seenTask.has(ev.task_id)) {
       seenTask.add(ev.task_id);
       taskIds.push(ev.task_id);
@@ -908,7 +943,7 @@ function buildSessionState(events, sessionId, opts) {
     for (const s of p.steps) if (s && s.task_id && !stepOf.has(s.task_id)) stepOf.set(s.task_id, { plan: p, step: s });
   }
   for (const id of [...planOfRoot.keys(), ...stepOf.keys()]) {
-    if (!seenTask.has(id)) { seenTask.add(id); taskIds.push(id); }
+    if (!seenTask.has(id) && !discarded.has(id)) { seenTask.add(id); taskIds.push(id); }
   }
   const per = new Map(taskIds.map((id) => [id, { dispatches: [], user: [], steers: [], overrides: [], agentIds: new Set() }]));
   events.forEach((ev, i) => {
@@ -925,7 +960,7 @@ function buildSessionState(events, sessionId, opts) {
   const agentVerdicts = new Map();
   for (const ev of events) {
     if (!ev || typeof ev !== 'object') continue;
-    if (ev.kind === 'complete' && agentTask.has(ev.agent_id)) completes.set(ev.agent_id, (completes.get(ev.agent_id) || 0) + 1);
+    if (ev.kind === 'complete' && agentTask.has(ev.agent_id)) completes.set(ev.agent_id, Math.max(completes.get(ev.agent_id) || 1, evMs(ev) || 1));
     if (ev.kind === 'verdict') {
       const v = verdictLayer(ev);
       if (v.by === 'user') {
@@ -970,7 +1005,9 @@ function buildSessionState(events, sessionId, opts) {
       const vs = (agentVerdicts.get(d.agent_id) || []).slice().sort(byTime);
       const last = vs[vs.length - 1];
       let status;
-      if (last) status = last.outcome;
+      // aborted (quota pause) then resumed and completed again, no verdict yet → done (waiting for a verdict)
+      if (last && last.outcome === 'aborted' && (completes.get(d.agent_id) || 0) > evMs(last)) status = 'done';
+      else if (last) status = last.outcome;
       else status = completes.get(d.agent_id) ? 'done' : 'running';
       return {
         agent_id: d.agent_id, role: d.role || 'exec', try: d.try === undefined ? null : d.try,
@@ -1209,6 +1246,32 @@ function scoutBriefPath(ctx) {
   return fs.existsSync(f) ? toPosix(f) : null;
 }
 
+const ORCH_LESSON_RE = /\[(?:orch|orchestrator)\]/i;
+const ORCH_LESSONS_MAX = 5;
+const ORCH_LESSON_CHARS = 240;
+const LESSONS_MAX_BYTES = 256 * 1024;
+
+/**
+ * Lessons addressed to the orchestrator (core 0.4.0): list lines of <skill_dir>/profile/lessons.md that carry the
+ * tag `[orch]` (legacy `[orchestrator]`), the last ORCH_LESSONS_MAX of them, each cut to ORCH_LESSON_CHARS chars.
+ * The orchestrator never reads lessons.md itself; `start` and the UserPromptSubmit block surface these lines.
+ */
+function orchLessons(ctx) {
+  const sd = ctx.config && ctx.config.skill_dir;
+  if (!sd) return [];
+  let txt;
+  try {
+    const f = path.join(sd, 'profile', 'lessons.md');
+    if (fs.statSync(f).size > LESSONS_MAX_BYTES) return [];
+    txt = fs.readFileSync(f, 'utf8');
+  } catch (_) { return []; }
+  const out = txt.split(/\r?\n/).map((l) => l.trim())
+    .filter((l) => /^[-*] /.test(l) && ORCH_LESSON_RE.test(l))
+    .map((l) => l.replace(/^[-*] +/, ''))
+    .map((l) => (l.length > ORCH_LESSON_CHARS ? `${l.slice(0, ORCH_LESSON_CHARS - 1)}…` : l));
+  return out.slice(-ORCH_LESSONS_MAX);
+}
+
 /** Local, network-free health: config, profile, run dir, cached sink status. */
 function quickHealth(ctx, runs) {
   const problems = [];
@@ -1256,7 +1319,15 @@ function stepIds(root, n) {
 function startInfo(ctx) {
   const run = startRun();
   const health = quickHealth(ctx, run.runs);
-  return { id: run.id, run_dir: run.run_dir, step_ids: stepIds(run.id, START_STEP_IDS), health, scout_brief: scoutBriefPath(ctx) };
+  return {
+    id: run.id, run_dir: run.run_dir, step_ids: stepIds(run.id, START_STEP_IDS), health, scout_brief: scoutBriefPath(ctx),
+    orch_lessons: orchLessons(ctx),
+  };
+}
+
+function orchLessonLines(info) {
+  const ls = (info && info.orch_lessons) || [];
+  return ls.length ? ['bài học cho điều phối viên (profile/lessons.md, [orch]):'].concat(ls.map((l) => `  - ${l}`)) : [];
 }
 
 function formatStartBlock(info) {
@@ -1267,6 +1338,7 @@ function formatStartBlock(info) {
     `step_ids: ${info.step_ids.join(' ')}`,
     `health: ${healthLine(info.health)}`,
     `scout_brief: ${info.scout_brief || '(không thấy — dùng references/brief-template.md mục E)'}`,
+    ...orchLessonLines(info),
     'Dùng khối này cho yêu cầu MỚI ở cổng 1 (không dùng nếu đang giữa một lần điều phối). Không chạy `dieu-phoi doctor` / `new-id` / mkdir: lượt đầu tiên là Agent scout + câu hỏi cổng 1 cho người dùng.',
   ].join('\n');
 }
@@ -1336,7 +1408,10 @@ function buildDispatch(p, ctx) {
     orch_ctx_baseline: orch.ctx_baseline,
     orch_compactions: orch.compactions,
     orch_cum_usd: orch.cum_usd,
-  }, commonFields(ctx));
+  }, tag.parent_task_id ? { parent_task_id: tag.parent_task_id } : {},
+  // core 0.5.0: an Agent call made inside a subagent (gen-2) carries the caller's agent_id
+  typeof p.agent_id === 'string' && p.agent_id ? { parent_agent_id: p.agent_id } : {},
+  commonFields(ctx));
 }
 
 function handlePostToolUse(p, ctx) {
@@ -1373,6 +1448,124 @@ function countSkippedInternal(ctx) {
   } catch (_) { /* best effort */ }
 }
 
+// ------------------------------------------------------------------ core 0.5.0: hand-over files
+//
+// Claude Code denies Write inside any subagent when the basename matches BLOCKED_RESULT_NAME_RE ("Subagents should
+// return findings as text, not write report files" — hardcoded, before permissions). So exec / verify / plan agents
+// write their full result to dp-out-<task>-<role>-try<n>.md and return only path + STATUS + a few lines. Run dirs
+// from before 0.5.0 hold report-<task>-try<n>.md / verify-<task>-try<n>.md: still recognised as results.
+
+const RESULT_ROLES = ['exec', 'verify', 'plan'];
+const BLOCKED_RESULT_NAME_RE = /^(REPORT|SUMMARY|FINDINGS|ANALYSIS).*\.md$/i;
+const INLINE_MAX_BYTES = 256 * 1024;
+
+function escRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Canonical hand-over file name of one attempt: dp-out-<task>-<role>-try<n>.md. */
+function resultFileName(taskId, role, tryN) {
+  return `dp-out-${safeName(taskId)}-${role}-try${Number(tryN) || 1}.md`;
+}
+
+/**
+ * Result files already in runDir for (task, role, try), sorted: dp-out-* (with -2 / -spot / .inline suffixes) and the
+ * legacy report-<task>-try<n>*.md (exec) / verify-<task>-try<n>*.md (verify). Never throws.
+ */
+function findResultFiles(runDir, taskId, role, tryN) {
+  let names;
+  try { names = fs.readdirSync(runDir); } catch (_) { return []; }
+  const t = escRe(safeName(taskId));
+  const n = Number(tryN) || 1;
+  const pats = [new RegExp(`^dp-out-${t}-${escRe(role)}-try${n}(?:[-.][A-Za-z0-9.-]*)?\\.md$`)];
+  if (role === 'exec') pats.push(new RegExp(`^report-${t}-try${n}(?:-[A-Za-z0-9-]*)?\\.md$`));
+  if (role === 'verify') pats.push(new RegExp(`^verify-${t}-try${n}(?:-[A-Za-z0-9-]*)?\\.md$`));
+  return names.filter((x) => pats.some((re) => re.test(x))).sort().map((x) => path.join(runDir, x));
+}
+
+function insideRunsDir(d) {
+  const r = path.relative(runsDir(), d);
+  return !!r && !r.startsWith('..') && !path.isAbsolute(r);
+}
+
+function expandHome(s) {
+  return s === '~' || s.startsWith('~/') ? path.join(os.homedir(), s.slice(1)) : s;
+}
+
+/**
+ * Run dir an agent's brief points at (never outside runsDir()): the folder of a dp-out-/handoff- path named in the
+ * brief, else a `…/runs/<id>` path (the one named after the task first), else runsDir()/<task_id>.
+ */
+function resultRunDir(prompt, taskId) {
+  const text = String(prompt || '').replace(/\\/g, '/');
+  const PATH = "(?:[A-Za-z]:)?~?[^\\s`'\"<>()|*?]*";
+  for (const m of text.matchAll(new RegExp(`(${PATH}/)(?:dp-out-|handoff-)[A-Za-z0-9_.-]*\\.md`, 'g'))) {
+    const d = path.resolve(expandHome(m[1]));
+    if (insideRunsDir(d)) return d;
+  }
+  const dirs = [];
+  for (const m of text.matchAll(new RegExp(`(${PATH}/runs/[A-Za-z0-9_-]{1,64})(?![A-Za-z0-9_-])`, 'g'))) {
+    const d = path.resolve(expandHome(m[1]));
+    if (insideRunsDir(d) && path.dirname(d) === path.resolve(runsDir())) dirs.push(d);
+  }
+  const own = dirs.find((d) => path.basename(d) === safeName(taskId));
+  if (own || dirs.length) return own || dirs[0];
+  return path.join(runsDir(), safeName(taskId));
+}
+
+/** Final text the agent returned: the payload's last_assistant_message, else the last assistant text in the transcript. */
+function finalAssistantText(lines, given) {
+  if (typeof given === 'string' && given.trim()) return given;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const l = lines[i];
+    if (!l || l.type !== 'assistant' || !l.message) continue;
+    if (l.isApiErrorMessage === true) return null;
+    const c = l.message.content;
+    const text = typeof c === 'string' ? c
+      : (Array.isArray(c) ? c.filter((x) => x && x.type === 'text' && typeof x.text === 'string').map((x) => x.text).join('\n') : '');
+    if (text.trim()) return text;
+  }
+  return null;
+}
+
+/** Whether the returned text names an existing dp-out-/handoff-/report-/verify-*.md under runsDir() (written under another name). */
+function namesExistingRunFile(text) {
+  const t = String(text).replace(/\\/g, '/');
+  for (const m of t.matchAll(/((?:[A-Za-z]:)?~?[^\s`'"<>()|*?]*\/(?:dp-out|handoff|report|verify)-[A-Za-z0-9_.-]+\.md)/g)) {
+    const f = path.resolve(expandHome(m[1]));
+    if (insideRunsDir(f) && fs.existsSync(f)) return true;
+  }
+  return false;
+}
+
+/**
+ * SubagentStop fallback: an exec / verify / plan agent that came back without its hand-over file (Write denied, or it
+ * answered inline) gets its returned text saved as <run>/dp-out-<task>-<role>-try<n>.inline.md so the next step can
+ * still read a file. Skipped when a result file for that attempt exists (dp-out or legacy), when the text names an
+ * existing run-dir .md file, and for handoffs (the handoff file is the hand-over). Returns the path written or null.
+ */
+function persistInlineResult(lines, tag, opts) {
+  const o = opts || {};
+  if (!tag || !RESULT_ROLES.includes(tag.role) || !tag.task_id) return null;
+  const text = finalAssistantText(lines, o.finalText);
+  if (!text) return null;
+  if (text.trimStart().startsWith(HANDOFF_MARKER)) return null;
+  const dir = resultRunDir(firstPromptText(lines), tag.task_id);
+  if (findResultFiles(dir, tag.task_id, tag.role, tag.try).length) return null;
+  if (namesExistingRunFile(text)) return null;
+  const file = path.join(dir, resultFileName(tag.task_id, tag.role, tag.try).replace(/\.md$/, '.inline.md'));
+  let body = text.replace(/\r\n/g, '\n');
+  if (Buffer.byteLength(body) > INLINE_MAX_BYTES) body = `${Buffer.from(body).subarray(0, INLINE_MAX_BYTES).toString('utf8')}\n\n[… cắt bớt]`;
+  fs.mkdirSync(dir, { recursive: true });
+  try {
+    fs.writeFileSync(file, `<!-- dieu-phoi: agent ${tag.role} không ghi file kết quả; hook SubagentStop lưu nguyên văn phần trả về -->\n\n${body}\n`, { flag: 'wx' });
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return null;
+    throw e;
+  }
+  return file;
+}
+
 function handleSubagentStop(p, ctx) {
   const agentId = typeof p.agent_id === 'string' && p.agent_id ? p.agent_id : null;
   if (!agentId) return null;
@@ -1425,9 +1618,386 @@ function handleSubagentStop(p, ctx) {
     });
   }
   appendEvent(ctx, ev);
+  if (exists && tag) {
+    try { persistInlineResult(lines, tag, { finalText: p.last_assistant_message }); } catch (_) { /* best effort */ }
+  }
+  // Core 0.4.0: a segment that ended on a usage-limit / quota pause gets an automatic agent verdict
+  // `aborted` (never a fail, never counted toward escalation); the real verdict comes after the resume.
+  const why = exists ? abortReasonOf(lines) : null;
+  if (why) {
+    appendEvent(ctx, Object.assign({
+      schema: SCHEMA, kind: 'verdict', ts: nowIso(), agent_id: agentId, task_id: t.task_id, by: 'agent', outcome: 'aborted',
+      verify: 'none', reason_code: `auto-${why}`, cause: null, round: null,
+    }, commonFields(ctx)));
+  }
   return ev;
 }
 
+// Exact marker an agent puts on the FIRST line of its final report when it stops at a safe point because of a quota
+// / usage limit (brief template A, SKILL.md). Nothing looser: "STATUS: partial" + "quota" can be a real failure
+// ("Drive storage quota exceeded", a half-built rate limiter).
+const QUOTA_PAUSE_MARKER = 'STATUS: partial — quota-pause';
+// Core 0.5.0: exact marker of an agent that stopped on the context watchdog and wrote handoff.md (continuation, not a fail).
+const HANDOFF_MARKER = 'STATUS: partial — handoff';
+// Claude Code's own usage-limit stop text on its synthetic API-error line ("You've hit your session limit · resets 11am").
+const CC_LIMIT_TEXT_RE = /^You['’]ve hit your (?:[\w-]+ )?limit\b/;
+
+/**
+ * Why the agent's last segment stopped on a usage limit, or null. Reads only the LAST assistant line:
+ * - Claude Code's synthetic API-error line (`model:"<synthetic>"` + `isApiErrorMessage:true`) whose `error` is
+ *   "rate_limit", or HTTP 429, or whose text starts "You've hit your … limit" → "usage-limit";
+ * - the agent's final report whose first line starts with the exact marker QUOTA_PAUSE_MARKER → "quota-pause".
+ * Only a short label is returned; no text is stored.
+ */
+function abortReasonOf(lines) {
+  let last = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const l = lines[i];
+    if (l && l.type === 'assistant' && l.message) { last = l; break; }
+  }
+  if (!last) return null;
+  const content = Array.isArray(last.message.content) ? last.message.content : [];
+  const text = content.filter((c) => c && c.type === 'text' && typeof c.text === 'string').map((c) => c.text).join('\n').slice(0, 2000);
+  if (last.isApiErrorMessage === true) {
+    if (last.message.model !== '<synthetic>') return null;
+    if (last.error === 'rate_limit' || last.apiErrorStatus === 429 || CC_LIMIT_TEXT_RE.test(text.trim())) return 'usage-limit';
+    return null;
+  }
+  const first = text.trimStart().split('\n')[0].trim();
+  if (first.startsWith(QUOTA_PAUSE_MARKER)) return 'quota-pause';
+  if (first.startsWith(HANDOFF_MARKER)) return 'handoff';
+  return null;
+}
+
+// ------------------------------------------------------------------ core 0.5.0: context watchdog + gen-2 gate
+//
+// Both run only from the hooks of the dp-* agent files (~/.claude/agents, installed by `dieu-phoi setup`), so a session
+// that never uses dieu-phoi never runs them. They still check that the subagent's first prompt carries a `[dp:` tag
+// (state cached per agent in data/watch/<agent_id>.json) and do nothing on the main thread (no agent_id).
+
+const HANDOFF_THRESHOLDS = Object.freeze([150000, 180000]);
+const WATCH_HEAD_BYTES = 64 * 1024;
+const WATCH_HEAD_MAX = 2 << 20;
+const WATCH_TAIL_BYTES = 256 * 1024;
+const WATCH_TAIL_MAX = 8 << 20;
+const WATCH_TTL_MS = 14 * 24 * 3600 * 1000;
+const GATE_MAX_CHILDREN = 4;
+const HELPER_AGENT_TYPE = 'dp-helper';
+const HELPER_MODELS = ['haiku', 'sonnet'];
+
+/** The subagent the hook fired in: payload agent_id, else the `agent-<id>.jsonl` transcript name; null on the main thread. */
+function watchAgentId(p) {
+  if (typeof p.agent_id === 'string' && p.agent_id) return p.agent_id;
+  for (const k of ['agent_transcript_path', 'transcript_path']) {
+    const m = typeof p[k] === 'string' ? /agent-([A-Za-z0-9_-]{6,64})\.jsonl$/.exec(p[k]) : null;
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * The subagent's own transcript. Claude Code layout: <project>/<session_id>.jsonl (main) and
+ * <project>/<session_id>/subagents/agent-<agent_id>.jsonl. Uses a payload path when it already names the agent's file.
+ */
+function subagentTranscriptPath(p, agentId) {
+  const name = `agent-${agentId}.jsonl`;
+  for (const k of ['agent_transcript_path', 'transcript_path']) {
+    if (typeof p[k] === 'string' && p[k] && path.basename(p[k]) === name) return p[k];
+  }
+  const tp = p.transcript_path;
+  if (typeof tp !== 'string' || !tp) return null;
+  const guesses = [
+    path.join(path.dirname(tp), path.basename(tp, '.jsonl'), 'subagents', name),
+    path.join(path.dirname(tp), name), // transcript_path already inside a subagents dir (nested spawn)
+  ];
+  for (const g of guesses) if (fs.existsSync(g)) return g;
+  return null;
+}
+
+function readSlice(fd, start, len) {
+  const buf = Buffer.allocUnsafe(len);
+  const n = fs.readSync(fd, buf, 0, len, start);
+  return buf.subarray(0, Math.max(0, n));
+}
+
+/**
+ * Tag of the subagent's first prompt, read from the head of its transcript only.
+ * Returns { found: false } while no user line is on disk yet (transcript written async), else { found: true, tag|null }.
+ */
+function readHeadTag(file) {
+  let fd;
+  try { fd = fs.openSync(file, 'r'); } catch (_) { return { found: false, tag: null }; }
+  try {
+    const size = fs.fstatSync(fd).size;
+    for (let want = WATCH_HEAD_BYTES; ; want *= 2) {
+      const len = Math.min(want, size, WATCH_HEAD_MAX);
+      const text = readSlice(fd, 0, len).toString('utf8');
+      const complete = len === size ? text : text.slice(0, text.lastIndexOf('\n') + 1);
+      const lines = parseJsonl(complete);
+      if (lines.some((l) => l && l.type === 'user' && l.message)) return { found: true, tag: tagFromTranscript(lines), prompt: firstPromptText(lines) };
+      if (len >= size || len >= WATCH_HEAD_MAX) return { found: false, tag: null };
+    }
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* ignore */ }
+  }
+}
+
+/** Context of the subagent's latest API request = input + cache_read + cache_creation (tail of the transcript only). */
+function lastContextTokens(file) {
+  let fd;
+  try { fd = fs.openSync(file, 'r'); } catch (_) { return null; }
+  try {
+    const size = fs.fstatSync(fd).size;
+    for (let win = WATCH_TAIL_BYTES; ; win *= 2) {
+      const start = Math.max(0, size - win);
+      const buf = readSlice(fd, start, size - start);
+      let end = buf.length;
+      while (end > 0) {
+        const nl = buf.lastIndexOf(0x0a, end - 1);
+        const line = buf.subarray(nl + 1, end);
+        end = nl < 0 ? 0 : nl;
+        if (nl < 0 && start > 0) break; // first partial line of the window
+        if (line.indexOf(USAGE_NEEDLE) < 0) continue;
+        let l;
+        try { l = JSON.parse(line.toString('utf8')); } catch (_) { continue; }
+        const msg = l && l.type === 'assistant' ? l.message : null;
+        if (!msg || !msg.usage || msg.model === '<synthetic>') continue;
+        const u = msg.usage;
+        return (Number(u.input_tokens) || 0) + (Number(u.cache_read_input_tokens) || 0) + (Number(u.cache_creation_input_tokens) || 0);
+      }
+      if (start === 0 || win >= WATCH_TAIL_MAX) return null;
+    }
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* ignore */ }
+  }
+}
+
+function watchFile(ctx, agentId) {
+  return path.join(ctx.paths.data, 'watch', `${safeName(agentId)}.json`);
+}
+
+function pruneWatch(dir) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (_) { return; }
+  const cutoff = Date.now() - WATCH_TTL_MS;
+  for (const n of names) {
+    const f = path.join(dir, n);
+    try { if (fs.statSync(f).mtimeMs < cutoff) fs.unlinkSync(f); } catch (_) { /* ignore */ }
+  }
+}
+
+/**
+ * Per-agent watch state { dp, task_id, role, parent_task_id, fired, t }, created on the agent's first hook from the
+ * head of its transcript with an exclusive create (two hooks racing to create it never clobber a later update). Only
+ * --watch updates it; the gate keeps its own slot files (gateDir). Returns { st, file, tpath }; st is null while the
+ * first prompt is not on disk yet.
+ */
+/** Name of the run dir a brief points at (dp-out-/handoff- folder or …/runs/<id>), else null. */
+function runIdFromPrompt(prompt) {
+  const d = resultRunDir(prompt, '');
+  return path.dirname(d) === path.resolve(runsDir()) ? path.basename(d) : null;
+}
+
+function watchState(p, ctx, agentId) {
+  const file = watchFile(ctx, agentId);
+  const tpath = subagentTranscriptPath(p, agentId);
+  let st = readJsonFile(file, null);
+  if (!st || typeof st !== 'object') {
+    st = null;
+    if (tpath) {
+      const h = readHeadTag(tpath);
+      if (h.found) {
+        st = h.tag
+          ? { dp: true, task_id: h.tag.task_id, run_id: h.tag.task_id ? null : runIdFromPrompt(h.prompt), role: h.tag.role, parent_task_id: h.tag.parent_task_id || null, fired: 0, t: Date.now() }
+          : { dp: false, t: Date.now() };
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        pruneWatch(path.dirname(file));
+        try {
+          fs.writeFileSync(file, `${JSON.stringify(st)}\n`, { flag: 'wx' });
+        } catch (_) {
+          st = readJsonFile(file, st); // another hook created it first: its copy wins
+        }
+      }
+    }
+  }
+  return { st, file, tpath };
+}
+
+function handoffMessage(st, tokens, level, thresholds) {
+  if (st.role && st.role !== 'exec') {
+    // verify / scout / helper: no continuation agent exists, so no handoff file — wrap up with what is there.
+    const what = st.role === 'verify' ? 'verdict (dòng STATUS + các phát hiện)' : 'bản tóm tắt';
+    const last = level >= thresholds.length ? ' NHẮC LẦN CUỐI.' : '';
+    return `dieu-phoi: ngữ cảnh của bạn đã ~${Math.round(tokens / 1000)}k token.${last} Dừng đọc/chạy thêm: trả ${what} NGAY với những gì đã có, ghi rõ phần nào chưa kiểm được. Không ghi file handoff — chỉ agent exec mới handoff.`;
+  }
+  const tid = safeName(st.task_id || st.run_id || 'task');
+  const file = `handoff-${tid}.md`;
+  const where = `\`${file}\` trong run dir của brief (đã có thì thêm -2, -3; brief không có run dir → ${toPosix(path.join(runsDir(), tid))}/)`;
+  const k = Math.round(tokens / 1000);
+  if (level >= thresholds.length) {
+    return `dieu-phoi: NHẮC LẦN CUỐI — ngữ cảnh của bạn đã ~${k}k token. Không làm thêm việc gì: ghi ${where} ngay (nếu chưa ghi) rồi kết thúc, dòng đầu báo cáo đúng \`${HANDOFF_MARKER}\` kèm đường dẫn file handoff.`;
+  }
+  return `dieu-phoi: ngữ cảnh của bạn đã ~${k}k token (ngưỡng ${Math.round(thresholds[level - 1] / 1000)}k). Dừng nhận việc mới: làm nốt thao tác đang dở tới điểm an toàn (không để file sửa dở, test đang chạy thì chờ kết quả), rồi ghi ${where} gồm 5 mục: Đã xong / Đang dở / Bước tiếp theo / File đã động / Bẫy & ghi chú (lệnh test, đường dẫn, quyết định đã chốt). Sau đó kết thúc: dòng đầu báo cáo đúng \`${HANDOFF_MARKER}\` kèm đường dẫn file handoff. Điều phối viên sẽ giao một agent tiếp nối cùng tier đọc file đó — đây không phải thất bại.`;
+}
+
+/** `--watch` (PostToolUse inside a dp-* subagent): additionalContext once per threshold crossing, else nothing. */
+function handleWatch(p, ctx, o) {
+  const agentId = watchAgentId(p);
+  if (!agentId) return null;
+  const { st, file, tpath } = watchState(p, ctx, agentId);
+  if (!st || !st.dp || !tpath) return null;
+  // Gate slots: a helper's first hook proves its spawn started; so does the exec's own successful Agent call.
+  if (st.role === 'helper' && st.parent_task_id && st.task_id) gateConfirm(ctx, st.parent_task_id, st.task_id);
+  if ((p.tool_name === 'Agent' || p.tool_name === 'Task') && st.role === 'exec') {
+    const ct = parseTag(p.tool_input && p.tool_input.prompt);
+    if (ct && ct.task_id) gateConfirm(ctx, st.task_id || agentId, ct.task_id);
+  }
+  const thresholds = Array.isArray(o && o.thresholds) && o.thresholds.length ? o.thresholds : HANDOFF_THRESHOLDS;
+  const tokens = lastContextTokens(tpath);
+  if (tokens === null) return null;
+  let level = 0;
+  while (level < thresholds.length && tokens >= thresholds[level]) level++;
+  if (level <= (Number(st.fired) || 0)) return null;
+  st.fired = level;
+  st.ctx_tokens = tokens;
+  st.t = Date.now();
+  writeFileAtomic(file, `${JSON.stringify(st)}\n`);
+  return {
+    level,
+    ctx_tokens: tokens,
+    stdout: JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: handoffMessage(st, tokens, level, thresholds) },
+    }),
+  };
+}
+
+/** A reservation that neither the parent's PostToolUse(Agent) nor the helper's own first hook confirmed in this long never started. */
+const GATE_PENDING_MS = 10 * 60 * 1000;
+
+/** Per-step gate dir: one `slot-<n>.json` file per reserved helper (n = 1..GATE_MAX_CHILDREN), keyed by the exec's task. */
+function gateDir(ctx, key) {
+  return path.join(ctx.paths.data, 'gate', safeName(key));
+}
+
+function pruneGate(root) {
+  let names = [];
+  try { names = fs.readdirSync(root); } catch (_) { return; }
+  const cutoff = Date.now() - WATCH_TTL_MS;
+  for (const n of names) {
+    const d = path.join(root, n);
+    try { if (fs.statSync(d).mtimeMs < cutoff) fs.rmSync(d, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+}
+
+/** Slots in use: a confirmed one always counts; an unconfirmed one counts until GATE_PENDING_MS, then it is released. */
+function gateSlots(dir) {
+  const out = [];
+  for (let i = 1; i <= GATE_MAX_CHILDREN; i++) {
+    const f = path.join(dir, `slot-${i}.json`);
+    const r = readJsonFile(f, null);
+    if (!r) continue;
+    if (!r.started && Date.now() - (Number(r.t) || 0) > GATE_PENDING_MS) {
+      try { fs.unlinkSync(f); } catch (_) { /* someone else released it */ }
+      continue;
+    }
+    out.push(Object.assign({ file: f, slot: i }, r));
+  }
+  return out;
+}
+
+/** Reserve a free slot with an exclusive create (atomic on Windows and POSIX): parallel calls never share a slot. */
+function gateReserve(dir, child) {
+  fs.mkdirSync(dir, { recursive: true });
+  gateSlots(dir); // drop stale reservations first
+  for (let i = 1; i <= GATE_MAX_CHILDREN; i++) {
+    const f = path.join(dir, `slot-${i}.json`);
+    try {
+      fs.writeFileSync(f, `${JSON.stringify({ child, t: Date.now(), started: false })}\n`, { flag: 'wx' });
+      return i;
+    } catch (_) { /* taken */ }
+  }
+  return 0;
+}
+
+/** Mark the reservation of `child` as a real spawn. Returns true when its slot was found. */
+function gateConfirm(ctx, key, child) {
+  if (!key || !child) return false;
+  const dir = gateDir(ctx, key);
+  if (!fs.existsSync(dir)) return false;
+  for (const r of gateSlots(dir)) {
+    if (r.child !== child) continue;
+    if (r.started) return true;
+    try {
+      writeFileAtomic(r.file, `${JSON.stringify({ child, t: r.t, started: true, started_t: Date.now() })}\n`);
+      return true;
+    } catch (_) { return false; }
+  }
+  return false;
+}
+
+/**
+ * `--gate` (PreToolUse(Agent) inside dp-exec): a dp-tagged exec may run at most GATE_MAX_CHILDREN gen-2 children per
+ * step, each `dp-helper`, model haiku|sonnet set explicitly, prompt tagged `role=helper|parent=<own task>|task=<new id>`.
+ * Anything else is denied with the reason; an allowed spawn prints nothing (normal permission flow). The budget is a set
+ * of slot files (gateReserve, exclusive create), separate from the watch state. A slot is confirmed by the parent's
+ * PostToolUse(Agent) or the helper's own first --watch, released by --gate-release (PostToolUseFailure) or, if never
+ * confirmed, after GATE_PENDING_MS — so only spawns that really start use the budget.
+ */
+function handleGate(p, ctx) {
+  if (p.tool_name !== 'Agent' && p.tool_name !== 'Task') return null;
+  const agentId = watchAgentId(p);
+  if (!agentId) return null;
+  const { st } = watchState(p, ctx, agentId);
+  if (!st || !st.dp) return null;
+  const ti = p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
+  const why = [];
+  if (st.role && st.role !== 'exec') why.push(`chỉ agent role=exec được giao helper (bạn là role=${st.role})`);
+  if (ti.subagent_type !== HELPER_AGENT_TYPE) why.push(`subagent_type phải là ${HELPER_AGENT_TYPE} (đang là ${ti.subagent_type || 'mặc định'})`);
+  if (!HELPER_MODELS.includes(shortModelName(ti.model))) why.push(`model phải đặt rõ haiku hoặc sonnet (đang là ${ti.model || 'không đặt = kế thừa'})`);
+  const tag = parseTag(ti.prompt);
+  const parentHint = st.task_id || '<task của bạn>';
+  if (!tag || tag.role !== 'helper' || !tag.task_id || !tag.parent_task_id) {
+    why.push(`dòng đầu prompt phải là [dp:<type>|s<n>|<urgency>|try1|task=<id mới từ dieu-phoi new-id>|role=helper|parent=${parentHint}]`);
+  } else if (st.task_id && tag.parent_task_id !== st.task_id) {
+    why.push(`parent= phải là task của bạn (${st.task_id})`);
+  }
+  const deny = (list) => ({
+    denied: true,
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `dieu-phoi gen-2: ${list.join('; ')}.`,
+      },
+    }),
+  });
+  if (why.length) return deny(why);
+  const root = path.join(ctx.paths.data, 'gate');
+  fs.mkdirSync(root, { recursive: true });
+  pruneGate(root);
+  const dir = gateDir(ctx, st.task_id || agentId);
+  const slot = gateReserve(dir, tag.task_id);
+  if (!slot) return deny([`đã giao đủ ${GATE_MAX_CHILDREN} helper cho bước này — tự làm phần còn lại`]);
+  return { denied: false, slot, children: gateSlots(dir).length };
+}
+
+/** `--gate-release` (PostToolUseFailure(Agent) inside dp-exec): the spawn failed, give its unconfirmed slot back. */
+function handleGateRelease(p, ctx) {
+  if (p.tool_name !== 'Agent' && p.tool_name !== 'Task') return null;
+  const agentId = watchAgentId(p);
+  if (!agentId) return null;
+  const { st } = watchState(p, ctx, agentId);
+  if (!st || !st.dp) return null;
+  const tag = parseTag(p.tool_input && p.tool_input.prompt);
+  if (!tag || !tag.task_id) return null;
+  for (const r of gateSlots(gateDir(ctx, st.task_id || agentId))) {
+    if (r.child !== tag.task_id || r.started) continue;
+    try { fs.unlinkSync(r.file); } catch (_) { /* already gone */ }
+    return { released: r.slot };
+  }
+  return null;
+}
+
 function maybeSpawnSync(ctx) {
   if (!ctx.config.sink_url || !ctx.config.sink_token) return false;
   if (process.env.DIEU_PHOI_NO_SPAWN === '1') return false;
@@ -1479,6 +2049,9 @@ function runHook(opts) {
     const ctx = makeCtx(home);
     let ev = null;
     const name = p.hook_event_name;
+    if (o.mode === 'watch') return handleWatch(p, ctx, o); // { stdout } or null
+    if (o.mode === 'gate') return handleGate(p, ctx, o); // { stdout } or null
+    if (o.mode === 'gate-release') return handleGateRelease(p, ctx); // { released } or null, prints nothing
     if (name === 'SessionStart') return handleSessionStart(p, ctx); // { stdout } or null, never an event
     if (name === 'UserPromptSubmit') return handleUserPromptSubmit(p, ctx); // { stdout } or null
     if (name === 'SubagentStop') ev = handleSubagentStop(p, ctx);
@@ -1632,13 +2205,15 @@ async function runSync(ctx, opts) {
 // ------------------------------------------------------------------ exports / main
 
 module.exports = {
-  runsDir, loadPlans, isDieuPhoiPrompt, foldPrompt, sinkStatusCached, sinkUrlKey, SINK_CACHE_TTL_MS, scoutBriefPath, quickHealth, startRun, startInfo, stepIds, START_STEP_IDS, healthLine, formatStartBlock, handleUserPromptSubmit, START_PREFIX, buildSessionState, formatSessionState, stateCounts, compactSystemMessage, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
+  runsDir, loadPlans, isDieuPhoiPrompt, foldPrompt, sinkStatusCached, sinkUrlKey, SINK_CACHE_TTL_MS, scoutBriefPath, quickHealth, startRun, startInfo, orchLessons, orchLessonLines, abortReasonOf, QUOTA_PAUSE_MARKER, stepIds, START_STEP_IDS, healthLine, formatStartBlock, handleUserPromptSubmit, START_PREFIX, buildSessionState, formatSessionState, stateCounts, compactSystemMessage, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
   CORE_VERSION, SCHEMA, TASK_TYPES, URGENCIES, ROLES, MODEL_ALIASES, UNTAGGED,
   sha8, nowIso, readJsonFile, writeFileAtomic, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
   logError, computeUserHash, userHash, commonFields, parseTag, TASK_ID_RE, isValidTaskId, newTaskId, taskIdError, normalizeModel, loadPricing,
   priceFor, usageBuckets, requestCost, parseJsonl, readTranscript, lastUuidOf,
-  tagFromTranscript, summarizeTranscript, orchestratorUsage, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, appendEvent, eventLinesFrom, readEventLines, readEvents,
+  firstPromptText, tagFromTranscript, summarizeTranscript,
+  RESULT_ROLES, BLOCKED_RESULT_NAME_RE, resultFileName, findResultFiles, resultRunDir, finalAssistantText, persistInlineResult, orchestratorUsage, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, appendEvent, eventLinesFrom, readEventLines, readEvents,
   loadSyncOffset, saveSyncOffset, recordRejected, unsyncedInfo, loadSegments, saveSegments, segmentFile,
+  HANDOFF_MARKER, HANDOFF_THRESHOLDS, GATE_MAX_CHILDREN, HELPER_AGENT_TYPE, watchAgentId, subagentTranscriptPath, readHeadTag, lastContextTokens, watchState, handoffMessage, handleWatch, handleGate, handleGateRelease, gateDir, gateSlots, gateReserve, gateConfirm, GATE_PENDING_MS,
   extractAgentId, hasAssistantUsage, hasDispatch, buildDispatch, handlePostToolUse, handleSubagentStop, maybeSpawnSync, runHook, runSync,
 };
 
@@ -1652,7 +2227,9 @@ if (require.main === module) {
       .catch((e) => logError(ctx.home, e, 'sync'))
       .finally(() => process.exit(0));
   } else {
-    const r = runHook();
+    const mode = process.argv.includes('--watch') ? 'watch'
+      : (process.argv.includes('--gate-release') ? 'gate-release' : (process.argv.includes('--gate') ? 'gate' : null));
+    const r = runHook({ mode });
     if (r && typeof r.stdout === 'string') process.stdout.write(r.stdout);
     process.exitCode = 0;
   }