@pan-stack/cli 0.3.31 → 0.3.33

package/dist/agent-plugin/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "pan-stack",
+  "interface": {
+    "displayName": "PAN Stack"
+  },
+  "plugins": [
+    {
+      "name": "pan-harness",
+      "source": {
+        "source": "local",
+        "path": "./plugins/pan-harness"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

package/dist/agent-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "pan-stack",
+  "owner": {
+    "name": "n46-labs"
+  },
+  "description": "PAN Stack: harness (danh tính AI, Pan Lineage) và bộ skill PAN, đi kèm @pan-stack/cli — cài bằng `pan harness setup`.",
+  "plugins": [
+    {
+      "name": "pan-harness",
+      "source": "./plugins/pan-harness",
+      "description": "Harness cho workspace PAN Stack: mọi commit của Claude mang danh tính AI + người chủ quản + máy; nguồn tài liệu (Pan Lineage) của tệp hiện ra trước khi sửa."
+    }
+  ]
+}

package/dist/agent-plugin/plugins/pan-harness/.claude-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "pan-harness",
+  "displayName": "Pan Harness",
+  "version": "0.3.33",
+  "description": "Harness cho workspace PAN Stack: mọi commit của Claude mang danh tính AI + người chủ quản + máy; nguồn tài liệu (Pan Lineage) của tệp hiện ra trước khi sửa.",
+  "author": {
+    "name": "n46-labs"
+  },
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "keywords": [
+    "pan-stack",
+    "lineage",
+    "harness"
+  ],
+  "hooks": "./hooks/claude.json",
+  "userConfig": {
+    "agent_code": {
+      "type": "string",
+      "title": "Mã agent",
+      "description": "Mã ghi vào sổ lineage cho mọi việc Claude làm trong phiên (vd claude, dev-a)",
+      "default": "claude"
+    },
+    "strict_lineage": {
+      "type": "boolean",
+      "title": "Chặn sửa khi nguồn đã đổi",
+      "description": "Bật: không cho sửa tệp có nguồn tài liệu đã đổi cho tới khi xem pan lineage diff rồi derive hoặc ack",
+      "default": false
+    }
+  }
+}

package/dist/agent-plugin/plugins/pan-harness/.codex-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "pan-harness",
+  "version": "0.3.33",
+  "description": "PAN Stack harness for AI agents: every commit carries AI + owner + machine identity, document sources (Pan Lineage) show before edits, and PAN skills load on their own.",
+  "author": {
+    "name": "n46-labs"
+  },
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "keywords": [
+    "pan-stack",
+    "lineage",
+    "harness"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Pan Harness",
+    "shortDescription": "PAN skills and workflow rules for PAN Stack workspaces",
+    "longDescription": "PAN Stack harness for AI agents: every commit carries AI + owner + machine identity, document sources (Pan Lineage) show before edits, and PAN skills load on their own.",
+    "developerName": "n46-labs",
+    "category": "Coding",
+    "capabilities": [
+      "Read",
+      "Write"
+    ]
+  }
+}

package/dist/agent-plugin/plugins/pan-harness/.cursor-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "pan-harness",
+  "displayName": "Pan Harness",
+  "version": "0.3.33",
+  "description": "PAN Stack harness for AI agents: every commit carries AI + owner + machine identity, document sources (Pan Lineage) show before edits, and PAN skills load on their own.",
+  "author": {
+    "name": "n46-labs"
+  },
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "keywords": [
+    "pan-stack",
+    "lineage",
+    "harness"
+  ],
+  "skills": "./skills/",
+  "rules": "./rules/"
+}

package/dist/agent-plugin/plugins/pan-harness/LICENSE.txt

