driftseal 0.5.0 → 0.6.0

package/README.md

@@ -42,11 +42,36 @@ For local development from this checkout:
 npm link
 ```
 
-## Give your coding agent the complete workflow
+## Recommended agent setup
 
-The package includes `skills/use-driftseal`, an agent-agnostic companion skill that drives repository work through the complete DriftSeal loop while keeping decision records selective. Install or link it using your agent runtime’s skill discovery convention, then invoke `use-driftseal` by name.
+Use `AGENTS.md` + the companion skill + the CLI as the default integration:
 
-## Use DriftSeal through MCP
+- `AGENTS.md`, installed by `driftseal init`, is the authoritative policy.
+- `skills/use-driftseal` is a small, agent-agnostic discovery and recovery guide.
+- `driftseal` is the default execution surface.
+
+Install the bundled skill for one platform. Project scope is the default:
+
+```sh
+driftseal skill install --target codex
+driftseal skill install --target kimi-code --scope global
+```
+
+| Target | Project scope | Global scope |
+| --- | --- | --- |
+| `codex` | `.agents/skills/use-driftseal` | `~/.agents/skills/use-driftseal` |
+| `kimi-code` | `.kimi/skills/use-driftseal` | `~/.kimi/skills/use-driftseal` |
+| `opencode` | `.opencode/skills/use-driftseal` | `~/.config/opencode/skills/use-driftseal` |
+| `claude-code` | `.claude/skills/use-driftseal` | `~/.claude/skills/use-driftseal` |
+| `cursor` | `.cursor/skills/use-driftseal` | `~/.cursor/skills/use-driftseal` |
+
+Use `--root <repository>` to select a project when running the installer
+elsewhere. Repeated installs of identical content are no-ops; a different
+existing skill requires `--force`. MCP and lifecycle hooks are optional
+adapters; enable them only for a concrete host constraint or reminder need, not
+as additional policy layers.
+
+## Optional: use DriftSeal through MCP
 
 The same package includes `driftseal-mcp`, a local stdio MCP server. It exposes
 structured tools for the complete intent and decision workflow while reusing the
@@ -112,8 +137,43 @@ The v1 server provides:
 | `driftseal://intents/recent` | Read the ten most recent intents as a JSON resource. |
 | `driftseal://decisions` | Read the decision catalog as a JSON resource. |
 
-The companion skill remains important: MCP supplies controlled, structured
-operations; the skill teaches the agent when to use them and how to avoid drift.
+MCP changes only the execution surface. It does not add policy beyond the
+repository's `AGENTS.md`, and the companion skill remains limited to discovery
+and recovery guidance.
+
+## Optional: keep the agent reminded through hooks
+
+Agents that support lifecycle hooks can inject a short DriftSeal reminder before
+the agent starts answering (`UserPromptSubmit`) and surface a warning when it
+finishes (`Stop`). The reminders are advisory — they ask whether the round needs
+an intent and whether an open intent still needs verification and
+`driftseal end`; they never force another model turn, and they stay silent in
+repositories without an intent log.
+
+Install them with:
+
+```sh
+cd /path/to/repository
+driftseal hook install --target kimi-code --scope global
+driftseal hook install --target claude-code
+driftseal hook install --target codex
+```
+
+| Target | Project config | Global config |
+| --- | --- | --- |
+| `kimi-code` | Not supported | `~/.kimi-code/config.toml` or `$KIMI_CODE_HOME/config.toml` |
+| `claude-code` | `.claude/settings.json` | `~/.claude/settings.json` |
+| `codex` | `.codex/hooks.json` | `~/.codex/hooks.json` |
+
+Like `mcp install`, the hook installer accepts `--scope global`,
+`--root <repository>`, and `--force`, is idempotent, and preserves unrelated
+config entries. Kimi Code documents hooks only in its global `config.toml`, so
+its target requires `--scope global`. Claude Code receives prompt context through
+`hookSpecificOutput.additionalContext`; its `Stop` reminder uses a UI-only
+`systemMessage`, avoiding a continuation loop. Codex installs only the prompt
+hook because its `Stop` event has no advisory context channel. Hook commands
+search the current directory and its ancestors for an intent log. OpenCode and
+Cursor have no supported hook surface for this yet.
 
 ## A work round
 
@@ -151,7 +211,10 @@ Single-step commands that only build, check, or record work already done — com
 | `driftseal decision update <id> [-s status] -n "..."` | Reconcile a linked decision in the open intent. |
 | `driftseal decision list [-s status] [--last N \| --count]` | List or count decision records, optionally filtered by status. |
 | `driftseal decision show <id>` | Read one decision record. |
+| `driftseal skill install --target TARGET [--scope project\|global] [--root path] [--force]` | Install the bundled skill for Codex, Kimi Code, OpenCode, Claude Code, or Cursor. |
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | Install the repository-pinned MCP server into Codex, Kimi Code, OpenCode, Claude Code, or Cursor. |
+| `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | Install advisory lifecycle reminders into Kimi Code, Claude Code, or Codex. |
+| `driftseal hook prompt\|stop [--format plain\|claude-code]` | Emit the reminder a lifecycle hook injects; never blocks. |
 | `driftseal init` | Add the adoption protocol to `AGENTS.md`. |
 | `driftseal help` | Print CLI usage. |
 

package/README.zh-CN.md

@@ -42,11 +42,35 @@ driftseal init
 npm link
 ```
 
