@brainervirus/workit-core 8.4.1 → 8.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.4.1",
+  "version": "8.5.2",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-retro/SKILL.md

@@ -15,8 +15,8 @@ proposes and stops. Nothing changes until the user approves.
    `retro:` row in `workit ledger list --type decision`), else the last ~10
    sessions. State the window in one line.
 2. **Read through workit, cheapest first.** Every finding cites these:
-   - `workit ledger list --last 200`: rulings (ambiguities the agent had to
-     settle), failed or self verdicts, handoffs, check runs, CI reruns.
+   - `workit ledger list --last 200`: rulings, failed/self verdicts, handoffs,
+     check runs, CI reruns, `skill.loaded` rows (skipped skills: routing).
    - `workit pr status --pr <n>` for each recent PR: threads, failing checks.
    - `git log --oneline -50`, plus reverts and fixups after review.
    - `workit knowledge lint`: today's AGENTS.md and need-based files.

package/src/hooks/context.ts

@@ -1,7 +1,10 @@
 // Session context shared by every host: the contract bootstrap, the current
 // task's compact context, and the one-time offer of unfinished tasks.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 import { invariantBootstrap } from "../core/methods";
+import { resolveStore } from "../store/paths";
 import { canonicalJson } from "../core/task-contract";
 import { isObservedCheck, type Freshness } from "../core/task-evaluation";
 import { worktreeSignal } from "../git/rev";
@@ -287,3 +290,99 @@ export const turnContextText = (input: HookInput, descriptor: HostDescriptor): s
     return null;
   }
 };