@@ -0,0 +1,41 @@
+NaNa Software License
+
+Copyright (c) 2026 NaNa Software. All rights reserved.
+
+This software, including its source code, compiled code and documentation (the
+"Software"), is owned by NaNa Software. It is licensed, not sold.
+
+1. License required. You may install, run or otherwise use the Software only if
+   NaNa Software has granted you a license in writing, and only within the scope
+   and term of that license. Being able to download the Software from a public
+   package registry or code host does not grant you a license.
+
+2. Restrictions. Unless your written license from NaNa Software allows it, you
+   may not:
+   a. copy, publish, distribute, sublicense, rent, lease, sell or otherwise
+      transfer the Software, in whole or in part;
+   b. modify the Software or create derivative works based on it;
+   c. reverse engineer, decompile or disassemble the Software, except to the
+      extent that applicable law expressly permits this despite this
+      restriction;
+   d. remove or change any copyright, trademark or other proprietary notice in
+      the Software.
+
+3. Third-party components. Parts of the Software come from third parties. Those
+   parts stay under their own licenses, which apply to those parts instead of
+   this license.
+
+4. Termination. Your right to use the Software ends automatically when you
+   break these terms or when your written license ends. You must then stop
+   using the Software and delete all copies of it.
+
+5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. Limitation of liability. IN NO EVENT SHALL NANA SOFTWARE BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OF OR OTHER DEALINGS IN THE SOFTWARE.
+
+To request a license, contact NaNa Software.

package/dist/agent-plugin/plugins/pan-harness/hooks/claude.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs", "session-start"], "timeout": 20 }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs", "after-read"], "timeout": 20 }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs", "after-edit"], "timeout": 30 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Edit|Write|MultiEdit|Bash|Agent|Task",
+        "hooks": [
+          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs", "pre-tool"], "timeout": 20 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs", "stop"], "timeout": 60 }
+        ]
+      }
+    ]
+  }
+}

package/dist/agent-plugin/plugins/pan-harness/rules/pan-skills.mdc

@@ -0,0 +1,15 @@
+---
+description: Tự chọn skill PAN cho mỗi yêu cầu
+alwaysApply: true
+---
+
+# Skill PAN
+
+Plugin pan-harness mang sẵn bộ skill PAN (thư mục `skills/` của plugin). Với **mỗi** yêu cầu của người dùng:
+
+1. Đối chiếu yêu cầu với tên và mô tả các skill PAN.
+2. Khớp rõ một skill: đọc `SKILL.md` của skill đó rồi làm theo, không cần người dùng gọi tên skill.
+3. Chỉ khớp một phần: hỏi người dùng một câu ngắn "Dùng skill <tên> cho việc này không?" trước khi làm.
+4. Không khớp skill nào: làm bình thường.
+
+Người dùng không phải gõ tên skill; tự chọn là việc của agent.

