@kienntpixon/dieu-phoi 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @kienntpixon/dieu-phoi
 
+## 0.5.0
+
+Giới hạn ngữ cảnh subagent (đo trên 429 subagent từ 2026-10-09: p50 đỉnh 144k, p90 373k, max 789k; lượt >128k = 83% chi phí; subagent không bao giờ tự nén vì chạy cửa sổ 1M).
+
+- **Nâng cấp:** dán lại `sheet/Code.gs` (cột `parent_task_id`, `parent_agent_id`; luật tiếp nối handoff) rồi `dieu-phoi setup` để cài agent `dp-*`.
+- **File bàn giao `dp-out-<task>-<role>-try<n>.md`:** Claude Code chặn cứng Write trong subagent khi tên khớp `/^(REPORT|SUMMARY|FINDINGS|ANALYSIS).*.md$/i` (trước cả permissions, không cấu hình được) nên exec/verify/scout ghi toàn bộ kết quả vào `dp-out-*` và chỉ trả đường dẫn + `STATUS` + ≤ 3 dòng. Hook `SubagentStop`: agent exec/verify/plan trả kết quả mà không có file (Write hỏng, trả inline) → lưu nguyên văn phần trả về thành `<run>/dp-out-<task>-<role>-try<n>.inline.md` (bỏ qua khi đã có `dp-out-*` hoặc `report-*`/`verify-*` cũ của lượt đó, khi agent handoff, khi là helper; run dir lấy từ đường dẫn trong brief, không bao giờ ra ngoài `runsDir()`). Agent `dp-exec`/`dp-verify`/`dp-scout` ghi rõ hợp đồng này.
+- **Loại agent `dp-exec`, `dp-verify`, `dp-scout`, `dp-helper`** (`cli/agents/`, `setup` cài vào `~/.claude/agents/`): `autoCompactWindow: 200000`, không đặt model, chỉ `dp-exec` có Agent; `dp-helper` không Agent/Edit/Write (độ sâu dừng ở 2). Setup idempotent, không bao giờ ghi đè file trùng tên không có dấu `# dieu-phoi-managed:`; `uninstall` gỡ đúng file của mình; `doctor` báo `agents: …=ok|outdated|missing|foreign`.
+- **Watchdog ngữ cảnh** (`hook.cjs --watch`, PostToolUse trong frontmatter agent dp-*): subagent có thẻ `[dp:` vượt 150k rồi 180k token ngữ cảnh → additionalContext một lần mỗi ngưỡng: ghi `handoff-<task_id>.md` trong run dir và dừng với `STATUS: partial — handoff`. Đọc đuôi transcript subagent, ~2 ms tính.
+- **Handoff = `aborted`, không phải fail:** `SubagentStop` ghi verdict `aborted` `reason_code=auto-handoff`; thước đo (CLI + sink, fixture parity thêm ô `refactor`) nối tầng agent của lượt exec đầu sang agent tiếp nối cùng `try`.
+- **Gen-2 có kiểm soát** (`hook.cjs --gate`, PreToolUse(Agent) của `dp-exec`): tối đa 4 `dp-helper`/bước, model haiku|sonnet đặt rõ, thẻ `role=helper|parent=<task>`; sai luật → deny kèm lý do. Thẻ nhận `role=helper` và `parent=`; dispatch ghi `parent_task_id` + `parent_agent_id`. `choose --role helper` kẹp trần sonnet/high; helper không bao giờ là lượt/mẫu.
+- **Sửa sau review:** suất helper của `--gate` là file `data/gate/<task>/slot-1..4.json` tạo độc quyền (`wx`) — gọi Agent song song không vượt 4, không còn ghi đè trạng thái `--watch` (hai file riêng; file watch tạo bằng `wx`). Suất chỉ tính khi helper chạy thật: xác nhận qua `--watch` (helper tự xác nhận, hoặc PostToolUse(Agent) của exec), trả lại qua `--gate-release` (PostToolUseFailure(Agent) mới trong `dp-exec`) hoặc sau 10 phút chưa xác nhận. Watchdog cho `dp-verify`/`dp-scout`/`dp-helper`: trả verdict/tóm tắt ngay, không ghi handoff (chỉ exec handoff). `attempt_*` (ước lượng `choose`) cộng mọi đoạn exec của chuỗi handoff; fixture parity thêm chuỗi 3 đoạn (ô `refactor` n=3). `doctor` so agent với node đã đăng ký trong settings, không báo "outdated" giả khi chạy bằng node khác.
+
 ## 0.4.0
 
 Theo bản rà soát telemetry tune0001 (2026-10-12: 886 sự kiện sạch, ~157 task, 8 phiên điều phối).