+
+// Change-only per-turn context. A hook-process host (Claude Code, Codex)
+// keeps each injected additionalContext in the transcript, so the task
+// context is resent only when it changed since the last injection for the
+// session. Each hook is a fresh process: the last digest lives in the
+// workspace store (`hooks/turn-<session hash>.json`). Every cache failure
+// answers "changed", so context is resent rather than lost.
+
+const TURN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const digestOf = (text: string): string => createHash("sha256").update(text).digest("hex");
+
+/** The session's last-injected digest file, or null when it cannot be told apart or stored. */
+const turnMarker = (input: HookInput): string | null => {
+  if (!input.session.id) return null;
+  try {
+    const location = resolveStore(input.cwd);
+    if (location instanceof Error) return null;
+    const session = [input.host, input.session.id, input.session.agentId ?? ""].join("\0");
+    return path.join(location.dir, "hooks", `turn-${digestOf(session).slice(0, 32)}.json`);
+  } catch {
+    return null;
+  }
+};
+
+const writeTurnDigest = (file: string, digest: string): void => {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ digest })}\n`);
+  } catch {
+    // An unwritable store only means the context is sent every turn.
+  }
+};
+
+const clearTurnDigest = (file: string): void => {
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // A stale digest only withholds one context equal to it.
+  }
+};
+
+/** Drops digests untouched for a week (sessions that ended). */
+const pruneTurnDigests = (dir: string, now: number): void => {
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.startsWith("turn-")) continue;
+      const file = path.join(dir, name);
+      try {
+        if (now - fs.statSync(file).mtimeMs > TURN_TTL_MS) fs.rmSync(file, { force: true });
+      } catch {
+        // Raced with another session: nothing to prune.
+      }
+    }
+  } catch {
+    // No hooks dir yet.
+  }
+};
+
+/**
+ * `text` when it differs from the last per-turn context injected for this
+ * session (recording it), else null.
+ */
+export const changedTurnContext = (input: HookInput, text: string | null): string | null => {
+  const file = turnMarker(input);
+  if (!text) {
+    // No context now: the next one is a change, even if it repeats an old one.
+    if (file) clearTurnDigest(file);
+    return null;
+  }
+  if (!file) return text;
+  const digest = digestOf(text);
+  try {
+    const previous = JSON.parse(fs.readFileSync(file, "utf8")) as { digest?: unknown };
+    if (previous.digest === digest) return null;
+  } catch {
+    // Missing or unreadable digest: treat as changed.
+  }
+  writeTurnDigest(file, digest);
+  return text;
+};
+
+/**
+ * A session start already injects the task context (inside the contract), so
+ * the per-turn digest is seeded with what the next prompt would carry: the
+ * first turn after a start, resume or compaction does not resend it. A
+ * session without task context clears its digest instead.
+ */
+export const seedTurnContext = (input: HookInput, descriptor: HostDescriptor): void => {
+  const file = turnMarker(input);
+  if (!file) return;
+  pruneTurnDigests(path.dirname(file), Date.now());
+  const text = turnContextText(input, descriptor);
+  if (text) writeTurnDigest(file, digestOf(text));
+  else clearTurnDigest(file);
+};

package/src/hooks/descriptor.ts

@@ -27,6 +27,12 @@ export type HostDescriptor = {
     /** How the session's current task is chosen: by a session bound to the task
      * record, or the workspace's single active task when sessions never bind. */
     task: "session-bound" | "single-active";
+    /** `on-change`: the host keeps each injected context in the transcript, so
+     * the core resends per-turn context only when it changed; `every-turn`:
+     * the core sends it on every turn (an in-process system-prompt hook needs
+     * it each time, or the host plugin dedups itself); `per-session`: the
+     * host plugin sends it once per session and again after compaction. */
+    turnResend: "on-change" | "every-turn" | "per-session";
   };
   subagents: {
     identity: Support;
@@ -34,6 +40,9 @@ export type HostDescriptor = {
     blockStart: Support;
     worktreeIsolation: Support;
     maxConcurrency: number | "undocumented";
+    /** How a Workit agent type is spelled: plugin-namespaced (`workit:verifier`)
+     * on hosts that namespace plugin agents, else a plain `workit-verifier`. */
+    agentPrefix: "workit:" | "workit-";
   };
   provenance: { sessionId: Support; agentIdOnTool: Support; postToolObserve: Support };
   /** Host-native interaction boundaries workit can observe. */

package/src/hooks/handle.ts

@@ -1,5 +1,10 @@
 // The one host-hook implementation: every host maps its native events here.
-import { sessionContextText, turnContextText } from "./context";
+import {
+  changedTurnContext,
+  seedTurnContext,
+  sessionContextText,
+  turnContextText,
+} from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
 import { shellPolicy } from "./policy";
 import {
@@ -10,6 +15,13 @@ import {
   rawGitPre,
   settlePendingCommit,
 } from "./raw-git";
+import {
+  promptNudge,
+  recordSkillLoad,
+  shipNudge,
+  skillReadIn,
+  withContextLine,
+} from "./skill-nudge";
 import { shellWrites, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
@@ -18,16 +30,34 @@ export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
 const usable = (value: Support) => value === "native" || value === "partial";
 const NONE: HookDecision = { kind: "none" };
 
+const resendsOnChange = (descriptor: HostDescriptor): boolean =>
+  descriptor.context.turnResend === "on-change" && usable(descriptor.context.perTurn);
+
 /** Sessions already offered unfinished tasks in this process. */
 const offered = new Set<string>();
 
-/** The Workit plugin's worktree-isolated implementer is the one Claude Code
- * subagent that writes. Claude namespaces plugin agents, so only the exact
- * `workit:implementer` is ours: a bare or other-plugin `implementer` is not. */
-const CLAUDE_WORKTREE_IMPLEMENTER = "workit:implementer";
+const ROLES: Readonly<Record<string, "implementer" | "judge">> = {
+  implementer: "implementer",
+  verifier: "judge",
+  reviewer: "judge",
+};
 
-/** The plugin's read-only judges: each records verdicts as its own session. */
-const CLAUDE_JUDGES: ReadonlySet<string> = new Set(["workit:verifier", "workit:reviewer"]);
+/**
+ * The Workit agent role an agent type names, spelled the host's way
+ * (`descriptor.subagents.agentPrefix`): Claude Code namespaces plugin agents
+ * (`workit:implementer`, so a bare `workit-implementer` is someone else's);
+ * other hosts name custom agents freely (`workit-implementer`). The
+ * implementer is the one subagent that writes; verifier and reviewer are
+ * read-only judges that record verdicts as their own session.
+ */
+const workitRole = (
+  descriptor: HostDescriptor,
+  agentType: string,
+): "implementer" | "judge" | null => {
+  const prefix = descriptor.subagents.agentPrefix;
+  const name = agentType.startsWith(prefix) ? agentType.slice(prefix.length) : "";
+  return Object.hasOwn(ROLES, name) ? ROLES[name] : null;
+};
 
 /** `<lead session>:<agent id>`, safe for the ledger's session grammar. */
 const subagentSession = (session: string | null, agentId: string): string =>
@@ -38,22 +68,24 @@ const subagentSession = (session: string | null, agentId: string): string =>
     .slice(0, 128);
 
 const subagentStartText = (
-  host: HookInput["host"],
   session: string | null,
   descriptor: HostDescriptor,
   event: Extract<HookInput["event"], { kind: "subagent.start" }>,
 ): string => {
-  if (host === "claude_code" && event.agentType === CLAUDE_WORKTREE_IMPLEMENTER)
-    return `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) working in its own git worktree: it may edit and commit there, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
-  const readOnly = `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided.`;
-  if (
-    host === "claude_code" &&
-    event.agentType &&
-    CLAUDE_JUDGES.has(event.agentType) &&
-    event.agentId
-  )
-    return `${readOnly} Its own Workit session is ${subagentSession(session, event.agentId)}: record verdicts with \`workit ledger verdict <result> --session ${subagentSession(session, event.agentId)} ...\` so the ledger tells it apart from the author.`;
-  return readOnly;
+  const role = workitRole(descriptor, event.agentType);
+  const who = `${descriptor.label} subagent ${event.agentId} (${event.agentType})`;
+  if (role === "implementer") {
+    // Only a host that isolates subagents in worktrees has already put it in one.
+    const where =
+      descriptor.subagents.worktreeIsolation === "native"
+        ? "working in its own git worktree: it may edit and commit there"
+        : "as an implementer: it edits and commits only in its own git worktree (the lead makes one with `workit fanout worktree create <slice>`), never in the lead's checkout";
+    return `Workit observed ${who} ${where}, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+  }
+  const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
+  if (role !== "judge" || !event.agentId) return readOnly;
+  const own = subagentSession(session, event.agentId);
+  return `${readOnly} Its own Workit session is ${own}: record verdicts with \`workit ledger verdict <result> --session ${own} ...\` so the ledger tells it apart from the author.`;
 };
 
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
@@ -71,17 +103,22 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         ? null
         : `Workit cannot gate file writes on ${descriptor.label} (no pre-write hook): before-write requirements (an open product choice, a missing plan) are advisory here, so settle them before editing.`;
       const addendum = [deps.addendum, advisory].filter(Boolean).join("\n") || null;
-      return {
-        kind: "context",
-        text: sessionContextText(input, descriptor, { offer, addendum }),
-      };
+      const text = sessionContextText(input, descriptor, { offer, addendum });
+      if (resendsOnChange(descriptor)) seedTurnContext(input, descriptor);
+      return { kind: "context", text };
     }
     case "context.turn": {
       if (!usable(descriptor.context.perTurn)) return NONE;
-      const text = turnContextText(input, descriptor);
-      return text ? { kind: "context", text } : NONE;
+      const current = turnContextText(input, descriptor);
+      const text = resendsOnChange(descriptor) ? changedTurnContext(input, current) : current;
+      return withContextLine(
+        text ? { kind: "context", text } : NONE,
+        promptNudge(input, event.prompt),
+      );
     }
     case "shell.pre": {
+      const skillRead = skillReadIn(event.command, event.dialect);
+      if (skillRead) recordSkillLoad(input, skillRead, "read");
       const canDeny = usable(descriptor.shellPolicy.deny);
       const policy = canDeny ? shellPolicy(input.cwd, event.command) : NONE;
       if (policy.kind !== "none") return policy;
@@ -102,7 +139,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
-      return raw;
+      return withContextLine(raw, shipNudge(input, event.command));
     }
     case "shell.post":
       if (usable(descriptor.events["shell.post"].support))