package/dist/agent-plugin/plugins/pan-harness/scripts/hook.mjs

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+// pan-harness — hook của Claude Code, một lối vào cho mọi sự kiện (`node hook.mjs <sự kiện>`, JSON của Claude Code
+// đi vào stdin). Thiết kế: repo pan-harness, docs/decisions/2026-10-28-pan-harness-plugin-solution.md và
+// …-lineage-solution.md §8.
+//
+//   session-start  ghi PAN_ACTOR_KIND/PAN_ACTOR/PAN_MODEL/PAN_RUN_MODE vào CLAUDE_ENV_FILE → mọi `git commit` Claude chạy
+//                  được hook `pan lineage` ghi đúng là AI thay mặt người chủ quản; nạp vài dòng ngữ cảnh (người chủ
+//                  quản, việc lineage cần xem lại).
+//   after-read     (PostToolUse của Read) tệp vừa đọc có nguồn trong sổ lineage → nạp nguồn + trạng thái, nguồn đã đổi
+//                  thì kèm diff. Đặt ở Read vì Claude Code bắt đọc tệp trước khi sửa, còn additionalContext của
+//                  PreToolUse chỉ đến Claude CÙNG kết quả tool — tức là sau khi đã sửa (đã đối chiếu tài liệu hooks).
+//   pre-tool       (PreToolUse) khối B — rào chắn: đọc / sửa tệp secret → deny (cả qua `cat .env` trong Bash); lệnh
+//                  không hoàn tác (`pan release-*`, `git push --force`, `--no-verify`…) → ask; `subagents: deny` trong
+//                  .pan-harness.yaml → deny tool Agent/Task. Lệnh khớp theo TOKEN (tôn trọng ngoặc kép) — chuỗi
+//                  `--no-verify` trong message commit không bị chặn nhầm. Sau đó với Edit/Write: lineage strict như cũ.
+//   after-edit     (PostToolUse của Edit/Write/MultiEdit) khối C — `pan harness lint <tệp>` theo `lint:` của
+//                  .pan-harness.yaml; vi phạm → nạp cho agent tự sửa, không chặn. Không khai `lint:` thì không gọi pan.
+//   before-edit    (giữ tên cũ) chỉ khi bật strict_lineage hoặc PAN_LINEAGE_STRICT=1: tệp có nguồn đã đổi → deny.
+//   stop           (Stop) khối D — cổng xong: `pan harness status --json`; cổng có sửa chưa commit trong phạm vi
+//                  (`changed`) mà chưa qua → mode enforce: chặn báo xong kèm cách làm; mode warn: chỉ nhắc người dùng.
+//                  Tối đa 2 lần chặn liên tiếp mỗi phiên (stop_hook_active) để không lặp vô hạn.
+//   Program        (OD-52) workspace khai Program (`studio:` trong .project.yaml), mọi lệnh `pan` chạy nền, không chờ:
+//                  pre-tool → `pan program presence` (đang làm; kèm tệp đang sửa để biết project con, mã phiên để mỗi
+//                  phiên là một bot), tối đa 30 giây/lần mỗi phiên trừ khi đổi trạng thái; stop → rảnh + `pan program
+//                  sync --auto`; session-start → `pan program sync --auto` (bắt kịp git pull giữa hai phiên).
+//
+// Ngoài workspace PAN thì không làm gì. Lỗi của chính hook không làm hỏng phiên: thoát 0, không in gì.
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const MESSAGES = {
+  vi: {
+    head: '[pan-harness] workspace {ws} · người chủ quản {principal} · agent {agent}{mode}',
+    noPrincipal: '[pan-harness] chưa có danh tính người chủ quản — chạy `pan me` trước khi commit',
+    autonomous: ' · tự chạy',
+    skills: 'Skill PAN có sẵn trong plugin pan-harness: yêu cầu khớp rõ một skill thì tự dùng skill đó; chỉ khớp một phần thì hỏi người dùng có dùng skill ấy không.',
+    staleCount: 'Lineage: {count} sản phẩm cần xem lại vì nguồn tài liệu đã đổi (`pan lineage stale`):',
+    rules:
+      'Luật: sửa tệp theo một mục tài liệu thì ghi nguồn `pan lineage derive <tệp> --source <repo>:<tài liệu>#<mục>`; ' +
+      'commit tự ghi phần còn lại nhờ hook `pan lineage`. Đã xem thay đổi nguồn mà tệp không cần sửa: `pan lineage ack … --reason "…"`.',
+    sources: '[pan-harness] {file} dẫn xuất từ:',
+    stale: 'Nguồn đã đổi từ lần dẫn xuất — cập nhật tệp theo nguồn mới rồi `pan lineage derive {file} --source {source}`, hoặc `pan lineage ack {file} --source {source} --reason "…"` nếu không cần sửa.',
+    deny: 'pan-harness (strict_lineage): {file} dựa trên nguồn đã đổi: {sources}. Xem `pan lineage diff {file}`, sửa theo nguồn mới, rồi `pan lineage derive` hoặc `ack` trước khi sửa tiếp.',
+    state: { fresh: 'khớp', stale: 'CẦN XEM LẠI', moved: 'đổi khoá', missing: 'nguồn mất', decision: 'quyết định', unknown: 'không rõ' },
+    secret: 'pan-harness: {file} chứa secret — không đọc / sửa nội dung. Dùng biến môi trường; cần giá trị thì hỏi người dùng.',
+    irreversible: 'pan-harness: `{command}` không hoàn tác được (phát hành / xoá / ép lịch sử / bỏ hook) — người dùng xác nhận trước.',
+    subagents: 'pan-harness: workspace cấm phóng subagent (.pan-harness.yaml › subagents: deny) — làm trực tiếp trong phiên này.',
+    approve: 'pan-harness: AI duyệt được — chạy `pan harness approve <pha>`, sổ ghi là AI thay người chủ quản. Không giả làm người: không đặt / xoá PAN_ACTOR_KIND, PAN_ACTOR trong lệnh duyệt, không gọi thẳng API nút Duyệt của dashboard (nút đó ghi là người bấm).',
+    gatesBlock: 'pan-harness (cổng xong): còn cổng chưa qua ở phần bạn đã sửa — {gates}. Chạy {commands}, sửa tới khi xanh rồi mới báo xong.',
+    gatesWarn: 'pan-harness: còn cổng chưa qua ở phần vừa sửa — {gates}. Chạy {commands} (hoặc nút Chạy cổng trên dashboard).',
+    gate: { fail: 'đỏ', outdated: 'cũ', never: 'chưa chạy' },
+    lint: '[pan-harness] lint {file}: {count} vi phạm luật của workspace (.pan-harness.yaml › lint) — sửa luôn:',
+  },
+  en: {
+    head: '[pan-harness] workspace {ws} · principal {principal} · agent {agent}{mode}',
+    noPrincipal: '[pan-harness] no principal identity yet — run `pan me` before committing',
+    autonomous: ' · autonomous',
+    skills: 'PAN skills ship with the pan-harness plugin: when a request clearly matches a skill, use it; when it only partly matches, ask the user whether to use that skill.',
+    staleCount: 'Lineage: {count} artifact(s) need review because their source documents changed (`pan lineage stale`):',
+    rules:
+      'Rule: when you change a file to follow a document section, record it with `pan lineage derive <file> --source <repo>:<doc>#<section>`; ' +
+      'commits record the rest through the `pan lineage` hook. Reviewed a source change and the file needs nothing: `pan lineage ack … --reason "…"`.',
+    sources: '[pan-harness] {file} is derived from:',
+    stale: 'The source changed since derivation — update the file to the new source, then `pan lineage derive {file} --source {source}`, or `pan lineage ack {file} --source {source} --reason "…"` if nothing needs to change.',
+    deny: 'pan-harness (strict_lineage): {file} depends on changed sources: {sources}. Read `pan lineage diff {file}`, follow the new source, then `pan lineage derive` or `ack` before editing further.',
+    state: { fresh: 'fresh', stale: 'NEEDS REVIEW', moved: 'key changed', missing: 'source gone', decision: 'decision', unknown: 'unknown' },
+    secret: 'pan-harness: {file} holds secrets — do not read or edit it. Use environment variables; ask the user if you need a value.',
+    irreversible: 'pan-harness: `{command}` cannot be undone (release / delete / rewrite history / skip hooks) — the user confirms first.',
+    subagents: 'pan-harness: this workspace forbids subagents (.pan-harness.yaml › subagents: deny) — do the work in this session.',
+    approve: 'pan-harness: the AI may approve — run `pan harness approve <phase>`; the ledger records the AI acting for the principal. Do not pose as a human: no setting / unsetting PAN_ACTOR_KIND or PAN_ACTOR in the approve command, no calling the dashboard Approve API directly (that button records a human click).',
+    gatesBlock: 'pan-harness (done gate): gates not passing in what you changed — {gates}. Run {commands}, fix until green, then report done.',
+    gatesWarn: 'pan-harness: gates not passing in what was just changed — {gates}. Run {commands} (or Run gates on the dashboard).',
+    gate: { fail: 'failing', outdated: 'outdated', never: 'not run' },
+    lint: '[pan-harness] lint {file}: {count} violation(s) of workspace rules (.pan-harness.yaml › lint) — fix them now:',
+  },
+};
+const MAX_DIFF_LINES = 60;
+
+function readInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function findUp(start, test) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (test(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return '';
+    dir = parent;
+  }
+}
+
+const workspaceOf = (start) => findUp(start, (dir) => fs.existsSync(path.join(dir, '.project.yaml')));
+const repoOf = (start) => findUp(start, (dir) => fs.existsSync(path.join(dir, '.git')));
+
+function format(template, values) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => (values[key] ?? match));
+}
+
+/** Ngôn ngữ theo pan: PAN_LANG → `language:` của `.project.yaml` → en. */
+function messagesFor(root) {
+  let code = (process.env.PAN_LANG || '').toLowerCase();
+  if (!code && root) code = /^language\s*:\s*(\w+)/m.exec(fs.readFileSync(path.join(root, '.project.yaml'), 'utf8'))?.[1] ?? '';
+  return MESSAGES[code] ?? MESSAGES.en;
+}
+
+/**
+ * Gọi `pan … --json`; lỗi / không có pan → null. Mã thoát 1 vẫn đọc JSON: theo hợp đồng của pan nó nghĩa là "còn việc
+ * chưa đạt" (vd `pan harness status` khi còn pha chưa xong), không phải lỗi.
+ */
+function pan(args, cwd) {
+  const parse = (out) => {
+    const parsed = JSON.parse(out);
+    return parsed.ok || Array.isArray(parsed.data) ? parsed.data : null;
+  };
+  try {
+    return parse(execFileSync('pan', [...args, '--json'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 30000 }));
+  } catch (error) {
+    try {
+      return error?.status === 1 && error.stdout ? parse(error.stdout) : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/** Lọc nhanh trước khi gọi pan: tệp có xuất hiện trong sổ `.pan-lineage/lineage.csv` của repo chứa nó không. */
+function inLedger(file) {
+  const repo = repoOf(path.dirname(file));
+  if (!repo) return false;
+  const ledger = path.join(repo, '.pan-lineage', 'lineage.csv');
+  if (!fs.existsSync(ledger)) return false;
+  return fs.readFileSync(ledger, 'utf8').includes(`:${path.relative(repo, file).split(path.sep).join('/')}`);
+}
+
+function emit(eventName, extra) {
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, ...extra } }));
+}
+
+function principalOf(root) {
+  try {
+    const text = fs.readFileSync(path.join(root, '.me.pan.yaml'), 'utf8');
+    const block = /^author\s*:[ \t]*\n((?:[ \t]+.*(?:\n|$))*)/m.exec(text)?.[1] ?? '';
+    const field = (key) => new RegExp(`^[ \\t]+${key}\\s*:\\s*(.*)$`, 'm').exec(block)?.[1]?.trim().replace(/^["']|["']$/g, '') ?? '';
+    return field('email') ? `${field('user')} <${field('email')}>` : '';
+  } catch {
+    return '';
+  }
+}
+
+function sessionStart(input) {
+  const root = workspaceOf(input.cwd || process.cwd());
+  if (!root) return;
+  const m = messagesFor(root);
+  const agent = process.env.CLAUDE_PLUGIN_OPTION_AGENT_CODE || 'claude';
+  const model = typeof input.model === 'string' ? input.model : (input.model?.id ?? '');
+  const runMode = process.env.PAN_RUN_MODE === 'autonomous' ? 'autonomous' : 'interactive';
+  if (process.env.CLAUDE_ENV_FILE) {
+    const quote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
+    const lines = [`export PAN_ACTOR_KIND=ai`, `export PAN_ACTOR=${quote(agent)}`, `export PAN_RUN_MODE=${runMode}`];
+    if (model) lines.push(`export PAN_MODEL=${quote(model)}`);
+    fs.appendFileSync(process.env.CLAUDE_ENV_FILE, `${lines.join('\n')}\n`);
+  }
+  const principal = principalOf(root);
+  const lines = [
+    principal
+      ? format(m.head, { ws: path.basename(root), principal, agent, mode: runMode === 'autonomous' ? m.autonomous : '' })
+      : m.noPrincipal,
+  ];
+  if (hasProgram(root)) background(['program', 'sync', '--auto'], root);
+  const stale = pan(['lineage', 'stale'], root) ?? [];
+  if (stale.length) {
+    lines.push(format(m.staleCount, { count: stale.length }));
+    for (const edge of stale.slice(0, 5)) lines.push(`  - ${edge.artifact} ← ${edge.source}`);
+  }
+  lines.push(m.skills, m.rules);
+  emit('SessionStart', { additionalContext: lines.join('\n') });
+}
+
+function afterRead(input) {
+  const file = input.tool_input?.file_path;
+  if (!file || !inLedger(file)) return;
+  const root = workspaceOf(path.dirname(file));
+  if (!root) return;
+  const m = messagesFor(root);
+  const edges = pan(['lineage', 'why', file], path.dirname(file)) ?? [];
+  if (!edges.length) return;
+  // địa chỉ `repo:đường dẫn` — ngắn, không lộ thư mục home, mọi lệnh `pan lineage` đều nhận
+  const address = edges[0].artifact || file;
+  const lines = [format(m.sources, { file: address })];
+  const changed = [];
+  for (const edge of edges) {
+    lines.push(`  - ${edge.source} [${m.state[edge.state] ?? edge.state}]${edge.note ? ` — ${edge.note}` : ''}`);
+    if (['stale', 'moved'].includes(edge.state)) changed.push(edge.source);
+  }
+  if (changed.length) {
+    const diffs = pan(['lineage', 'diff', file], path.dirname(file)) ?? [];
+    const text = diffs.map((item) => item.diff).join('\n').split('\n');
+    lines.push(...text.slice(0, MAX_DIFF_LINES), ...(text.length > MAX_DIFF_LINES ? ['…'] : []));
+    for (const source of changed) lines.push(format(m.stale, { file: address, source }));
+  }
+  emit('PostToolUse', { additionalContext: lines.join('\n') });
+}
+
+const MAX_LINT_LINES = 20;
+
+function afterEdit(input) {
+  const file = input.tool_input?.file_path;
+  if (!file) return;
+  const root = workspaceOf(path.dirname(file));
+  const repo = repoOf(path.dirname(file));
+  const declares = (dir) => dir && /^lint\s*:/m.test(workspaceConfig(dir));
+  if (!root || !(declares(root) || declares(repo))) return;
+  const violations = pan(['harness', 'lint', file], root) ?? [];
+  if (!violations.length) return;
+  const m = messagesFor(root);
+  const lines = [format(m.lint, { file: violations[0].file, count: violations.length })];
+  for (const item of violations) {
+    const where = `${item.file}${item.line ? `:${item.line}` : ''}`;
+    lines.push(`  - ${where} ${item.rule}${item.message ? ` — ${item.message}` : ''}`);
+    if (item.text) lines.push(...item.text.split('\n').map((text) => `      ${text}`));
+  }
+  emit('PostToolUse', { additionalContext: [...lines.slice(0, MAX_LINT_LINES), ...(lines.length > MAX_LINT_LINES ? ['…'] : [])].join('\n') });
+}
+
+function beforeEdit(input) {
+  const strict = ['true', '1'].includes(String(process.env.CLAUDE_PLUGIN_OPTION_STRICT_LINEAGE)) || process.env.PAN_LINEAGE_STRICT === '1';
+  const file = input.tool_input?.file_path;
+  if (!strict || !file || !inLedger(file)) return;
+  const root = workspaceOf(path.dirname(file));
+  if (!root) return;
+  const changed = (pan(['lineage', 'why', file], path.dirname(file)) ?? []).filter((edge) => ['stale', 'moved', 'missing'].includes(edge.state));
+  if (!changed.length) return;
+  const m = messagesFor(root);
+  emit('PreToolUse', {
+    permissionDecision: 'deny',
+    permissionDecisionReason: format(m.deny, { file: changed[0].artifact || file, sources: changed.map((edge) => edge.source).join(', ') }),
+  });
+}
+
+// ── Khối B: rào chắn ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Tệp secret (plugin §4.5 no-secret-read): theo tên tệp, mẫu .example/.sample được đọc. */
+function isSecretFile(file) {
+  const name = path.basename(String(file ?? ''));
+  if (/\.(example|sample|template)$/i.test(name)) return false;
+  return name === '.pan-env-build.yaml' || name === '.env' || name.startsWith('.env.') || name === 'credentials.json';
+}
+
+/** Tách lệnh shell thành các đoạn (`&&` `||` `;` `|`), mỗi đoạn là danh sách token — tôn trọng ngoặc đơn / kép. */
+function shellSegments(command) {
+  const segments = [[]];
+  let token = '';
+  let quote = '';
+  let hasToken = false;
+  const push = () => {
+    if (hasToken) segments.at(-1).push(token);
+    token = '';
+    hasToken = false;
+  };
+  const text = String(command ?? '');
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quote) {
+      if (char === quote) quote = '';
+      else token += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      hasToken = true;
+    } else if (/\s/.test(char)) push();
+    else if (char === ';' || char === '|' || char === '&') {
+      push();
+      if (segments.at(-1).length) segments.push([]);
+      if ((char === '|' || char === '&') && text[i + 1] === char) i++;
+    } else {
+      token += char;
+      hasToken = true;
+    }
+  }
+  push();
+  return segments.filter((segment) => segment.length);
+}
+
+const READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'grep', 'rg', 'sed', 'awk', 'strings', 'xxd', 'base64', 'cp', 'scp', 'open', 'code', 'vi', 'vim', 'nano']);
+const HTTP_CLIENTS = new Set(['curl', 'wget', 'http', 'https', 'xh']);
+
+/** Đoạn lệnh không hoàn tác được → mô tả ngắn để hỏi người dùng; không thì ''. */
+function irreversible(tokens) {
+  const words = tokens.filter((token) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token));
+  const [tool, sub] = words;
+  if (tool === 'pan' && (/^release-/.test(sub ?? '') || sub === 'publish-npm' || (sub === 'gh-artifacts' && words.includes('delete')))) return words.slice(0, 3).join(' ');
+  if (tool === 'git' && sub === 'push' && words.some((word) => word === '--force' || word === '-f' || word.startsWith('--force-with-lease') || /^\+/.test(word))) return 'git push --force';
+  if (tool === 'git' && sub === 'commit' && words.includes('--no-verify')) return 'git commit --no-verify';
+  if (tool === 'git' && sub === 'reset' && words.includes('--hard')) return 'git reset --hard';
+  return '';
+}
+
+function workspaceConfig(root) {
+  try {
+    return fs.readFileSync(path.join(root, '.pan-harness.yaml'), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function guard(input) {
+  const tool = input.tool_name ?? '';
+  const args = input.tool_input ?? {};
+  const root = workspaceOf(input.cwd || process.cwd());
+  const m = messagesFor(root);
+  const deny = (reason) => emit('PreToolUse', { permissionDecision: 'deny', permissionDecisionReason: reason });
+  const ask = (reason) => emit('PreToolUse', { permissionDecision: 'ask', permissionDecisionReason: reason });
+
+  if (['Read', 'Edit', 'Write', 'MultiEdit'].includes(tool) && isSecretFile(args.file_path)) {
+    deny(format(m.secret, { file: path.basename(args.file_path) }));
+    return true;
+  }
+  if (tool === 'Bash') {
+    // AI duyệt được, sổ ghi là AI (OD-51) — chỉ chặn giả làm người: đổi PAN_ACTOR_KIND/PAN_ACTOR trong lệnh duyệt, hoặc
+    // gọi thẳng API nút Duyệt bằng công cụ HTTP (dashboard ghi mọi lần bấm là người).
+    const command = String(args.command ?? '');
+    const touchesIdentity = /\bPAN_ACTOR(_KIND)?\b/.test(command);
+    for (const tokens of shellSegments(command)) {
+      const words = tokens.filter((token) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token));
+      const at = words.findIndex((word, index) => word === 'pan' && words[index + 1] === 'harness' && words[index + 2] === 'approve');
+      const viaEnv = at > 0 && words.slice(0, at).every((word) => /^(env|-u|-i|--unset(=.*)?|-|[A-Z_][A-Z0-9_]*)$/.test(word));
+      const approving = at === 0 || viaEnv;
+      if ((approving && touchesIdentity) || (HTTP_CLIENTS.has(path.basename(words[0] ?? '')) && tokens.some((token) => token.includes('/api/harness/approve')))) {
+        deny(m.approve);
+        return true;
+      }
+      const program = path.basename(tokens.find((token) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) ?? '');
+      const secret = tokens.find((token) => token !== tokens[0] && isSecretFile(token));
+      if ((READERS.has(program) || tokens.some((token) => token === '<')) && secret) {
+        deny(format(m.secret, { file: path.basename(secret) }));
+        return true;
+      }
+      const risky = irreversible(tokens);
+      if (risky) {
+        ask(format(m.irreversible, { command: risky }));
+        return true;
+      }
+    }
+  }
+  if ((tool === 'Agent' || tool === 'Task') && root && /^subagents\s*:\s*deny\b/m.test(workspaceConfig(root))) {
+    deny(m.subagents);
+    return true;
+  }
+  return false;
+}
+
+function preTool(input) {
+  if (guard(input)) return;
+  beat(input, 'working');
+  if (['Edit', 'Write', 'MultiEdit'].includes(input.tool_name)) beforeEdit(input);
+}
+
+// ── Nhịp tim Program (OD-52) ─────────────────────────────────────────────────────────────────────────────────────
+
+const BEAT_MS = 30_000;
+
+const hasProgram = (root) => /^studio\s*:/m.test(fs.readFileSync(path.join(root, '.project.yaml'), 'utf8'));
+const sessionOf = (input) => String(input.session_id ?? 'session').replace(/[^\w-]/g, '');
+
+/** `pan …` tách khỏi hook, không chờ — không làm chậm tool; lỗi (chưa đăng nhập, VIEWER…) `pan` tự ghi cho `pan program status`. */
+function background(args, root) {
+  const env = { ...process.env, PAN_ACTOR_KIND: 'ai', PAN_ACTOR: process.env.CLAUDE_PLUGIN_OPTION_AGENT_CODE || 'claude' };
+  spawn('pan', args, { cwd: root, env, detached: true, stdio: 'ignore' })
+    .on('error', () => {})
+    .unref();
+}
+
+/** Bảng công trường của Program biết agent nào đang làm, ở project con nào (suy từ tệp đang sửa). */
+function beat(input, presence) {
+  const root = workspaceOf(input.cwd || process.cwd());
+  if (!root || !hasProgram(root)) return;
+  const file = path.join(os.tmpdir(), `pan-harness-beat-${sessionOf(input)}.json`);
+  let last = {};
+  try {
+    last = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    last = {};
+  }
+  if (last.presence === presence && Date.now() - (last.at ?? 0) < BEAT_MS) return;
+  fs.writeFileSync(file, JSON.stringify({ presence, at: Date.now() }));
+  const where = input.tool_input?.file_path || input.cwd || root;
+  background(['program', 'presence', '--presence', presence, '--path', where, '--session', sessionOf(input).slice(0, 8)], root);
+}
+
+// ── Khối D: cổng xong ────────────────────────────────────────────────────────────────────────────────────────────
+
+const MAX_STOP_BLOCKS = 2;
+
+function stop(input) {
+  beat(input, 'idle');
+  const root = workspaceOf(input.cwd || process.cwd());
+  // Agent làm xong một lượt: đẩy mọi thay đổi Pan Plans lên Program, không trông vào việc agent nhớ gọi sync.
+  if (root && hasProgram(root)) background(['program', 'sync', '--auto'], root);
+  if (!root || !workspaceConfig(root)) return;
+  // Đếm số lần chặn liên tiếp của phiên — quá ngưỡng thì để agent dừng (người dùng thấy nhắc), không lặp vô hạn.
+  const counter = path.join(os.tmpdir(), `pan-harness-stop-${String(input.session_id ?? 'session').replace(/[^\w-]/g, '')}.json`);
+  let blocks = 0;
+  try {
+    blocks = input.stop_hook_active ? JSON.parse(fs.readFileSync(counter, 'utf8')).blocks ?? 0 : 0;
+  } catch {
+    blocks = 0;
+  }
+  const phases = pan(['harness', 'status'], root) ?? [];
+  const pending = new Map();
+  for (const phase of phases)
+    for (const gate of phase.gates ?? [])
+      if (gate.changed && gate.status !== 'pass') pending.set(`${gate.repo}:${gate.id}`, { ...gate, phase: phase.phase });
+  if (!pending.size) {
+    fs.rmSync(counter, { force: true });
+    return;
+  }
+  const m = messagesFor(root);
+  const gates = [...pending.values()].map((gate) => `${gate.id} @ ${gate.repo} (${m.gate[gate.status] ?? gate.status})`).join(', ');
+  const commands = [...new Set([...pending.values()].map((gate) => `\`pan harness check ${gate.phase}\``))].join(', ');
+  const enforce = /^mode\s*:\s*enforce\b/m.test(workspaceConfig(root));
+  if (!enforce || blocks >= MAX_STOP_BLOCKS) {
+    fs.rmSync(counter, { force: true });
+    process.stdout.write(JSON.stringify({ systemMessage: format(m.gatesWarn, { gates, commands }) }));
+    return;
+  }
+  fs.writeFileSync(counter, JSON.stringify({ blocks: blocks + 1 }));
+  process.stdout.write(JSON.stringify({ decision: 'block', reason: format(m.gatesBlock, { gates, commands }) }));
+}
+
+try {
+  const input = readInput();
+  const handlers = { 'session-start': sessionStart, 'after-read': afterRead, 'after-edit': afterEdit, 'before-edit': beforeEdit, 'pre-tool': preTool, stop };
+  handlers[process.argv[2]]?.(input);
+} catch {
+  // hook không được làm hỏng phiên
+}
+process.exit(0);