-## 让 coding agent 掌握完整工作流
+## 推荐的 agent 配置
 
-npm package 内含 `skills/use-driftseal`。这是一个不绑定特定 agent runtime 的配套 skill，会按完整 DriftSeal 闭环执行仓库任务，同时克制地使用 decision record。按照所用 agent runtime 的 skill discovery 约定安装或 link，之后通过名称 `use-driftseal` 调用即可。
+默认组合是 `AGENTS.md` + 配套 skill + CLI：
 
-## 通过 MCP 使用 DriftSeal
+- `driftseal init` 写入的 `AGENTS.md` 是唯一的 policy 来源。
+- `skills/use-driftseal` 是不绑定特定 agent runtime 的轻量发现与恢复指南。
+- `driftseal` CLI 是默认执行入口。
+
+为指定平台安装 package 内置的 skill。默认使用项目级 scope：
+
+```sh
+driftseal skill install --target codex
+driftseal skill install --target kimi-code --scope global
+```
+
+| Target | 项目级 scope | 全局 scope |
+| --- | --- | --- |
+| `codex` | `.agents/skills/use-driftseal` | `~/.agents/skills/use-driftseal` |
+| `kimi-code` | `.kimi/skills/use-driftseal` | `~/.kimi/skills/use-driftseal` |
+| `opencode` | `.opencode/skills/use-driftseal` | `~/.config/opencode/skills/use-driftseal` |
+| `claude-code` | `.claude/skills/use-driftseal` | `~/.claude/skills/use-driftseal` |
+| `cursor` | `.cursor/skills/use-driftseal` | `~/.cursor/skills/use-driftseal` |
+
+如果不在目标 repository 中执行，用 `--root <repository>` 明确指定项目。
+重复安装相同内容不会产生改动；目标位置已有不同版本时必须显式传入 `--force`。
+MCP 与 lifecycle hook 都是可选适配层；只有确实存在 host 限制或提醒需求时
+才启用，不要把它们叠成额外的 policy 层。
+
+## 可选：通过 MCP 使用 DriftSeal
 
 同一个 package 还提供本地 stdio MCP server：`driftseal-mcp`。它为完整的
 intent 与 decision 工作流提供结构化 tools，并与 CLI 复用同一套锁、WAL、
@@ -110,8 +134,40 @@ v1 server 提供：
 | `driftseal://intents/recent` | 以 JSON resource 读取最近十条 intent。 |
 | `driftseal://decisions` | 以 JSON resource 读取 decision catalog。 |
 
-配套 skill 仍然不可替代：MCP 提供受控、结构化的操作，skill 则告诉 agent
-何时使用这些操作，以及怎样避免 drift。
+MCP 只替换执行入口，不会在 repository 的 `AGENTS.md` 之外增加 policy；
+配套 skill 也仍只负责发现与恢复工作流。
+
+## 可选：用 hook 持续提醒 agent
+
+对于支持 lifecycle hook 的 agent，可以在每轮回答前（`UserPromptSubmit`）
+注入一条简短的 DriftSeal 提醒，并在回答完毕时（`Stop`）显示警告。提醒是
+建议性的——它提示是否需要开启 intent、是否还有未关闭的 intent 需要验证并
+`driftseal end`；它不会强制模型再跑一轮，并且在还没有 intent log 的
+repository 中保持沉默。
+
+安装方式：
+
+```sh
+cd /path/to/repository
+driftseal hook install --target kimi-code --scope global
+driftseal hook install --target claude-code
+driftseal hook install --target codex
+```
+
+| Target | 项目级配置 | 全局配置 |
+| --- | --- | --- |
+| `kimi-code` | 不支持 | `~/.kimi-code/config.toml` 或 `$KIMI_CODE_HOME/config.toml` |
+| `claude-code` | `.claude/settings.json` | `~/.claude/settings.json` |
+| `codex` | `.codex/hooks.json` | `~/.codex/hooks.json` |
+
+与 `mcp install` 一样，hook 安装器支持 `--scope global`、
+`--root <repository>` 和 `--force`，重复安装是幂等的，并保留无关的配置项。
+Kimi Code 只在全局 `config.toml` 中记录 hook，因此该 target 必须指定
+`--scope global`。Claude Code 的 prompt 提醒使用
+`hookSpecificOutput.additionalContext`，`Stop` 提醒则使用只显示在 UI 中的
+`systemMessage`，不会造成 continuation loop。Codex 只安装 prompt hook，
+因为它的 `Stop` 事件没有建议性上下文通道。Hook 命令会从当前目录开始向上
+查找 intent log。OpenCode 和 Cursor 目前还没有可用的 hook 入口。
 
 ## 一轮标准工作流
 