@@ -115,7 +152,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     case "subagent.start":
       return {
         kind: "context",
-        text: subagentStartText(input.host, input.session.id ?? null, descriptor, event),
+        text: subagentStartText(input.session.id ?? null, descriptor, event),
       };
     case "compact.pre":
       return {
@@ -123,9 +160,12 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         userMessage:
           "Workit context may be stale after compaction; re-run inspection or resume before acting.",
       };
-    // Host permission policy owns other tools; attestation, prompt and stop
-    // control arrive with the CLI-observed evidence model.
     case "tool.pre":
+      // Host permission policy owns other tools; a skill load is recorded.
+      if (event.skill) recordSkillLoad(input, event.skill, "tool");
+      return NONE;
+    // Attestation, prompt and stop control arrive with the CLI-observed
+    // evidence model.
     case "subagent.stop":
     case "prompt.submit":
     case "stop":

package/src/hooks/hosts/claude-code.ts

@@ -15,7 +15,7 @@ import {
   isWriteTool,
   nonEmpty,
   optionalText,
-  writePaths,
+  writeTargets,
 } from "./fields";
 
 type ClaudeHookEvent =
@@ -43,11 +43,14 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     "shell.post": { support: "native", native: "PostToolUse" },
     // SubagentStart output is additionalContext only: it cannot block or bind.
     "subagent.start": { support: "native", native: "SubagentStart" },
-    "subagent.stop": { support: "native", native: "SubagentStop" },
     "prompt.submit": { support: "native", native: "UserPromptSubmit" },
-    // PreCompact cannot inject context (only a systemMessage); restore runs on SessionStart source=compact.
-    "compact.pre": { support: "partial", native: "PreCompact" },
-    stop: { support: "native", native: "Stop" },
+    // Claude Code has SubagentStop, PreCompact and Stop, but the plugin
+    // registers none of them: events list what workit registers
+    // (docs/agents/hosts.md, Host parity). Compaction restore runs on
+    // SessionStart source=compact.
+    "subagent.stop": { support: "none", native: null },
+    "compact.pre": { support: "none", native: null },
+    stop: { support: "none", native: null },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {
@@ -55,6 +58,9 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     perTurn: "native",
     afterCompact: "native",
     task: "session-bound",
+    // The plugin's src/hook.ts dedups per-turn context itself (its own cache)
+    // until it moves onto the core's on-change resend.
+    turnResend: "every-turn",
   },
   subagents: {
     identity: "native",
@@ -62,6 +68,8 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     blockStart: "none",
     worktreeIsolation: "native",
     maxConcurrency: "undocumented",
+    // Plugin agents are namespaced: `workit:implementer`, never a bare `workit-implementer`.
+    agentPrefix: "workit:",
   },
   provenance: { sessionId: "native", agentIdOnTool: "native", postToolObserve: "native" },
   interaction: { questions: "undocumented", writeBoundary: "partial" },