package/README.md

@@ -8,6 +8,8 @@ Hook + CLI cho skill **dieu-phoi**: ghi lại mỗi lần Claude Code giao việ
 
 ## Cài đặt
 
+> Nâng cấp lên 0.5.0: dán lại `sheet/Code.gs` (cột `parent_task_id`, `parent_agent_id`, luật tiếp nối handoff) rồi chạy lại `dieu-phoi setup` để cài agent `dp-*`.
+
 > Nâng cấp lên 0.4.0: **dán lại `sheet/Code.gs` và deploy bản mới TRƯỚC khi nâng CLI** — Code.gs cũ từ chối kind mới `discard` và tính `orch_share` theo cách cũ; sau đó `npm i -g @kienntpixon/dieu-phoi@0.4.0` rồi `dieu-phoi setup`.
 >
 > Nâng cấp lên 0.2.0: **dán lại `sheet/Code.gs` và deploy bản mới TRƯỚC khi nâng CLI** — Code.gs cũ bỏ qua (làm rơi) các trường mới `session_id, orch_ctx_tokens, orch_cum_usd, orch_ctx_baseline, orch_compactions` của bản ghi được đẩy lên trong lúc chưa cập nhật; sau đó `npm i -g @kienntpixon/dieu-phoi@0.2.0` rồi `dieu-phoi setup`.
