@brainervirus/workit-core 8.7.0 → 8.9.0

package/src/hooks/handle.ts

@@ -22,6 +22,7 @@ import {
   skillReadIn,
   withContextLine,
 } from "./skill-nudge";
+import { stopDecision } from "./stop";
 import { shellWrites, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
@@ -67,21 +68,35 @@ const subagentSession = (session: string | null, agentId: string): string =>
     .replace(/[^A-Za-z0-9_.:@/+-]/g, "-")
     .slice(0, 128);
 
+/** A Claude Code worktree path: `<repo>/.claude/worktrees/<name>`. */
+const CLAUDE_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]/;
+
+/**
+ * Claude Code's worktree isolation refuses any command that wraps git
+ * (`workit git …` included) and cannot be turned off, so an isolated agent
+ * runs git itself and workit for everything else.
+ */
+const ISOLATED_GIT =
+  'Run git as plain, separate commands inside your worktree (`git switch -c <branch> <base>`, `git commit --trailer "Workit-Session=<your session>"`, `git push`; `workit doctor --fix` can install a commit-msg hook that adds the trailer), never `workit git …`: Claude Code\'s worktree isolation refuses a command that wraps git and cannot be turned off (https://code.claude.com/docs/en/worktrees#how-claude-code-enforces-isolation). Never dodge that check by renaming or re-wrapping git. Use workit for the non-git verbs (`workit check`, `workit ledger`, `workit pr`).';
+
 const subagentStartText = (
-  session: string | null,
+  input: HookInput,
   descriptor: HostDescriptor,
   event: Extract<HookInput["event"], { kind: "subagent.start" }>,
 ): string => {
+  const session = input.session.id ?? null;
   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 isolated =
+    descriptor.subagents.worktreeIsolation === "native" &&
+    (role === "implementer" || CLAUDE_WORKTREE.test(input.cwd));
+  if (role === "implementer" && isolated)
+    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${ISOLATED_GIT} Use a policy-compliant branch (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.`;
+  if (isolated)
+    return `${ISOLATED_GIT}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
+  if (role === "implementer")
+    // No host isolation: the lead makes the worktree, and workit git works there.
+    return `Workit observed ${who} 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, 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);
@@ -125,7 +140,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       // Without a post-tool event, the previous raw commit is recorded now.
       const postTool = usable(descriptor.events["shell.post"].support);
       if (!postTool) settlePendingCommit(input);
-      const raw = canDeny ? rawGitPre(input, event.command) : NONE;
+      const raw = canDeny ? rawGitPre(input, event.command, { nudge: false }) : NONE;
       if (raw.kind === "deny") return raw;
       const writes = usable(descriptor.events["write.pre"].support)
         ? shellWrites(event.command)
@@ -139,7 +154,13 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
-      return withContextLine(raw, shipNudge(input, event.command));
+      // An in-process plugin shows nudges on the tool result (shellNudge):
+      // spending the once-per-session nudge here would lose it.
+      if (descriptor.transport !== "hook-process") return NONE;
+      return withContextLine(
+        canDeny ? rawGitPre(input, event.command) : NONE,
+        shipNudge(input, event.command),
+      );
     }
     case "shell.post":
       if (usable(descriptor.events["shell.post"].support))
@@ -152,7 +173,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     case "subagent.start":
       return {
         kind: "context",
-        text: subagentStartText(input.session.id ?? null, descriptor, event),
+        text: subagentStartText(input, descriptor, event),
       };
     case "compact.pre":
       return {
@@ -164,11 +185,12 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       // 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 "stop":
+      return usable(descriptor.events.stop.support) ? stopDecision(input, descriptor) : NONE;
+    // A subagent's stop is never blocked; attestation and prompt control
+    // arrive with the CLI-observed evidence model.
     case "subagent.stop":
     case "prompt.submit":
-    case "stop":
       return NONE;
   }
 }

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

@@ -44,13 +44,15 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     // SubagentStart output is additionalContext only: it cannot block or bind.
     "subagent.start": { support: "native", native: "SubagentStart" },
     "prompt.submit": { support: "native", native: "UserPromptSubmit" },
-    // 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
+    // Claude Code has SubagentStop and PreCompact, but the plugin registers
+    // neither: events list what workit registers (docs/agents/hosts.md, Host
+    // parity). A subagent's stop is never blocked; compaction restore runs on
     // SessionStart source=compact.
     "subagent.stop": { support: "none", native: null },
     "compact.pre": { support: "none", native: null },
-    stop: { support: "none", native: null },
+    // `{"decision":"block","reason"}` continues the turn; the input carries
+    // `stop_hook_active` and `last_assistant_message` (claude 2.1.295).
+    stop: { support: "native", native: "Stop" },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {

package/src/hooks/hosts/codex.ts

@@ -18,7 +18,8 @@ export type CodexHookEvent =
   | "PreToolUse"
   | "PostToolUse"
   | "SubagentStart"
-  | "SubagentStop";
+  | "SubagentStop"
+  | "Stop";
 // The session-start.command.input schema in codex-cli 0.160.1 lists fork as a source.
 type SessionSource = "startup" | "resume" | "clear" | "compact" | "fork";
 
@@ -80,10 +81,12 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     "subagent.start": { support: "native", native: "SubagentStart" },
     "subagent.stop": { support: "native", native: "SubagentStop" },
     "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).
+    // Codex has PreCompact, but workit does not register it: events list what
+    // workit registers (docs/agents/hosts.md, Host parity).
     "compact.pre": { support: "none", native: null },
-    stop: { support: "none", native: null },
+    // stop.command.input (codex-cli 0.160.1): stop_hook_active,
+    // last_assistant_message, turn_id; output `{"decision":"block","reason"}`.
+    stop: { support: "native", native: "Stop" },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {
@@ -104,7 +107,7 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
   },
   provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "native" },
   interaction: { questions: "none", writeBoundary: "partial" },
-  stopControl: "undocumented",
+  stopControl: "native",
   shellAvailable: "native",
   perEventCost: "low",
   capabilities: [
@@ -178,6 +181,7 @@ const EVENTS: Record<CodexHookEvent, HookEventKind> = {
   PostToolUse: "shell.post",
   SubagentStart: "subagent.start",
   SubagentStop: "subagent.stop",
+  Stop: "stop",
 };
 const SHELL_TOOLS = new Set(["bash", "unified-exec"]);
 const isShellTool = (name: unknown) => SHELL_TOOLS.has(String(name).toLowerCase());
@@ -227,6 +231,12 @@ export const parseCodexHookInput = (value: unknown): CodexParseResult => {
       ...(nonEmpty(value.tool_use_id) ? { tool_use_id: value.tool_use_id } : {}),
       ...(nonEmpty(value.agent_id) ? { agent_id: value.agent_id } : {}),
       ...(nonEmpty(value.agent_type) ? { agent_type: value.agent_type } : {}),
+      ...(event === "Stop"
+        ? {
+            last_assistant_message: optionalText(value.last_assistant_message),
+            stop_hook_active: value.stop_hook_active === true,
+          }
+        : {}),
       ...(event === "SubagentStop"
         ? {
             agent_transcript_path: optionalText(value.agent_transcript_path),
@@ -287,6 +297,12 @@ const protocolEvent = (input: CodexHookInput): HookEvent => {
         lastMessage: input.last_assistant_message ?? null,
         stopHookActive: input.stop_hook_active ?? false,
       };
+    case "Stop":
+      return {
+        kind: "stop",
+        lastMessage: input.last_assistant_message ?? null,
+        stopHookActive: input.stop_hook_active ?? false,
+      };
   }
 };
 
@@ -295,7 +311,11 @@ const output = (event: string, extra: Record<string, unknown> = {}) => ({
 });
 
 const render = (decision: HookDecision, native: string | null) => {
-  if (native === "SubagentStop" || native === null) return { json: {}, exitCode: 0 };
+  // stop.command.output takes no hookSpecificOutput: a block with a reason continues.
+  if (native === "Stop" && decision.kind === "continue")
+    return { json: { decision: "block", reason: decision.reason }, exitCode: 0 };
+  if (native === "SubagentStop" || native === "Stop" || native === null)
+    return { json: {}, exitCode: 0 };
   if (decision.kind === "deny")
     return {
       json: output(native, {

package/src/hooks/hosts/cursor.ts

@@ -1,4 +1,5 @@
 // Cursor: command hooks (hooks/hooks-cursor.json) mapped onto the protocol.
+import fs from "node:fs";
 import path from "node:path";
 import type { HostDescriptor } from "../descriptor";
 import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
@@ -10,7 +11,8 @@ export type CursorHookEvent =
   | "beforeShellExecution"
   | "subagentStart"
   | "subagentStop"
-  | "preCompact";
+  | "preCompact"
+  | "stop";
 
 export type CursorHookInput = {
   hook_event_name: CursorHookEvent;
@@ -26,6 +28,8 @@ export type CursorHookInput = {
   parent_conversation_id?: string;
   task?: string;
   status?: "completed" | "error" | "aborted";
+  loop_count?: number;
+  transcript_path?: string;
 };
 
 export type CursorParseResult = { ok: true; data: CursorHookInput } | { ok: false; error: string };
@@ -53,8 +57,11 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     "prompt.submit": undocumented,
     // preCompact can only show a user message.
     "compact.pre": { support: "partial", native: "preCompact" },
-    // Cursor has a stop hook (followup_message), but workit registers none yet.
-    stop: none,
+    // stop (cursor-agent 2026.09.26): `{"followup_message"}` queues one more
+    // user turn; the input carries loop_count and transcript_path, not the
+    // last message (read from transcript_path). Registered with
+    // `loop_limit: 1`, so the continuation's own stop never runs the hook.
+    stop: { support: "native", native: "stop" },
   },
   shellPolicy: { deny: "native", channel: "exit2+json", failClosed: true },
   context: {
@@ -78,7 +85,7 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     postToolObserve: "undocumented",
   },
   interaction: { questions: "none", writeBoundary: "partial" },
-  stopControl: "undocumented",
+  stopControl: "native",
   shellAvailable: "native",
   // Hooks run the plugin's launcher against a local runtime (bundled dist or a
   // global bin); only an install with neither falls back to a pinned,
@@ -155,6 +162,7 @@ const EVENTS: Record<CursorHookEvent, HookEventKind> = {
   subagentStart: "subagent.start",
   subagentStop: "subagent.stop",
   preCompact: "compact.pre",
+  stop: "stop",
 };
 
 /** Validate the keys each Cursor event needs; unknown keys are ignored. */
@@ -205,6 +213,15 @@ export const parseCursorHookInput = (value: unknown): CursorParseResult => {
         ? { parent_conversation_id: value.parent_conversation_id }
         : {}),
       ...(event === "subagentStart" && nonEmpty(value.task) ? { task: value.task } : {}),
+      ...(event === "stop"
+        ? {
+            ...(nonEmpty(value.status)
+              ? { status: value.status as CursorHookInput["status"] }
+              : {}),
+            ...(typeof value.loop_count === "number" ? { loop_count: value.loop_count } : {}),
+            ...(nonEmpty(value.transcript_path) ? { transcript_path: value.transcript_path } : {}),
+          }
+        : {}),
     },
   };
 };
@@ -244,6 +261,61 @@ const protocolEvent = (input: CursorHookInput): HookEvent => {
       };
     case "preCompact":
       return { kind: "compact.pre", trigger: "auto" };
+    case "stop":
+      return {
+        kind: "stop",
+        // Only a completed turn is continued; an aborted or failed one stops.
+        lastMessage:
+          (input.status ?? "completed") === "completed"
+            ? lastAssistantText(input.transcript_path)
+            : null,
+        // A followup_message turn reports loop_count > 0: one continue per turn.
+        stopHookActive: (input.loop_count ?? 0) > 0,
+      };
+  }
+};
+
+/** The transcript tail read for the last assistant message. */
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+/**
+ * The text of the last assistant entry in a Cursor agent transcript
+ * (`{"role":"assistant","message":{"content":[{"type":"text","text":…}]}}`
+ * per line), or null when it cannot be read.
+ */
+export const lastAssistantText = (file: string | null | undefined): string | null => {
+  if (!file || !path.isAbsolute(file)) return null;
+  try {
+    const size = fs.statSync(file).size;
+    const start = Math.max(0, size - TRANSCRIPT_TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    const fd = fs.openSync(file, "r");
+    try {
+      fs.readSync(fd, buffer, 0, buffer.length, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const lines = buffer.toString("utf8").split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+      let entry: unknown;
+      try {
+        entry = JSON.parse(lines[index]);
+      } catch {
+        continue;
+      }
+      if (!isRecord(entry) || entry.role !== "assistant") continue;
+      const content = isRecord(entry.message) ? entry.message.content : entry.content;
+      if (typeof content === "string") return content;
+      if (!Array.isArray(content)) return null;
+      const text = content
+        .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
+        .map((part) => (part as { text: string }).text)
+        .join("\n");
+      return text || null;
+    }
+    return null;
+  } catch {
+    return null;
   }
 };
 
@@ -291,6 +363,8 @@ const render = (decision: HookDecision, native: string | null) => {
     return { json: { additional_context: decision.text }, exitCode: 0 };
   if (decision.kind === "notice")
     return { json: { user_message: decision.userMessage }, exitCode: 0 };
+  if (decision.kind === "continue" && native === "stop")
+    return { json: { followup_message: decision.reason }, exitCode: 0 };
   return {
     json: native !== null && BLOCKING.has(native) ? { permission: "allow" } : {},
     exitCode: 0,

package/src/hooks/hosts/opencode.ts

@@ -19,8 +19,11 @@ 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")' },
-    // OpenCode reports session.idle, but the plugin registers no stop hook yet.
-    stop: { support: "none", native: null },
+    // No stop hook: the plugin's event subscription sees session.idle and
+    // resumes the session with `ctx.session.synthetic({resume: true})`
+    // (@opencode/client 2.0.18). Partial: the continuation lands after the
+    // session went idle, and resume semantics are inferred from the schema.
+    stop: { support: "partial", native: 'event("session.idle")' },
   },
   shellPolicy: { deny: "native", channel: "effect", failClosed: false },
   context: {

package/src/hooks/hosts/pi.ts

@@ -19,7 +19,10 @@ export const PI_DESCRIPTOR: HostDescriptor = {
     "subagent.stop": { support: "none", native: null },
     "prompt.submit": { support: "undocumented", native: null },
     "compact.pre": { support: "native", native: "session_before_compact" },
-    stop: { support: "none", native: null },
+    // agent_end carries the run's messages; pi.sendMessage(…, {triggerTurn})
+    // starts one more turn (pi-coding-agent 0.85.1 types.d.ts). The host has
+    // no loop guard: the extension continues at most once per run.
+    stop: { support: "native", native: "agent_end" },
   },
   shellPolicy: { deny: "native", channel: "block", failClosed: false },
   context: {
@@ -41,7 +44,7 @@ export const PI_DESCRIPTOR: HostDescriptor = {
   },
   provenance: { sessionId: "native", agentIdOnTool: "none", postToolObserve: "native" },
   interaction: { questions: "native", writeBoundary: "native" },
-  stopControl: "none",
+  stopControl: "native",
   shellAvailable: "native",
   perEventCost: "low",
   capabilities: [

package/src/hooks/index.ts

@@ -20,6 +20,7 @@ export {
 } from "./context";
 export { shellPolicy } from "./policy";
 export { shellWrites, writeGate } from "./write-gate";
+export { asksUser, stopDecision, stopObligation, type StopObligation } from "./stop";
 export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
 export { promptNudge, recordSkillLoad, shellNudge, skillFileIn } from "./skill-nudge";
 export { isWriteTool, writePaths } from "./hosts/fields";

package/src/hooks/raw-git.ts

@@ -6,7 +6,8 @@
 //     remote onto a protected branch or the default target, naming the
 //     workit command;
 //   - lets routine raw commands run (`git commit`, a feature-branch push,
-//     `gh pr create|view|checks`, `glab mr create|view`) with a short nudge.
+//     `gh pr create|view|checks`, `glab mr create|view`) with a short nudge,
+//     once per kind per session, and none on a command that runs workit.
 // A raw `git commit` is recorded as the session's `commit.recorded` row so
 // the author's own verdict never reads as independent. The pre-tool hook
 // notes HEAD before the command (a marker in the commit's own repository);
@@ -29,6 +30,7 @@ import { pushRemoteName } from "../git/rev";
 import { appendHookObserved, readLedger } from "../ledger";
 import { resolveStore, resolveTaskKey, type StoreLocation } from "../store/paths";
 import type { HookDecision, HookInput } from "./protocol";
+import { readSessionMarker, sessionMarkerFile, writeSessionMarker } from "./session-marker";
 import { segmentsOf, type ShellDialect } from "./shell-words";
 
 const NONE: HookDecision = { kind: "none" };
@@ -176,6 +178,47 @@ export function rawInvocations(
   return found;
 }
 
+const LAUNCHERS = new Set([
+  "npx",
+  "bunx",
+  "pnpx",
+  "-y",
+  "--yes",
+  "pnpm",
+  "dlx",
+  "exec",
+  "env",
+  "sudo",
+  "command",
+]);
+const WORKIT_BIN = /(?:^|[\\/])workit(?:\.exe)?$|^@brainervirus\/workit-cli$/;
+
+/**
+ * The arguments of every workit CLI invocation in a shell command: past env
+ * assignments and package runners (`npx -y @brainervirus/workit-cli …`), and
+ * inside `bash -c '…'` scripts.
+ */
+export function workitInvocations(
+  command: string,
+  dialect: ShellDialect = "posix",
+  depth = 0,
+): string[][] {
+  const found: string[][] = [];
+  for (const { words } of segmentsOf(command, dialect)) {
+    const at = words.findIndex((word) => !/^\w+=/.test(word) && !LAUNCHERS.has(word));
+    if (at < 0) continue;
+    if (WORKIT_BIN.test(words[at])) {
+      found.push(words.slice(at + 1));
+      continue;
+    }
+    const shell = SHELLS.has(commandName(words[at]));
+    const script = shell && words[at + 1] === "-c" ? words[at + 2] : undefined;
+    if (depth < 3 && script !== undefined)
+      found.push(...workitInvocations(script, "posix", depth + 1));
+  }
+  return found;
+}
+
 /** What one raw invocation means for workit. */
 export type RawAction =
   | { kind: "commit"; amend: boolean }
@@ -336,7 +379,7 @@ const isWorkitWorkspace = (repo: Repo): boolean => {
 };
 
 /** Protected by the branch policy, or the workspace's default target. */
-const guardedBranch = (dir: string, branch: string): boolean => {
+export const guardedBranch = (dir: string, branch: string): boolean => {
   try {
     const policy = resolveBranchPolicyFor(dir);
     return (
@@ -459,16 +502,53 @@ const dialectOf = (input: HookInput): ShellDialect =>
     ? input.event.dialect
     : undefined) ?? "posix";
 
+/** The nudge kind an action shows: each is shown once per session (agent). */
+const nudgeKind = (action: RawAction): string =>
+  action.kind === "commit" && action.amend
+    ? "commit-amend"
+    : action.kind === "push" && action.blindForce
+      ? "push-force"
+      : action.kind;
+
+/**
+ * The nudges a session (or one of its subagents) has not been shown yet,
+ * recorded as shown in the per-session marker. Without a session or a
+ * marker, every nudge shows: the throttle fails open to repeating.
+ */
+const unseenNudges = (input: HookInput, nudges: Map<string, string>, store: string): string[] => {
+  const session = input.session.id;
+  const file = session ? sessionMarkerFile(input, session, store) : null;
+  if (!file) return [...nudges.values()];
+  const marker = readSessionMarker(file);
+  const agent = input.session.agentId ? `${input.session.agentId}:` : "";
+  const fresh = [...nudges.keys()].filter((kind) => !marker.raw.includes(agent + kind));
+  if (fresh.length)
+    writeSessionMarker(file, {
+      ...marker,
+      raw: [...marker.raw, ...fresh.map((kind) => agent + kind)],
+    });
+  return fresh.map((kind) => nudges.get(kind) as string);
+};
+
 /**
  * The pre-tool decision for a shell command: deny a gate bypass inside a
  * Workit workspace, else a nudge (as context) for routine raw delivery
- * commands, else nothing. Never throws, never writes.
+ * commands, else nothing. Each nudge kind is shown once per session, and a
+ * command that runs a workit verb itself gets none (denies still apply).
+ * `nudge: false` asks for the deny alone and spends no nudge. Never throws.
  */
-export function rawGitPre(input: HookInput, command: string): HookDecision {
+export function rawGitPre(
+  input: HookInput,
+  command: string,
+  options: { nudge?: boolean } = {},
+): HookDecision {
   try {
     if (!mentionsRawTool(command)) return NONE;
-    const nudges: string[] = [];
-    for (const { action, repo } of actionsIn(input.cwd, command, dialectOf(input))) {
+    const dialect = dialectOf(input);
+    const nudges = new Map<string, string>();
+    let store: string | null = null;
+    for (const { action, repo } of actionsIn(input.cwd, command, dialect)) {
+      store ??= repo.location.dir;
       if (action.kind === "merge") return deny(refusal(action, null));
       if (action.kind === "push")
         for (const target of action.targets) {
@@ -477,9 +557,12 @@ export function rawGitPre(input: HookInput, command: string): HookDecision {
             return deny(refusal(action, branch));
         }
       const nudge = nudgeFor(action, input.host, input.session.id);
-      if (nudge && !nudges.includes(nudge)) nudges.push(nudge);
+      if (nudge && !nudges.has(nudgeKind(action))) nudges.set(nudgeKind(action), nudge);
     }
-    return nudges.length ? { kind: "context", text: nudges.join("\n") } : NONE;
+    if (options.nudge === false || !store || nudges.size === 0) return NONE;
+    if (workitInvocations(command, dialect).length > 0) return NONE;
+    const shown = unseenNudges(input, nudges, store);
+    return shown.length ? { kind: "context", text: shown.join("\n") } : NONE;
   } catch {
     return NONE;
   }

package/src/hooks/session-marker.ts

@@ -0,0 +1,53 @@
+// The per-session nudge marker in the workspace store
+// (`<store>/hooks/skills-<session hash>.json`): which skills a session was
+// nudged about or loaded, and which raw-git nudge kinds it was shown, so each
+// nudge fires once per session. Each hook is a fresh process, so the marker
+// lives on disk. Every failure reads as an empty marker: hooks fail open.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStore } from "../store/paths";
+import type { HookInput } from "./protocol";
+
+export type SessionMarker = { nudged: string[]; loaded: string[]; raw: string[] };
+
+/**
+ * The marker in the workspace's store (null outside one: nothing is nudged or
+ * recorded there). `store` names the store directly when the command acts in
+ * another checkout than the hook's cwd.
+ */
+export const sessionMarkerFile = (
+  input: HookInput,
+  session: string,
+  store?: string,
+): string | null => {
+  let dir = store;
+  if (dir === undefined) {
+    const location = resolveStore(input.cwd);
+    if (location instanceof Error || !location.shared) return null;
+    dir = location.dir;
+  }
+  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
+  return path.join(dir, "hooks", `skills-${name}.json`);
+};
+
+const list = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+
+export const readSessionMarker = (file: string): SessionMarker => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    return { nudged: list(value.nudged), loaded: list(value.loaded), raw: list(value.raw) };
+  } catch {
+    return { nudged: [], loaded: [], raw: [] };
+  }
+};
+
+export const writeSessionMarker = (file: string, marker: SessionMarker): 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.
+  }
+};