@@ -149,7 +205,10 @@ driftseal end \
 | `driftseal decision update <id> [-s status] -n "..."` | 在当前 intent 中 reconcile 已关联的 decision。 |
 | `driftseal decision list [-s status] [--last N \| --count]` | 列出或统计 decision records，也可按 status 筛选。 |
 | `driftseal decision show <id>` | 查看单条 decision record。 |
+| `driftseal skill install --target TARGET [--scope project\|global] [--root path] [--force]` | 为 Codex、Kimi Code、OpenCode、Claude Code 或 Cursor 安装内置 skill。 |
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | 把固定到 repository 的 MCP server 安装到 Codex、Kimi Code、OpenCode、Claude Code 或 Cursor。 |
+| `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | 把建议性的 lifecycle 提醒安装到 Kimi Code、Claude Code 或 Codex。 |
+| `driftseal hook prompt\|stop [--format plain\|claude-code]` | 输出 lifecycle hook 注入的提醒；绝不阻断。 |
 | `driftseal init` | 把接入协议写入 `AGENTS.md`。 |
 | `driftseal help` | 查看 CLI 用法。 |
 

package/bin/driftseal.js

@@ -35,7 +35,7 @@ const DECISION_STATUSES = [
   'superseded',
 ];
 const EVENT_SCHEMA_VERSION = 3;
-const PROTOCOL_VERSION = 7;
+const PROTOCOL_VERSION = 8;
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const MAX_DECISION_SLUG_LENGTH = 180;
@@ -191,8 +191,7 @@ function normalizeEvent(event, line) {
   fail(`unknown event type "${event.type}" on log line ${line}`);
 }
 
-function readEvents({ repairTail = false } = {}) {
-  const file = logFile();
+function readEvents({ repairTail = false, file = logFile() } = {}) {
   if (!fs.existsSync(file)) return [];
   let content = fs.readFileSync(file, 'utf8');
   const rawLines = content.split('\n');
@@ -1111,6 +1110,10 @@ function intentProtocolBlock(version = PROTOCOL_VERSION) {
 
 This repo uses DriftSeal (\`driftseal\`) to prevent agent drift. Every work round:
 
+This \`AGENTS.md\` protocol is the source of truth. Use the \`driftseal\` CLI by
+default; the companion skill only helps discover and resume the workflow, while
+MCP and lifecycle hooks are optional adapters.
+
 1. **Write intent first**, before modifying, creating, or deleting files, or
    making any other change that may need a rollback:
    \`driftseal begin "<what this round will accomplish>" --verify "<command or check that proves it>"\`.
@@ -1148,7 +1151,14 @@ ${INTENT_PROTOCOL_END}`;
 }
 
 function previousIntentProtocolBlock(version) {
-  const v6 = intentProtocolBlock(version).replace(
+  const v7 = intentProtocolBlock(version).replace(
+    '\nThis `AGENTS.md` protocol is the source of truth. Use the `driftseal` CLI by\n' +
+      'default; the companion skill only helps discover and resume the workflow, while\n' +
+      'MCP and lifecycle hooks are optional adapters.\n',
+    ''
+  );
+  if (version >= 7) return v7;
+  const v6 = v7.replace(
     'doing anything else. The open intent is the source of truth: resume it when its\n' +
       '   objective still matches the current task; otherwise close it (`partial` or\n' +
       '   `abandoned`, with a note) and `begin` a new one.',
@@ -1265,6 +1275,7 @@ Commit \`.decision-log/\` with the code.`;
 }
 
 function previousDecisionProtocolBlock(version) {
+  if (version >= 7) return decisionProtocolBlock(version);
   return decisionProtocolBlock(version).replace(' --driver "<decision driver>"', '');
 }
 
@@ -1534,6 +1545,465 @@ function installMcp(request) {
   return request.target === 'codex' ? installCodexMcp(request) : installJsonMcp(request);
 }
 
+const SKILL_NAME = 'use-driftseal';
+
+function skillInstallUsage() {
+  return 'usage: driftseal skill install --target <codex|kimi-code|opencode|claude-code|cursor> [--scope project|global] [--root <repository>] [--force]';
+}
+
+function skillInstallLocation(target, scope, root) {
+  const home = os.homedir();
+  const roots = {
+    codex: {
+      project: path.join(root, '.agents', 'skills'),
+      global: path.join(home, '.agents', 'skills'),
+    },
+    'kimi-code': {
+      project: path.join(root, '.kimi', 'skills'),
+      global: path.join(home, '.kimi', 'skills'),
+    },
+    opencode: {
+      project: path.join(root, '.opencode', 'skills'),
+      global: path.join(home, '.config', 'opencode', 'skills'),
+    },
+    'claude-code': {
+      project: path.join(root, '.claude', 'skills'),
+      global: path.join(home, '.claude', 'skills'),
+    },
+    cursor: {
+      project: path.join(root, '.cursor', 'skills'),
+      global: path.join(home, '.cursor', 'skills'),
+    },
+  };
+  const skillsDir = roots[target][scope];
+  return { skillsDir, skillDir: path.join(skillsDir, SKILL_NAME) };
+}
+
+function parseSkillInstallRequest(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== 'install') fail(skillInstallUsage());
+  const { positionals, flags } = parseArgs(rest, {
+    target: 'single',
+    scope: 'single',
+    root: 'single',
+    force: 'boolean',
+  });
+  if (positionals.length > 0 || !flags.target) fail(skillInstallUsage());
+
+  const target = flags.target.toLowerCase();
+  if (!MCP_TARGETS.includes(target)) {
+    fail(`unsupported skill target "${flags.target}" (expected: ${MCP_TARGETS.join(', ')})`);
+  }
+  const scope = (flags.scope || 'project').toLowerCase();
+  if (!MCP_SCOPES.includes(scope)) {
+    fail(`invalid skill install scope "${scope}" (expected: ${MCP_SCOPES.join(', ')})`);
+  }
+  const root = repositoryRoot(flags.root || process.cwd());
+  return {
+    target,
+    targetLabel: MCP_TARGET_LABELS[target],
+    scope,
+    root,
+    force: Boolean(flags.force),
+    ...skillInstallLocation(target, scope, root),
+  };
+}
+
+function directoryDigest(directory) {
+  if (!fs.existsSync(directory)) return null;
+  const digest = crypto.createHash('sha256');
+
+  function visit(current, relative) {
+    const stat = fs.lstatSync(current);
+    if (stat.isDirectory()) {
+      digest.update(`directory\0${relative}\0${stat.mode & 0o777}\0`);
+      for (const name of fs.readdirSync(current).sort()) {
+        visit(path.join(current, name), relative ? path.join(relative, name) : name);
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      digest.update(`file\0${relative}\0${stat.mode & 0o777}\0`);
+      digest.update(fs.readFileSync(current));
+      digest.update('\0');
+      return;
+    }
+    if (stat.isSymbolicLink()) {
+      digest.update(`symlink\0${relative}\0${fs.readlinkSync(current)}\0`);
+      return;
+    }
+    digest.update(`other\0${relative}\0${stat.mode}\0`);
+  }
+
+  visit(directory, '');
+  return digest.digest('hex');
+}
+
+function installSkill(request) {
+  const { force, root, scope, skillDir, skillsDir, target, targetLabel } = request;
+  const sourceDir = path.join(__dirname, '..', 'skills', SKILL_NAME);
+  if (!fs.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+    fail(`bundled ${SKILL_NAME} skill is missing from this DriftSeal installation: ${sourceDir}`);
+  }
+
+  const sourceDigest = directoryDigest(sourceDir);
+  const existingDigest = directoryDigest(skillDir);
+  if (existingDigest === sourceDigest) {
+    printLine(`${SKILL_NAME} skill is already installed for ${targetLabel} (${scope}): ${skillDir}`);
+    return { changed: false, target, scope, root, skillDir };
+  }
+  if (existingDigest !== null && !force) {
+    fail(
+      `${targetLabel} already has a different ${SKILL_NAME} skill at ${skillDir}; ` +
+        're-run with --force to replace it'
+    );
+  }
+
+  ensureDirectoryDurable(skillsDir);
+  const suffix = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  const temporary = path.join(skillsDir, `.${SKILL_NAME}.tmp-${suffix}`);
+  const backup = path.join(skillsDir, `.${SKILL_NAME}.backup-${suffix}`);
+  let movedExisting = false;
+  try {
+    fs.cpSync(sourceDir, temporary, { recursive: true, errorOnExist: true });
+    if (existingDigest !== null) {
+      fs.renameSync(skillDir, backup);
+      movedExisting = true;
+    }
+    fs.renameSync(temporary, skillDir);
+    if (movedExisting) fs.rmSync(backup, { recursive: true, force: true });
+    fsyncDirectory(skillsDir);
+  } catch (err) {
+    try {
+      fs.rmSync(temporary, { recursive: true, force: true });
+      if (movedExisting && !fs.existsSync(skillDir) && fs.existsSync(backup)) {
+        fs.renameSync(backup, skillDir);
+      }
+    } catch {}
+    throw err;
+  }
+
+  printLine(`Installed ${SKILL_NAME} skill for ${targetLabel} (${scope}): ${skillDir}`);
+  if (scope === 'project') printLine(`Repository root: ${root}`);
+  return { changed: true, target, scope, root, skillDir };
+}
+
+const HOOK_TARGETS = ['kimi-code', 'claude-code', 'codex'];
+const HOOK_EVENTS = ['prompt', 'stop'];
+const HOOK_EVENT_NAMES = { prompt: 'UserPromptSubmit', stop: 'Stop' };
+
+function hookUsage() {
+  return (
+    'usage: driftseal hook install --target <kimi-code|claude-code|codex> [--scope project|global] [--root <repository>] [--force]\n' +
+    '       driftseal hook prompt|stop [--format plain|claude-code]'
+  );
+}
+
+function hookConfigLocation(target, scope, root) {
+  const home = os.homedir();
+  if (target === 'kimi-code') {
+    const userDir = process.env.KIMI_CODE_HOME
+      ? path.resolve(process.env.KIMI_CODE_HOME)
+      : path.join(home, '.kimi-code');
+    if (scope === 'project') {
+      fail('Kimi Code hooks support only global scope; re-run with --scope global');
+    }
+    const configDir = userDir;
+    return { configDir, configFile: path.join(configDir, 'config.toml') };
+  }
+  if (target === 'claude-code') {
+    const configDir = scope === 'project' ? path.join(root, '.claude') : path.join(home, '.claude');
+    return { configDir, configFile: path.join(configDir, 'settings.json') };
+  }
+  if (target === 'codex') {
+    const configDir = scope === 'project' ? path.join(root, '.codex') : path.join(home, '.codex');
+    return { configDir, configFile: path.join(configDir, 'hooks.json') };
+  }
+  fail(`unsupported hook target "${target}"`);
+}
+
+function parseHookInstallRequest(argv) {
+  const { positionals, flags } = parseArgs(argv, {
+    target: 'single',
+    scope: 'single',
+    root: 'single',
+    force: 'boolean',
+  });
+  if (positionals.length > 0 || !flags.target) {
+    fail(hookUsage());
+  }
+
+  const target = flags.target.toLowerCase();
+  if (!HOOK_TARGETS.includes(target)) {
+    fail(`unsupported hook target "${flags.target}" (expected: ${HOOK_TARGETS.join(', ')})`);
+  }
+  const scope = (flags.scope || 'project').toLowerCase();
+  if (!MCP_SCOPES.includes(scope)) {
+    fail(`invalid hook install scope "${scope}" (expected: ${MCP_SCOPES.join(', ')})`);
+  }
+  const root = repositoryRoot(flags.root || process.cwd());
+  const { configDir, configFile } = hookConfigLocation(target, scope, root);
+  return {
+    target,
+    targetLabel: MCP_TARGET_LABELS[target],
+    scope,
+    root,
+    force: Boolean(flags.force),
+    configDir,
+    configFile,
+  };
+}
+
+function hookCommand(event, format) {
+  return format === 'plain' ? `driftseal hook ${event}` : `driftseal hook ${event} --format ${format}`;
+}
+
+function kimiHookSection(eol = '\n') {
+  const blocks = HOOK_EVENTS.map((event) =>
+    [
+      '[[hooks]]',
+      `event = "${HOOK_EVENT_NAMES[event]}"`,
+      `command = ${tomlString(hookCommand(event, 'plain'))}`,
+      'timeout = 5',
+    ].join(eol)
+  );
+  return blocks.join(eol + eol);
+}
+
+/** Ranges of [[hooks]] tables whose command invokes driftseal hook. */
+function driftsealHookBlockRanges(content) {
+  const tables = [
+    ...content.matchAll(/^[ \t]*\[(?:\[[^\]\r\n]+\]|[^\]\r\n]+)\][ \t]*(?:#.*)?\r?$/gm),
+  ];
+  const ranges = [];
+  for (let index = 0; index < tables.length; index++) {
+    const start = tables[index].index;
+    const end = index + 1 < tables.length ? tables[index + 1].index : content.length;
+    const body = content.slice(start, end);
+    if (
+      /^[ \t]*\[\[hooks\]\]/.test(tables[index][0]) &&
+      /^[ \t]*command[ \t]*=[ \t]*["']driftseal\s+hook\s/m.test(body)
+    ) {
+      ranges.push({ start, end, body });
+    }
+  }
+  return ranges;
+}
+
+function installKimiHook(request) {
+  const { configDir, configFile, force, scope, target, targetLabel } = request;
+  const existed = fs.existsSync(configFile);
+  const current = existed ? fs.readFileSync(configFile, 'utf8') : '';
+  const eol = current.includes('\r\n') ? '\r\n' : '\n';
+  const section = kimiHookSection(eol);
+  const ranges = driftsealHookBlockRanges(current);
+  let updated;
+
+  if (ranges.length === 0) {
+    const separator =
+      current.length === 0
+        ? ''
+        : current.endsWith(eol + eol)
+          ? ''
+          : current.endsWith(eol)
+            ? eol
+            : eol + eol;
+    updated = current + separator + section + eol;
+  } else {
+    const existing = ranges
+      .map((range) => range.body.trim().replace(/\r\n/g, '\n'))
+      .join('\n\n');
+    if (ranges.length === HOOK_EVENTS.length && existing === section.replace(/\r\n/g, '\n')) {
+      printLine(`DriftSeal hooks are already installed for ${targetLabel} (${scope}): ${configFile}`);
+      return { changed: false, target, scope, configFile };
+    }
+    if (!force) {
+      fail(
+        `${targetLabel} config already defines driftseal hooks in ${configFile}; ` +
+          're-run with --force to replace those entries'
+      );
+    }
+    let stripped = current;
+    for (const range of [...ranges].reverse()) {
+      stripped = stripped.slice(0, range.start) + stripped.slice(range.end);
+    }
+    stripped = stripped.replace(new RegExp(`(?:\\r?\\n){3,}$`), eol + eol);
+    const separator =
+      stripped.length === 0 || stripped.endsWith(eol + eol)
+        ? ''
+        : stripped.endsWith(eol)
+          ? eol
+          : eol + eol;
+    updated = stripped + separator + section + eol;
+  }
+
+  ensureDirectoryDurable(configDir);
+  atomicWriteFile(configFile, updated);
+  printLine(`Installed DriftSeal hooks for ${targetLabel} (${scope}): ${configFile}`);
+  return { changed: true, target, scope, configFile };
+}
+
+/**
+ * Hook groups per JSON-config target. Codex gets only the prompt hook. Claude
+ * Code also gets Stop, but its output is a UI-only systemMessage so the hook
+ * does not force another model turn.
+ */
+function jsonHookGroups(target) {
+  if (target === 'codex') {
+    return {
+      [HOOK_EVENT_NAMES.prompt]: [
+        { hooks: [{ type: 'command', command: hookCommand('prompt', 'plain') }] },
+      ],
+    };
+  }
+  const groups = {};
+  for (const event of HOOK_EVENTS) {
+    groups[HOOK_EVENT_NAMES[event]] = [
+      { hooks: [{ type: 'command', command: hookCommand(event, 'claude-code') }] },
+    ];
+  }
+  return groups;
+}
+
+/** True when every hook group in the list is one of ours. */
+function isDriftsealHookGroup(group) {
+  return (
+    jsonObject(group) &&
+    Array.isArray(group.hooks) &&
+    group.hooks.some(
+      (hook) => jsonObject(hook) && typeof hook.command === 'string' && /\bdriftseal hook\s/.test(hook.command)
+    )
+  );
+}
+
+function installJsonHook(request) {
+  const { configDir, configFile, force, scope, target, targetLabel } = request;
+  const config = readJsonConfig(configFile, targetLabel, target);
+  if (config.hooks === undefined) config.hooks = {};
+  if (!jsonObject(config.hooks)) {
+    fail(`${targetLabel} config field hooks must be a JSON object: ${configFile}`);
+  }
+
+  const groups = jsonHookGroups(target);
+  let changed = false;
+  let conflict = false;
+  for (const eventName of Object.keys(groups)) {
+    const existing = config.hooks[eventName];
+    if (existing === undefined) {
+      changed = true;
+      continue;
+    }
+    if (!Array.isArray(existing)) {
+      fail(`${targetLabel} config field hooks.${eventName} must be an array: ${configFile}`);
+    }
+    const ours = existing.filter(isDriftsealHookGroup);
+    if (ours.length === 0) {
+      changed = true;
+    } else if (ours.some((group) => JSON.stringify(group) !== JSON.stringify(groups[eventName][0]))) {
+      changed = true;
+      conflict = true;
+    }
+  }
+
+  if (!changed) {
+    printLine(`DriftSeal hooks are already installed for ${targetLabel} (${scope}): ${configFile}`);
+    return { changed: false, target, scope, configFile };
+  }
+  if (conflict && !force) {
+    fail(
+      `${targetLabel} config already defines driftseal hooks in ${configFile}; ` +
+        're-run with --force to replace those entries'
+    );
+  }
+
+  for (const [eventName, group] of Object.entries(groups)) {
+    const existing = config.hooks[eventName] || [];
+    config.hooks[eventName] = [...existing.filter((entry) => !isDriftsealHookGroup(entry)), ...group];
+  }
+  ensureDirectoryDurable(configDir);
+  atomicWriteFile(configFile, JSON.stringify(config, null, 2) + '\n');
+  printLine(`Installed DriftSeal hooks for ${targetLabel} (${scope}): ${configFile}`);
+  return { changed: true, target, scope, configFile };
+}
+
+function installHook(request) {
+  return request.target === 'kimi-code' ? installKimiHook(request) : installJsonHook(request);
+}
+
+function hookLogFile() {
+  if (process.env.DRIFTSEAL_HOME) {
+    const configured = logFile();
+    return fs.existsSync(configured) ? configured : null;
+  }
+  let current = path.resolve(process.cwd());
+  while (true) {
+    const candidate = path.join(current, '.intent-log', 'events.jsonl');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** Advisory reminder text; null when no ancestor has an intent log yet. */
+function hookReminder(event) {
+  const file = hookLogFile();
+  if (!file) return null;
+  if (event === 'prompt') {
+    return (
+      'DriftSeal reminder: if this round will modify files or anything else that may need a ' +
+      'rollback, begin an intent first: driftseal begin "<intent>" --verify "<check>". ' +
+      'Questions, read-only exploration, and single-step checks need no intent — skip this ' +
+      'reminder when it does not apply.'
+    );
+  }
+  const open = openIntent(fold(readEvents({ file })));
+  if (open) {
+    return (
+      `DriftSeal reminder: intent ${open.id} is still in_progress: "${open.intent}". ` +
+      'If its work is done, run the declared verification and close it with driftseal end; ' +
+      'if this turn was unrelated, ignore this reminder.'
+    );
+  }
+  return (
+    'DriftSeal reminder: no intent is open. If this round changed files without one, consider ' +
+    'whether the work should have been logged; ignore this reminder when nothing changed.'
+  );
+}
+
+function runHookReminder(event, argv) {
+  const { positionals, flags } = parseArgs(argv, { format: 'single' });
+  if (positionals.length > 0) fail(hookUsage());
+  const format = (flags.format || 'plain').toLowerCase();
+  if (!['plain', 'claude-code'].includes(format)) {
+    fail(`unsupported hook output format "${flags.format}" (expected: plain, claude-code)`);
+  }
+
+  // Hooks must never block the agent: any failure exits quietly with no output.
+  let reminder = null;
+  try {
+    reminder = hookReminder(event);
+  } catch {
+    reminder = null;
+  }
+  if (reminder === null) return { changed: false, event, format };
+  if (format === 'claude-code') {
+    const output =
+      event === 'stop'
+        ? { systemMessage: reminder }
+        : {
+            hookSpecificOutput: {
+              hookEventName: HOOK_EVENT_NAMES[event],
+              additionalContext: reminder,
+            },
+          };
+    printLine(JSON.stringify(output));
+  } else {
+    printLine(reminder);
+  }
+  return { changed: true, event, format };
+}
+
 const commands = {
   begin(argv) {
     const { positionals, flags } = parseArgs(argv, {
@@ -1939,6 +2409,21 @@ const commands = {
     return installMcp(request);
   },
 
+  skill(argv) {
+    return installSkill(parseSkillInstallRequest(argv));
+  },
+
+  hook(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand === 'install') {
+      return installHook(parseHookInstallRequest(rest));
+    }
+    if (HOOK_EVENTS.includes(subcommand)) {
+      return runHookReminder(subcommand, rest);
+    }
+    fail(hookUsage());
+  },
+
   init(argv) {
     const { positionals } = parseArgs(argv, {});
     if (positionals.length > 0) fail('usage: driftseal init');
@@ -1961,6 +2446,7 @@ const commands = {
         protocolEol(previousIntentProtocolBlock(4), eol),
         protocolEol(previousIntentProtocolBlock(5), eol),
         protocolEol(previousIntentProtocolBlock(6), eol),
+        protocolEol(previousIntentProtocolBlock(7), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyIntentProtocolBlock(), eol)],
     });
@@ -1977,6 +2463,7 @@ const commands = {
         protocolEol(previousDecisionProtocolBlock(4), eol),
         protocolEol(previousDecisionProtocolBlock(5), eol),
         protocolEol(previousDecisionProtocolBlock(6), eol),
+        protocolEol(previousDecisionProtocolBlock(7), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyDecisionProtocolBlock(), eol)],
     });
@@ -2025,9 +2512,17 @@ usage:
   driftseal decision list [--status STATUS] [--last N | --count]
                                  list or count filtered MADR decision records
   driftseal decision show <id>         print one MADR decision record
+  driftseal skill install --target TARGET [--scope project|global] [--root <repository>] [--force]
+                                 install the bundled use-driftseal skill (default: project)
+                                 targets: codex, kimi-code, opencode, claude-code, cursor
   driftseal mcp install --target TARGET [--scope project|global] [--root <repository>] [--force]
                                  install the repository-pinned MCP server (default: project)
                                  targets: codex, kimi-code, opencode, claude-code, cursor
+  driftseal hook install --target TARGET [--scope project|global] [--root <repository>] [--force]
+                                 install advisory lifecycle hooks (default: project)
+                                 targets: kimi-code (global only), claude-code, codex (prompt only)
+  driftseal hook prompt|stop [--format plain|claude-code]
+                                 emit the reminder a lifecycle hook injects; never blocks
   driftseal init                       inject intent and decision protocols into ./AGENTS.md
   driftseal help
 
@@ -2052,7 +2547,9 @@ function requestedEndStatus(argv) {
 }
 
 function mutationResources(cmd, argv) {
+  if (cmd === 'skill') return [parseSkillInstallRequest(argv).skillsDir];
   if (cmd === 'mcp') return [parseMcpInstallRequest(argv).configDir];
+  if (cmd === 'hook') return [parseHookInstallRequest(argv.slice(1)).configDir];
   if (cmd === 'init') return [process.cwd()];
   if (cmd === 'reclaim' || cmd === 'unreclaim') return [logDir()];
   if (cmd === 'begin' && !argv.some((arg) => arg === '--decision' || arg.startsWith('--decision='))) {
@@ -2072,7 +2569,8 @@ function dispatch(argv) {
   const fn = commands[cmd];
   if (!fn) fail(`unknown command: ${cmd} (run: driftseal help)`);
   const mutates =
-    ['begin', 'end', 'init', 'mcp', 'reclaim', 'unreclaim'].includes(cmd) ||
+    ['begin', 'end', 'init', 'skill', 'mcp', 'reclaim', 'unreclaim'].includes(cmd) ||
+    (cmd === 'hook' && rest[0] === 'install') ||
     (cmd === 'decision' && ['add', 'update'].includes(rest[0]));
   const readsIntentLog = ['status', 'log'].includes(cmd);
   if (mutates || readsIntentLog) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",
@@ -21,7 +21,7 @@
     "url": "git+https://github.com/rowan-hiro/DriftSeal.git"
   },
   "license": "MIT",
-  "author": "Ruan Boyu <boyuruan@gmail.com>",
+  "author": "Hiro <rowan_hiro@proton.me>",
   "type": "commonjs",
   "main": "index.js",
   "bin": {

package/skills/use-driftseal/SKILL.md

@@ -1,66 +1,41 @@
 ---
 name: use-driftseal
-description: Run repository work through the DriftSeal (`driftseal`) intent, verification, and selective decision workflow. Use when the user asks to use DriftSeal, invokes the skill by name, or works in a repository whose instructions require `driftseal`; also use to resume a DriftSeal-managed task after context loss, reconcile scope changes, close work honestly, or preserve decision context that Git and the intent log cannot recover.
+description: Follow DriftSeal-managed repository work when AGENTS.md requires `driftseal`, the user invokes DriftSeal, or an interrupted intent must be resumed. Use this skill to locate the authoritative repository policy, re-anchor state after context loss, and choose the execution surface; prefer the `driftseal` CLI, using MCP only when the repository or user explicitly selects it.
 ---
 
 # Use DriftSeal
 
-This skill is the usage guide for DriftSeal: how to find it and which command
-or tool to reach for. The binding protocol — when an intent is required, how
-to close one honestly, when a decision record is warranted, how reclamation
-works — lives in the target repository's `AGENTS.md` (injected by
-`driftseal init`). Follow that file; do not substitute this guide or memory
-for it.
+Treat the target repository's applicable `AGENTS.md` as the source of truth.
+This skill helps locate and resume that workflow; it does not restate or extend
+the policy.
 
 ## Locate DriftSeal
 
-- Prefer the `driftseal_*` MCP tools when the DriftSeal MCP server is available
-  for the target repository: `driftseal_status`, `driftseal_begin`,
-  `driftseal_end`, `driftseal_log`, `driftseal_reclaim`, `driftseal_unreclaim`,
-  and the `driftseal_decision_*` tools. Their input schemas come from the MCP
-  client, not from `driftseal help`. The server keeps state in its fixed
-  repository root and ignores storage-override environment variables.
-- Otherwise prefer `driftseal` from `PATH`, where `DRIFTSEAL_HOME` and
-  `DRIFTSEAL_DECISION_HOME` overrides apply. In a DriftSeal source checkout,
-  fall back to `node bin/driftseal.js`.
+- Read the applicable `AGENTS.md` before making changes.
+- Prefer `driftseal` from `PATH`. In a DriftSeal source checkout, fall back to
+  `node bin/driftseal.js`.
+- Use an explicitly configured, repository-pinned MCP server only when the user
+  or repository selects it, or when shell execution is unavailable. Its tool
+  schemas, not `driftseal help`, define the MCP interface.
 - Use one interface consistently within a round.
 - If DriftSeal is unavailable, limit activity to read-only discovery and report
   the blocker. Do not mutate the repository without the required log.
 
-## Command Map
+## Re-anchor When Needed
 
-Re-anchor after context loss or uncertainty; when `status` reports an open
-intent, the repository protocol defines whether to resume or replace it:
+After context loss or when intent state is uncertain, run:
 
 ```sh
 driftseal status
-driftseal log --last 3        # add --all to include reclaimed records
+driftseal log --last 3
 ```
 
-Run each work round as the repository's protocol directs (`-v`, `-s`, `-n`,
-and `-r` are the short forms of `--verify`, `--status`, `--note`, and
-`--verify-result`):
+Then resume, replace, verify, or close the intent exactly as `AGENTS.md`
+requires. For command syntax, run:
 
 ```sh
-driftseal begin "<objective>" --verify "<proof>" [--decision <id>]
-# ... do only what the intent covers ...
-driftseal end --status <status> --note "<what happened>" --verify-result "<proof output>"
+driftseal help
 ```
 
-Record and reconcile decisions as the repository's decision protocol directs:
-
-```sh
-driftseal decision add "<title>" --context "..." --outcome "..."
-driftseal decision update <id> [--status <status>] --note "<what changed or was confirmed>"
-driftseal decision list --status deferred
-```
-
-Retire meaningless closed records as the repository's protocol directs:
-
-```sh
-driftseal reclaim [id ...] --reason "<why>" [--dry-run]
-driftseal unreclaim <id> --reason "<why>"
-```
-
-For exact flags, eligibility rules, and recovery behavior, run
-`driftseal help` and read the repository's `AGENTS.md`.
+Do not treat this skill, MCP descriptions, or lifecycle-hook reminders as
+additional policy. If they conflict with `AGENTS.md`, follow `AGENTS.md`.