@@ -27,6 +29,7 @@ Không cài toàn cục được thì dùng `npx -y @kienntpixon/dieu-phoi <lệ
 1. chép `hook.cjs` + `pricing.json` vào `~/.claude/dieu-phoi/bin/`;
 2. sao lưu `~/.claude/settings.json` thành `settings.json.bak-dieu-phoi-<thời gian>` rồi đăng ký `PostToolUse` (matcher `Agent`) và `SubagentStop` chạy `"<đường dẫn node>" "<…>/dieu-phoi/bin/hook.cjs"` (node tuyệt đối, không phụ thuộc PATH). Các hook và khoá khác giữ nguyên, kể cả mảng/đối tượng rỗng. Chạy lại khi hook đã đúng thì không ghi file, không tạo bản sao lưu. Đổi phiên bản node (nvm…) thì chạy lại `setup`;
 3. ghi `~/.claude/dieu-phoi/config.json` (phòng ban, sink, đường dẫn skill, mã băm người dùng). Thư mục skill tự dò: `<claude>/skills/dieu-phoi`, hoặc thư mục `<claude>/skills/*` có `profile/profile.json` và `SKILL.md` mang `name: dieu-phoi` (fork phòng ban đổi tên thư mục vẫn tìm được).
+4. (0.5.0) ghi `~/.claude/agents/dp-exec.md`, `dp-verify.md`, `dp-scout.md`, `dp-helper.md` (`autoCompactWindow: 200000`, hook watchdog ngữ cảnh + cổng helper gen-2 trong frontmatter — chỉ chạy khi điều phối viên giao bằng các loại agent này). File trùng tên không phải của dieu-phoi được giữ nguyên.
 
 Khởi động lại Claude Code sau khi cài. Kiểm tra bằng `dieu-phoi doctor` (chạy thử chính lệnh hook đã đăng ký).
 

package/agents/dp-exec.md

@@ -0,0 +1,38 @@
+---
+name: dp-exec
+description: "dieu-phoi only — executor subagent dispatched by the dieu-phoi orchestrator with a [dp:...] brief. Do not pick this agent on your own."
+# dieu-phoi-managed: do not edit (dieu-phoi setup rewrites this file)
+autoCompactWindow: 200000
+hooks:
+  PostToolUse:
+    - matcher: "*"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --watch'
+          timeout: 5
+  PreToolUse:
+    - matcher: "Agent|Task"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --gate'
+          timeout: 5
+  PostToolUseFailure:
+    - matcher: "Agent|Task"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --gate-release'
+          timeout: 5
+---
+Bạn là agent thực thi (exec) của dieu-phoi. Brief ở tin nhắn đầu (dòng đầu là thẻ `[dp:...]`) là hợp đồng: làm đúng phạm vi, tự kiểm chứng, ghi báo cáo vào run dir và trả về bản tóm tắt ngắn đúng định dạng brief yêu cầu.
+
+Bàn giao qua file: ghi TOÀN BỘ kết quả vào `dp-out-<task_id>-exec-try<n>.md` trong run dir (đường dẫn brief chỉ định), rồi chỉ trả: đường dẫn file đó, dòng `STATUS:`, và ≤ 3 dòng ý chính. Không đặt tên file `report*` / `summary*` / `findings*` / `analysis*.md` — Claude Code chặn cứng Write các tên đó trong subagent. File dp-out/handoff mà brief trỏ tới là báo cáo chính thức: đọc thẳng, không cần xin thêm quyền.
+
+Helper thế hệ 2 (tuỳ chọn, chỉ khi giúp giữ ngữ cảnh nhỏ): tối đa 4 agent `subagent_type: dp-helper`, `model` đặt rõ `haiku` hoặc `sonnet`, cho đúng hai loại việc — (a) đọc/quét code hoặc tài liệu rồi trả tóm tắt ≤ 15 dòng, (b) chạy test / Unity smoke rồi tóm tắt log. Dòng đầu prompt helper: `[dp:<type>|s<n>|<urgency>|try1|task=<id mới từ dieu-phoi new-id>|role=helper|parent=<task của bạn>]`. Hook từ chối mọi lần giao sai luật. Không giao helper sửa code.
+
+Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
+- Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
+- Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
+- Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.
+- Không bao giờ đọc transcript phiên (`~/.claude/projects/**/*.jsonl`).
+- Khi hook dieu-phoi báo ngữ cảnh chạm ngưỡng: dừng việc mới, ghi file handoff hook chỉ định (`handoff-<task_id>.md` trong run dir: Đã xong / Đang dở / Bước tiếp theo / File đã động / Bẫy & ghi chú) rồi kết thúc với dòng đầu báo cáo đúng `STATUS: partial — handoff`.

package/agents/dp-helper.md

@@ -0,0 +1,23 @@
+---
+name: dp-helper
+description: "dieu-phoi only — gen-2 helper spawned by a dp-exec agent (read/scan and summarize, or run tests and summarize logs). Do not pick this agent on your own."
+# dieu-phoi-managed: do not edit (dieu-phoi setup rewrites this file)
+disallowedTools: Agent, Task, Edit, Write, NotebookEdit
+autoCompactWindow: 200000
+hooks:
+  PostToolUse:
+    - matcher: "*"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --watch'
+          timeout: 5
+---
+Bạn là helper thế hệ 2 của dieu-phoi, do một agent exec giao (thẻ `[dp:...|role=helper|parent=...]`). Chỉ làm một trong hai việc: (a) đọc/quét code hoặc tài liệu được chỉ định rồi trả tóm tắt ≤ 15 dòng (đường dẫn + dòng + kết luận, không dán nguyên văn dài); (b) chạy test / Unity smoke được chỉ định rồi tóm tắt log (pass/fail, lỗi đầu tiên, đường dẫn log). Không sửa file, không giao việc tiếp. Câu trả lời cuối ≤ 15 dòng, trả bằng chữ cho dp-exec cha (helper không ghi file).
+
+Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
+- Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
+- Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
+- Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.
+- Không bao giờ đọc transcript phiên (`~/.claude/projects/**/*.jsonl`).
+- Khi hook dieu-phoi báo ngữ cảnh chạm ngưỡng: dừng đọc/chạy thêm, trả bản tóm tắt NGAY với những gì đã có và ghi rõ phần chưa kiểm được. Không ghi file handoff — chỉ agent exec mới handoff.

package/agents/dp-scout.md

@@ -0,0 +1,25 @@
+---
+name: dp-scout
+description: "dieu-phoi only — read-only scout/planner subagent dispatched by the dieu-phoi orchestrator with a [dp:...|role=plan] brief. Do not pick this agent on your own."
+# dieu-phoi-managed: do not edit (dieu-phoi setup rewrites this file)
+disallowedTools: Agent, Task, Edit, NotebookEdit
+autoCompactWindow: 200000
+hooks:
+  PostToolUse:
+    - matcher: "*"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --watch'
+          timeout: 5
+---
+Bạn là scout/planner của dieu-phoi: khảo sát (code, tài liệu, dữ liệu) theo brief ở tin nhắn đầu (thẻ `[dp:...|role=plan]`) và trả về kế hoạch/câu hỏi đúng định dạng brief. Không sửa file của dự án; Write chỉ dùng để ghi báo cáo/kế hoạch vào run dir.
+
+Bàn giao qua file: ghi TOÀN BỘ kết quả vào `dp-out-<task_id>-plan-try<n>.md` trong run dir (đường dẫn brief chỉ định), rồi chỉ trả: đường dẫn file đó, dòng `STATUS:`, và ≤ 3 dòng ý chính. Không đặt tên file `report*` / `summary*` / `findings*` / `analysis*.md` — Claude Code chặn cứng Write các tên đó trong subagent. File dp-out/handoff mà brief trỏ tới là báo cáo chính thức: đọc thẳng, không cần xin thêm quyền.
+
+Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
+- Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
+- Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
+- Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.
+- Không bao giờ đọc transcript phiên (`~/.claude/projects/**/*.jsonl`).
+- Khi hook dieu-phoi báo ngữ cảnh chạm ngưỡng: dừng đọc/chạy thêm, trả bản tóm tắt NGAY với những gì đã có và ghi rõ phần chưa kiểm được. Không ghi file handoff — chỉ agent exec mới handoff.

package/agents/dp-verify.md

@@ -0,0 +1,25 @@
+---
+name: dp-verify
+description: "dieu-phoi only — independent verifier subagent dispatched by the dieu-phoi orchestrator with a [dp:...|role=verify] brief. Do not pick this agent on your own."
+# dieu-phoi-managed: do not edit (dieu-phoi setup rewrites this file)
+disallowedTools: Agent, Task, Edit, NotebookEdit
+autoCompactWindow: 200000
+hooks:
+  PostToolUse:
+    - matcher: "*"
+      hooks:
+        - type: command
+          command: '__DP_HOOK__ --watch'
+          timeout: 5
+---
+Bạn là agent kiểm chứng (verify) của dieu-phoi: kiểm tra độc lập kết quả của bước exec theo brief ở tin nhắn đầu (thẻ `[dp:...|role=verify]`). Chỉ đọc và chạy lệnh kiểm tra (test, lint, build); không sửa code của dự án. Ghi báo cáo vào run dir (Write chỉ dùng cho báo cáo) và trả về verdict ngắn đúng định dạng brief.
+
+Bàn giao qua file: ghi TOÀN BỘ kết quả vào `dp-out-<task_id>-verify-try<n>.md` trong run dir (đường dẫn brief chỉ định), rồi chỉ trả: đường dẫn file đó, dòng `STATUS:`/`VERDICT:`, và ≤ 3 dòng ý chính. Không đặt tên file `report*` / `summary*` / `findings*` / `analysis*.md` — Claude Code chặn cứng Write các tên đó trong subagent. File dp-out/handoff mà brief trỏ tới là báo cáo chính thức: đọc thẳng, không cần xin thêm quyền.
+
+Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
+- Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
+- Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
+- Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.
+- Không bao giờ đọc transcript phiên (`~/.claude/projects/**/*.jsonl`).
+- Khi hook dieu-phoi báo ngữ cảnh chạm ngưỡng: dừng đọc/chạy thêm, trả verdict (dòng STATUS + các phát hiện) NGAY với những gì đã có và ghi rõ phần chưa kiểm được. Không ghi file handoff — chỉ agent exec mới handoff.

package/bin/dieu-phoi.cjs

@@ -27,7 +27,7 @@ Cách dùng: dieu-phoi <lệnh> [tuỳ chọn]
   stats [--type T] [--json]
                          bảng task_type × model/effort: n, accept%, agent_pass%, chi phí/thời gian (TB, p50, p75), steer
   choose --type T --score N [--urgency relaxed|normal|urgent] [--reversible y|n]
-         [--verifiable y|n] [--role exec|verify|plan] [--task ID]
+         [--verifiable y|n] [--role exec|verify|plan|helper] [--task ID]
          [--override model/effort (cần --task) | --approved model/effort] [--skill-dir P] [--seed S] [--json]
                          đề xuất model + effort, lý do, action (dispatch|ask_user), ước tính chi phí/thời gian
   ctx [--session <id>] [--json]

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.4.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
@@ -1398,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) {
@@ -1435,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;
@@ -1487,6 +1618,9 @@ 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;
@@ -1503,6 +1637,8 @@ function handleSubagentStop(p, ctx) {
 // / 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/;
 
@@ -1527,7 +1663,338 @@ function abortReasonOf(lines) {
     if (last.error === 'rate_limit' || last.apiErrorStatus === 429 || CC_LIMIT_TEXT_RE.test(text.trim())) return 'usage-limit';
     return null;
   }
-  if (text.trimStart().split('\n')[0].trim().startsWith(QUOTA_PAUSE_MARKER)) return 'quota-pause';
+  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;
 }
 
@@ -1582,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);
@@ -1740,8 +2210,10 @@ module.exports = {
   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,
 };
 
@@ -1755,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;
   }

package/lib/aggregate.cjs

@@ -15,6 +15,9 @@ const ABORTED = 'aborted';
 // Exact markers only (anchored): `quota-pause`, `usage-limit`, the hook's `auto-*` codes and the legacy
 // `paused-for-quota-*` codes the orchestrator wrote before 0.4.0. A reason that merely mentions a rate limit stays a timeout.
 const QUOTA_REASON_RE = /^(?:quota-pause|usage-limit|auto-quota-pause|auto-usage-limit|paused-for-quota)(?:-|$)/;
+// core 0.5.0: `aborted` with this reason = the agent stopped on the context watchdog and wrote handoff.md. Its
+// continuation (next exec agent of the task with the same try) carries the attempt's agent-layer result.
+const HANDOFF_REASON_RE = /^(?:auto-)?handoff(?:-|$)/;
 
 function tsOf(ev) {
   const t = Date.parse(ev && ev.ts);
@@ -174,6 +177,7 @@ function buildAgents(events) {
       // every non-aborted agent verdict in time order: a retry by SendMessage to the same agent is a new result
       verdict_seq: v.map((x) => ({ outcome: x.outcome, ts: tsOf(x), idx: x._idx })),
       aborted: vAll.length > 0 && vAll[vAll.length - 1].outcome === ABORTED,
+      handoff: vAll.some((x) => x.outcome === ABORTED && HANDOFF_REASON_RE.test(String(x.reason_code || ''))),
       verify: verdict ? verdict.verify : null,
       reason_code: verdict ? verdict.reason_code : null,
       steers: a.steers.map((s) => s.steer_kind).filter(Boolean),
@@ -206,10 +210,20 @@ function buildTasks(agents, userVerdicts) {
   const tasks = [];
   for (const t of map.values()) {
     const byTry = (x, y) => (x.try - y.try) || (x.ts - y.ts) || (x._idx - y._idx);
-    const attempts = t.agents.filter((a) => a.role !== 'verify').sort(byTry);
+    // gen-2 helpers (role=helper, own task_id) are never attempts
+    const attempts = t.agents.filter((a) => a.role !== 'verify' && a.role !== 'helper').sort(byTry);
     const verifies = t.agents.filter((a) => a.role === 'verify');
     // First exec attempt: lowest try among role=exec (ties: earliest). No exec attempt -> no sample.
-    const first = t.agents.filter((a) => a.role === 'exec').sort(byTry)[0] || null;
+    const execs = t.agents.filter((a) => a.role === 'exec').sort(byTry);
+    const first = execs[0] || null;
+    // core 0.5.0: a first exec that stopped on a context handoff (no result of its own) passes the agent layer to its
+    // continuation(s) with the same try; the tier stays the first exec's.
+    let firstRes = first;
+    const chain = first ? [first] : [];
+    for (let i = 1; firstRes && !firstRes.first_outcome && firstRes.handoff && i < execs.length && execs[i].try === first.try; i++) {
+      firstRes = execs[i];
+      chain.push(firstRes);
+    }
     const user = t.user.slice().sort((x, y) => ((x.round || 0) - (y.round || 0)) || (tsOf(x) - tsOf(y)) || (x._idx - y._idx));
 
     // Results for escalation. Each agent verdict of an attempt is one result at its tier (a retry by
@@ -240,8 +254,8 @@ function buildTasks(agents, userVerdicts) {
       else userOutcome = firstUser.cause === 'scope' ? 'reject_scope' : 'reject_quality';
     }
     // Agent layer of the first exec attempt: its first agent verdict.
-    const agentFirst = first && first.first_outcome && (first.first_outcome === 'pass' || FAIL_OUTCOMES.has(first.first_outcome))
-      ? first.first_outcome === 'pass' : null;
+    const agentFirst = firstRes && firstRes.first_outcome && (firstRes.first_outcome === 'pass' || FAIL_OUTCOMES.has(firstRes.first_outcome))
+      ? firstRes.first_outcome === 'pass' : null;
     let success = null;
     let source = null;
     if (userOutcome === 'accept') { success = true; source = 'user'; } else if (userOutcome === 'reject_quality') { success = false; source = 'user'; } else if (!userOutcome && agentFirst !== null) {
@@ -255,6 +269,11 @@ function buildTasks(agents, userVerdicts) {
       task_id: t.task_id,
       task_type: first ? first.task_type : (t.agents[0] && t.agents[0].task_type) || 'untagged',
       first,
+      // the first attempt as a whole: its exec segment plus every handoff continuation (time/cost summed over all
+      // segments; the result comes from the last one, firstRes)
+      first_chain: chain,
+      first_cost: chain.length ? sumOrNull(chain.map((a) => a.cost_usd)) : null,
+      first_time_s: chain.length ? sumOrNull(chain.map((a) => a.duration_s)) : null,
       attempts,
       verifies,
       user_verdicts: user,
@@ -304,8 +323,9 @@ function buildCells(tasks, opts) {
     const passes = c.tasks.filter((t) => t.success).length;
     const costs = c.tasks.map((t) => t.total_cost);
     const timesMin = c.tasks.map((t) => (t.total_time_s === null ? null : t.total_time_s / 60));
-    const attemptTimes = c.tasks.map((t) => (t.first.duration_s === null ? null : t.first.duration_s / 60));
-    const attemptCosts = c.tasks.map((t) => t.first.cost_usd);
+    // a handoff chain is one attempt: all its segments count (t.first alone would bill only the first segment)
+    const attemptTimes = c.tasks.map((t) => (t.first_time_s === null || t.first_time_s === undefined ? null : t.first_time_s / 60));
+    const attemptCosts = c.tasks.map((t) => (t.first_cost === undefined ? null : t.first_cost));
     const costMean = mean(costs);
     const timeMean = mean(timesMin);
     out.push({
@@ -472,6 +492,6 @@ function analyze(events, opts) {
 }
 
 module.exports = {
-  MIN_N, FAIL_OUTCOMES, HEAVY_STEERS, ABORTED, QUOTA_REASON_RE, discardedTaskIds, withoutDiscarded, CANONICAL_CELL_FIELDS, normalizeVerdict, isInternalComplete, buildAgents, buildTasks,
+  MIN_N, FAIL_OUTCOMES, HEAVY_STEERS, ABORTED, QUOTA_REASON_RE, HANDOFF_REASON_RE, discardedTaskIds, withoutDiscarded, CANONICAL_CELL_FIELDS, normalizeVerdict, isInternalComplete, buildAgents, buildTasks,
   buildCells, buildSteers, canonicalCells, orchestrationSummary, analyze, cellKey, mean, percentile, tsOf, steerIdOf,
 };

package/lib/choose.cjs

@@ -17,6 +17,7 @@ const LADDER = [
   { model: 'opus', effort: 'medium' },
 ];
 const TOP = LADDER.length - 1;
+const HELPER_TOP = 4; // sonnet/high: ceiling for role=helper (gen-2)
 const EFFORT_RANK = { low: 0, medium: 1, high: 2, xhigh: 3, max: 4 };
 
 // Built-in defaults = skill/profile/profile.json for the fixed task types (time caps as tuned 2026-10-12: feature-impl 80,
@@ -418,7 +419,10 @@ function choose(opts) {
     && shortModel(c.model) === LADDER[i].model && c.effort === LADDER[i].effort) || null;
 
   const src = profile.source || 'builtin';
-  const finish = (idx, reason, explored, extra) => {
+  const finish = (idx0, reason0, explored, extra) => {
+    // core 0.5.0: a gen-2 helper (spawned by a dp-exec) is haiku|sonnet only — clamp to sonnet/high
+    const idx = role === 'helper' ? Math.min(idx0, HELPER_TOP) : idx0;
+    const reason = idx === idx0 ? reason0 : `${reason0}; helper: trần ${tierName(HELPER_TOP)}`;
     const t = LADDER[idx];
     const cell = cellAt(idx);
     return Object.assign({

package/lib/commands.cjs

@@ -65,6 +65,7 @@ function cmdSetup(opts) {
     res.settings_changed
       ? `Đã đăng ký PostToolUse(Agent) + SubagentStop + SessionStart(compact) + UserPromptSubmit trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
       : `settings.json đã có hook, không đổi gì (${res.settings})`,
+    `Agent dp-*: ${res.agents.map((a) => `${a.name}=${a.action}`).join(', ')}${res.agents.some((a) => a.action === 'skipped-foreign') ? ' (file trùng tên không phải của dieu-phoi: giữ nguyên, đổi tên rồi chạy lại setup)' : ''}`,
     `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ộ)'}`,
@@ -80,7 +81,7 @@ function cmdUninstall(opts) {
   return {
     code: 0,
     out: res.removed
-      ? `Đã gỡ ${res.removed} hook khỏi ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}. Dữ liệu giữ ở ${res.data_kept}.`
+      ? `Đã gỡ ${res.removed} hook khỏi ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}${res.agents_removed.length ? `, agent ${res.agents_removed.join(', ')}` : ''}. Dữ liệu giữ ở ${res.data_kept}.`
       : `Không thấy hook dieu-phoi trong ${res.settings}.`,
   };
 }
@@ -105,6 +106,11 @@ async function cmdDoctor(opts) {
   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');
+  // compare with the node binary setup wrote into settings.json (and the agent files), not this process's node: a doctor run
+  // under another node (nvm, upgrade) must not report a false "outdated"
+  const agentSt = setupLib.agentStatus(claudeDir, ctx.paths.hook, setupLib.nodePathOf(reg.commands[0]));
+  const agentsOk = agentSt.every((a) => a.state === 'ok');
+  add(agentsOk, 'agents', `${agentSt.map((a) => `${a.name}=${a.state}`).join(', ')}${agentsOk ? '' : ' — chạy `dieu-phoi setup` (foreign = file trùng tên không phải của dieu-phoi, không bị ghi đè)'}`, '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;

package/lib/setup.cjs

@@ -245,6 +245,71 @@ function skillVersionOf(dir) {
   }
 }
 
+// ------------------------------------------------------------------ dp-* agent files (core 0.5.0)
+
+const AGENT_NAMES = ['dp-exec', 'dp-verify', 'dp-scout', 'dp-helper'];
+const AGENT_MARKER = '# dieu-phoi-managed:';
+const AGENT_HOOK_PLACEHOLDER = '__DP_HOOK__';
+
+function agentsDirOf(claudeDir) {
+  return path.join(path.resolve(claudeDir), 'agents');
+}
+
+/** Agent file content for this install: template with the absolute hook command (YAML single-quoted). */
+function renderAgent(name, hookPath, nodePath) {
+  const tpl = fs.readFileSync(path.join(PKG_ROOT, 'agents', `${name}.md`), 'utf8').replace(/\r\n/g, '\n');
+  const cmd = hookCommand(hookPath, nodePath).replace(/'/g, "''");
+  return tpl.split(AGENT_HOOK_PLACEHOLDER).join(cmd);
+}
+
+/** Node binary of a registered hook command (`"<node>" "<hook>" ...`), or undefined. */
+function nodePathOf(cmd) {
+  const m = typeof cmd === 'string' ? /^\s*"([^"]+)"\s+"[^"]+"/.exec(cmd) : null;
+  return m ? m[1] : undefined;
+}
+
+/**
+ * State of each dp-* agent file: ok (ours, identical), outdated (ours, differs), missing, foreign (a file with
+ * that name we did not write — never touched).
+ */
+function agentStatus(claudeDir, hookPath, nodePath) {
+  const dir = agentsDirOf(claudeDir);
+  return AGENT_NAMES.map((name) => {
+    const file = path.join(dir, `${name}.md`);
+    let cur = null;
+    try { cur = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n'); } catch (_) { /* missing */ }
+    let state = 'missing';
+    if (cur !== null) {
+      if (!cur.includes(AGENT_MARKER)) state = 'foreign';
+      else state = cur === renderAgent(name, hookPath, nodePath) ? 'ok' : 'outdated';
+    }
+    return { name, file, state };
+  });
+}
+
+/** Write missing/outdated dp-* agent files (LF). Foreign files are reported, never overwritten. */
+function installAgents(claudeDir, hookPath, nodePath) {
+  const dir = agentsDirOf(claudeDir);
+  fs.mkdirSync(dir, { recursive: true });
+  return agentStatus(claudeDir, hookPath, nodePath).map((a) => {
+    if (a.state === 'ok' || a.state === 'foreign') return Object.assign({ action: a.state === 'ok' ? 'unchanged' : 'skipped-foreign' }, a);
+    core.writeFileAtomic(a.file, renderAgent(a.name, hookPath, nodePath));
+    return Object.assign({}, a, { action: a.state === 'missing' ? 'installed' : 'updated', state: 'ok' });
+  });
+}
+
+/** Remove only our dp-* agent files (marker present). */
+function removeAgents(claudeDir) {
+  const removed = [];
+  for (const name of AGENT_NAMES) {
+    const file = path.join(agentsDirOf(claudeDir), `${name}.md`);
+    try {
+      if (fs.readFileSync(file, 'utf8').includes(AGENT_MARKER)) { fs.unlinkSync(file); removed.push(name); }
+    } catch (_) { /* missing */ }
+  }
+  return removed;
+}
+
 /**
  * Install: copy hook + pricing, register hooks, write config.
  * opts: { claudeDir, dept, sinkUrl, sinkToken, skillDir }
@@ -302,8 +367,11 @@ function setup(opts) {
   if (legacyRemoved) dirty = true;
   if (addOurPermissions(obj, perms)) dirty = true;
   if (dirty) res = writeSettings(settingsFile, before, obj);
+  // 5. dp-* agent types (~/.claude/agents): only used when the orchestrator dispatches with subagent_type dp-*
+  const agents = installAgents(claudeDir, paths.hook, opts.nodePath);
 
   return {
+    agents,
     home,
     hook: paths.hook,
     command: cmd,
@@ -329,13 +397,14 @@ function uninstall(opts) {
     + stripOurPermissions(obj, permissionEntries(legacyRunsDirOf(claudeDir)));
   let res = { changed: false, backup: null };
   if (removed || permsRemoved) res = writeSettings(settingsFile, before, obj);
+  const agentsRemoved = removeAgents(claudeDir);
   const hookFile = core.pathsFor(home).hook;
   let hookRemoved = false;
   if (opts.purge && fs.existsSync(hookFile)) {
     fs.unlinkSync(hookFile);
     hookRemoved = true;
   }
-  return { removed, permissions_removed: permsRemoved, settings: settingsFile, backup: res.backup, hook_removed: hookRemoved, data_kept: core.pathsFor(home).data };
+  return { removed, agents_removed: agentsRemoved, permissions_removed: permsRemoved, settings: settingsFile, backup: res.backup, hook_removed: hookRemoved, data_kept: core.pathsFor(home).data };
 }
 
 /** Inspect settings for our registration. */
@@ -369,6 +438,6 @@ function registration(claudeDir) {
 }
 
 module.exports = {
-  MARKER, setup, uninstall, registration, stripOurHooks, addOurHooks, alreadyRegistered, hookCommand,
+  MARKER, AGENT_NAMES, AGENT_MARKER, renderAgent, agentStatus, nodePathOf, installAgents, removeAgents, agentsDirOf, setup, uninstall, registration, stripOurHooks, addOurHooks, alreadyRegistered, hookCommand,
   skillVersionOf, findSkillDir, tsStamp, runsDir, legacyRunsDirOf, permissionEntries, addOurPermissions, stripOurPermissions, hasOurPermissions,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kienntpixon/dieu-phoi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Hook + CLI ghi log subagent của Claude Code và chọn model/effort theo chi phí + thời gian tới lúc nghiệm thu.",
   "license": "MIT",
   "author": "kiennt <kiennt@pixon.games>",
@@ -20,6 +20,7 @@
   "main": "hook.cjs",
   "files": [
     "bin/",
+    "agents/",
     "lib/",
     "hook.cjs",
     "pricing.json",