@zyaiting/keelson 0.4.1 → 0.5.0

package/src/commands/init.js

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
 import { projectPaths, findProjectRoot } from '../lib/paths.js';
 import { exists, write, read, mkdirp, readOr } from '../lib/fs.js';
 import { loadConfig, saveConfig, DEFAULT_CONFIG, CONFIG_VERSION } from '../lib/config.js';
-import { PLATFORMS, PLATFORM_IDS, RETIRED_PLATFORM_IDS, installTargets, installCanonicalSkill, installSkill, installWorkflow, installInstructions, installHooks, installSessionAdapter, skillSource, plannedCanonicalSkillFiles, plannedSkillFiles, plannedWorkflowFile, plannedManagedRemovals, plannedSessionAdapterFiles, readManagedState, reconcileManagedTargets, removeCanonicalRuntime, removeLegacyCopiedHooks, writeManagedState, assertSkillsInstallable } from '../platforms/index.js';
+import { PLATFORMS, PLATFORM_IDS, RETIRED_PLATFORM_IDS, installTargets, installCanonicalSkill, installSkill, installWorkflow, installInstructions, installHooks, installSessionAdapter, skillSource, plannedCanonicalSkillFiles, plannedSkillFiles, plannedWorkflowFile, plannedManagedRemovals, plannedSessionAdapterFiles, readManagedState, reconcileManagedTargets, removeCanonicalRuntime, removeLegacyCopiedHooks, writeManagedState, assertSkillsInstallable, assertCanonicalSkillInstallable, assertWorkflowInstallable } from '../platforms/index.js';
 import { list } from '../lib/args.js';
 import { ok, info, warn, heading, dim } from '../lib/out.js';
 import { detectAndCache, detectLocal } from '../lib/models.js';
@@ -149,7 +149,11 @@ export async function init({ flags }, cwd = process.cwd()) {
 
   heading(`Keelson ${fresh ? 'init' : 'update'} in ${root}`);
   // Refuse a protected shim before changing config or removing v0.3 runtime.
-  assertSkillsInstallable(root, targets, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, force: flags.force });
+  assertSkillsInstallable(root, targets, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, previousState: priorManaged, force: flags.force });
+  if (cfg.vendor) {
+    assertWorkflowInstallable(root, { lang: cfg.lang, guide: cfg.guide, previousState: priorManaged, force: flags.force });
+    assertCanonicalSkillInstallable(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, previousState: priorManaged, force: flags.force });
+  }
   if (retiredFromConfig.length) warn(`retired host adapters removed from config: ${retiredFromConfig.join(', ')}; use the portable agents layer or select one of: ${PLATFORM_IDS.filter((id) => id !== 'agents').join(', ')}`);
   if (retiredOverrides.length) warn(`retired platform overrides removed: ${retiredOverrides.join(', ')}`);
   if (retiredModelOverrides.length) warn(`retired model overrides removed: ${retiredModelOverrides.join(', ')}`);
@@ -201,8 +205,8 @@ export async function init({ flags }, cwd = process.cwd()) {
   }
 
   if (cfg.vendor) {
-    const workflowPath = installWorkflow(root, { lang: cfg.lang, guide: cfg.guide, force: flags.force });
-    const canonicalSkillPath = installCanonicalSkill(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, force: flags.force });
+    const workflowPath = installWorkflow(root, { lang: cfg.lang, guide: cfg.guide, previousState: priorManaged, force: flags.force });
+    const canonicalSkillPath = installCanonicalSkill(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, previousState: priorManaged, force: flags.force });
     ok(`vendored guidance → ${workflowPath}; ${canonicalSkillPath}`);
   } else info('guidance stays in the installed package; agents load it with `keelson guide`');
 
@@ -211,18 +215,19 @@ export async function init({ flags }, cwd = process.cwd()) {
     const discoveryKey = `${t.instructions}|${t.skillsDir}|${t.rulesFile ?? ''}`;
     if (!discoveryInstalled.has(discoveryKey)) {
       discoveryInstalled.add(discoveryKey);
-      const skillPath = installSkill(root, t, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, force: flags.force });
+      const skillPath = installSkill(root, t, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, previousState: priorManaged, force: flags.force });
       const files = installInstructions(root, t, { lang: cfg.lang });
       ok(`${t.label}: discovery shim → ${skillPath}; instructions → ${files.join(', ')}${t.confidence === 'convention' ? dim(' (path by convention; run `keelson doctor` after your first session)') : ''}`);
     } else {
       info(`${t.label}: reuses existing discovery surface ${t.instructions} + ${t.skillsDir}/keelson`);
     }
-    if (t.hooks) {
+    if (t.hooks && t.id === 'claude') {
       installHooks(root);
-      ok(`${t.label}: hooks → .claude/settings.json (session snapshot + per-prompt state line)`);
+      ok(`${t.label}: hooks → .claude/settings.json (workflow restore + file-tool gate + phase context injection)`);
     }
     const sessionFiles = installSessionAdapter(root, t);
     if (sessionFiles.length) ok(`${t.label}: native session adapter → ${sessionFiles.join(', ')}`);
+    if (t.sessionAdapter === 'codex-thread-env') info('Codex: review and trust the generated project hooks in /hooks when prompted; host permissions stay in control');
     else if (t.sessionAdapter === 'pi-env') info(`${t.label}: native session focus uses PI_SESSION_ID; no adapter file needed`);
   }
   writeManagedState(root, targets, PKG_VERSION, { vendor: cfg.vendor });

package/src/commands/new.js

@@ -43,7 +43,7 @@ export async function newChange({ flags, positional }, cwd = process.cwd()) {
   const front = [
     `tier: ${tier}`,
     `created: ${vars.date}`,
-    `status: ${tier === 'spec' ? 'clarifying' : 'in-progress'}`,
+    'status: clarifying',
     `owner: ${owner}`,
     ...(worktree ? [`branch: ${name}`, `worktree: ${path.relative(root, worktree)}`] : branch ? [`branch: ${branch}`] : []),
     ...(list(flags.depends).length ? [`depends: [${list(flags.depends).join(', ')}]`] : []),

package/src/commands/platforms.js

@@ -16,7 +16,7 @@ export async function platforms({ flags }, cwd = process.cwd()) {
     const configured = id === 'agents' ? portableConfigured : cfg?.tools?.includes(id) ?? false;
     const sessionFocus = p.sessionFocus ?? 'degraded';
     const effectiveSessionFocus =
-      configured && cfg?.hooks === false && p.sessionAdapter && p.sessionAdapter !== 'pi-env'
+      configured && cfg?.hooks === false && p.sessionAdapter && !['pi-env', 'codex-thread-env'].includes(p.sessionAdapter)
         ? 'degraded'
         : sessionFocus;
     return { id, label: p.label, support: p.support ?? 'first-class', sessionFocus, effectiveSessionFocus, instructions: p.instructions, skills: p.skillsDir, skillDiscovery: p.skillsDir, rules: p.rulesFile ?? null, hooks: p.hooks, confidence: p.confidence, examples: p.examples ?? null, installed: det[id]?.installed ?? null, configured };

package/src/commands/start.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { requireProjectRoot } from '../lib/paths.js';
+import { exists, read, write, writeJson, withLock } from '../lib/fs.js';
+import { runtimeDir } from '../lib/runtime-path.js';
+import { bindSession } from '../lib/session.js';
+import { activeWorkflow, planningBlockers, planFingerprint, phaseContext } from '../lib/workflow.js';
+
+export async function start({ positional = [], flags = {} }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  return withLock(path.join(runtimeDir(root), 'landing'), () => {
+    const workflow = activeWorkflow(root, positional[0] ?? flags.change);
+    const blockers = planningBlockers(workflow.change, workflow.changes);
+    if (blockers.length) throw new Error(`cannot start implementation: ${blockers.join(' ')}`);
+    const { change } = workflow;
+    const pack = phaseContext(root, workflow); // Validate before changing state.
+    const file = path.join(change.dir, 'change.md');
+    const text = read(file);
+    const updated = /^status:/m.test(text.split('\n---')[0])
+      ? text.replace(/^status:.*$/m, 'status: in-progress')
+      : text.replace(/^---\r?\n/, '---\nstatus: in-progress\n');
+    write(file, updated);
+    writeJson(path.join(change.dir, 'execution.json'), { schema: 1, plan: planFingerprint(change), startedAt: new Date().toISOString() });
+    bindSession(root, change.name, { source: 'start' });
+    const contextFile = path.join(change.dir, 'context.json');
+    if (!exists(contextFile)) {
+      const files = pack.files.map(({ file }) => file.replace(' (including shards)', ''));
+      writeJson(contextFile, { schema: 1, implement: files, check: files });
+    }
+    const result = { change: change.name, state: 'in-progress' };
+    console.log(flags.json ? JSON.stringify(result) : `Started ${change.name}; follow \`keelson context --phase implement\` before editing.`);
+    return 0;
+  });
+}

package/src/commands/uninstall.js

@@ -14,7 +14,7 @@ export async function uninstall({ flags }, cwd = process.cwd()) {
   const removed = removeSurfaces(root, cfg.tools ?? [], cfg);
   for (const r of removed) ok(`removed ${r}`);
   if (managed?.vendor === true) {
-    const canonical = removeCanonicalRuntime(root, { lang: cfg.lang, profile: cfg.profile, version: managed.packageVersion, guide: cfg.guide });
+    const canonical = removeCanonicalRuntime(root, { lang: cfg.lang, profile: cfg.profile, version: managed.packageVersion, guide: cfg.guide, previousState: managed });
     for (const r of canonical.removed) ok(`removed ${r}`);
     for (const r of canonical.preserved) warn(`kept ${r}: it differs from the vendored Keelson output`);
   }

package/src/lib/decisions.js

@@ -37,8 +37,10 @@ export function validateDecisionData(data) {
 
 export function decisionFrontier(data, limit = 3) {
   const ready = data.decisions.filter((d) => d.state === 'open' && d.depends.every((id) => data.decisions.some((x) => x.id === id && x.state === 'settled')));
+  const ownerReady = ready.filter((d) => d.owner === 'user');
   return {
-    questions: ready.filter((d) => d.owner === 'user').slice(0, limit),
+    questions: ownerReady.slice(0, limit),
+    remaining: ownerReady.slice(limit),
     investigate: ready.filter((d) => d.owner !== 'user'),
     blocked: data.decisions.filter((d) => d.state === 'open' && !ready.includes(d)),
     assumptions: data.decisions.filter((d) => d.state === 'assumed'),

package/src/lib/hook-context.js

@@ -0,0 +1,30 @@
+import crypto from 'node:crypto';
+import { readSession, writeSession } from './session.js';
+import { activeWorkflow, phaseContext, renderPhaseContext, workflowHint } from './workflow.js';
+
+/** Match the identity exported to each host's CLI tools, without persisting raw IDs. */
+export function hookEnvironment(host, input, inherited = process.env) {
+  const env = { ...inherited };
+  // Codex child events identify the child thread with agent_id; session_id
+  // identifies the shared root. Match the child's CODEX_THREAD_ID in shell tools.
+  const child = host === 'codex' && typeof input.agent_id === 'string' ? input.agent_id.trim() : '';
+  const id = child || (typeof input.session_id === 'string' ? input.session_id.trim() : '');
+  if (id) {
+    const namespace = host === 'codex' ? 'codex_thread_id' : host;
+    env.KEELSON_SESSION_ID = crypto.createHash('sha256').update(`${namespace}:${id}`).digest('hex').slice(0, 32);
+  }
+  return env;
+}
+
+export function sessionContext(root, env, event, host) {
+  const session = writeSession(root, {
+    source: `${host}-hook`, ...(event === 'SessionStart' ? { injectedContexts: [] } : {}),
+  }, env);
+  const lines = [workflowHint(root, env)];
+  const focus = session?.state.change ?? readSession(root, env).state?.change;
+  if (focus) {
+    const workflow = activeWorkflow(root, focus, env);
+    if (workflow.change) lines.push(renderPhaseContext(phaseContext(root, workflow)));
+  }
+  return lines.join('\n\n');
+}

package/src/lib/markdown.js

@@ -200,7 +200,7 @@ export function parseLedger(text) {
       const exits = [...s.body.matchAll(/exit\s*(?:code)?\s*[:=]?\s*(\d+)/gi)].map((m) => Number(m[1]));
       entry.exit = exits.length ? Math.max(...exits) : null;
       entry.command = (s.body.match(/`([^`]+)`/) || [])[1] ?? null;
-      entry.tree = (s.body.match(/\btree\s*[:=]?\s*([0-9a-f]{7,40})\b/i) || [])[1] ?? null;
+      entry.tree = (s.body.match(/\btree\s*[:=]?\s*([0-9a-f]{7,64})\b/i) || [])[1] ?? null;
     }
     if (kind === 'dispatch') {
       const dm = entry.title.match(/(light|standard|deep)/i);

package/src/lib/rules.js

@@ -12,12 +12,20 @@ export function parseRulesIndex(text) {
   return entries;
 }
 
-export function matchRules(rulesDir, paths) {
+// Declared touches can themselves be globs. Keep every rule whose literal
+// prefix can overlap; extra context is preferable to silently missing a rule.
+function mayOverlap(a, b) {
+  const prefix = (s) => s.replace(/^\.\//, '').split(/[*?{]/, 1)[0].replace(/\/$/, '');
+  const x = prefix(a), y = prefix(b);
+  return x.startsWith(y) || y.startsWith(x);
+}
+
+export function matchRules(rulesDir, paths, { patterns = false } = {}) {
   const index = parseRulesIndex(readOr(path.join(rulesDir, 'index.md')));
   const hits = new Map();
   for (const e of index) {
     const always = e.glob === '**' || e.glob === '*';
-    const matched = always || paths.some((p) => globMatch(e.glob, p));
+    const matched = always || paths.some((p) => globMatch(e.glob, p) || (patterns && /[*?{]/.test(p) && mayOverlap(e.glob, p)));
     if (!matched) continue;
     const f = path.join(rulesDir, e.file);
     if (!hits.has(e.file)) hits.set(e.file, { file: e.file, globs: [], exists: exists(f), content: readOr(f) });

package/src/lib/workflow.js

@@ -0,0 +1,102 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { exists, read, readJson } from './fs.js';
+import { projectPaths, resolveWithin } from './paths.js';
+import { loadConfig } from './config.js';
+import { loadAllChanges } from './changes.js';
+import { readSession } from './session.js';
+import { decisionFrontier } from './decisions.js';
+import { matchRules } from './rules.js';
+import { readCapabilitySpec } from './specs.js';
+
+export function activeWorkflow(root, name, env = process.env) {
+  const cfg = loadConfig(projectPaths(root).config);
+  const paths = projectPaths(root, cfg);
+  const changes = loadAllChanges(paths.changes);
+  const focused = name ?? readSession(root, env).state?.change;
+  // A sole change is a CLI convenience, not permission for an unrelated host
+  // session to start writing. Hooks require an explicit session binding.
+  const change = changes.find((c) => c.name === (focused ?? (changes.length === 1 ? changes[0].name : null)));
+  return { cfg, paths, changes, change };
+}
+
+export function planFingerprint(change) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    body: change.body.replace(/\[[xX ]\]/g, '[ ]'),
+    decisions: change.decisionRecords,
+    depends: change.depends, touches: change.touches,
+    deltas: change.deltaFiles.map((file) => [file, read(path.join(change.dir, 'specs', file)).replace(/\r\n?/g, '\n')]),
+  })).digest('hex');
+}
+
+export function planningBlockers(change, changes = []) {
+  if (!change) return ['No active change. Create the smallest useful change and run `keelson start <name>`.'];
+  const blocked = [];
+  if (['blocked', 'cancelled', 'integrated'].includes(change.storedWork)) blocked.push(`Change is ${change.storedWork}.`);
+  if (!decisionFrontier({ decisions: change.decisionRecords }, Infinity).complete) blocked.push('Resolve the registered decision tree with `keelson ask frontier --all`.');
+  if (change.open.length || change.assumed.length) blocked.push('Resolve the change\'s open questions and unconfirmed assumptions.');
+  if (!change.acceptance.length || change.acceptance.some((a) => /^\s*(?:…|<[^>]+>)(?:\s|$)/.test(a.text))) blocked.push('Write concrete acceptance checks in change.md.');
+  if (change.depends.some((name) => changes.some((c) => c.name === name))) blocked.push('Finish the prerequisite changes first.');
+  return blocked;
+}
+
+export function implementationBlockers(change, changes = []) {
+  const blockers = planningBlockers(change, changes);
+  if (!change) return blockers;
+  const receipt = readJson(path.join(change.dir, 'execution.json'), null);
+  if (receipt?.schema !== 1 || receipt.plan !== planFingerprint(change)) blockers.push('Run `keelson start` after settling the current plan; its start record is missing or stale.');
+  if (change.storedWork !== 'in-progress') blockers.push('Implementation requires the in-progress state set by `keelson start`.');
+  return blockers;
+}
+
+/** Declarative additions augment mandatory context; they cannot omit a contract. */
+export function phaseContext(root, workflow, phase = 'implement', touched = []) {
+  if (!['implement', 'check'].includes(phase)) throw new Error('phase must be implement or check');
+  const { cfg, paths, change } = workflow;
+  const files = new Map();
+  const add = (file, required = false) => {
+    const rel = path.relative(root, file).replace(/\\/g, '/');
+    const safe = resolveWithin(root, rel);
+    if (exists(safe)) files.set(rel, read(safe).trim());
+    else if (required) throw new Error(`declared context file ${rel} is missing; restore it or correct context.json`);
+  };
+  add(paths.intent);
+  if (change) {
+    for (const name of ['request.md', 'change.md', 'decisions.json', 'tasks.md']) add(path.join(change.dir, name));
+    for (const file of change.deltaFiles) add(path.join(change.dir, 'specs', file), true);
+    for (const cap of change.capabilities) {
+      const logical = readCapabilitySpec(paths.specs, cap);
+      if (logical) files.set(`${paths.specsRel}/${cap}/spec.md (including shards)`, logical);
+    }
+    const manifestPath = path.join(change.dir, 'context.json');
+    if (exists(manifestPath)) {
+      const manifest = JSON.parse(read(manifestPath));
+      if (manifest.schema !== 1 || !['implement', 'check'].every((key) => Array.isArray(manifest[key]) && manifest[key].every((v) => typeof v === 'string'))) throw new Error('context.json requires schema 1 and implement/check path arrays');
+      for (const rel of manifest[phase]) add(resolveWithin(root, rel), true);
+    }
+  }
+  for (const rule of matchRules(paths.rules, [...(change?.touches ?? []), ...touched], { patterns: true })) add(path.join(paths.rules, rule.file), true);
+  const instructions = phase === 'check'
+    ? 'Review the original request, acceptance, current/delta specs and diff in a fresh context. Find uncovered behavior and risky assumptions. Report findings with evidence; implementation owns repairs, then re-review the affected result. Do not treat the implementer\'s summary as proof.'
+    : 'Resolve owner decisions before dependent implementation. Follow the supplied contracts, run relevant checks, and send material changes to an independent reviewer. Continue within existing authorization.';
+  return {
+    phase, change: change?.name ?? null, instructions,
+    checks: cfg.check ?? [],
+    files: [...files].map(([file, content]) => ({ file, content })),
+  };
+}
+
+export function renderPhaseContext(pack) {
+  return [`[keelson] ${pack.phase} context${pack.change ? `: ${pack.change}` : ''}`, pack.instructions,
+    `Configured checks (review trust before running): ${JSON.stringify(pack.checks)}`,
+    ...pack.files.map(({ file, content }) => `\n--- ${file} ---\n${content}`)].join('\n');
+}
+
+export function workflowHint(root, env = process.env) {
+  const focus = readSession(root, env).state?.change;
+  if (!focus) return '[keelson] Read `keelson guide` for this request. Investigate facts first; use one question for a simple gap or the whole ready frontier for connected uncertainty. Before modifying files, create/focus a change and run `keelson start`; keep read-only requests read-only.';
+  const workflow = activeWorkflow(root, focus, env);
+  if (!workflow.change) return '[keelson] Previous focus is no longer active. Re-read context and select work for the current request.';
+  const blocked = implementationBlockers(workflow.change, workflow.changes);
+  return `[keelson] ${focus}: ${blocked.length ? 'planning — ' + blocked.join(' ') : 'implement — follow the current context, then independent review → fresh checks → land → reconcile.'} Verification is determined by signed current-tree evidence in \`keelson status\`, never by handwritten ledger text.`;
+}

package/src/platforms/integration.js

@@ -3,7 +3,7 @@ import crypto from 'node:crypto';
 import path from 'node:path';
 import { exists, read, readJson, readOr, rmrf, write, writeJson } from '../lib/fs.js';
 import { installTargets, PLATFORMS } from './registry.js';
-import { managedSkillShimMatches, residentBlock } from './runtime.js';
+import { captureRuntimeOwnership, managedSkillShimMatches, residentBlock } from './runtime.js';
 
 export const MANAGED_STATE = path.join('.keelson', 'manifest.json');
 export const LEGACY_MANAGED_STATE = path.join('.keelson', '.managed.json');
@@ -100,7 +100,7 @@ export function managedStateMatches(root, targets) {
 }
 
 export function writeManagedState(root, targets, packageVersion, { vendor = false } = {}) {
-  writeJson(path.join(root, MANAGED_STATE), { schema: 1, packageVersion, vendor: Boolean(vendor), targets: targets.map(managedTarget) });
+  writeJson(path.join(root, MANAGED_STATE), { schema: 1, packageVersion, vendor: Boolean(vendor), targets: targets.map(managedTarget), runtime: captureRuntimeOwnership(root, targets, vendor) });
   if (exists(path.join(root, LEGACY_MANAGED_STATE))) rmrf(path.join(root, LEGACY_MANAGED_STATE));
   return MANAGED_STATE;
 }
@@ -173,11 +173,11 @@ const LEGACY_CLAUDE_HOOK_COMMANDS = new Set([
   'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/session-start.mjs"',
   'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/prompt-state.mjs"',
 ]);
-const CLAUDE_HOOK_COMMANDS = new Set(['keelson hook session-start', 'keelson hook prompt-state', ...LEGACY_CLAUDE_HOOK_COMMANDS]);
+const CLAUDE_HOOK_COMMANDS = new Set(['keelson hook session-start', 'keelson hook prompt-state', 'keelson hook workflow-guard', ...LEGACY_CLAUDE_HOOK_COMMANDS]);
 const isClaudeHook = (hook) => hook?.type === 'command' && CLAUDE_HOOK_COMMANDS.has(String(hook.command));
 
 export function installHooks(root) {
-  removeHooks(root, { legacyOnly: true });
+  removeHooks(root);
   const settingsPath = path.join(root, '.claude', 'settings.json');
   const settings = readJson(settingsPath, {}) ?? {};
   settings.hooks ??= {};
@@ -192,6 +192,8 @@ export function installHooks(root) {
   };
   ensure('SessionStart', 'startup|resume|clear|compact', 'session-start.mjs');
   ensure('UserPromptSubmit', null, 'prompt-state.mjs');
+  ensure('PreToolUse', 'Edit|Write|MultiEdit|NotebookEdit|Agent|Task', 'workflow-guard.mjs');
+  ensure('SubagentStart', null, 'workflow-guard.mjs');
   writeJson(settingsPath, settings);
   return ['.claude/settings.json'];
 }
@@ -216,78 +218,41 @@ export function removeHooks(root, { legacyOnly = false } = {}) {
   writeJson(settingsPath, settings);
 }
 
-const CODEBUDDY_SESSION_COMMAND = 'keelson hook codebuddy-session';
 const LEGACY_CODEBUDDY_SESSION_COMMAND = 'node "$CODEBUDDY_PROJECT_DIR/.keelson/hooks/codebuddy-session.mjs"';
-const isCodeBuddyHook = (hook) => hook?.type === 'command' && hook.command === CODEBUDDY_SESSION_COMMAND;
-
-function ensureCodeBuddyHook(settings, event, matcher = null) {
-  settings.hooks ??= {};
-  settings.hooks[event] ??= [];
-  const found = settings.hooks[event].find((g) =>
-    (g.hooks ?? []).some(isCodeBuddyHook),
-  );
-  if (found) {
-    if (matcher && found.matcher !== matcher) found.matcher = matcher;
-    else if (!matcher && 'matcher' in found) delete found.matcher;
-    return;
-  }
-  const group = {
-    hooks: [{
-      type: 'command',
-      command: CODEBUDDY_SESSION_COMMAND,
-      timeout: 10,
-    }],
-  };
-  if (matcher) group.matcher = matcher;
-  settings.hooks[event].push(group);
-}
-
-export function installSessionAdapter(root, target) {
-  const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return [];
-
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    removeCodeBuddyHooks(root, { legacyOnly: true });
-    const settingsPath = path.join(root, '.codebuddy', 'settings.json');
-    const settings = readJson(settingsPath, {}) ?? {};
-    ensureCodeBuddyHook(settings, 'SessionStart');
-    ensureCodeBuddyHook(settings, 'UserPromptSubmit');
-    ensureCodeBuddyHook(settings, 'PreToolUse', 'Bash|PowerShell');
-    writeJson(settingsPath, settings);
-    return [path.relative(root, settingsPath)];
-  }
-
-  return [];
-}
-
-export function plannedSessionAdapterFiles(root, target) {
-  const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const rows = [];
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return rows;
-
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
-    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
-      (matcher === null || g.matcher === matcher) &&
-      (g.hooks ?? []).some(isCodeBuddyHook),
-    );
-    const ready = has('SessionStart') && has('UserPromptSubmit') && has('PreToolUse', 'Bash|PowerShell');
-    rows.push({ path: '.codebuddy/settings.json (Keelson session hooks)', status: ready ? 'unchanged' : exists(path.join(root, '.codebuddy', 'settings.json')) ? 'update' : 'create' });
-  }
-
-  return rows;
-}
-
-function removeCodeBuddyHooks(root, { legacyOnly = false } = {}) {
-  const settingsPath = path.join(root, '.codebuddy', 'settings.json');
+const HOST_HOOKS = {
+  'codebuddy-hooks': {
+    file: '.codebuddy/settings.json',
+    registrations: [
+      ['SessionStart', null, 'codebuddy-session'],
+      ['UserPromptSubmit', null, 'codebuddy-session'],
+      ['PreToolUse', 'Bash|PowerShell', 'codebuddy-session'],
+      ['PreToolUse', '^(Edit|Write|MultiEdit|NotebookEdit|NotebookWrite|Agent|Task)$', 'codebuddy-workflow'],
+    ],
+  },
+  'codex-thread-env': {
+    file: '.codex/hooks.json',
+    registrations: [
+      ['SessionStart', null, 'codex-session'],
+      ['UserPromptSubmit', null, 'codex-session'],
+      ['PreToolUse', '^(apply_patch|Edit|Write|Agent|spawn_agent)$', 'codex-workflow'],
+      ['SubagentStart', null, 'codex-workflow'],
+    ],
+  },
+};
+const adapterFor = (target) => HOST_HOOKS[target?.sessionAdapter];
+const isAdapterHook = (h, adapter) => h?.type === 'command' && adapter.registrations.some(([, , name]) => h.command === `keelson hook ${name}`);
+const hasRegistration = (settings, [event, matcher, name]) => (settings.hooks?.[event] ?? []).some((g) =>
+  (g.matcher ?? null) === matcher && (g.hooks ?? []).some((h) => h.type === 'command' && h.command === `keelson hook ${name}`));
+
+function removeAdapterHooks(root, adapter) {
+  const settingsPath = path.join(root, adapter.file);
   const settings = readJson(settingsPath, null);
   if (!settings?.hooks) return false;
   let changed = false;
   for (const event of Object.keys(settings.hooks)) {
     settings.hooks[event] = settings.hooks[event].map((g) => {
-      const hooks = (g.hooks ?? []).filter((h) =>
-        !(h?.type === 'command' && h.command === LEGACY_CODEBUDDY_SESSION_COMMAND) && (legacyOnly || !isCodeBuddyHook(h)),
-      );
+      const hooks = (g.hooks ?? []).filter((h) => !isAdapterHook(h, adapter) &&
+        !(adapter.file.startsWith('.codebuddy/') && h?.type === 'command' && h.command === LEGACY_CODEBUDDY_SESSION_COMMAND));
       if (hooks.length === (g.hooks ?? []).length) return g;
       changed = true;
       return hooks.length ? { ...g, hooks } : null;
@@ -301,32 +266,49 @@ function removeCodeBuddyHooks(root, { legacyOnly = false } = {}) {
   return true;
 }
 
-export function removeSessionAdapter(root, target, keep = new Set()) {
+export function installSessionAdapter(root, target) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const removed = [];
-  if (p?.sessionAdapter === 'codebuddy-hooks') {
-    if (removeCodeBuddyHooks(root)) removed.push('.codebuddy/settings.json (Keelson hooks)');
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  // Split owned hooks out of mixed groups; never change a user's matcher.
+  removeAdapterHooks(root, adapter);
+  const settingsPath = path.join(root, adapter.file);
+  const settings = readJson(settingsPath, {}) ?? {};
+  settings.hooks ??= {};
+  for (const [event, matcher, name] of adapter.registrations) {
+    settings.hooks[event] ??= [];
+    settings.hooks[event].push({
+      ...(matcher ? { matcher } : {}),
+      hooks: [{ type: 'command', command: `keelson hook ${name}`, timeout: 10 }],
+    });
   }
-  return removed;
+  writeJson(settingsPath, settings);
+  return [adapter.file];
 }
 
-export function sessionAdapterProblems(root, target) {
+export function plannedSessionAdapterFiles(root, target) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const problems = [];
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return problems;
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  const file = path.join(root, adapter.file);
+  const settings = readJson(file, {}) ?? {};
+  const ready = adapter.registrations.every((registration) => hasRegistration(settings, registration));
+  return [{ path: `${adapter.file} (Keelson workflow hooks)`, status: ready ? 'unchanged' : exists(file) ? 'update' : 'create' }];
+}
 
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
-    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
-      (matcher === null || g.matcher === matcher) &&
-      (g.hooks ?? []).some(isCodeBuddyHook),
-    );
-    if (!has('SessionStart')) problems.push(`${p.label}: SessionStart session hook not registered`);
-    if (!has('UserPromptSubmit')) problems.push(`${p.label}: UserPromptSubmit session hook not registered`);
-    if (!has('PreToolUse', 'Bash|PowerShell')) problems.push(`${p.label}: Bash|PowerShell PreToolUse session hook not registered`);
-  }
+export function removeSessionAdapter(root, target, keep = new Set()) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const adapter = adapterFor(p);
+  return adapter && removeAdapterHooks(root, adapter) ? [`${adapter.file} (Keelson hooks)`] : [];
+}
 
-  return problems;
+export function sessionAdapterProblems(root, target) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  const settings = readJson(path.join(root, adapter.file), {}) ?? {};
+  return adapter.registrations.filter((r) => !hasRegistration(settings, r))
+    .map(([event, matcher, name]) => `${p.label}: ${event}${matcher ? ` (${matcher})` : ''} hook ${name} not registered`);
 }
 
 function removeTargetSurfaces(root, p, keep = new Set()) {
@@ -334,7 +316,7 @@ function removeTargetSurfaces(root, p, keep = new Set()) {
   const skillRel = path.join(p.skillsDir, 'keelson');
   const skill = path.join(root, skillRel);
   const managed = readManagedState(root);
-  if (!keep.has(skillRel) && exists(skill) && managedSkillShimMatches(root, p, managed?.packageVersion)) {
+  if (!keep.has(skillRel) && exists(skill) && managedSkillShimMatches(root, p, managed?.packageVersion, managed)) {
     rmrf(skill);
     removed.push(path.relative(root, skill));
   }
@@ -348,7 +330,7 @@ function removeTargetSurfaces(root, p, keep = new Set()) {
     rmrf(path.join(root, p.rulesFile));
     removed.push(p.rulesFile);
   }
-  if (p.hooks && !keep.has('.claude/settings.json')) removeHooks(root);
+  if (p.hooks && p.id === 'claude' && !keep.has('.claude/settings.json')) removeHooks(root);
   removed.push(...removeSessionAdapter(root, p, keep));
   return removed;
 }
@@ -357,13 +339,13 @@ export function reconcileManagedTargets(root, targets) {
   const removed = [];
   const stale = staleManagedTargets(root, targets);
   const keep = new Set(targets.flatMap(managedSurfacePaths));
-  if (targets.some((p) => p.hooks)) keep.add('.claude/settings.json');
+  if (targets.some((p) => p.hooks && p.id === 'claude')) keep.add('.claude/settings.json');
   for (const p of stale) removed.push(...removeTargetSurfaces(root, p, keep));
   for (const rel of legacyManagedRemovals(root, targets)) {
     rmrf(path.join(root, rel));
     removed.push(rel);
   }
-  if (stale.some((p) => p.hooks) && !targets.some((p) => p.hooks)) {
+  if (stale.some((p) => p.hooks && p.id === 'claude') && !targets.some((p) => p.hooks && p.id === 'claude')) {
     removeHooks(root);
   }
   return [...new Set(removed)];