pendingyou 0.12.0 → 0.13.0

package/dist/permission.js

@@ -0,0 +1,738 @@
+// Claude Code's permission prompts, on a card (0.13.0; Darin, 2026-10-04: "Tell me: a card and a push, cleared once I
+// answer in the terminal"). A Claude Code agent kept asking to remove files and sat waiting until Darin noticed. Now,
+// when Claude Code stops to ask for the person's OK and nobody answers within a few seconds, a card says so ("Claude Code
+// is waiting for your OK: rm -rf dist/"), asked in both places (askedFirst), so it stays quiet for their hand-off
+// minutes and pushes only once it has waited that long; and it goes away once they answer in Claude Code.
+//
+// - `pendingyou permission` is Claude Code's PermissionRequest hook (https://code.claude.com/docs/en/hooks: it runs
+//   "when Claude Code is about to ask you for permission to use a tool", with `tool_name` and `tool_input`; since
+//   2.0.45). It never decides: it prints nothing, so the prompt shows exactly as before, and it's done in milliseconds.
+//   It writes the prompt down (a redacted title, never the tool's input: redact.ts) in the session's own file,
+//   ~/.config/pendingyou/permission-cards/<session>.json, and starts the session's worker unless one is running.
+// - `pendingyou permission-done` is its PostToolUse, PostToolUseFailure and SessionEnd hook: the call it asked about ran
+//   (it was allowed), so that prompt is settled, or the session ended, so all of them are. The next message (handoff) and the end of a
+//   turn (stopcheck) settle the session's prompts too, since a denial runs no PostToolUse. The shim skips Node
+//   altogether while no session has a file here (shim.ts), so a tool call costs a few milliseconds.
+// - `pendingyou permission-card --session <id> --worker <id>`, detached, is the session's one worker: it waits until a
+//   prompt has waited GRACE_MS (one answered sooner gets no card), posts the card through Pending You's MCP with Claude
+//   Code's own connection (whoami, match_area, post_request; create_area when nothing fits, as the guide says), changes
+//   it to the newest prompt (update_request with a changeNote: one card per session, never a second), withdraws it
+//   once nothing waits (cancel_request, answeredHere; without, when the session ended), and stops.
+//
+// No card for a session that can't show a prompt: `claude -p` and the Agent SDK (CLAUDE_CODE_ENTRYPOINT `sdk-…`, as
+// Claude Code 2.1.289 sets it), or a session in dontAsk or bypassPermissions mode; nor without this computer's own
+// connection for Claude Code (a sign-in that only hears can't post).
+import { createHash, randomBytes } from 'node:crypto';
+import { open, readdir, rm, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { DEFAULT_ORIGIN } from "./args.js";
+import { McpFailure, mcpClient, SIGN_IN_ERROR, ToolRefused } from "./bridge.js";
+import { sessionLink } from "./confirm.js";
+import { connectionMachine, readCredential } from "./credentials.js";
+import { configDir, PERMISSION_FOLDER, readJson, withLock, writeWhole } from "./files.js";
+import { cut, redactCommand, redactText, redactUrl, shortPath } from "./redact.js";
+import { machineOf } from "./remote.js";
+/** How long a prompt waits before its card goes up: one answered sooner was answered by someone at the terminal. */
+export const GRACE_MS = 10_000;
+/** The longest a card's title is (the guide's "under 90 characters"). */
+export const TITLE_MAX = 90;
+/** What every card's title starts with. */
+export const WAITING = 'Claude Code is waiting for your OK';
+/**
+ * Whether a card is one of these (by its title): the hooks' own, which closes by itself, so the hand-off neither names
+ * it among the agent's open cards nor hands an agent a Done the person pressed on it.
+ */
+export const isPermissionCard = (title) => typeof title === 'string' &&
+    (title.startsWith(WAITING) || title.startsWith('Claude Code is waiting for your answer'));
+/** The name a card is asked under when the session never told Pending You its own. */
+export const DEFAULT_NAME = 'Claude Code';
+/** A worker whose lease is older than this has died; the next event starts another. */
+const LEASE_STALE_MS = 120_000;
+/** How long a worker keeps going at most; the next event starts another. */
+const WORKER_MS = 60 * 60_000;
+/** The longest one sleep of the worker, so its lease stays fresh. */
+const NAP_MS = 20_000;
+/** How long one call to Pending You may take. */
+const CALL_MS = 15_000;
+/** Pauses after a failed call, then it gives that step up. */
+const BACKOFF_MS = [2000, 5000, 10_000, 20_000];
+/** The most prompts a session's file keeps (queued subagents' prompts): the newest. */
+const MAX_PROMPTS = 20;
+/** A session's file untouched this long is left from a session that never ended cleanly. */
+const KEEP_MS = 7 * 24 * 60 * 60_000;
+/** The most of a hook's stdin read: a Write's whole file can be in it. */
+const STDIN_MAX = 8_000_000;
+/** The most of a transcript read, from its end, for the session's name. */
+const TRANSCRIPT_CAP = 4 * 1024 * 1024;
+/** A session's id, as Claude Code gives it (a UUID): also its file's name. */
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
+/** Pending You's tools that carry the asking session's name, under any server name (the plugin's too). */
+const NAMED_TOOL = /^mcp__.*pendingyou.*__(whoami|post_request|update_request|cancel_request|reply_in_thread|get_request|ack_answer|list_pending|get_attachment)$/i;
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const folderOf = (io) => join(configDir(io), PERMISSION_FOLDER);
+const pathOf = (io, session) => join(folderOf(io), `${session}.json`);
+/** JSON with its keys in order, so the same input always hashes the same. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (isObject(value))
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+/** Tools whose input comes back with the person's answer in it: their prompt is the tool's, whatever the input. */
+const ANSWERED_IN_INPUT = new Set(['AskUserQuestion', 'ExitPlanMode']);
+/** Which call a prompt is about: PermissionRequest's tool and input, which PostToolUse repeats for the same call. */
+export function promptKey(tool, input) {
+    const what = ANSWERED_IN_INPUT.has(tool) ? '' : canonical(input ?? {});
+    return createHash('sha256').update(`${tool}\n${what}`).digest('hex').slice(0, 32);
+}
+const text = (value) => (typeof value === 'string' ? value : '');
+/** A tool's name as a card may say it: letters, digits and a few marks. */
+const toolName = (tool) => cut(tool.replace(/[^\w.:-]/g, ''), 40) || 'a tool';
+/**
+ * What a card says about a prompt: its title (WAITING and what it's for, at most TITLE_MAX characters), what it asks
+ * in short, and what Claude Code waits for. Every command, path, address and question goes through redact.ts.
+ */
+export function promptWords(tool, input, home) {
+    const path = (value) => shortPath(text(value), home, 50);
+    const said = (what, doing) => ({
+        title: cut(`${WAITING}: ${what}`, TITLE_MAX),
+        what,
+        doing,
+    });
+    switch (tool) {
+        case 'Bash':
+        case 'PowerShell':
+            return said(redactCommand(text(input.command), tool).text, 'to run a command');
+        case 'Edit':
+        case 'MultiEdit':
+            return said(`edit ${path(input.file_path)}`, 'to edit a file');
+        case 'Write':
+            return said(`write ${path(input.file_path)}`, 'to write a file');
+        case 'NotebookEdit':
+            return said(`edit ${path(input.notebook_path)}`, 'to edit a notebook');
+        case 'Read':
+            return said(`read ${path(input.file_path)}`, 'to read a file');
+        case 'Glob':
+        case 'Grep':
+        case 'LS':
+            return said(input.path ? `search ${path(input.path)}` : 'search files', 'to search files');
+        case 'WebFetch': {
+            const address = redactUrl(text(input.url).trim()).replace(/^https?:\/\//i, '');
+            return said(`fetch ${cut(redactText(address, 60), 60)}`, 'to fetch a page');
+        }
+        case 'WebSearch':
+            return said(`search the web for “${redactText(text(input.query), 40)}”`, 'to search the web');
+        case 'ExitPlanMode':
+            return { title: `${WAITING} on its plan`, what: 'its plan', doing: 'on its plan' };
+        case 'AskUserQuestion': {
+            const first = Array.isArray(input.questions) ? input.questions[0] : undefined;
+            const question = redactText(text(isObject(first) ? first.question : ''), 80) || 'a question';
+            return {
+                title: cut(`Claude Code is waiting for your answer: ${question}`, TITLE_MAX),
+                what: question,
+                doing: 'to answer its question',
+            };
+        }
+        case 'Skill':
+            return said(`use the ${toolName(text(input.skill))} skill`, 'to use a skill');
+        case 'Task':
+        case 'Agent':
+            return said('start an agent', 'to start an agent');
+    }
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(tool);
+    if (mcp) {
+        const [, server = '', name = ''] = mcp;
+        return said(`${toolName(name)} on ${toolName(server)}`, `to use ${toolName(server)}’s ${toolName(name)}`);
+    }
+    return said(toolName(tool), `to use ${toolName(tool)}`);
+}
+async function load(io, session) {
+    const file = await readJson(pathOf(io, session)).catch(() => null);
+    if (!isObject(file) || !Array.isArray(file.prompts) || typeof file.origin !== 'string')
+        return null;
+    return file;
+}
+/** Changes a session's file under its lock: `edit` returns the new state, or null to remove the file. */
+async function change(io, session, edit) {
+    const path = pathOf(io, session);
+    return withLock(path, io, async () => {
+        const next = edit(await load(io, session));
+        if (next)
+            await writeWhole(path, `${JSON.stringify(next, null, 2)}\n`, { secret: true });
+        else
+            await rm(path, { force: true });
+        return next;
+    });
+}
+const alive = (state, now) => Boolean(state.worker && now - state.worker.at < LEASE_STALE_MS);
+/** Hands the session to a new worker unless one is alive: its id, to start it with, or null. */
+function claim(state, now) {
+    if (alive(state, now))
+        return null;
+    const id = randomBytes(8).toString('hex');
+    state.worker = { id, at: now };
+    return id;
+}
+/** Starts the session's worker, detached: it outlives the hook, prints nowhere, and nobody waits for it. */
+function startWorker(io, origin, session, worker) {
+    io.background([
+        'permission-card',
+        '--session',
+        session,
+        '--worker',
+        worker,
+        ...(origin === DEFAULT_ORIGIN ? [] : ['--origin', origin]),
+    ]);
+}
+const sessionOf = (input) => {
+    const id = text(input.session_id);
+    return SESSION.test(id) ? id : null;
+};
+/** PermissionRequest: writes the prompt down and makes sure the session's worker is going. */
+async function asked(io, origin, input) {
+    if (io.platform === 'win32')
+        return;
+    // `claude -p` and the Agent SDK: nobody sees a prompt, and Claude Code denies the call itself.
+    if (/^sdk-/.test(io.env.CLAUDE_CODE_ENTRYPOINT ?? ''))
+        return;
+    if (input.permission_mode === 'dontAsk' || input.permission_mode === 'bypassPermissions')
+        return;
+    const session = sessionOf(input);
+    const tool = text(input.tool_name);
+    if (!session || !tool)
+        return;
+    // Only this computer's own connection for Claude Code can post a card; a sign-in that only hears can't.
+    if ((await readCredential(io, origin))?.kind !== 'connection')
+        return;
+    const now = io.now();
+    const agent = text(input.agent_id);
+    const prompt = {
+        key: promptKey(tool, input.tool_input),
+        ...promptWords(tool, isObject(input.tool_input) ? input.tool_input : {}, io.home),
+        ...(agent ? { agent: agent.slice(0, 100) } : {}),
+        at: now,
+    };
+    const cwd = text(input.cwd) || io.cwd;
+    const transcript = text(input.transcript_path);
+    const link = sessionLink(io.env);
+    let worker = null;
+    await change(io, session, (state) => {
+        const next = state ?? { version: 1, origin, session, cwd, prompts: [], at: now };
+        next.origin = origin;
+        next.cwd = cwd;
+        if (transcript)
+            next.transcript = transcript;
+        if (link)
+            next.link = link;
+        // The same call asked again (the hook run twice) is still the one prompt.
+        if (!next.prompts.some((each) => each.key === prompt.key))
+            next.prompts.push(prompt);
+        next.prompts = next.prompts.slice(-MAX_PROMPTS);
+        delete next.settled;
+        next.at = now;
+        worker = claim(next, now);
+        return next;
+    });
+    if (worker)
+        startWorker(io, origin, session, worker);
+}
+/**
+ * Settles the session's prompts that `which` picks: answered in Claude Code, or the session ended. Starts the worker
+ * when there's a card to change or withdraw; a file with nothing left in it goes (unless a worker is busy with it).
+ */
+async function settle(io, session, which, how) {
+    const before = await load(io, session);
+    if (!before?.prompts.some(which))
+        return;
+    const now = io.now();
+    let worker = null;
+    let origin = before.origin;
+    await change(io, session, (state) => {
+        if (!state)
+            return null;
+        origin = state.origin;
+        const left = state.prompts.filter((prompt) => !which(prompt));
+        if (left.length === state.prompts.length)
+            return state;
+        state.prompts = left;
+        state.settled = how;
+        state.at = now;
+        if (!state.card && left.length === 0)
+            return alive(state, now) ? state : null;
+        worker = claim(state, now);
+        return state;
+    });
+    if (worker)
+        startWorker(io, origin, session, worker);
+}
+/** PostToolUse (and PostToolUseFailure): the call ran, so its prompt was answered. Quick when there's none. */
+async function ran(io, input) {
+    const session = sessionOf(input);
+    const tool = text(input.tool_name);
+    if (!session || !tool)
+        return;
+    const key = promptKey(tool, input.tool_input);
+    await settle(io, session, (prompt) => prompt.key === key, 'answered');
+}
+/**
+ * The person's next message (handoff) or the end of a turn (stopcheck): the session's own prompts are settled (a
+ * denied call runs no PostToolUse). A subagent's are too at the end of a turn, unless a subagent is still running in
+ * the background (the Stop hook's `background_tasks`), which may still be waiting on one. Quick when there's none.
+ */
+export async function settlePrompts(io, input) {
+    try {
+        if (!input.session || !SESSION.test(input.session))
+            return;
+        const subagentsDone = input.event === 'stop' && !input.subagents;
+        await settle(io, input.session, (prompt) => !prompt.agent || subagentsDone, 'answered');
+    }
+    catch { }
+}
+/** Whether the Stop hook's input says a subagent is still running in the background (its `background_tasks`). */
+export function subagentsRunning(input) {
+    if (!isObject(input) || !Array.isArray(input.background_tasks))
+        return false;
+    return input.background_tasks.some((task) => isObject(task) &&
+        task.type === 'subagent' &&
+        !['completed', 'failed', 'killed', 'cancelled', 'stopped'].includes(text(task.status)));
+}
+/**
+ * `pendingyou permission` and `permission-done`: Claude Code's PermissionRequest, PostToolUse and SessionEnd hooks.
+ * Prints nothing, ever (a PermissionRequest hook's output could decide the prompt), and exits 0.
+ */
+export async function permissionHook(io, options) {
+    try {
+        const input = JSON.parse(await io.readStdin(1000, STDIN_MAX));
+        if (!isObject(input))
+            return 0;
+        switch (input.hook_event_name) {
+            case 'PermissionRequest':
+                await asked(io, options.origin, input);
+                break;
+            case 'PostToolUse':
+            case 'PostToolUseFailure':
+                await ran(io, input);
+                break;
+            case 'SessionEnd': {
+                const session = sessionOf(input);
+                if (session)
+                    await settle(io, session, () => true, 'ended');
+                break;
+            }
+        }
+    }
+    catch { }
+    return 0;
+}
+/**
+ * The next step: withdraw the card once nothing waits; post one once the oldest prompt has waited `grace`, showing the
+ * newest; change it to the newest once that one has waited `grace` too; otherwise wait, or nothing (in step).
+ */
+export function planFor(state, now, grace) {
+    if (state.prompts.length === 0)
+        return state.card ? { kind: 'cancel' } : { kind: 'done' };
+    const newest = state.prompts.at(-1);
+    if (state.card) {
+        if (state.card.key === newest.key)
+            return { kind: 'done' };
+        const due = newest.at + grace - now;
+        return due > 0 ? { kind: 'wait', ms: due } : { kind: 'update', prompt: newest };
+    }
+    const live = state.prompts.filter((prompt) => !prompt.failed);
+    const oldest = live[0];
+    if (!oldest)
+        return { kind: 'done' };
+    const due = oldest.at + grace - now;
+    return due > 0 ? { kind: 'wait', ms: due } : { kind: 'post', prompt: live.at(-1) };
+}
+/** How long a prompt waits for its card: GRACE_MS, or PENDINGYOU_PERMISSION_GRACE_MS (for tests). */
+function graceOf(env) {
+    const given = Number(env.PENDINGYOU_PERMISSION_GRACE_MS);
+    return Number.isInteger(given) && given >= 0 ? given : GRACE_MS;
+}
+/** The computer as Pending You names it ("Claude Code on Darin’s MacBook Pro"). */
+async function computerOf(io, origin) {
+    const named = await connectionMachine(io, origin).catch(() => null);
+    return cut(named ?? (machineOf(io.host) || 'this computer'), 60);
+}
+/** The folder as the person reads it: under ~. */
+const tilde = (io, path) => shortPath(path, io.home, 200);
+/**
+ * The name the session gave Pending You, as its transcript says: the latest of its Pending You calls with a `name`
+ * (whoami's, a card tool's) or post_request's `session.label`. Null when it never gave one (or it can't be read).
+ */
+export async function sessionName(path) {
+    if (!path)
+        return null;
+    let file;
+    try {
+        file = await open(path, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = (await file.stat()).size;
+        let position = size;
+        let carry = Buffer.alloc(0);
+        const nameIn = (line) => {
+            if (!line.includes('pendingyou'))
+                return null;
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+            if (!isObject(entry) || entry.type !== 'assistant' || entry.isSidechain === true)
+                return null;
+            const message = isObject(entry.message) ? entry.message : {};
+            const blocks = Array.isArray(message.content) ? message.content : [];
+            for (const block of [...blocks].reverse()) {
+                if (!isObject(block) || block.type !== 'tool_use' || !NAMED_TOOL.test(text(block.name)))
+                    continue;
+                const args = isObject(block.input) ? block.input : {};
+                const session = isObject(args.session) ? args.session : {};
+                const name = (text(args.name) || text(session.label)).trim();
+                if (name && [...name].length <= 40)
+                    return name;
+            }
+            return null;
+        };
+        while (position > 0 && size - position < TRANSCRIPT_CAP) {
+            const length = Math.min(64 * 1024, position);
+            position -= length;
+            const chunk = Buffer.alloc(length);
+            await file.read(chunk, 0, length, position);
+            let buffer = Buffer.concat([chunk, carry]);
+            let newline = buffer.lastIndexOf(10);
+            while (newline !== -1) {
+                const found = nameIn(buffer.subarray(newline + 1).toString('utf8'));
+                if (found)
+                    return found;
+                buffer = buffer.subarray(0, newline);
+                newline = buffer.lastIndexOf(10);
+            }
+            carry = buffer;
+        }
+        return position === 0 ? nameIn(carry.toString('utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await file.close().catch(() => { });
+    }
+}
+/** The folder's git remote as match_area takes it (github.com/org/repo): never a user name, password or port. */
+export function remoteOf(url) {
+    const plain = url
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+        .replace(/^[^@/]+@/, '')
+        .replace(/^([^/:]+):\d+\//, '$1/')
+        .replace(/^([^/:]+):/, '$1/')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '');
+    return /^[\w.-]+\/[\w./-]+$/.test(plain) ? plain : null;
+}
+async function gitRemote(io, cwd) {
+    const result = await io.run('git', ['-C', cwd, 'remote', 'get-url', 'origin'], 3000);
+    return result.code === 0 ? remoteOf(result.stdout.split('\n')[0] ?? '') : null;
+}
+const idOf = (result, field, prefix) => {
+    const id = result[field];
+    return typeof id === 'string' && id.startsWith(prefix) ? id : null;
+};
+/** The area the session's cards go in: match_area's pick, or one made for the work when nothing fits (the guide). */
+async function areaFor(io, client, state, name) {
+    const remote = await gitRemote(io, state.cwd);
+    const match = await client.call('match_area', {
+        cwd: cut(state.cwd, 300),
+        ...(remote ? { remote: cut(remote, 300) } : {}),
+        ...(name !== DEFAULT_NAME ? { task: cut(name, 60) } : {}),
+    });
+    const suggestions = Array.isArray(match.suggestions) ? match.suggestions.filter(isObject) : [];
+    const top = suggestions[0] ? idOf(suggestions[0], 'areaId', 'prj_') : null;
+    if (match.decision !== 'create' && top)
+        return top;
+    const group = isObject(match.proposedGroup) ? idOf(match.proposedGroup, 'id', 'agr_') : null;
+    const proposed = text(match.proposedName).trim();
+    const created = await client.call('create_area', {
+        idempotencyKey: `claude-code-area:${createHash('sha256').update(state.cwd).digest('hex').slice(0, 32)}`,
+        name: cut(proposed || basename(state.cwd) || 'Inbox', 40),
+        description: cut(`Work in ${remote ?? tilde(io, state.cwd)}`, 160),
+        tint: text(match.proposedTint) || 'sky',
+        ...(group ? { group } : {}),
+        repo: remote ? { remote } : { path: state.cwd },
+    });
+    const areaId = idOf(created, 'areaId', 'prj_');
+    if (!areaId)
+        throw new McpFailure(-32000, 'Pending You made no area.');
+    return areaId;
+}
+/** The card's summary and its one step: the folder and the computer, and where to answer. */
+function cardWords(io, state, prompt, name, machine) {
+    const who = name === DEFAULT_NAME ? 'Claude Code' : `Claude Code (${name})`;
+    const waiting = prompt.doing === 'to answer its question'
+        ? 'is waiting for your answer to its question'
+        : `is waiting for your OK ${prompt.doing}`;
+    const summary = cut(`${who} in ${tilde(io, state.cwd)} on ${machine} ${waiting}. It goes on once you answer it there.`, 400);
+    const place = `Claude Code on ${machine}`;
+    const linked = state.link ? `${place}, ${state.link}` : place;
+    return {
+        summary,
+        action: {
+            where: linked.length <= 120 ? linked : cut(place, 120),
+            steps: [
+                {
+                    text: state.link
+                        ? `Answer it in ${place}, or open the session’s link and answer it there.`
+                        : `Answer it in ${place}.`,
+                },
+            ],
+            done: 'This card closes by itself once you answer there.',
+        },
+    };
+}
+/** Records what the worker did, while the session is still its own; false when it isn't any more. */
+async function record(io, session, worker, edit) {
+    let ours = false;
+    await change(io, session, (state) => {
+        if (!state || state.worker?.id !== worker)
+            return state;
+        ours = true;
+        edit(state);
+        state.worker = { id: worker, at: io.now() };
+        return state;
+    });
+    return ours;
+}
+/** Posts the session's card for its newest prompt. A card it can't record (the session moved on) is withdrawn. */
+async function post(io, client, state, prompt, worker) {
+    const name = (await sessionName(state.transcript)) ?? DEFAULT_NAME;
+    await client.call('whoami', { name });
+    const areaId = state.areaId ?? (await areaFor(io, client, state, name));
+    const machine = await computerOf(io, state.origin);
+    const result = await client.call('post_request', {
+        idempotencyKey: `claude-code-permission:${state.session}:${prompt.key}:${prompt.at}`,
+        areaId,
+        session: { label: name, machine, cwd: cut(tilde(io, state.cwd), 300) },
+        kind: 'action',
+        title: prompt.title,
+        ...cardWords(io, state, prompt, name, machine),
+        blocking: false,
+        urgency: 'now',
+        askedFirst: { where: 'terminal', askedAt: new Date(prompt.at).toISOString() },
+    });
+    const requestId = idOf(result, 'requestId', 'req_');
+    const version = typeof result.version === 'number' ? result.version : 1;
+    if (!requestId)
+        throw new McpFailure(-32000, 'Pending You posted no card.');
+    const card = { requestId, version, key: prompt.key, name };
+    const kept = await record(io, state.session, worker, (state) => {
+        state.card = card;
+        state.areaId = areaId;
+    });
+    if (!kept)
+        await withdraw(io, client, card, state, 'answered').catch(() => { });
+}
+/** Whether the card is still in front of the person (get_request), with its version; null when it's closed. */
+async function stillOpen(client, card) {
+    const now = await client.call('get_request', { requestId: card.requestId, name: card.name });
+    const open = ['pending', 'snoozed', 'delegated'].includes(text(now.status)) && now.turn !== 'agent';
+    return open && typeof now.version === 'number' ? now.version : null;
+}
+/** Changes the card to the newest prompt; a card that closed meanwhile is let go, and the next step posts anew. */
+async function update(io, client, state, prompt, worker) {
+    const card = state.card;
+    const machine = await computerOf(io, state.origin);
+    const words = cardWords(io, state, prompt, card.name, machine);
+    const change = (expectedVersion) => client.call('update_request', {
+        requestId: card.requestId,
+        name: card.name,
+        expectedVersion,
+        changeNote: cut(prompt.doing === 'to answer its question'
+            ? `Now waiting for your answer: ${prompt.what}`
+            : `Now waiting for your OK: ${prompt.what}`, 120),
+        title: prompt.title,
+        summary: words.summary,
+        action: words.action,
+    });
+    let result;
+    try {
+        result = await change(card.version);
+    }
+    catch (error) {
+        if (!(error instanceof ToolRefused))
+            throw error;
+        const version = await stillOpen(client, card);
+        if (version === null) {
+            await record(io, state.session, worker, (state) => {
+                if (state.card?.requestId === card.requestId)
+                    delete state.card;
+            });
+            return;
+        }
+        result = await change(version);
+    }
+    const version = typeof result.version === 'number' ? result.version : card.version + 1;
+    await record(io, state.session, worker, (state) => {
+        if (state.card?.requestId === card.requestId)
+            state.card = { ...card, version, key: prompt.key };
+    });
+}
+/** Withdraws a card: answered in Claude Code (answeredHere), or the session ended before anyone answered. */
+async function withdraw(io, client, card, state, how) {
+    const machine = await computerOf(io, state.origin);
+    try {
+        await client.call('cancel_request', {
+            requestId: card.requestId,
+            name: card.name,
+            reason: how === 'answered'
+                ? cut(`Answered in Claude Code on ${machine}.`, 200)
+                : cut(`That Claude Code session on ${machine} ended, so it isn’t waiting any more.`, 200),
+            ...(how === 'answered' ? { answeredHere: true } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ToolRefused))
+            throw error;
+        // Closed already. One they pressed Done on waits for its agent to acknowledge it: done here, so nobody is told.
+        const now = await client
+            .call('get_request', { requestId: card.requestId, name: card.name })
+            .catch(() => null);
+        if (now?.status === 'answered' && typeof now.version === 'number')
+            await client
+                .call('ack_answer', {
+                requestId: card.requestId,
+                name: card.name,
+                expectedVersion: now.version,
+                outcome: cut(`Answered in Claude Code on ${machine}.`, 200),
+            })
+                .catch(() => { });
+    }
+}
+/** Renews the worker's lease; false once the session isn't its own. */
+const renew = (io, session, worker) => record(io, session, worker, () => { });
+/**
+ * Lets the session go once nothing is left to do, under its lock, so an event written meanwhile is never missed: true
+ * when it's let go (and the file removed when nothing is in it), false when there's more to do.
+ */
+async function letGo(io, session, worker, grace) {
+    let done = true;
+    await change(io, session, (state) => {
+        if (!state || state.worker?.id !== worker)
+            return state;
+        if (planFor(state, io.now(), grace).kind !== 'done') {
+            done = false;
+            return state;
+        }
+        delete state.worker;
+        return state.prompts.length === 0 && !state.card ? null : state;
+    });
+    return done;
+}
+/** Removes files left by sessions that never ended cleanly. */
+async function prune(io) {
+    const folder = folderOf(io);
+    const names = await readdir(folder).catch(() => []);
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const path = join(folder, name);
+        const info = await stat(path).catch(() => null);
+        if (info && Date.now() - info.mtimeMs > KEEP_MS)
+            await rm(path, { force: true });
+    }
+}
+/**
+ * `pendingyou permission-card --session <id> --worker <id>`: the session's worker, detached and quiet. Posts, changes
+ * and withdraws the session's one card until nothing is left to do, then lets the session go. A step that keeps
+ * failing is given up (a post: its prompts get no card; a withdrawal: the card is forgotten); a sign-in that has ended
+ * gives everything up.
+ */
+export async function permissionWorker(io, options) {
+    const { session, worker } = options;
+    if (!SESSION.test(session))
+        return 0;
+    const started = io.now();
+    const grace = graceOf(io.env);
+    let client = null;
+    let failures = 0;
+    try {
+        while (!io.signal.aborted && io.now() - started < WORKER_MS) {
+            const state = await load(io, session);
+            if (!state || state.worker?.id !== worker)
+                return 0;
+            const plan = planFor(state, io.now(), grace);
+            if (plan.kind === 'done') {
+                if (await letGo(io, session, worker, grace)) {
+                    await prune(io).catch(() => { });
+                    return 0;
+                }
+                continue;
+            }
+            if (!(await renew(io, session, worker)))
+                return 0;
+            if (plan.kind === 'wait') {
+                await io.sleep(Math.min(plan.ms, NAP_MS), io.signal);
+                continue;
+            }
+            try {
+                client ??= await mcpClient(io, state.origin, 'claude-code', CALL_MS);
+                if (plan.kind === 'post')
+                    await post(io, client, state, plan.prompt, worker);
+                else if (plan.kind === 'update')
+                    await update(io, client, state, plan.prompt, worker);
+                else {
+                    const card = state.card;
+                    await withdraw(io, client, card, state, state.settled ?? 'answered');
+                    await record(io, session, worker, (state) => {
+                        if (state.card?.requestId === card.requestId)
+                            delete state.card;
+                    });
+                }
+                failures = 0;
+            }
+            catch (error) {
+                client = null;
+                // The sign-in has ended: nothing here can reach Pending You until init runs again.
+                if (error instanceof McpFailure && error.code === SIGN_IN_ERROR) {
+                    await change(io, session, (state) => (state?.worker?.id === worker ? null : state));
+                    return 0;
+                }
+                if (failures >= BACKOFF_MS.length) {
+                    failures = 0;
+                    await record(io, session, worker, (state) => {
+                        if (plan.kind === 'post')
+                            state.prompts = state.prompts.map((prompt) => ({ ...prompt, failed: true }));
+                        else if (plan.kind === 'update' && state.card)
+                            state.card = { ...state.card, key: plan.prompt.key };
+                        else
+                            delete state.card;
+                    });
+                    continue;
+                }
+                await io.sleep(BACKOFF_MS[failures++], io.signal);
+            }
+        }
+        return 0;
+    }
+    finally {
+        await client?.close().catch(() => { });
+    }
+}
+/** What uninstall says it took away, when there was anything. */
+export async function removePermissionFiles(io) {
+    const folder = folderOf(io);
+    const there = await stat(folder).then(() => true, () => false);
+    await rm(folder, { recursive: true, force: true });
+    return there;
+}