pendingyou 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.3.0
+
+- New Stop hook, `pendingyou stopcheck`: when Claude Code ends a turn with a question for you, a step only you can do
+  or a "Your part:" list, and posted nothing to Pending You in that turn, it's asked once to post them as cards (or
+  say they don't need one). Pattern matching only, on the last turn, at most 4 MB of the transcript; quiet when not
+  signed in, never twice in a row (`stop_hook_active`), and silent on any error.
+- The next-message hook adds one line while you're signed in: “Pending You: anything you need from your person also
+  goes on a card.”
+- `init` adds the Stop hook (run it again on 0.2.x to get it), `uninstall` removes it, and `status` lists it.
+
+## 0.2.1
+
+- Fixed: after `init --origin <url>` (any origin but the default), every Claude Code message was blocked with
+  `UserPromptSubmit operation blocked by hook: … There's no "--origin" command.` 0.2.0 wrote its hooks with `--origin`
+  before the command, which it couldn't read. To repair: `npx pendingyou@latest init --origin <url>` (or, if you ran
+  `uninstall` to get unblocked, the same command sets it up again).
+- Hooks now name the command first (`pendingyou@0.2.1 handoff --origin <url>`), add `--origin` only when it isn't the
+  default, and end in `|| true`.
+- Options can come before or after the command.
+- `pickup` and `handoff` never block: on any error (bad options, no network, not signed in) they exit 0, print nothing
+  for Claude Code, and leave at most a short note on stderr.
+- Running `init` again repairs hook lines an older version wrote.
+
+## 0.2.0
+
+- `login --device` for computers with no browser, and `watch` for always-on scripts.

package/README.md

@@ -12,13 +12,37 @@ Run it once on each computer. It:
 - adds the Pending You MCP server to Claude Code for every project (unless it's already there),
 - saves the Pending You skill to `~/.claude/skills/pendingyou/SKILL.md`,
 - signs this computer in (your browser opens once; press Allow),
-- adds two hooks to `~/.claude/settings.json`: a new session picks up answers that arrived while nothing was running,
-  and your next message brings a waiting answer with it,
+- adds three hooks to `~/.claude/settings.json`: a new session picks up answers that arrived while nothing was
+  running, your next message brings a waiting answer with it, and a check when Claude Code finishes a turn (below),
 - lets Claude Code start `npx pendingyou hold` and use Pending You's tools without a permission prompt, so a question
   it asks while you're away doesn't wait on one.
 
 Your other settings are kept as they are. `npx pendingyou uninstall` removes exactly what `init` added.
 
+The hooks never get in your way: if anything goes wrong (no network, not signed in, a bad option), they print nothing
+and let your message through. Running `init` again updates them in place, and adds any a newer version brings.
+
+## Nothing left only in chat
+
+Deep into a long conversation, Claude Code tends to end a turn with a question for you, a step only you can do, or a
+"Your part:" list, and not put it in Pending You. Two small things catch that while you're signed in:
+
+- Each message you send carries one line for Claude Code (about 18 tokens): *Pending You: anything you need from your
+  person also goes on a card.*
+- When Claude Code finishes a turn, `pendingyou stopcheck` looks at its last message. If it has something for you and
+  nothing was posted, updated or replied to in Pending You that turn (and the message doesn't say it's on a card),
+  Claude Code is asked to go on once (about 31 tokens): post them as cards, or say they don't need one. It never asks
+  twice in a row.
+
+The check is pattern matching on your computer: no model, no network. It reads only the last turn from the end of the
+transcript (at most 4 MB) and skips code blocks and quotes. It counts as for you: a question to you (a sentence ending
+in "?" with "you" or "your"); "you'll need to", "your step", "can you", "please run", "in your terminal", "only you
+can", "waiting on you" and the like; or a list under a heading like "Your part", "Your steps", "For you", "Waiting on
+you" or "Left for you".
+
+**On 0.2.0 with another origin?** Its hooks blocked every message (`There's no "--origin" command`). Run
+`npx pendingyou@latest init --origin <url>` again to repair them; see [CHANGELOG.md](CHANGELOG.md).
+
 ## How Claude Code uses it
 
 After it posts a question to Pending You, Claude Code runs this in the background and keeps working:
@@ -69,9 +93,11 @@ more, then skipped. `--once` stops after the first.
 | `login` / `logout` | Sign this computer in or out (`--device`, `--force`, `--all`) |
 | `watch -- <command>` | Run a command each time an answer is ready (`--once`) |
 | `pickup` / `handoff` | The session-start and next-message hooks |
+| `stopcheck` | The Stop hook: items for you left only in chat |
 | `uninstall` | Remove what `init` added, and sign out |
 
-Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDINGYOU_ORIGIN`).
+Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDINGYOU_ORIGIN`). Options can come
+before or after the command.
 
 ## What it can see, and where it keeps things
 

