@kammcs/buildit-mcp 0.2.0 → 0.7.0

package/dist/channel/mask.js

@@ -0,0 +1,365 @@
+/**
+ * What a tool approval card's details hold, and how they are made safe to
+ * show.
+ *
+ * Claude Code's PermissionRequest hook passes the tool call's raw input.
+ * Before any of it leaves this process, every value is cleaned (control and
+ * bidi characters removed), credential-shaped text in it is replaced with
+ * `[REDACTED]`, and long values are cut. buildIt.Social cleans and masks the
+ * stored details again with the same rules, so a second pass changes nothing
+ * this one already did (the rules are idempotent).
+ *
+ * The rules are a list of known shapes: private key blocks, Authorization
+ * headers and bearer tokens, passwords in URLs, password and token options
+ * and assignments, the prefixes of well-known API keys, and JSON Web Tokens;
+ * plus any field whose name says it is a secret. A secret without a known
+ * shape is not caught.
+ */
+/* eslint-disable no-control-regex, no-misleading-character-class -- removing control, combining and variation characters is the point */
+/**
+ * Removed from every value: control characters but the line feed and tab,
+ * the soft hyphen, bidi controls, zero-width and invisible joiners and
+ * separators, variation selectors, the byte order mark and tag characters.
+ */
+const STRIP = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u00AD\u034F\u061C\u180E\u200B-\u200F\u202A-\u202E\u2060\u2066-\u2069\uFE00-\uFE0F\uFEFF\u{E0000}-\u{E007F}]/gu;
+/* eslint-enable no-control-regex, no-misleading-character-class */
+/** What replaces a secret. */
+export const REDACTED = '[REDACTED]';
+/**
+ * A value as it may be shown: CR LF, CR, and the Unicode line and paragraph
+ * separators become line feeds; the other control characters, bidi controls,
+ * zero-width characters and the byte order mark go. Line feeds and tabs stay.
+ */
+export function cleanApprovalText(text) {
+    return text
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\u2028\u2029]/g, '\n')
+        .replace(STRIP, '');
+}
+/** A field's name: cleaned, its line feeds and tabs folded to spaces, trimmed. */
+export function cleanApprovalKey(text) {
+    return cleanApprovalText(text)
+        .replace(/[\n\t]/g, ' ')
+        .trim();
+}
+/**
+ * The masking rules, in the order they apply. Each replaces only the secret.
+ *
+ * **Masking never hides what is being approved.** A span becomes
+ * `[REDACTED]` only when all of it is in the token charset
+ * `[A-Za-z0-9._~+=-]`: never shell syntax, a path, a URL, a space or a line
+ * break. A value that holds anything else (`"$(curl … | sh)"`, a path) is
+ * shown as it is, and quotes around a value stay. A key block is masked
+ * only when every line between its BEGIN and END lines is armor (base64, or
+ * a `Name: value` header). Masking twice gives what masking once gave
+ * (`[REDACTED]` is not in the token charset).
+ *
+ * They are written so that no input makes them slow: a match may start only
+ * where a lookbehind allows it (the start of a name, a token, an option or
+ * a URL, never inside a run of letters), names are at most 64 characters
+ * and spaces 16, and the alternatives of a value start differently, so a
+ * regular expression engine that takes the longest match gives the same
+ * result as this one (which takes the first alternative).
+ */
+const RULES = [
+    // R1: a PEM or PGP private key block whose body is all armor, to its END line or the end.
+    {
+        pattern: /-----BEGIN [A-Z0-9 ]{0,64}PRIVATE KEY(?: BLOCK)?-----\n(?:(?:[A-Za-z0-9+/=]*|[A-Za-z0-9-]{1,64}: [A-Za-z0-9._~+= -]*)\n)*?(?:-----END [A-Z0-9 ]{0,64}PRIVATE KEY(?: BLOCK)?-----|(?:[A-Za-z0-9+/=]*|[A-Za-z0-9-]{1,64}: [A-Za-z0-9._~+= -]*)$)/g,
+        replacement: REDACTED,
+    },
+    // R2: an Authorization header's credentials (its quotes may be JSON-escaped).
+    {
+        pattern: /(authorization(?:\\?["'])?[ \t\n\v\f\r]{0,16}[:=][ \t\n\v\f\r]{0,16}(?:\\?["'])?(?:bearer|basic|token|bot)[ \t\n\v\f\r]{1,16})[A-Za-z0-9._~+=-]+(?![^ \t\n\v\f\r"'\\&;,])/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // R3: a bearer token anywhere.
+    {
+        pattern: /(?<![A-Za-z0-9_])(bearer[ \t\n\v\f\r]{1,16})[A-Za-z0-9._~+=-]{16,}(?![^ \t\n\v\f\r"'\\&;,])/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // R4: the password in a URL's user info (the host after it stays).
+    {
+        pattern: /(?<![a-z0-9+.-])([a-z][a-z0-9+.-]{0,31}:\/\/[^/ \t\n\v\f\r:@]{1,64}:)[A-Za-z0-9._~+=-]+@/gi,
+        replacement: `$1${REDACTED}@`,
+    },
+    // R5: a password, secret, token or API key option's value (--password x, --token=x),
+    // plain or in quotes (which stay).
+    {
+        pattern: /(?<![^ \t\n\v\f\r])(--?[A-Za-z0-9-]{0,64}(?:password|passwd|secret|token|api-?key)(?:[ \t\n\v\f\r]{1,16}|=)(?:"(?=[A-Za-z0-9._~+=-]+")|'(?=[A-Za-z0-9._~+=-]+')|(?=[A-Za-z0-9._~+=-]+(?![^ \t\n\v\f\r]))))[A-Za-z0-9._~+=-]+/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // R6: an assignment or JSON member whose name says it holds a secret: the value
+    // plain, in quotes, or in JSON-escaped quotes inside a shell string (the quotes stay).
+    {
+        pattern: /(?<![A-Za-z0-9_-])([A-Za-z0-9_-]{0,64}(?:password|passwd|secret|token|api[_-]?key|apikey|private[_-]?key|access[_-]?key)(?:\\?["'])?[ \t\n\v\f\r]{0,16}[:=][ \t\n\v\f\r]{0,16}(?:\\"(?=[A-Za-z0-9._~+=-]+\\")|"(?=[A-Za-z0-9._~+=-]+")|'(?=[A-Za-z0-9._~+=-]+')|(?=[A-Za-z0-9._~+=-]+(?![^ \t\n\v\f\r"'\\&;,]))))[A-Za-z0-9._~+=-]+/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // R7: well-known API key and token prefixes.
+    {
+        pattern: /(?<![A-Za-z0-9_])(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|sk-[A-Za-z0-9_-]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|xapp-[A-Za-z0-9-]{10,}|(?:AKIA|ASIA)[A-Z0-9]{16}|AIza[A-Za-z0-9_-]{30,}|[sr]k_(?:live|test)_[A-Za-z0-9]{10,}|whsec_[A-Za-z0-9]{10,}|buildit_(?:pat|ags|app)_[A-Za-z0-9]{10,}|buildit_whsec_[0-9a-f]{10,})/g,
+        replacement: REDACTED,
+    },
+    // R8: a JSON Web Token.
+    {
+        pattern: /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]*)?/g,
+        replacement: REDACTED,
+    },
+];
+/** R9: a field whose name says its whole value is a secret. */
+const SECRET_KEY = /^[A-Za-z0-9_-]{0,64}(?:password|passwd|secret|token|api[_-]?key|apikey|private[_-]?key|access[_-]?key|authorization|credentials?)$/i;
+/** The only characters a masked span may hold. */
+const TOKEN_CHARSET = /^[A-Za-z0-9._~+=-]+$/;
+/** Replaces every credential-shaped part of a text with `[REDACTED]` (rules R1 to R8). */
+export function maskCredentials(text) {
+    let out = text;
+    for (const rule of RULES)
+        out = out.replace(rule.pattern, rule.replacement);
+    return out;
+}
+/**
+ * A field's value masked: R1 to R8, then, when the field's name is a
+ * secret's and the (masked) value is all token charset, the whole value
+ * (R9). A value with anything else in it keeps what R1 to R8 made of it.
+ */
+export function maskField(key, value) {
+    const masked = maskCredentials(value);
+    return SECRET_KEY.test(key) && TOKEN_CHARSET.test(masked) ? REDACTED : masked;
+}
+// ---------------------------------------------------------------------------
+// Cutting
+// ---------------------------------------------------------------------------
+/** The longest value kept whole, in code points. */
+export const VALUE_MAX = 3500;
+/** What a cut value keeps: its first and last code points around the marker. */
+export const VALUE_HEAD = 2400;
+export const VALUE_TAIL = 1000;
+/** Marks where a value was cut. */
+export const CUT_MARKER = '\n⋯\n';
+const MARKER_LENGTH = Array.from(CUT_MARKER).length;
+/** The longest description, in code points. */
+export const DESCRIPTION_MAX = 1000;
+/** The longest field name, in code points. */
+export const KEY_MAX = 100;
+/** At most this many fields; the rest are counted in more_fields. */
+export const FIELDS_MAX = 20;
+/** The details' JSON, in UTF-8 bytes, at most. */
+export const DETAILS_MAX_BYTES = 12_288;
+/** A value is never cut below this many code points to fit the details' size; fields go instead. */
+const VALUE_FLOOR = 200;
+/**
+ * Before masking, a value over this many code points keeps only its first
+ * and last PRECUT_KEEP (so masking a huge input stays fast; it is cut far
+ * below this afterwards anyway).
+ */
+export const PRECUT_MAX = 16_384;
+export const PRECUT_KEEP = 8_192;
+/** The text cut to `max` code points with "…", only when it is longer. */
+function cutWithEllipsis(text, max) {
+    const chars = Array.from(text);
+    return chars.length <= max ? text : chars.slice(0, max - 1).join('') + '…';
+}
+/** The pre-cut marker's place: the marker nearest the middle. */
+function markerIndex(chars) {
+    let best = -1;
+    const middle = chars.length / 2;
+    for (let i = 0; i + 2 < chars.length; i++) {
+        if (chars[i] === '\n' && chars[i + 1] === '⋯' && chars[i + 2] === '\n') {
+            if (best < 0 || Math.abs(i - middle) < Math.abs(best - middle))
+                best = i;
+        }
+    }
+    return best;
+}
+/** Cleans a value, cuts it to its ends when it is huge, and masks it. */
+function prepare(text, mask) {
+    const cleaned = Array.from(cleanApprovalText(text));
+    if (cleaned.length <= PRECUT_MAX) {
+        return { chars: Array.from(mask(cleaned.join(''))), base: 0, markerAt: -1 };
+    }
+    const pre = cleaned.slice(0, PRECUT_KEEP).join('') +
+        CUT_MARKER +
+        cleaned.slice(cleaned.length - PRECUT_KEEP).join('');
+    const chars = Array.from(mask(pre));
+    return { chars, base: cleaned.length - 2 * PRECUT_KEEP, markerAt: markerIndex(chars) };
+}
+/**
+ * A value cut to its first `head` and last `tail` code points around the
+ * marker, and how many of the original code points were left out (the
+ * pre-cut's too, but not its marker).
+ */
+function keepEnds(p, head, tail) {
+    const n = p.chars.length;
+    if (head + tail >= n)
+        return { value: p.chars.join(''), cut: p.base };
+    const removedMarker = p.markerAt < 0
+        ? 0
+        : Math.max(0, Math.min(p.markerAt + MARKER_LENGTH, n - tail) - Math.max(p.markerAt, head));
+    return {
+        value: p.chars.slice(0, head).join('') + CUT_MARKER + p.chars.slice(n - tail).join(''),
+        cut: p.base + (n - head - tail) - removedMarker,
+    };
+}
+/** A value over 3,500 code points: its first 2,400 and last 1,000, with the marker between. */
+export function cutValue(value) {
+    const chars = Array.from(value);
+    if (chars.length <= VALUE_MAX)
+        return { value, cut: 0 };
+    return keepEnds({ chars, base: 0, markerAt: -1 }, VALUE_HEAD, VALUE_TAIL);
+}
+const bytesOf = (details) => Buffer.byteLength(JSON.stringify(details), 'utf8');
+function assemble(description, fields, more) {
+    return {
+        ...(description === undefined ? {} : { description }),
+        fields: fields.map((f) => ({
+            key: f.key,
+            value: f.value,
+            ...(f.cut > 0 ? { cut: f.cut } : {}),
+        })),
+        ...(more > 0 ? { more_fields: more } : {}),
+    };
+}
+/**
+ * The details of a tool call, cleaned, masked and cut: for Bash and
+ * PowerShell a string `description` is the description; every other
+ * top-level key of the input, in order, is a field (a string as it is,
+ * anything else as indented JSON). Each value is cleaned, cut to its first
+ * and last 8,192 code points when it is over 16,384 (so masking stays
+ * fast), masked, then cut past 3,500 code points; at most 20 fields; then, while the JSON is over
+ * 12 KB, the longest value is cut to half (never below 200 code points),
+ * and once none is longer than that, fields are dropped from the end.
+ */
+export function buildDetails(toolName, input) {
+    let description;
+    const entries = Object.entries(input);
+    const pending = [];
+    let more = 0;
+    for (const [rawKey, raw] of entries) {
+        if ((toolName === 'Bash' || toolName === 'PowerShell') &&
+            rawKey === 'description' &&
+            typeof raw === 'string') {
+            const text = prepare(raw, maskCredentials).chars.join('').trim();
+            if (text !== '')
+                description = cutWithEllipsis(text, DESCRIPTION_MAX);
+            continue;
+        }
+        if (pending.length >= FIELDS_MAX) {
+            more++;
+            continue;
+        }
+        const cleanedKey = cleanApprovalKey(rawKey);
+        // A key is shown too, so it is masked like a value (R9 reads the name as given).
+        const shownKey = maskCredentials(cleanedKey);
+        const key = cutWithEllipsis(shownKey === '' ? '_' : shownKey, KEY_MAX);
+        const text = typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2);
+        const full = prepare(text, (value) => maskField(cleanedKey, value));
+        const first = full.chars.length > VALUE_MAX
+            ? keepEnds(full, VALUE_HEAD, VALUE_TAIL)
+            : { value: full.chars.join(''), cut: full.base };
+        pending.push({ key, full, value: first.value, cut: first.cut });
+    }
+    let details = assemble(description, pending, more);
+    while (bytesOf(details) > DETAILS_MAX_BYTES && pending.length > 0) {
+        const lengths = pending.map((f) => Array.from(f.value).length);
+        const longest = lengths.indexOf(Math.max(...lengths));
+        const field = pending[longest];
+        const kept = lengths[longest] ?? 0;
+        if (field !== undefined && kept > VALUE_FLOOR) {
+            // Cut again from the whole value: what is kept, the marker counted in.
+            const target = Math.max(VALUE_FLOOR, Math.floor(kept / 2)) - MARKER_LENGTH;
+            const head = Math.ceil((target * 2) / 3);
+            const again = keepEnds(field.full, head, target - head);
+            field.value = again.value;
+            field.cut = again.cut;
+        }
+        else {
+            pending.pop();
+            more++;
+        }
+        details = assemble(description, pending, more);
+    }
+    return details;
+}
+const TOOL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$/;
+const RULE_FORBIDDEN = 
+// eslint-disable-next-line no-control-regex -- control characters disqualify a rule
+/[\u0000-\u001F\u007F-\u009F\u061C\u200B-\u200F\u202A-\u202E\u2060\u2066-\u2069\uFEFF]/;
+const RULE_CONTENT_MAX = 500;
+const RULES_MAX = 5;
+const RULE_MAX_BYTES = 2048;
+const isPlain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const hasOnly = (o, keys) => Object.keys(o).every((k) => keys.includes(k));
+/** One suggestion as a session rule, or undefined when it isn't exactly one. */
+function asSessionRule(entry, toolName) {
+    if (!isPlain(entry) || entry.destination !== 'session')
+        return undefined;
+    if (entry.type === 'setMode') {
+        if (!hasOnly(entry, ['type', 'mode', 'destination']) || entry.mode !== 'acceptEdits') {
+            return undefined;
+        }
+        return { type: 'setMode', mode: 'acceptEdits', destination: 'session' };
+    }
+    if (entry.type !== 'addRules' || entry.behavior !== 'allow')
+        return undefined;
+    if (!hasOnly(entry, ['type', 'rules', 'behavior', 'destination']))
+        return undefined;
+    const rules = entry.rules;
+    if (!Array.isArray(rules) || rules.length < 1 || rules.length > RULES_MAX)
+        return undefined;
+    const out = [];
+    for (const r of rules) {
+        if (!isPlain(r) || !hasOnly(r, ['toolName', 'ruleContent']))
+            return undefined;
+        if (typeof r.toolName !== 'string' || !TOOL_NAME_RE.test(r.toolName))
+            return undefined;
+        // A rule only for the tool that asks: never another tool's.
+        if (r.toolName !== toolName)
+            return undefined;
+        if (r.ruleContent === undefined) {
+            out.push({ toolName: r.toolName });
+            continue;
+        }
+        if (typeof r.ruleContent !== 'string')
+            return undefined;
+        // Cleaned by the strip rules only; a line feed or tab left in it disqualifies it.
+        const content = cleanApprovalText(r.ruleContent);
+        const chars = Array.from(content).length;
+        if (chars < 1 || chars > RULE_CONTENT_MAX || RULE_FORBIDDEN.test(content))
+            return undefined;
+        out.push({ toolName: r.toolName, ruleContent: content });
+    }
+    const rule = {
+        type: 'addRules',
+        rules: out,
+        behavior: 'allow',
+        destination: 'session',
+    };
+    return Buffer.byteLength(JSON.stringify(rule), 'utf8') <= RULE_MAX_BYTES ? rule : undefined;
+}
+/**
+ * The session rule to offer, from Claude Code's permission_suggestions (an
+ * array, or its JSON text): the first entry that is exactly a session-scoped
+ * allow rule (1 to 5 rules, each for the tool that asks) or "accept edits
+ * for the session". Anything else (another destination, a directory grant,
+ * another mode, a rule for another tool) is never offered.
+ */
+export function sessionRuleFrom(suggestions, toolName) {
+    let list = suggestions;
+    if (typeof list === 'string') {
+        if (list.trim() === '' || list.startsWith('${'))
+            return undefined;
+        try {
+            list = JSON.parse(list);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!Array.isArray(list))
+        return undefined;
+    for (const entry of list) {
+        const rule = asSessionRule(entry, toolName);
+        if (rule !== undefined)
+            return rule;
+    }
+    return undefined;
+}

package/dist/channel/threads.js

@@ -0,0 +1,60 @@
+/**
+ * Which thread a channel tool (reply, ask, an approval card) posts in.
+ *
+ * A thread named by `thread_id`, or a work item's by `item` (its key: its
+ * id comes from the items the events named, else from get_item; the
+ * item's id is its thread's). Without either, the thread of the latest
+ * message, mention or assignment, but only while one thread is active:
+ * once the session works in several (an item's thread besides the direct
+ * message, or two items; the lead's item workers post in parallel through
+ * this one server), "the latest" could be another worker's, so a thread
+ * must be named, and the refusal lists the active ones.
+ */
+import { ToolInputError } from '../errors.js';
+import { sanitizeLabel } from '../untrusted.js';
+const UUID_RE = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+export const isUuid = (s) => UUID_RE.test(s);
+/** An item reference as the tools take it (a leading # is fine). */
+const keyOf = (ref) => (ref.startsWith('#') ? ref.slice(1) : ref);
+/** An item's thread id: its own id, from the events' items or read with get_item. */
+export async function itemThreadId(ref, ctx) {
+    const key = keyOf(ref);
+    if (isUuid(key))
+        return key;
+    const known = ctx.channel?.items.get(key.toUpperCase());
+    if (known !== undefined)
+        return known;
+    const { item } = await ctx.call('get_item', { path: { key } });
+    ctx.channel?.rememberItem(item.key, item.id);
+    return item.id;
+}
+/** The refusal when several threads are active and none was named. */
+export function threadRequiredMessage(state, tool, how) {
+    const listed = state
+        .activeThreads()
+        .map((t) => t.item === undefined
+        ? `your direct message (thread_id ${t.thread_id})`
+        : `${sanitizeLabel(t.item, 40)} (thread_id ${t.thread_id})`);
+    return `This session works in several threads now, so ${tool} needs ${how}: ${listed.join('; ')}. Name the thread of the message or item you are working on (list_threads shows them all).`;
+}
+/**
+ * The thread to post in: `item`'s, `thread_id`, else the latest one while
+ * only one thread is active (undefined: none yet, a new message of the
+ * direct message). Throws ToolInputError for a conflict, or when several
+ * threads are active and none is named.
+ */
+export async function resolveThread(state, ctx, given, tool, how = 'thread_id or item') {
+    const fromItem = given.item === undefined ? undefined : await itemThreadId(given.item, ctx);
+    if (fromItem !== undefined &&
+        given.thread_id !== undefined &&
+        given.thread_id.toLowerCase() !== fromItem.toLowerCase()) {
+        throw new ToolInputError("Give item or thread_id, not both: item's thread is the item's own id, and this thread_id is another thread.");
+    }
+    const named = fromItem ?? given.thread_id;
+    if (named !== undefined)
+        return named;
+    if (state.activeThreads().length > 1) {
+        throw new ToolInputError(threadRequiredMessage(state, tool, how));
+    }
+    return state.lastThreadId;
+}

package/dist/channel/tool-ring.js

@@ -0,0 +1,124 @@
+/**
+ * The recent tool calls Claude Code announced (the plugin's PreToolUse hook,
+ * `tool_seen`), so a tool approval can name the call it is for.
+ *
+ * Claude Code's PermissionRequest hook gets no `tool_use_id`, but PreToolUse
+ * fires for the same call just before it, with the same input and agent id,
+ * and with the id. So `tool_seen` records each call (its agent, tool, a hash
+ * of its input and its id), and `approve` claims the oldest unclaimed entry
+ * that matches. An answer in the terminal then shows as such in the app: the
+ * call's PostToolUse names that id (`tool_done`).
+ *
+ * Only these four values are kept, for 10 seconds, at most 256 entries; the
+ * input itself never is.
+ */
+import { createHash } from 'node:crypto';
+/** How many calls are remembered. */
+export const RING_SIZE = 256;
+/** How long a call is remembered. */
+export const RING_TTL_MS = 10_000;
+/** How old a call may be for an approval to claim it. */
+export const CLAIM_MAX_AGE_MS = 5_000;
+/** JSON with every object's keys sorted, at every level, and no spaces. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const o = value;
+        return `{${Object.keys(o)
+            .sort()
+            .filter((k) => o[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** The hex SHA-256 of a tool input's canonical JSON. */
+export function inputHash(input) {
+    return createHash('sha256').update(canonicalJson(input), 'utf8').digest('hex');
+}
+/**
+ * A tool input as the hooks pass it (`${tool_input}` is JSON text; an object
+ * works too): the object, or undefined when it isn't one.
+ */
+export function parseToolInput(value) {
+    let raw = value;
+    if (typeof raw === 'string') {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : undefined;
+}
+export class ToolRing {
+    now;
+    entries = [];
+    listeners = new Set();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** How many calls are remembered (tests). */
+    get size() {
+        this.prune();
+        return this.entries.length;
+    }
+    /** A call Claude Code is about to make (PreToolUse). */
+    record(init) {
+        this.prune();
+        this.entries.push({ ...init, at: this.now(), claimed: false });
+        while (this.entries.length > RING_SIZE)
+            this.entries.shift();
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    /**
+     * The oldest unclaimed call that matches, at most 5 seconds old: its id,
+     * now claimed. Claude Code asks for permission in the order it announced
+     * the calls, so the oldest is the one asking.
+     */
+    claim(agentId, toolName, hash) {
+        const oldest = this.now() - CLAIM_MAX_AGE_MS;
+        for (const e of this.entries) {
+            if (e.at < oldest)
+                continue;
+            if (e.claimed || e.agentId !== agentId || e.toolName !== toolName || e.hash !== hash) {
+                continue;
+            }
+            e.claimed = true;
+            return e.toolUseId;
+        }
+        return undefined;
+    }
+    /** claim, waiting up to `waitMs` for the call to be recorded. */
+    async claimSoon(agentId, toolName, hash, waitMs) {
+        const found = this.claim(agentId, toolName, hash);
+        if (found !== undefined || waitMs <= 0)
+            return found;
+        return new Promise((resolve) => {
+            const listener = () => {
+                const id = this.claim(agentId, toolName, hash);
+                if (id !== undefined)
+                    finish(id);
+            };
+            const timer = setTimeout(() => {
+                finish(this.claim(agentId, toolName, hash));
+            }, waitMs);
+            const finish = (id) => {
+                clearTimeout(timer);
+                this.listeners.delete(listener);
+                resolve(id);
+            };
+            this.listeners.add(listener);
+        });
+    }
+    prune() {
+        const oldest = this.now() - RING_TTL_MS;
+        while (this.entries.length > 0 && (this.entries[0]?.at ?? 0) < oldest)
+            this.entries.shift();
+    }
+}