@@ -79,13 +87,14 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     },
     {
       name: "native_subagents",
-      surface: "SubagentStart/SubagentStop",
-      refs: ["SubagentStart", "SubagentStop"],
-      requires: ["event:subagent.start", "event:subagent.stop"],
-      observed: ["subagent.start", "subagent.stop"],
+      // SubagentStop is not registered: identity and guidance come from SubagentStart.
+      surface: "SubagentStart",
+      refs: ["SubagentStart"],
+      requires: ["event:subagent.start"],
+      observed: ["subagent.start"],
       assurance: "agent_guided",
       reason: "Claude Code reports stable agent identities, but SubagentStart cannot block or bind",
-      unavailableReason: "Claude Code subagent lifecycle hooks are unavailable",
+      unavailableReason: "Claude Code SubagentStart is unavailable",
     },
     {
       name: "fresh-context-review",
@@ -148,7 +157,7 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
         ? { ok: true, event: { kind: "session.start", source: value.source as SessionSource } }
         : { ok: false, error: "SessionStart source is required" };
     case "UserPromptSubmit":
-      return { ok: true, event: { kind: "context.turn" } };
+      return { ok: true, event: { kind: "context.turn", prompt: optionalText(value.prompt) } };
     case "PreToolUse": {
       if (!nonEmpty(value.tool_name)) return { ok: false, error: "tool_name is required" };
       if (isWriteTool(value.tool_name))
@@ -157,8 +166,18 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
           event: {
             kind: "write.pre",
             tool: value.tool_name,
-            paths: writePaths(value.tool_input),
+            paths: writeTargets(value.tool_input),
+            toolUseId,
+          },
+        };
+      if (value.tool_name === "Skill")
+        return {
+          ok: true,
+          event: {
+            kind: "tool.pre",
+            tool: value.tool_name,
             toolUseId,
+            skill: isRecord(value.tool_input) ? optionalText(value.tool_input.skill) : null,
           },
         };
       if (!SHELL_TOOLS.has(value.tool_name))

package/src/hooks/hosts/codex.ts

@@ -1,16 +1,26 @@
 // Codex CLI and Desktop: command hooks (hooks/hooks.json) mapped onto the protocol.
 import type { HostDescriptor } from "../descriptor";
 import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
-import { commandText, existingDirectory, isRecord, nonEmpty, optionalText } from "./fields";
+import {
+  commandText,
+  existingDirectory,
+  isRecord,
+  isWriteTool,
+  nonEmpty,
+  optionalText,
+  writeTargets,
+} from "./fields";
 
 export type CodexHost = "codex_cli" | "codex_desktop";
 export type CodexHookEvent =
   | "SessionStart"
+  | "UserPromptSubmit"
   | "PreToolUse"
   | "PostToolUse"
   | "SubagentStart"
   | "SubagentStop";
-type SessionSource = "startup" | "resume" | "clear" | "compact";
+// The session-start.command.input schema in codex-cli 0.160.1 lists fork as a source.
+type SessionSource = "startup" | "resume" | "clear" | "compact" | "fork";
 
 export type CodexHookInput = {
   hook_event_name: CodexHookEvent;
@@ -21,6 +31,8 @@ export type CodexHookInput = {
   transcript_path: string | null;
   source?: SessionSource;
   turn_id?: string;
+  /** UserPromptSubmit: the prompt about to be sent. */
+  prompt?: string | null;
   tool_name?: string;
   tool_input?: unknown;
   /** The shell command as one string; argv arrays are joined. */
@@ -44,35 +56,43 @@ export function detectCodexSurface(env: NodeJS.ProcessEnv): CodexHost {
     : "codex_cli";
 }
 
-const undocumented = { support: "undocumented", native: null } as const;
-
 export const CODEX_DESCRIPTOR: HostDescriptor = {
   host: "codex_cli",
   label: "Codex",
-  verifiedAgainst: "codex-cli 0.153.4; Codex Desktop 26.901.20858",
+  // The hook JSON schemas embedded in the codex-cli 0.160.1 binary
+  // (pre-tool-use, user-prompt-submit, subagent-start .command.input/output)
+  // and the hooks page: "PreToolUse can intercept Bash, file edits performed
+  // through apply_patch, MCP tool calls…"; apply_patch arrives as tool_name
+  // "apply_patch" with the patch in tool_input.command (Edit and Write are
+  // matcher aliases only).
+  verifiedAgainst:
+    "codex-cli 0.160.1 (hook JSON schemas in the binary); Codex Desktop 26.901.20858",
   docs: ["https://developers.openai.com/codex/hooks"],
   transport: "hook-process",
   events: {
     "session.start": { support: "native", native: "SessionStart" },
-    "context.turn": undocumented,
+    "context.turn": { support: "native", native: "UserPromptSubmit" },
     "shell.pre": { support: "native", native: "PreToolUse" },
     "tool.pre": { support: "native", native: "PreToolUse" },
-    // Codex PreToolUse intercepts shell calls, not apply_patch edits: the
-    // before-write gate stays advisory rather than half-enforced.
-    "write.pre": { support: "undocumented", native: null },
+    // PreToolUse covers apply_patch; the files come from the patch body.
+    "write.pre": { support: "native", native: "PreToolUse" },
     "shell.post": { support: "native", native: "PostToolUse" },
     "subagent.start": { support: "native", native: "SubagentStart" },
     "subagent.stop": { support: "native", native: "SubagentStop" },
-    "prompt.submit": undocumented,
+    "prompt.submit": { support: "native", native: "UserPromptSubmit" },
+    // Codex has PreCompact and Stop, but workit registers neither yet: events
+    // list what workit registers (docs/agents/hosts.md, Host parity).
     "compact.pre": { support: "none", native: null },
-    stop: undocumented,
+    stop: { support: "none", native: null },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {
     sessionStart: "native",
-    perTurn: "undocumented",
+    perTurn: "native",
     afterCompact: "native",
     task: "single-active",
+    // UserPromptSubmit additionalContext stays in the thread as developer context.
+    turnResend: "on-change",
   },
   subagents: {
     identity: "native",
@@ -80,6 +100,7 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     blockStart: "none",
     worktreeIsolation: "undocumented",
     maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
   },
   provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "native" },
   interaction: { questions: "none", writeBoundary: "partial" },
@@ -152,6 +173,7 @@ export const codexDescriptor = (host: CodexHost): HostDescriptor => ({ ...CODEX_
 
 const EVENTS: Record<CodexHookEvent, HookEventKind> = {
   SessionStart: "session.start",
+  UserPromptSubmit: "context.turn",
   PreToolUse: "shell.pre",
   PostToolUse: "shell.post",
   SubagentStart: "subagent.start",
@@ -159,7 +181,7 @@ const EVENTS: Record<CodexHookEvent, HookEventKind> = {
 };
 const SHELL_TOOLS = new Set(["bash", "unified-exec"]);
 const isShellTool = (name: unknown) => SHELL_TOOLS.has(String(name).toLowerCase());
-const SOURCES = new Set<string>(["startup", "resume", "clear", "compact"]);
+const SOURCES = new Set<string>(["startup", "resume", "clear", "compact", "fork"]);
 
 /**
  * Read a Codex payload, checking only what each mapping needs (D17): the
@@ -195,6 +217,7 @@ export const parseCodexHookInput = (value: unknown): CodexParseResult => {
         ? { source: SOURCES.has(String(value.source)) ? (value.source as SessionSource) : "resume" }
         : {}),
       ...(nonEmpty(value.turn_id) ? { turn_id: value.turn_id } : {}),
+      ...(event === "UserPromptSubmit" ? { prompt: optionalText(value.prompt) } : {}),
       ...(nonEmpty(value.tool_name) ? { tool_name: value.tool_name } : {}),
       ...(toolEvent ? { tool_input: value.tool_input } : {}),
       ...(event === "PostToolUse" && typeof value.tool_response === "string"
@@ -219,15 +242,21 @@ const protocolEvent = (input: CodexHookInput): HookEvent => {
   switch (input.hook_event_name) {
     case "SessionStart":
       return { kind: "session.start", source: input.source! };
+    case "UserPromptSubmit":
+      return { kind: "context.turn", prompt: input.prompt ?? null };
     case "PreToolUse": {
       const toolUseId = input.tool_use_id ?? null;
-      return isShellTool(input.tool_name)
-        ? {
-            kind: "shell.pre",
-            command: input.command ?? "",
-            toolUseId,
-          }
-        : { kind: "tool.pre", tool: input.tool_name!, toolUseId };
+      if (isShellTool(input.tool_name))
+        return { kind: "shell.pre", command: input.command ?? "", toolUseId };
+      // apply_patch: the files are the patch body's `*** … File:` headers.
+      if (isWriteTool(input.tool_name))
+        return {
+          kind: "write.pre",
+          tool: input.tool_name!,
+          paths: writeTargets(input.tool_input),
+          toolUseId,
+        };
+      return { kind: "tool.pre", tool: input.tool_name!, toolUseId };
     }
     case "PostToolUse": {
       const toolUseId = input.tool_use_id ?? null;
@@ -313,5 +342,5 @@ export const codexAdapter: HostAdapter = {
   },
   render,
   addendum: (input) =>
-    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under a session the lead assigns (WORKIT_HOST=codex_cli WORKIT_SESSION_ID=<lead>-v<n>), never the author's. Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
+    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under its own session, never the author's: a workit-verifier or workit-reviewer agent uses the --session its SubagentStart context names; any other uses one the lead assigns (WORKIT_HOST=codex_cli WORKIT_SESSION_ID=<lead>-v<n>). Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
 };

package/src/hooks/hosts/cursor.ts

@@ -2,7 +2,7 @@
 import path from "node:path";
 import type { HostDescriptor } from "../descriptor";
 import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
-import { existingDirectory, isRecord, isWriteTool, nonEmpty, writePaths } from "./fields";
+import { existingDirectory, isRecord, isWriteTool, nonEmpty, writeTargets } from "./fields";
 
 export type CursorHookEvent =
   | "sessionStart"
@@ -53,7 +53,8 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     "prompt.submit": undocumented,
     // preCompact can only show a user message.
     "compact.pre": { support: "partial", native: "preCompact" },
-    stop: undocumented,
+    // Cursor has a stop hook (followup_message), but workit registers none yet.
+    stop: none,
   },
   shellPolicy: { deny: "native", channel: "exit2+json", failClosed: true },
   context: {
@@ -61,6 +62,7 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     perTurn: "none",
     afterCompact: "partial",
     task: "single-active",
+    turnResend: "every-turn",
   },
   subagents: {
     identity: "native",
@@ -68,6 +70,7 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     blockStart: "native",
     worktreeIsolation: "undocumented",
     maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
   },
   provenance: {
     sessionId: "native",
@@ -220,7 +223,7 @@ const protocolEvent = (input: CursorHookInput): HookEvent => {
         ? {
             kind: "write.pre",
             tool: input.tool_name ?? "",
-            paths: writePaths(input.tool_input),
+            paths: writeTargets(input.tool_input),
             toolUseId: null,
           }
         : { kind: "tool.pre", tool: input.tool_name ?? "", toolUseId: null };

package/src/hooks/hosts/fields.ts

@@ -78,13 +78,21 @@ export const isWriteTool = (name: unknown): boolean =>
   typeof name === "string" && WRITE_TOOLS.has(name.toLowerCase().replace(/[_-]/g, ""));
 
 const PATH_KEYS = ["file_path", "filePath", "notebook_path", "path", "target_file", "file"];
+/** apply_patch file headers. Codex trims patch lines, so an indented header still applies. */
+const PATCH_HEADER = /^[ \t]*\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$/gm;
+
 /** The files a write tool names: its path fields, or the files of an apply_patch body. */
 export const writePaths = (input: unknown): string[] => {
   if (!isRecord(input)) return [];
   const paths = PATH_KEYS.map((key) => input[key]).filter(nonEmpty);
   for (const value of Object.values(input))
     if (typeof value === "string")
-      for (const match of value.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm))
-        paths.push(match[1].trim());
+      for (const match of value.matchAll(PATCH_HEADER)) paths.push(match[1].trim());
   return [...new Set(paths)];
 };
+
+/** A write tool's targets for the before-write gate: null (unknown, so gated) when none parse. */
+export const writeTargets = (input: unknown): string[] | null => {
+  const paths = writePaths(input);
+  return paths.length > 0 ? paths : null;
+};

package/src/hooks/hosts/opencode.ts

@@ -19,7 +19,8 @@ export const OPENCODE_DESCRIPTOR: HostDescriptor = {
     "subagent.stop": { support: "native", native: 'tool.hook("execute.after") subagent' },
     "prompt.submit": { support: "undocumented", native: null },
     "compact.pre": { support: "native", native: 'session.hook("compaction")' },
-    stop: { support: "partial", native: "session.idle" },
+    // OpenCode reports session.idle, but the plugin registers no stop hook yet.
+    stop: { support: "none", native: null },
   },
   shellPolicy: { deny: "native", channel: "effect", failClosed: false },
   context: {
@@ -27,6 +28,8 @@ export const OPENCODE_DESCRIPTOR: HostDescriptor = {
     perTurn: "native",
     afterCompact: "native",
     task: "session-bound",
+    // The context hook rebuilds the system prompt on every agent-loop call.
+    turnResend: "every-turn",
   },
   subagents: {
     identity: "native",
@@ -34,6 +37,7 @@ export const OPENCODE_DESCRIPTOR: HostDescriptor = {
     blockStart: "native",
     worktreeIsolation: "undocumented",
     maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
   },
   provenance: { sessionId: "native", agentIdOnTool: "native", postToolObserve: "native" },
   interaction: { questions: "native", writeBoundary: "partial" },

package/src/hooks/hosts/pi.ts

@@ -24,9 +24,12 @@ export const PI_DESCRIPTOR: HostDescriptor = {
   shellPolicy: { deny: "native", channel: "block", failClosed: false },
   context: {
     sessionStart: "native",
-    perTurn: "native",
+    // before_agent_start runs every turn, but the extension injects the task
+    // context once per session and again after compaction, never on change.
+    perTurn: "partial",
     afterCompact: "native",
     task: "session-bound",
+    turnResend: "per-session",
   },
   subagents: {
     identity: "none",
@@ -34,6 +37,7 @@ export const PI_DESCRIPTOR: HostDescriptor = {
     blockStart: "none",
     worktreeIsolation: "none",
     maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
   },
   provenance: { sessionId: "native", agentIdOnTool: "none", postToolObserve: "native" },
   interaction: { questions: "native", writeBoundary: "native" },

package/src/hooks/index.ts

@@ -19,6 +19,7 @@ export {
 export { shellPolicy } from "./policy";
 export { shellWrites, writeGate } from "./write-gate";
 export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
+export { promptNudge, recordSkillLoad, shellNudge, skillFileIn } from "./skill-nudge";
 export { isWriteTool, writePaths } from "./hosts/fields";
 export { dispatchHook, failureDecision, handleHook, type HookDeps } from "./handle";
 export { HOOK_ADAPTERS, runHookProcess } from "./run";

package/src/hooks/protocol.ts

@@ -16,7 +16,11 @@ export type SessionSource = "startup" | "resume" | "clear" | "compact" | "fork";
 export type HookEvent =
   | { kind: "session.start"; source: SessionSource }
   /** Per-turn injection (OpenCode session context, Pi before_agent_start, Claude UserPromptSubmit). */
-  | { kind: "context.turn" }
+  | {
+      kind: "context.turn";
+      /** The submitted prompt, on hosts whose per-turn event carries it. */
+      prompt?: string | null;
+    }
   | {
       kind: "shell.pre";
       command: string;
@@ -25,9 +29,21 @@ export type HookEvent =
       dialect?: "posix" | "powershell";
     }
   /** A pre-tool gate for a non-shell tool. Host permission policy owns these. */
-  | { kind: "tool.pre"; tool: string; toolUseId: string | null }
+  | {
+      kind: "tool.pre";
+      tool: string;
+      toolUseId: string | null;
+      /** The skill a skill-loading tool loads (Claude Code's Skill tool). */
+      skill?: string | null;
+    }
   /** A file-writing tool (Edit, Write, apply_patch…): the before-write gate (S17). */
-  | { kind: "write.pre"; tool: string; paths: string[]; toolUseId: string | null }
+  | {
+      kind: "write.pre";
+      tool: string;
+      /** The files written; null when they cannot be read (unknown targets, gated). */
+      paths: string[] | null;
+      toolUseId: string | null;
+    }
   | {
       kind: "shell.post";
       command: string;

package/src/hooks/raw-git.ts

@@ -438,6 +438,19 @@ const actionsIn = (cwd: string, command: string, dialect: ShellDialect): Located
   return out;
 };
 
+/** Is `dir` in a repository Workit manages? */
+export const inWorkitWorkspace = (dir: string): boolean => {
+  const repo = repoAt(dir);
+  return repo !== null && isWorkitWorkspace(repo);
+};
+
+/** A raw push, PR/MR create or merge in a Workit workspace (help and dry runs excluded). */
+export const rawDelivery = (cwd: string, command: string, dialect: ShellDialect): boolean =>
+  mentionsRawTool(command) &&
+  actionsIn(cwd, command, dialect).some(
+    ({ action }) => action.kind !== "commit" && action.kind !== "pr-read",
+  );
+
 /** Cheap pre-filter: no git/gh/glab word, nothing to do. */
 const mentionsRawTool = (command: string) => /\b(?:git|gh|glab)\b/i.test(command);
 

package/src/hooks/skill-nudge.ts

@@ -0,0 +1,338 @@
+// Skill routing at the moment it matters. The session-start contract names a
+// trigger for each skill, but in a long or compacted session that table loses
+// weight and agents act without loading the skill. Three deterministic aids,
+// inside a Workit workspace only:
+//   - a prompt that asks for a skill's work in so many words gets one
+//     advisory line naming the skill;
+//   - a delivery command (push, PR create or merge, CI wait) gets one line
+//     naming workit-ship;
+//   - each skill load is recorded as a `skill.loaded` ledger row, so a nudge
+//     stops once the skill is loaded and workit-retro can count skill use.
+// A session is nudged about one skill at most once (a marker per session
+// in the workspace store), never in a subagent, never once it loaded the skill.
+// Every failure answers "no nudge": hooks fail open.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  skillLoadWording,
+  WORKIT_METHOD_SKILLS,
+  WORKIT_SKILL_ALIASES,
+  type SkillHost,
+  type WorkitSkill,
+} from "../core/skill-manifests";
+import { appendHookObserved, readLedger } from "../ledger";
+import { resolveStore } from "../store/paths";
+import type { HookDecision, HookInput, HostId } from "./protocol";
+import { inWorkitWorkspace, rawDelivery, rawGitPre } from "./raw-git";
+import { segmentsOf, type ShellDialect } from "./shell-words";
+
+/** Skills the user starts; a nudge says to offer them, never to load them. */
+const USER_INVOKED: ReadonlySet<WorkitSkill> = new Set(["workit-retro", "workit-architecture"]);
+
+const SKILL_HOST: Record<HostId, SkillHost> = {
+  claude_code: "claude-code",
+  opencode: "opencode",
+  codex_cli: "codex",
+  codex_desktop: "codex",
+  cursor: "cursor",
+  pi: "pi",
+};
+
+/**
+ * Prompt phrasings that ask for a skill's work. The contract's single-word
+ * triggers (plan, build, merge, CI) are for the model's judgment; a hook
+ * cannot tell "plan the cache" from "what's in the plan?", so it matches
+ * phrases only. Ordered by precedence: a broken thing is debug work before
+ * it is a feature or a plan.
+ */
+const PROMPT_INTENTS: ReadonlyArray<readonly [WorkitSkill, RegExp]> = [
+  [
+    "workit-debug",
+    /\b(flaky|regressed|(?:is|introduced) a regression|regression (?:in|after|since|from)|(?:is|are|got|looks) broken|debug (?:this|it|the|why)|fix (?:the|this|a) bug)\b/i,
+  ],
+  [
+    "workit-continue",
+    /\b(pick up where|where (?:were|did) we|resume (?:the|this|my|our|work|where)|hand ?off)\b/i,
+  ],
+  [
+    "workit-review",
+    /\b(blast radius|code review|review (?:the|this|my|PR|pr|#\d+|branch|diff|changes))\b/i,
+  ],
+  [
+    "workit-ship",
+    /\b(ship (?:it|this|the)|babysit|open (?:a|the) (?:PR|pr|MR|mr)(?=\s*$|\s+(?:for|to|on|with|and|against|into|from|after|once)\b|[.!,;])|merge (?:the|this|my) (?:PR|pr|MR|mr|branch)|(?:get|until|make) CI (?:is )?green)\b/i,
+  ],
+  ["workit-bdd", /\b(BDD|TDD|acceptance criteria|Given\/When\/Then)(?![\w/])/],
+  ["workit-test-audit", /\b(test audit|audit the tests|tautolog\w*|weak tests)\b/i],
+  ["workit-deslop", /\b(deslop|slop|dead code)\b/i],
+  [
+    "workit-fanout",
+    /\b(fan(?: |-)?out|parallelize|parallel agents|agent swarm|swarm of agents)\b/i,
+  ],
+  ["workit-verify-app", /\b(verify the app|smoke test|prove it works)\b/i],
+  ["workit-retro", /\b((?:a|the) retro(?![-\w]|\.\w)|retrospective)/i],
+  ["workit-architecture", /\b(deepen (?:the )?modules|architecture (?:review|pass|audit))\b/i],
+  [
+    "workit-shape",
+    /\b(brainstorm\w*|grill me|should we|let'?s plan|plan (?:out|how|the|a|for)|(?:write|draft) (?:a|the) spec)\b/i,
+  ],
+  [
+    "workit-implement",
+    /\b(implement (?:the|this|a|it)|add (?:a|the) feature|build (?:a|an|the) (?:new )?(?:feature|command|verb|page|endpoint|component|cli|tool))\b/i,
+  ],
+];
+
+/** The workit skill a loaded name refers to (`workit:shape`, `workit-shape`, `wk-shape`). */
+export const workitSkillOf = (name: string): WorkitSkill | null => {
+  const bare = name.trim().replace(/^\//, "").toLowerCase();
+  const alias = (WORKIT_SKILL_ALIASES as Record<string, WorkitSkill>)[bare];
+  if (alias) return alias;
+  const skill = bare.replace(/^workit:/, "workit-");
+  return (WORKIT_METHOD_SKILLS as readonly string[]).includes(skill)
+    ? (skill as WorkitSkill)
+    : null;
+};
+
+/** The skill a prompt asks for, by precedence, with the phrase that did. */
+export const promptTrigger = (prompt: string): { skill: WorkitSkill; trigger: string } | null => {
+  // Code blocks and quoted output carry words the user did not ask with.
+  const text = prompt.replace(/```[\s\S]*?```/g, " ").slice(0, 4000);
+  for (const [skill, pattern] of PROMPT_INTENTS) {
+    const match = pattern.exec(text);
+    if (match) return { skill, trigger: match[1] ?? match[0] };
+  }
+  return null;
+};
+
+/** Per-session nudge state: skills nudged or loaded, so each nudges once. */
+type Marker = { nudged: string[]; loaded: string[] };
+
+/** The marker in the workspace's store (null outside one: nothing is nudged or recorded there). */
+const markerFile = (input: HookInput, session: string): string | null => {
+  const location = resolveStore(input.cwd);
+  if (location instanceof Error || !location.shared) return null;
+  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
+  return path.join(location.dir, "hooks", `skills-${name}.json`);
+};
+
+const readMarker = (file: string): Marker => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Marker>;
+    return { nudged: value.nudged ?? [], loaded: value.loaded ?? [] };
+  } catch {
+    return { nudged: [], loaded: [] };
+  }
+};
+
+const writeMarker = (file: string, marker: Marker): void => {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(marker));
+  } catch {
+    // Fail open: without a marker a later nudge repeats.
+  }
+};
+
+/** Skills this session already loaded, from its `skill.loaded` rows. */
+const loadedSkills = (cwd: string, session: string): Set<string> => {
+  const ledger = readLedger(cwd);
+  const loaded = new Set<string>();
+  if (!ledger.ok) return loaded;
+  for (const row of ledger.value.rows)
+    if (
+      row.type === "skill.loaded" &&
+      row.actor.session === session &&
+      typeof row.skill === "string"
+    )
+      loaded.add(row.skill);
+  return loaded;
+};
+
+const SKILL_FILE = /(?:^|[\\/])(workit-[a-z-]+)[\\/]SKILL\.md$/;
+
+/** The workit skill whose SKILL.md a path names (Pi's read tool). */
+export const skillFileIn = (file: string): string | null => SKILL_FILE.exec(file)?.[1] ?? null;
+
+/** Commands that read a file for the agent: a shell-loaded skill is one of these on its SKILL.md. */
+const READERS = new Set([
+  "cat",
+  "sed",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "bat",
+  "nl",
+  "get-content",
+  "gc",
+  "type",
+]);
+
+/** The workit skill whose SKILL.md a shell command reads (Codex, Cursor); never git, grep or an editor. */
+export const skillReadIn = (command: string, dialect: ShellDialect = "posix"): string | null => {
+  for (const { words } of segmentsOf(command, dialect)) {
+    if (!READERS.has((words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase())) continue;
+    // `sed -i` edits the file; it does not load it.
+    if (words.some((word) => /^(?:-i(?:\.\w+)?|--in-place(?:=.*)?)$/.test(word))) continue;
+    for (const word of words.slice(1)) {
+      const skill = skillFileIn(word);
+      if (skill) return skill;
+    }
+  }
+  return null;
+};
+
+/** Record that the session loaded a workit skill (`via`: the tool, a slash command, a file read). */
+export function recordSkillLoad(
+  input: HookInput,
+  name: string,
+  via: "tool" | "slash" | "read",
+): void {
+  try {
+    const skill = workitSkillOf(name);
+    const session = input.session.id;
+    if (!skill || !session) return;
+    if (!inWorkitWorkspace(input.cwd)) return;
+    const file = markerFile(input, session);
+    if (!file) return;
+    const marker = readMarker(file);
+    if (marker.loaded.includes(skill)) return;
+    writeMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
+    if (loadedSkills(input.cwd, session).has(skill)) return;
+    appendHookObserved(input.cwd, {
+      type: "skill.loaded",
+      actor: { host: input.host, session, agentId: input.session.agentId },
+      skill,
+      via,
+    });
+  } catch {
+    // Fail open: a lost row only means a later nudge or a retro miscount.
+  }
+}
+
+/** The nudge for `skill` once per session: null when it was nudged or loaded. */
+const nudgeOnce = (
+  input: HookInput,
+  session: string,
+  skill: WorkitSkill,
+  line: string,
+): string | null => {
+  const file = markerFile(input, session);
+  if (!file) return null;
+  const marker = readMarker(file);
+  if (marker.nudged.includes(skill) || marker.loaded.includes(skill)) return null;
+  if (loadedSkills(input.cwd, session).has(skill)) return null;
+  writeMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
+  return line;
+};
+
+const nudgeText = (input: HookInput, skill: WorkitSkill, why: string): string =>
+  USER_INVOKED.has(skill)
+    ? `Workit: ${why} looks like ${skill} work, which the user starts; offer it (/${skill.replace(/^workit-/, "wk-")}) rather than loading it.`
+    : `Workit: ${why} looks like ${skill} work; if it is, ${skillLoadWording(SKILL_HOST[input.host], skill)} first.`;
+
+/** A skill the prompt already loads: `/wk-shape`, `/workit:shape`, Pi's expanded
+ * `/skill:` block, or OpenCode's rewritten `/wk-*` command. */
+const promptLoads = (prompt: string): string | null =>
+  /^\s*\/(?:skill:)?([\w:-]+)/.exec(prompt)?.[1] ??
+  /^\s*<skill name="([\w:-]+)"/.exec(prompt)?.[1] ??
+  /^\s*Load the (workit-[a-z-]+) skill with the skill tool\b/.exec(prompt)?.[1] ??
+  null;
+
+/** A main session's prompt in a Workit workspace: one advisory line naming the skill it asks for. */
+export function promptNudge(input: HookInput, prompt: string | null | undefined): string | null {
+  try {
+    const session = input.session.id;
+    if (!prompt || !session || input.session.agentId) return null;
+    const loads = promptLoads(prompt);
+    if (loads) {
+      // The prompt already loads its skill; record it, never nudge.
+      recordSkillLoad(input, loads, "slash");
+      return null;
+    }
+    const hit = promptTrigger(prompt);
+    if (!hit || !inWorkitWorkspace(input.cwd)) return null;
+    return nudgeOnce(
+      input,
+      session,
+      hit.skill,
+      nudgeText(input, hit.skill, `this request ("${hit.trigger}")`),
+    );
+  } catch {
+    return null;
+  }
+}
+
+const WORKIT_DELIVERY = /^(?:pr (?:create|merge)|ci wait|git push)\b/;
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const LAUNCHERS = new Set([
+  "npx",
+  "bunx",
+  "pnpx",
+  "-y",
+  "--yes",
+  "pnpm",
+  "dlx",
+  "exec",
+  "env",
+  "sudo",
+  "command",
+]);
+
+/** Does a segment list run a workit delivery verb (also inside `bash -c '…'`)? */
+const runsWorkitDelivery = (command: string, dialect: ShellDialect, depth = 0): boolean =>
+  segmentsOf(command, dialect).some(({ words }) => {
+    // The command word, past env assignments and package runners (`npx -y`).
+    const at = words.findIndex((word) => !/^\w+=/.test(word) && !LAUNCHERS.has(word));
+    if (at >= 0 && /(?:^|[\\/])workit(?:\.exe)?$|^@brainervirus\/workit-cli$/.test(words[at])) {
+      const args = words.slice(at + 1);
+      if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run")) return false;
+      return WORKIT_DELIVERY.test(args.join(" "));
+    }
+    const shell = SHELLS.has(words[at]?.split(/[\\/]/).at(-1) ?? "");
+    const script = shell && words[at + 1] === "-c" ? words[at + 2] : undefined;
+    return depth < 3 && script !== undefined && runsWorkitDelivery(script, "posix", depth + 1);
+  });
+
+/**
+ * Does the command deliver in a Workit workspace: a push, a PR/MR create or
+ * merge, or a CI wait (never help or a dry run)?
+ */
+export const isDeliveryCommand = (
+  cwd: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+): boolean =>
+  rawDelivery(cwd, command, dialect) ||
+  (runsWorkitDelivery(command, dialect) && inWorkitWorkspace(cwd));
+
+/** A delivery command in a main session that has not loaded workit-ship. */
+export function shipNudge(input: HookInput, command: string): string | null {
+  try {
+    const session = input.session.id;
+    if (!session || input.session.agentId) return null;
+    const dialect = input.event.kind === "shell.pre" ? (input.event.dialect ?? "posix") : "posix";
+    if (!isDeliveryCommand(input.cwd, command, dialect)) return null;
+    return nudgeOnce(
+      input,
+      session,
+      "workit-ship",
+      nudgeText(input, "workit-ship", "this delivery step"),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** `decision` with `line` added: a context grows by a line, `none` becomes one. */
+export const withContextLine = (decision: HookDecision, line: string | null): HookDecision => {
+  if (!line) return decision;
+  if (decision.kind === "none") return { kind: "context", text: line };
+  if (decision.kind === "context") return { kind: "context", text: `${decision.text}\n${line}` };
+  return decision;
+};
+
+/** Hosts whose shell nudge rides on the tool result: the raw-git nudge plus the ship line. */
+export const shellNudge = (input: HookInput, command: string): HookDecision =>
+  withContextLine(rawGitPre(input, command), shipNudge(input, command));

package/src/hooks/write-gate.ts

@@ -207,13 +207,15 @@ const gateFor = (cwd: string): Gate | null => {
 /**
  * Deny a working-tree edit while the branch task has unmet before-write
  * requirements. `paths` are the files the tool writes, or null when unknown
- * (shell); an edit touching only exempt files is always allowed.
+ * (a shell write, a patch whose headers cannot be read); unknown or empty
+ * targets are gated, and an edit touching only exempt files is always allowed.
  */
 export function writeGate(cwd: string, paths: readonly string[] | null): HookDecision {
   try {
     const gate = gateFor(cwd);
     if (!gate || gate.blockers.length === 0) return NONE;
-    if (paths && paths.every((file) => exempt(cwd, gate.root, file, gate.plans))) return NONE;
+    if (paths?.length && paths.every((file) => exempt(cwd, gate.root, file, gate.plans)))
+      return NONE;
     const reasons = gate.blockers.map((item) => `${item.ruleId}: ${item.reason}`).join("; ");
     return {
       kind: "deny",

package/src/ledger.ts

@@ -1784,6 +1784,9 @@ export function summarizeRow(row: ReadRow): RowSummary {
     case "standing.cleared":
       summary = `cleared ${text("target") || "every standing order"} (fanout ${text("fanout")})`;
       break;
+    case "skill.loaded":
+      summary = `${text("skill")} (${text("via") || "tool"})${row.actor.session ? "" : " (no session)"}`;
+      break;
     case "commit.recorded":
       summary = `${(row.head ?? "?").slice(0, 12)} ${text("subject")}${row.actor.session ? "" : " (no session)"}`;
       break;