package/dist/args.js

@@ -1,5 +1,6 @@
-// The command line's arguments: one command, then its flags. No dependencies, no surprises: an unknown flag or a
-// stray argument is an error, never ignored.
+// The command line's arguments: one command and its flags, which may come before or after it (`pendingyou handoff
+// --origin <url>` and `pendingyou --origin <url> handoff` are the same; 0.2.0 wrote its hooks the second way). No
+// dependencies, no surprises: an unknown flag or a stray argument is an error, never ignored.
 export const DEFAULT_ORIGIN = 'https://www.pendingyou.com';
 /** How long `hold` waits for an answer before it lets go (4 hours). */
 export const DEFAULT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
@@ -44,6 +45,7 @@ const COMMANDS = new Set([
     'hold',
     'pickup',
     'handoff',
+    'stopcheck',
     'init',
     'uninstall',
     'watch',
@@ -58,18 +60,48 @@ const FLAGS = {
     hold: { origin: true, timeout: true },
     pickup: { origin: true },
     handoff: { origin: true },
+    stopcheck: { origin: true },
     init: { origin: true, 'no-login': false, 'no-browser': false, device: false },
     uninstall: { origin: true },
     watch: { origin: true, once: false },
 };
+/** Options that take a value, whichever command they belong to: needed to find the command behind them. */
+const VALUE_OPTIONS = new Set(['origin', 'timeout']);
+/** Splits off the options given before the command: [those options, the command, everything after it]. */
+function splitCommand(argv) {
+    let index = 0;
+    while (index < argv.length) {
+        const arg = argv[index];
+        if (arg === '--' || !arg.startsWith('-'))
+            break;
+        index += arg.startsWith('--') && !arg.includes('=') && VALUE_OPTIONS.has(arg.slice(2)) ? 2 : 1;
+    }
+    return [argv.slice(0, index), argv[index], argv.slice(index + 1)];
+}
+/** The command the arguments name, wherever its options are; undefined when there isn't one. */
+export function commandOf(argv) {
+    return splitCommand(argv)[1];
+}
+/** The commands Claude Code's hooks run. Whatever goes wrong, they exit 0 and never block the person. */
+export const HOOK_COMMANDS = new Set(['pickup', 'handoff', 'stopcheck']);
 export function parseArgs(argv, env = {}) {
-    const [first, ...rest] = argv;
-    if (first === undefined || first === '-h' || first === '--help')
+    const [leading, first, after] = splitCommand(argv);
+    const helps = (arg) => arg === '-h' || arg === '--help';
+    const versions = (arg) => arg === '-v' || arg === '--version';
+    if (leading.some(helps))
         return { name: 'help' };
-    if (first === '-v' || first === '--version')
+    if (first === undefined) {
+        if (leading.some(versions))
+            return { name: 'version' };
+        if (leading.length === 0)
+            return { name: 'help' };
+        throw new UsageError('Which command? Like: pendingyou status');
+    }
+    if (leading.some(versions))
         return { name: 'version' };
     if (!COMMANDS.has(first))
         throw new UsageError(`There’s no “${first}” command.`);
+    const rest = [...leading, ...after];
     const allowed = FLAGS[first] ?? {};
     const flags = new Map();
     const positional = [];
@@ -139,6 +171,9 @@ export function parseArgs(argv, env = {}) {
         case 'handoff':
             none();
             return { name: 'handoff', origin };
+        case 'stopcheck':
+            none();
+            return { name: 'stopcheck', origin };
         case 'uninstall':
             none();
             return { name: 'uninstall', origin };
@@ -174,7 +209,8 @@ export function parseArgs(argv, env = {}) {
 export const USAGE = `pendingyou: Pending You for Claude Code
 
   npx pendingyou init          Set up Claude Code on this computer: the MCP server, the skill,
-                               this command's sign-in, and two hooks that hand answers over
+                               this command's sign-in, and three hooks (answers, and a check
+                               that what Claude Code leaves you in chat is also in Pending You)
   npx pendingyou hold <req_…>  Wait in the background until the answer to a request is ready,
                                print it, and exit (which wakes Claude Code)
   npx pendingyou status        What's set up, and whether Claude Code hears answers right away
@@ -185,6 +221,7 @@ export const USAGE = `pendingyou: Pending You for Claude Code
   npx pendingyou uninstall     Remove exactly what init added
   npx pendingyou pickup        Answers waiting for this folder (the session-start hook)
   npx pendingyou handoff       The same, only while a hold is outstanding (the next-message hook)
+  npx pendingyou stopcheck     Questions or steps for you left only in chat (the Stop hook)
 
 Options: --origin <url> (default ${DEFAULT_ORIGIN}), --timeout 4h (hold), --no-browser and --device (login,
 init), --no-login (init), --all (logout), --force (login), --once (watch).

package/dist/claude.js

@@ -1,5 +1,5 @@
 // Claude Code's side of `pendingyou init` and `uninstall`: the Pending You MCP server (user scope), the stub skill, the
-// two hooks (session-start pickup, next-message hand-off) and the permissions the background wait needs, in
+// three hooks (session-start pickup, next-message hand-off, the Stop check) and the permissions the background wait needs, in
 // ~/.claude/settings.json. Settings are merged, never replaced: a file that isn't JSON is left alone, entries that
 // aren't ours are never touched, and running init again changes nothing it doesn't need to. What init added is written
 // down in ~/.config/pendingyou/claude-code.json, so uninstall removes exactly that.
@@ -12,7 +12,11 @@ import { claudeDir, configDir, readJson, readText, writeWhole } from "./files.js
 import { VERSION } from "./version.js";
 export const MCP_NAME = 'pendingyou';
 /** The hooks, by Claude Code event, and the command each runs. */
-export const HOOKS = { SessionStart: 'pickup', UserPromptSubmit: 'handoff' };
+export const HOOKS = {
+    SessionStart: 'pickup',
+    UserPromptSubmit: 'handoff',
+    Stop: 'stopcheck',
+};
 /** Seconds Claude Code gives each hook; they time-box themselves well inside it. */
 const HOOK_TIMEOUT = 10;
 /**
@@ -31,18 +35,26 @@ const quote = (text) => /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replaceA
  * How a hook runs this command line: through npx when that's how it was started (pinned to this version, from npx's
  * cache), the installed `pendingyou` when it's installed, or this very file.
  */
-export function selfCommand(io, origin) {
+export function selfCommand(io) {
     const script = io.script.replaceAll('\\', '/');
-    const base = io.env.PENDINGYOU_SELF
+    return io.env.PENDINGYOU_SELF
         ? io.env.PENDINGYOU_SELF
         : !script || script.includes('/_npx/')
             ? `npx -y --prefer-offline pendingyou@${VERSION}`
             : script.includes('/node_modules/pendingyou/')
                 ? 'pendingyou'
                 : `node ${quote(io.script)}`;
-    return origin === DEFAULT_ORIGIN ? base : `${base} --origin ${quote(origin)}`;
 }
-/** Whether a hook command is one of ours: it runs pendingyou's `pickup` or `handoff`. */
+/**
+ * A hook's command line: the command first, then `--origin` only when it isn't the default. `|| true` keeps the hook
+ * from ever blocking the person, even when npx can't fetch the package or the command fails before it starts (Claude
+ * Code blocks a message when its UserPromptSubmit hook exits 2, and flags any other non-zero exit).
+ */
+export function hookCommand(io, origin, sub) {
+    const flag = origin === DEFAULT_ORIGIN ? '' : ` --origin ${quote(origin)}`;
+    return `${selfCommand(io)} ${sub}${flag} || true`;
+}
+/** Whether a hook command is one of ours: it runs pendingyou's `pickup`, `handoff` or `stopcheck`. */
 export function isOurHook(command, sub) {
     if (typeof command !== 'string' || !command.includes('pendingyou'))
         return false;
@@ -71,7 +83,10 @@ const objectAt = (parent, key) => {
         ? value
         : null;
 };
-/** Adds (or updates) our hooks and permissions. Returns the permissions it added. */
+/**
+ * Adds our hooks and permissions, or updates our hooks in place (a new version, or a line an older version wrote, like
+ * 0.2.0's `… --origin <url> handoff`, which 0.2.0 itself can't read). Returns the permissions it added.
+ */
 export function mergeSettings(settings, commands) {
     const next = structuredClone(settings);
     let changed = false;
@@ -80,7 +95,7 @@ export function mergeSettings(settings, commands) {
         throw new PlainError('Claude Code’s settings have a “hooks” that isn’t an object, so I left them alone.');
     for (const event of Object.keys(HOOKS)) {
         const sub = HOOKS[event];
-        const wanted = `${commands[event]} ${sub}`;
+        const wanted = commands[event];
         const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
         if (hooks[event] !== undefined && !Array.isArray(hooks[event]))
             throw new PlainError(`Claude Code’s ${event} hooks aren’t a list, so I left them alone.`);
@@ -231,15 +246,17 @@ export async function installClaude(io, origin) {
     steps.push(mcp.step);
     const skill = await saveSkill(io, origin, before?.skill ?? null);
     steps.push(skill.step);
-    const self = selfCommand(io, origin);
-    const commands = { SessionStart: self, UserPromptSubmit: self };
+    const commands = Object.fromEntries(Object.keys(HOOKS).map((event) => [
+        event,
+        hookCommand(io, origin, HOOKS[event]),
+    ]));
     const merged = mergeSettings(await readSettings(io), commands);
     if (merged.changed)
         await writeSettings(io, merged.settings);
     steps.push({
         ok: true,
         text: merged.changed
-            ? `Installed the session-start pickup and next-message hand-off hooks in ${settingsPath(io)}.`
+            ? `Installed or updated the session-start pickup, next-message hand-off and Stop check hooks in ${settingsPath(io)}.`
             : 'The hooks were already installed.',
     });
     const manifest = {
@@ -248,10 +265,7 @@ export async function installClaude(io, origin) {
         claudeDir: claudeDir(io),
         mcpAdded: mcp.added || (before?.mcpAdded ?? false),
         skill: skill.skill,
-        hooks: {
-            SessionStart: `${self} ${HOOKS.SessionStart}`,
-            UserPromptSubmit: `${self} ${HOOKS.UserPromptSubmit}`,
-        },
+        hooks: commands,
         permissions: [...new Set([...(before?.permissions ?? []), ...merged.permissionsAdded])],
     };
     await writeWhole(manifestPath(io), `${JSON.stringify(manifest, null, 2)}\n`, { secret: true });
@@ -299,13 +313,18 @@ export async function claudeState(io) {
     const claude = version.code === 0 ? version.stdout.trim().split(/\s+/)[0] || 'installed' : null;
     const mcp = claude ? (await io.run('claude', ['mcp', 'get', MCP_NAME], 20_000)).code === 0 : false;
     const skill = (await readText(skillPath(io))) !== null;
-    let hooks = false;
+    let installed = (_event) => false;
     try {
-        const settings = await readSettings(io);
-        const all = objectAt(settings, 'hooks') ?? {};
-        hooks = Object.keys(HOOKS).every((event) => Array.isArray(all[event]) &&
-            all[event].some((group) => (group.hooks ?? []).some((hook) => isOurHook(hook.command, HOOKS[event]))));
+        const all = objectAt(await readSettings(io), 'hooks') ?? {};
+        installed = (event) => Array.isArray(all[event]) &&
+            all[event].some((group) => (group.hooks ?? []).some((hook) => isOurHook(hook.command, HOOKS[event])));
     }
     catch { }
-    return { claude, mcp, skill, hooks };
+    return {
+        claude,
+        mcp,
+        skill,
+        hooks: installed('SessionStart') && installed('UserPromptSubmit'),
+        stopcheck: installed('Stop'),
+    };
 }

package/dist/cli.js

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
 // `npx pendingyou …`: runs the command line with the real computer (realIo) and exits with its code.
 import { realIo } from "./io.js";
-import { main } from "./main.js";
-main(process.argv.slice(2), realIo()).then((code) => process.exit(code), () => {
+import { isHook, main } from "./main.js";
+const argv = process.argv.slice(2);
+// A hook (pickup, handoff, stopcheck) exits 0 even here: it must never block the person's message.
+const failed = isHook(argv) ? 0 : 1;
+try {
+    main(argv, realIo()).then((code) => process.exit(code), () => {
+        process.stderr.write('pendingyou: Something went wrong.\n');
+        process.exit(failed);
+    });
+}
+catch {
     process.stderr.write('pendingyou: Something went wrong.\n');
-    process.exit(1);
-});
+    process.exit(failed);
+}

package/dist/main.js

@@ -1,13 +1,14 @@
 // The command line: parse the arguments, run the command, return the exit code. `cli.ts` runs it for real; tests run
 // it with their own Io.
 import { getJson, SignInNeeded, Unavailable } from "./api.js";
-import { parseArgs, USAGE, UsageError } from "./args.js";
+import { commandOf, HOOK_COMMANDS, parseArgs, USAGE, UsageError } from "./args.js";
 import { claudeState, installClaude, uninstallClaude } from "./claude.js";
 import { readCredential, signedInOrigins, updateCredential } from "./credentials.js";
 import { PlainError } from "./errors.js";
 import { hold } from "./hold.js";
 import { OAuthError, revoke, signIn, signInWithDevice } from "./oauth.js";
 import { pickup } from "./pickup.js";
+import { stopcheck } from "./stopcheck.js";
 import { VERSION } from "./version.js";
 import { watch } from "./watch.js";
 /** Whether this computer's sign-in works, and how many Claude Code connections it hears for. */
@@ -81,7 +82,7 @@ async function status(io, origin) {
             ? 'ended; run npx pendingyou login'
             : signIn.state === 'none'
                 ? 'not signed in; run npx pendingyou login'
-                : 'Pending You couldn’t be reached'}`, `  ${mark(claude.claude !== null)} Claude Code: ${claude.claude ?? 'not found on PATH'}`, `  ${mark(claude.mcp)} MCP server: ${claude.mcp ? 'pendingyou' : 'not added; run npx pendingyou init'}`, `  ${mark(claude.skill)} Skill: ${claude.skill ? 'saved' : 'not saved; run npx pendingyou init'}`, `  ${mark(claude.hooks)} Hooks: ${claude.hooks ? 'session-start pickup and next-message hand-off' : 'not installed; run npx pendingyou init'}`);
+                : 'Pending You couldn’t be reached'}`, `  ${mark(claude.claude !== null)} Claude Code: ${claude.claude ?? 'not found on PATH'}`, `  ${mark(claude.mcp)} MCP server: ${claude.mcp ? 'pendingyou' : 'not added; run npx pendingyou init'}`, `  ${mark(claude.skill)} Skill: ${claude.skill ? 'saved' : 'not saved; run npx pendingyou init'}`, `  ${mark(claude.hooks)} Hooks: ${claude.hooks ? 'session-start pickup and next-message hand-off' : 'not installed; run npx pendingyou init'}`, `  ${mark(claude.stopcheck)} Stop check: ${claude.stopcheck ? 'asks Claude Code to post what it leaves you in chat' : 'not installed; run npx pendingyou init'}`);
     const ready = signIn.state === 'ok' && claude.hooks;
     lines.push(ready
         ? 'Ready: Claude Code hears answers right away (report_setup hears "instant").'
@@ -135,6 +136,8 @@ async function run(io, command) {
             return pickup(io, { origin: command.origin, mode: 'pickup' });
         case 'handoff':
             return pickup(io, { origin: command.origin, mode: 'handoff' });
+        case 'stopcheck':
+            return stopcheck(io, { origin: command.origin });
         case 'init':
             return init(io, command);
         case 'uninstall':
@@ -143,18 +146,33 @@ async function run(io, command) {
             return watch(io, command);
     }
 }
+/**
+ * Whether these arguments run a Claude Code hook (pickup, handoff or stopcheck). A hook must never get in the way of the person:
+ * Claude Code blocks their message when a UserPromptSubmit hook exits 2 and flags any other failure, so a hook exits 0
+ * whatever goes wrong, with at most a short note on stderr (which Claude Code doesn't add to the conversation).
+ */
+export const isHook = (argv) => HOOK_COMMANDS.has(commandOf(argv) ?? '');
 export async function main(argv, io) {
+    const hook = isHook(argv);
     let command;
     try {
         command = parseArgs(argv, io.env);
     }
     catch (error) {
+        if (hook) {
+            const message = error instanceof UsageError ? error.message : 'Something went wrong.';
+            io.err(`pendingyou: ${message} Skipped this hook; run npx pendingyou@latest init to repair it.\n`);
+            return 0;
+        }
         if (error instanceof UsageError) {
             io.err(`${error.message}\n\n${USAGE}`);
             return 2;
         }
         throw error;
     }
+    // `pickup --help` and the like: nothing for Claude Code to add to the conversation.
+    if (hook && !HOOK_COMMANDS.has(command.name))
+        return 0;
     try {
         return await run(io, command);
     }
@@ -167,6 +185,6 @@ export async function main(argv, io) {
             ? error.message
             : 'Something went wrong.';
         io.err(`pendingyou: ${message}\n`);
-        return 1;
+        return hook ? 0 : 1;
     }
 }

package/dist/pickup.js

@@ -4,14 +4,18 @@
 //   running, for questions asked from this folder.
 // - `pendingyou handoff` (UserPromptSubmit): your next message brings a waiting answer with it ("You answered in
 //   Pending You: …"). It only calls Pending You while a hold from this computer is outstanding, so an ordinary message
-//   costs no network call.
+//   costs no network call. While signed in, it also adds one short line (REMINDER) to every message, so an assistant
+//   deep in a long conversation still puts what it needs from the person on a card.
 //
 // Whatever they print, Claude Code adds to the conversation. A hook must never get in the way: each is time-boxed,
 // prints nothing when there's nothing new, never repeats an answer it handed over, and always exits 0.
 import { getJson, SignInNeeded } from "./api.js";
+import { readCredential } from "./credentials.js";
 import { describe, isClosed } from "./format.js";
 import { markHanded, momentOf, waitingOn, wasHanded } from "./state.js";
 const TIME_BOX_MS = { pickup: 5000, handoff: 2500 };
+/** What every message carries while signed in (about 18 tokens). */
+export const REMINDER = 'Pending You: anything you need from your person also goes on a card.';
 /** The folder Claude Code says the session is in (the hook's stdin), or where this runs. */
 async function sessionFolder(io) {
     const text = await io.readStdin(500).catch(() => '');
@@ -33,10 +37,14 @@ export function folderForms(cwd, home) {
 }
 export async function pickup(io, options) {
     const { origin, mode } = options;
+    let remind = false;
     try {
         const cwd = await sessionFolder(io);
-        if (mode === 'handoff' && (await waitingOn(io, origin)).length === 0)
-            return 0;
+        if (mode === 'handoff') {
+            remind = (await readCredential(io, origin)) !== null;
+            if ((await waitingOn(io, origin)).length === 0)
+                return 0;
+        }
         const query = new URLSearchParams([
             ...folderForms(cwd, io.home).map((form) => ['cwd', form]),
             ['limit', '5'],
@@ -69,6 +77,12 @@ export async function pickup(io, options) {
     catch (error) {
         if (mode === 'pickup' && error instanceof SignInNeeded && error.ended)
             io.out('Pending You: this computer’s pendingyou sign-in has ended, so answers can’t wake Claude Code. Ask your person to run `npx pendingyou login`.\n');
+        if (error instanceof SignInNeeded)
+            remind = false;
         return 0;
     }
+    finally {
+        if (remind)
+            io.out(`${REMINDER}\n`);
+    }
 }

package/dist/stopcheck.js

@@ -0,0 +1,178 @@
+// `pendingyou stopcheck`, the Stop hook `init` installs: when Claude Code is about to end its turn with something for
+// the person in the chat (a question to them, a step only they can do, a "Your part:" list) and it posted nothing to
+// Pending You in that turn, it asks Claude Code to go on and post it (`{"decision":"block","reason":…}`), once.
+//
+// Pattern matching only, no model, no network: it reads the hook's JSON, the final message, and the tail of the
+// transcript back to the person's last message, never more than READ_CAP bytes. It never loops (stop_hook_active),
+// stays quiet for anyone not signed in to this origin, and exits 0 silently on any error.
+import { open } from 'node:fs/promises';
+import { readCredential } from "./credentials.js";
+/** The most of the transcript it reads, from the end. A turn longer than this is let through. */
+export const READ_CAP = 4 * 1024 * 1024;
+const CHUNK = 64 * 1024;
+/** What Claude Code reads when it's asked to go on: one short line (about 30 tokens). */
+export const STOP_REASON = 'Items for your person are in chat but not in Pending You: post them as cards (ask in both places), or say they don’t need one.';
+/** Tools that put something in front of the person: Pending You's, under any MCP server name. */
+const POSTING_TOOL = /^mcp__.+__(post_request|update_request|reply_in_thread)$/;
+/** Text that says the items are already in Pending You. */
+const SAYS_POSTED = /\b(posted|put|added|raised|filed)\b[^.\n]{0,60}\b(cards?|pending ?you)\b|\bon (a|the|its|their|your|that|this) cards?\b|\b(in|to|through|via|on) pending ?you\b|\bpending ?you cards?\b/i;
+/** Steps only the person can take, said to them. */
+const STEPS_FOR_THEM = /\b(you(?:'|’)ll need to|you will need to|you(?:'|’)ll have to|you will have to|your (?:next )?steps?\b|can you|could you|would you mind|please (?:run|confirm|approve|check|add|set|sign|create|open|paste|reply|send|choose|pick|decide|let me know)|in your terminal|only you can|waiting on you|waiting for you|needs? you to|over to you|parked for you|when you(?:'|’)re ready|up to you|your call\b|is yours\b|say the word|let me know (?:which|whether)|tell me (?:which|whether)|needs? your (?:ok|okay|approval|decision|sign-?off|go-ahead))/i;
+/** A heading over a list of things for the person. */
+const FOR_THEM_HEADING = /\b(your part|your steps?|your to-?dos?|your turn|your call|for you|waiting on you|left for you|parked for you|needs you|over to you|what you need to do|you(?:'|’)ll need)\b/i;
+const LIST_ITEM = /^\s*(?:\d+[.)]|[-*•]|\[ \])\s+\S/;
+const YOU = /\byou(?:r|rs|(?:'|’)(?:ll|d|re|ve))?\b/i;
+/** The text without what isn't said to the person: code (fenced and inline), block quotes and quoted strings. */
+export function plainText(text) {
+    const kept = [];
+    let fence = null;
+    for (const line of text.split('\n')) {
+        const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+        if (fence) {
+            if (marker?.startsWith(fence))
+                fence = null;
+            continue;
+        }
+        if (marker) {
+            fence = marker;
+            continue;
+        }
+        if (/^\s*>/.test(line))
+            continue;
+        kept.push(line.replace(/`[^`]*`/g, '').replace(/“[^”]*”|"[^"]*"/g, ''));
+    }
+    return kept.join('\n');
+}
+/** A heading's words (`## Your part`, `**Your part:**`, `Your part:`), or null when the line isn't one. */
+function headingOf(line) {
+    const bare = line.replace(/[*_#]/g, '').trim();
+    if (!bare || bare.length > 80)
+        return null;
+    return /^\s*#/.test(line) || bare.endsWith(':') || /^\s*\*\*.+\*\*\s*$/.test(line) ? bare : null;
+}
+/**
+ * What in the final text is for the person, or null: `list` (a list under a heading like "Your part:"), `steps`
+ * (something only they can do) or `question` (a question to them).
+ */
+export function itemsForPerson(text) {
+    const plain = plainText(text);
+    const lines = plain.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        const heading = headingOf(lines[index]);
+        if (!heading || !FOR_THEM_HEADING.test(heading))
+            continue;
+        const next = lines.slice(index + 1, index + 4).find((candidate) => candidate.trim());
+        if (next && LIST_ITEM.test(next))
+            return 'list';
+    }
+    if (STEPS_FOR_THEM.test(plain))
+        return 'steps';
+    for (const sentence of plain.split(/(?<=[.!?])\s+|\n/))
+        if (sentence.trim().endsWith('?') && YOU.test(sentence))
+            return 'question';
+    return null;
+}
+/** Whether the text says the items are already in Pending You. */
+export const saysPosted = (text) => SAYS_POSTED.test(plainText(text));
+/** A message from the person (not a tool's result): where a turn starts. */
+function startsTurn(entry) {
+    if (entry.type !== 'user' || entry.isMeta || entry.message?.role !== 'user')
+        return false;
+    const content = entry.message.content;
+    if (typeof content === 'string')
+        return true;
+    return Array.isArray(content) && content.some((block) => block?.type === 'text');
+}
+/**
+ * The last turn of a Claude Code transcript (JSONL): read backwards from the end in chunks, line by line, until the
+ * person's last message, never more than `cap` bytes.
+ */
+export async function lastTurn(path, cap = READ_CAP) {
+    const file = await open(path, 'r');
+    try {
+        const size = (await file.stat()).size;
+        let position = size;
+        let bytesRead = 0;
+        let carry = Buffer.alloc(0);
+        const texts = [];
+        let finalDone = false;
+        let posted = false;
+        const take = (raw) => {
+            if (!raw.trim())
+                return false;
+            let entry;
+            try {
+                entry = JSON.parse(raw);
+            }
+            catch {
+                return false;
+            }
+            if (entry.isSidechain)
+                return false;
+            if (startsTurn(entry))
+                return true;
+            if (entry.type !== 'assistant' || !Array.isArray(entry.message?.content))
+                return false;
+            const blocks = entry.message.content;
+            for (const block of [...blocks].reverse()) {
+                if (block?.type === 'tool_use') {
+                    finalDone = true;
+                    const name = typeof block.name === 'string' ? block.name : '';
+                    const command = typeof block.input?.command === 'string' ? block.input.command : '';
+                    if (POSTING_TOOL.test(name) || /\bpendingyou\b.*\bhold\s+req_/.test(command))
+                        posted = true;
+                }
+                else if (block?.type === 'text' && !finalDone && typeof block.text === 'string')
+                    texts.unshift(block.text);
+            }
+            return false;
+        };
+        while (position > 0 && bytesRead < cap) {
+            const length = Math.min(CHUNK, position, cap - bytesRead);
+            position -= length;
+            const chunk = Buffer.alloc(length);
+            await file.read(chunk, 0, length, position);
+            bytesRead += length;
+            let buffer = Buffer.concat([chunk, carry]);
+            let newline = buffer.lastIndexOf(10);
+            while (newline !== -1) {
+                if (take(buffer.subarray(newline + 1).toString('utf8')))
+                    return { text: texts.join('\n'), posted, complete: true, bytesRead };
+                buffer = buffer.subarray(0, newline);
+                newline = buffer.lastIndexOf(10);
+            }
+            carry = buffer;
+        }
+        if (position === 0 && take(carry.toString('utf8')))
+            return { text: texts.join('\n'), posted, complete: true, bytesRead };
+        return { text: texts.join('\n'), posted, complete: position === 0, bytesRead };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function stopcheck(io, options) {
+    try {
+        const input = JSON.parse(await io.readStdin(1000));
+        if (typeof input !== 'object' || input === null || input.stop_hook_active === true)
+            return 0;
+        if (typeof input.transcript_path !== 'string' || !input.transcript_path)
+            return 0;
+        if (!(await readCredential(io, options.origin)))
+            return 0;
+        const turn = await lastTurn(input.transcript_path);
+        if (!turn.complete)
+            return 0;
+        // The transcript can lag the final message; Claude Code hands it over itself.
+        const text = typeof input.last_assistant_message === 'string' && input.last_assistant_message.trim()
+            ? input.last_assistant_message
+            : turn.text;
+        if (turn.posted || !text || saysPosted(text) || !itemsForPerson(text))
+            return 0;
+        io.out(`${JSON.stringify({ decision: 'block', reason: STOP_REASON })}\n`);
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 // The command line's version, as published (package.json). A test keeps them the same.
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pendingyou",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pending You for Claude Code: hear your answers from Pending You in the background, and set Claude Code up in one command.",
   "license": "Apache-2.0",
   "homepage": "https://www.pendingyou.com",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {