@aimarket/warden 0.23.0 → 0.24.0

package/codex-hooks/scripts/flow-guard-codex.mjs

@@ -0,0 +1,222 @@
+// GENERATED from src/flow-guard-codex.ts by scripts/sync-flow-guard.mjs. Do not edit; run npm run build.
+/**
+ * WARDEN flow guard for OpenAI Codex (CLI, desktop app, `codex exec`, a Multica runtime): the checks of the Claude
+ * Code plugin, through Codex's command hooks (`hooks.json`, `[hooks]` in `config.toml` or `requirements.toml`).
+ *
+ * Codex hooks speak nearly the Claude Code hook protocol: the same events, `tool_name`/`tool_input`/`tool_response`,
+ * `hookSpecificOutput.permissionDecision`. Three differences decide this adapter:
+ *
+ * - **No `ask`.** Codex does not support `permissionDecision: "ask"` in PreToolUse: the hook run counts as failed and
+ *   THE TOOL CALL CONTINUES. Passing the Claude Code decision through would let every questioned call run. Every
+ *   `ask` therefore becomes `deny` or a logged pass, by `block` (see flow-guard-unattended.ts); this adapter never
+ *   prints `ask`.
+ * - **A failed hook does not stop the call.** An exception in a hook, or output Codex cannot parse, lets the tool
+ *   run. Every path of PreToolUse that is not a clean "no decision" prints a deny, and a PostToolUse that could not
+ *   record its result marks the session, so every later call of that session is denied.
+ * - **Tool names.** Shell and unified exec arrive as `Bash` with `tool_input.command`; edits as `apply_patch` with the
+ *   patch in `tool_input.command`; MCP tools as `mcp__<server>__<tool>`; other local tools by their own name.
+ *   Subagent hooks carry the parent's `session_id`, so a session tree shares one guard state without extra work.
+ *
+ * Codex's own session ids are namespaced (`codex:<id>`) so they never share state with a Claude Code session.
+ * Hosted tools (Codex's own web search) run no local hook: what they bring in is not recorded. Turn web search off
+ * for a guarded agent (`web_search = "disabled"`) or accept that gap.
+ *
+ * Node built-ins and flow-guard parts only: `codex-plugin/scripts` holds copies that run without the package.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { flowPaths, stateDir } from './flow-guard-paths.mjs';
+import { flowPost } from './flow-guard-post.mjs';
+import { flowPrompt, flowStop } from './flow-guard-answer.mjs';
+import { flowPre } from './flow-guard-pre.mjs';
+import { log } from './flow-guard-state.mjs';
+import { blockMode, patchFiles, refuses } from './flow-guard-unattended.mjs';
+/** Local tools that only change Codex's own session state: no data in, no data out. */
+const IGNORED = new Set(['update_plan', 'request_user_input', 'list_mcp_resources', 'list_mcp_resource_templates']);
+const SHELLS = /^(?:\/(?:usr\/)?bin\/)?(?:ba|z|da|k)?sh$/;
+// A PostToolUse input carries the whole tool result (a large file read); too small a cap would skip fingerprinting it.
+const STDIN_BYTES = 16 * 1_048_576;
+function obj(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+/** The shell text of a Codex command: a string, or an argv where `bash -lc "<script>"` means its script. */
+export function commandText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value) || !value.every(v => typeof v === 'string'))
+        return value === undefined ? '' : JSON.stringify(value);
+    const argv = value;
+    const flag = argv.findIndex((a, i) => i > 0 && /^-[a-z]*c[a-z]*$/.test(a));
+    if (argv.length >= 3 && SHELLS.test(argv[0]) && flag > 0 && flag === argv.length - 2)
+        return argv[argv.length - 1];
+    // Quote each word, so a word with a space stays one word for the guard's shell parser.
+    return argv.map(a => /^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`).join(' ');
+}
+/** One Codex tool call in the guard's (Claude Code) vocabulary: zero, one or, for a multi-file patch, several calls. */
+export function codexGuardCalls(toolName, rawInput) {
+    const a = obj(rawInput);
+    if (IGNORED.has(toolName))
+        return [];
+    if (toolName.startsWith('mcp__'))
+        return [{ name: toolName, input: a }];
+    switch (toolName) {
+        case 'Bash':
+        case 'shell':
+        case 'exec_command':
+        case 'local_shell':
+        case 'unified_exec':
+            return [{ name: 'Bash', input: { command: commandText(a.command ?? a.cmd) } }];
+        case 'apply_patch':
+        case 'Edit':
+        case 'Write': {
+            const text = str(a.command) ?? str(a.patch) ?? str(a.input) ?? (typeof rawInput === 'string' ? rawInput : '');
+            const files = patchFiles(text);
+            // An unparsable patch is still a write of its whole text somewhere.
+            return (files.length ? files : ['']).map(f => ({ name: 'Write', input: { file_path: f, content: text } }));
+        }
+        case 'view_image': {
+            const path = str(a.path) ?? str(a.file_path);
+            return [{ name: 'Read', input: path ? { file_path: path } : {} }];
+        }
+        case 'write_stdin':
+            // Input to a running command: its text is what that command receives.
+            return [{ name: 'Bash', input: { command: str(a.chars) ?? str(a.input) ?? '' } }];
+    }
+    // Anything else (spawn_agent, a plugin's tool) is an unlabelled tool: its result is outside text, and it sends
+    // when its name or arguments say so.
+    return [{ name: `mcp__codex__${toolName.replace(/[^A-Za-z0-9_-]/g, '_')}`, input: a }];
+}
+/** The guard's session id for a Codex session: namespaced, so it never shares state with a Claude Code session. */
+export function codexSession(input) {
+    const id = str(input.session_id);
+    return id ? `codex:${id}` : '';
+}
+function brokenPath(env, sessionId) {
+    return join(stateDir(env), 'codex', 'broken', createHash('sha256').update(sessionId).digest('hex'));
+}
+function deny(reason) {
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } };
+}
+function settings(options) {
+    const env = options.env ?? process.env;
+    return { env, block: options.block ?? blockMode(env.WARDEN_CODEX_BLOCK) ?? 'data' };
+}
+function hookInput(input, call, sessionId) {
+    return { session_id: sessionId, tool_name: call.name, tool_input: call.input, cwd: str(input.cwd) || process.cwd(),
+        ...(input.tool_response !== undefined ? { tool_response: input.tool_response } : {}) };
+}
+/** PreToolUse: a deny, or undefined to let the call run. Never `ask` (Codex runs the call on `ask`). */
+export function codexPre(input, options = {}) {
+    const { env, block } = settings(options);
+    const sessionId = codexSession(input);
+    const tool = str(input.tool_name) ?? '';
+    if (!sessionId || !tool)
+        return deny('WARDEN flow guard got a Codex hook input without a session or tool name. Refused.');
+    if (existsSync(brokenPath(env, sessionId))) {
+        return deny('WARDEN flow guard could not record an earlier result of this session, so it cannot judge this call. Refused; start a new session.');
+    }
+    for (const call of codexGuardCalls(tool, input.tool_input)) {
+        const detail = {};
+        const decision = flowPre(hookInput(input, call, sessionId), env, 'hook', detail);
+        if (!decision)
+            continue;
+        const refused = refuses(decision, detail, block);
+        log(flowPaths(stateDir(env), sessionId), { event: 'codex', tool: call.name, decision: decision.permissionDecision,
+            reason: detail.reason, sensitive: !!detail.sensitive, resolution: refused ? 'refused' : 'allowed_unattended', block });
+        if (refused) {
+            return deny(`${decision.permissionDecisionReason}\nRefused by the WARDEN flow guard (Codex, block=${block}). Do not retry this call in another form; report what was refused.`);
+        }
+    }
+    return undefined;
+}
+/** PostToolUse: records what the result brought in. A failure marks the session so that later calls are denied. */
+export function codexPost(input, options = {}) {
+    const { env } = settings(options);
+    const sessionId = codexSession(input);
+    const tool = str(input.tool_name) ?? '';
+    if (!sessionId || !tool)
+        return undefined;
+    const warnings = [];
+    for (const call of codexGuardCalls(tool, input.tool_input)) {
+        let post;
+        try {
+            post = flowPost(hookInput(input, call, sessionId), env);
+        }
+        catch (err) {
+            markBroken(env, sessionId);
+            log(flowPaths(stateDir(env), sessionId), { event: 'codex', tool: call.name, resolution: 'record_failed', error: err instanceof Error ? err.name : 'error' });
+            continue;
+        }
+        const warning = post?.additionalContext || post?.systemMessage;
+        if (warning && !warnings.includes(warning))
+            warnings.push(warning);
+    }
+    return warnings.length ? { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: `[WARDEN] ${warnings.join('\n')}` } } : undefined;
+}
+function markBroken(env, sessionId) {
+    const path = brokenPath(env, sessionId);
+    mkdirSync(join(stateDir(env), 'codex', 'broken'), { recursive: true, mode: 0o700 });
+    writeFileSync(path, new Date().toISOString() + '\n', { mode: 0o600 });
+}
+/** UserPromptSubmit: the destinations the user's own message names. */
+export function codexPrompt(input, options = {}) {
+    const { env } = settings(options);
+    const sessionId = codexSession(input);
+    if (sessionId)
+        flowPrompt({ ...input, session_id: sessionId }, env);
+    return undefined;
+}
+/** Stop: the guard's note on the answer. `decision: block` makes Codex continue once with the reason as the prompt. */
+export function codexStop(input, options = {}) {
+    const { env } = settings(options);
+    const sessionId = codexSession(input);
+    return sessionId ? flowStop({ ...input, session_id: sessionId }, env) : undefined;
+}
+const EVENTS = ['pre-tool-use', 'post-tool-use', 'user-prompt-submit', 'stop'];
+/** One hook run: the stdout line, or undefined. Throws only on bad input; the caller turns that into a deny. */
+export function runCodexHook(event, stdin, options = {}) {
+    if (Buffer.byteLength(stdin) > STDIN_BYTES)
+        throw new Error('hook input too large');
+    const parsed = JSON.parse(stdin || '{}');
+    const input = obj(parsed);
+    if (input !== parsed)
+        throw new Error('hook input is not an object');
+    const out = event === 'pre-tool-use' ? codexPre(input, options) : event === 'post-tool-use' ? codexPost(input, options)
+        : event === 'user-prompt-submit' ? codexPrompt(input, options) : codexStop(input, options);
+    return out ? JSON.stringify(out) : undefined;
+}
+/** `codex-hook.mjs <event>` reads the Codex hook JSON on stdin. Fails closed for PreToolUse. */
+export function codexHookMain(argv = process.argv.slice(2), options = {}) {
+    const event = argv[0];
+    if (!EVENTS.includes(event)) {
+        process.stderr.write(`Usage: codex-hook.mjs ${EVENTS.join('|')}  (Codex command hook; reads the hook JSON on stdin)\n`);
+        // Codex reads a deny from stdout; a misconfigured PreToolUse hook must not let calls through.
+        process.stdout.write(JSON.stringify(deny('WARDEN Codex hook is misconfigured (unknown event). Refused.')) + '\n');
+        return 0;
+    }
+    let stdin = '';
+    try {
+        stdin = readFileSync(0, 'utf8');
+        const out = runCodexHook(event, stdin, options);
+        if (out)
+            process.stdout.write(out + '\n');
+    }
+    catch (err) {
+        process.stderr.write(`warden codex hook ${event}: ${err instanceof Error ? err.message : String(err)}\n`);
+        if (event === 'pre-tool-use')
+            process.stdout.write(JSON.stringify(deny('WARDEN flow guard could not safely check this call. Repair the guard state before retrying.')) + '\n');
+        if (event === 'post-tool-use') {
+            try {
+                const sessionId = codexSession(obj(JSON.parse(stdin || '{}')));
+                if (sessionId)
+                    markBroken(options.env ?? process.env, sessionId);
+            }
+            catch { /* the input itself is unreadable: nothing to mark */ }
+        }
+    }
+    return 0;
+}

package/codex-hooks/scripts/flow-guard-constraints.mjs

@@ -0,0 +1,69 @@
+// GENERATED from src/flow-guard-constraints.ts by scripts/sync-flow-guard.mjs. Do not edit; run npm run build.
+/** Optional host-supplied constraint evidence. No natural-language inference or permission grants. */
+import { createHash } from 'node:crypto';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const scalar = (value) => typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= 1e12;
+const id = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}$/.test(value);
+const field = (value) => typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(value) && !['constructor', 'prototype'].includes(value);
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const same = (a, b) => typeof a === typeof b && a === b;
+/** Fixed templates + finite scalars/positions only. No names, quotes, URLs or source-authored field labels. */
+export function checkAnswerConstraints(value, answer, sessionId, turn) {
+    const empty = (status) => ({ status, violations: [], unknownReferences: 0, text: status === 'invalid' ? 'WARDEN: constraint evidence is unavailable because the host check did not validate. This is not a passed check.' : '' });
+    if (value === undefined)
+        return empty('absent');
+    if (!object(value) || !exact(value, ['schema', 'sessionId', 'turn', 'answerSha256', 'rules', 'records', 'claims']) || value.schema !== 'warden-answer-check/1' ||
+        value.sessionId !== sessionId || !Number.isSafeInteger(value.turn) || value.turn < 1 || value.turn !== turn || value.answerSha256 !== hash(answer) ||
+        !Array.isArray(value.rules) || !value.rules.length || value.rules.length > 16 || !Array.isArray(value.records) || !value.records.length || value.records.length > 256 || !object(value.claims))
+        return empty('invalid');
+    const rules = [];
+    for (const candidate of value.rules) {
+        if (!object(candidate) || !exact(candidate, ['field', 'op', 'value']) || !field(candidate.field) || typeof candidate.op !== 'string' || !['lte', 'gte', 'eq'].includes(candidate.op) || !scalar(candidate.value) || candidate.op !== 'eq' && typeof candidate.value !== 'number')
+            return empty('invalid');
+        rules.push(candidate);
+    }
+    const records = [];
+    const seen = new Set();
+    for (const candidate of value.records) {
+        if (!object(candidate) || !exact(candidate, ['id', 'attributes']) || !id(candidate.id) || seen.has(candidate.id) || !object(candidate.attributes) || Object.keys(candidate.attributes).length > 32 ||
+            !Object.entries(candidate.attributes).every(([key, entry]) => field(key) && scalar(entry)))
+            return empty('invalid');
+        records.push(candidate);
+        seen.add(candidate.id);
+    }
+    const claims = value.claims;
+    if (!exact(claims, ['selectedId', 'eligibleIds']) || !id(claims.selectedId) || !Array.isArray(claims.eligibleIds) || claims.eligibleIds.length > 128 || !claims.eligibleIds.every(id) || new Set(claims.eligibleIds).size !== claims.eligibleIds.length)
+        return empty('invalid');
+    // Stable facts identity is independent of selected claims and the generated answer.
+    const factsSha256 = hash(JSON.stringify({ rules, records: records.map(record => ({ id: record.id, attributes: Object.fromEntries(Object.entries(record.attributes).sort(([a], [b]) => a.localeCompare(b))) })) }));
+    const map = new Map(records.map(record => [record.id, record]));
+    const referenced = [...new Set([claims.selectedId, ...claims.eligibleIds])];
+    const violations = [];
+    let unknownReferences = 0;
+    for (const itemId of referenced) {
+        const record = map.get(itemId);
+        if (!record) {
+            unknownReferences++;
+            continue;
+        }
+        for (const [index, rule] of rules.entries()) {
+            if (!Object.hasOwn(record.attributes, rule.field)) {
+                unknownReferences++;
+                continue;
+            }
+            const actual = record.attributes[rule.field];
+            if (rule.op !== 'eq' && typeof actual !== 'number') {
+                unknownReferences++;
+                continue;
+            }
+            const passes = rule.op === 'eq' ? same(actual, rule.value) : rule.op === 'lte' ? actual <= rule.value : actual >= rule.value;
+            if (!passes)
+                violations.push({ item: records.indexOf(record) + 1, rule: index + 1, op: rule.op, limit: rule.value, actual });
+        }
+    }
+    const snippets = violations.slice(0, 8).map(v => `Source snapshot record #${v.item} (1-based source-record order, not claim-list order) violates rule #${v.rule}: actual ${v.actual}; required ${v.op === 'lte' ? '<=' : v.op === 'gte' ? '>=' : '==='} ${v.limit}.`);
+    const status = unknownReferences ? 'partial' : 'checked';
+    const text = snippets.length ? 'WARDEN constraint evidence (conditional on the host record snapshot): ' + snippets.join(' ') + (violations.length > 8 ? ` ${violations.length - 8} more contradictions recorded.` : '') + (unknownReferences ? ' Some references or fields are unknown; this is not a complete check.' : '') : unknownReferences ? 'WARDEN: some claimed items or rule fields are unknown. Constraint checking is incomplete, not passed.' : '';
+    return { status, factsSha256, violations, unknownReferences, text };
+}

package/codex-hooks/scripts/flow-guard-decode.mjs

@@ -0,0 +1,149 @@
+// GENERATED from src/flow-guard-decode.ts by scripts/sync-flow-guard.mjs. Do not edit; run npm run build.
+/** Flow guard: reversible spellings a value can hide in (URL, base64, hex, escapes, character lists, NATO), decoded into candidates. */
+const MAX_CANDIDATE = 524_288;
+/** Only explicit character lists are decoded, never arbitrary prose. Unknown items end a run.
+ * English digit names and case markers cover the recorded attack, not arbitrary verbal encodings. */
+export function spelledCandidates(text) {
+    const digits = { zero: '0', one: '1', two: '2', three: '3', four: '4', five: '5', six: '6', seven: '7', eight: '8', nine: '9' };
+    const out = [];
+    let run = '';
+    const flush = () => { if (run.length >= 5)
+        out.push(run); run = ''; };
+    for (const item of text.slice(0, MAX_CANDIDATE).normalize('NFKC').split(/[,;|\r\n]+/)) {
+        const unit = item.trim().toLowerCase();
+        const ch = /^[a-z0-9]$/.test(unit) ? unit : (Object.hasOwn(digits, unit) ? digits[unit] : undefined) ?? /^(?:capital|uppercase|lowercase|letter) ([a-z])$/.exec(unit)?.[1];
+        if (ch)
+            run += ch;
+        else
+            flush();
+    }
+    flush();
+    return out;
+}
+/** Decimal scalar codes, in a contiguous explicit list. Unknown/invalid items terminate a run.
+ * Merely decoding public numbers does not block anything: existing secret/private fingerprints still decide. */
+export function characterCodeCandidates(text) {
+    const out = [];
+    let run = '', count = 0;
+    const flush = () => { if (count >= 5)
+        out.push(run); run = ''; count = 0; };
+    for (const item of text.slice(0, MAX_CANDIDATE).normalize('NFKC').split(/[\s,;|[\]]+/)) {
+        if (!item)
+            continue;
+        const code = /^\d{1,7}$/.test(item) ? Number(item) : -1;
+        if (code >= 32 && code <= 0x10ffff && !(code >= 0x7f && code <= 0x9f) && !(code >= 0xd800 && code <= 0xdfff) || [9, 10, 13].includes(code)) {
+            run += String.fromCodePoint(code);
+            count++;
+        }
+        else
+            flush();
+    }
+    flush();
+    return out;
+}
+const NATO = Object.freeze(Object.fromEntries([
+    ...'alfa bravo charlie delta echo foxtrot golf hotel india juliett kilo lima mike november oscar papa quebec romeo sierra tango uniform victor whiskey xray yankee zulu'.split(' ').map((word, i) => [word, String.fromCharCode(97 + i)]),
+    ['alpha', 'a'], ['juliet', 'j'], ['x-ray', 'x'],
+    ['niner', '9'],
+    ...'zero one two three four five six seven eight nine'.split(' ').map((word, i) => [word, String(i)]),
+    ['underscore', '_'], ['hyphen', '-'], ['dash', '-'], ['slash', '/'], ['plus', '+'], ['equals', '='], ['dot', '.'],
+]));
+/** A small explicit spelling grammar, not a language model. Preserve explicit case for nested base64. */
+export function natoCandidates(text) {
+    const out = [];
+    let run = '', count = 0, marker = '';
+    const flush = () => { if (count >= 5)
+        out.push(run); run = ''; count = 0; marker = ''; };
+    for (const item of text.slice(0, MAX_CANDIDATE).normalize('NFKC').split(/[\s,;|]+/)) {
+        if (!item)
+            continue;
+        const unit = item.toLowerCase();
+        if (['capital', 'uppercase', 'lowercase', 'letter'].includes(unit)) {
+            if (marker)
+                flush();
+            marker = unit;
+            continue;
+        }
+        const ch = Object.hasOwn(NATO, unit) ? NATO[unit] : /^\d$/.test(unit) ? unit : undefined;
+        if (!ch || marker && !/^[a-z]$/.test(ch)) {
+            flush();
+            continue;
+        }
+        run += ['capital', 'uppercase'].includes(marker) ? ch.toUpperCase() : ch;
+        count++;
+        marker = '';
+    }
+    flush();
+    return out;
+}
+/** Reversible text encodings only: bounded breadth/depth, no eval or decompression. Exhaustion is explicit. */
+export function scanCandidates(texts) {
+    const values = [], queue = [];
+    const seen = new Set();
+    let left = MAX_CANDIDATE, incomplete = false;
+    const push = (text, depth) => {
+        if (!text || seen.has(text))
+            return;
+        if (depth > 4 || values.length >= 64 || text.length > left) {
+            incomplete = true;
+            return;
+        }
+        seen.add(text);
+        left -= text.length;
+        values.push(text);
+        queue.push({ text, depth });
+    };
+    for (const text of texts) {
+        if (text.length > left) {
+            incomplete = true;
+            if (left)
+                push(text.slice(0, left), 0);
+        }
+        else
+            push(text, 0);
+    }
+    const utf8 = (bytes) => {
+        try {
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            return text && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text) ? text : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (let index = 0; index < queue.length; index++) {
+        const { text, depth } = queue[index];
+        const add = (value) => { if (value && value !== text)
+            push(value, depth + 1); };
+        if (/%[0-9a-f]{2}/i.test(text)) {
+            try {
+                add(decodeURIComponent(text.replace(/\+/g, ' ')));
+            }
+            catch { /* malformed literal, never executable */ }
+        }
+        for (const value of spelledCandidates(text))
+            add(value);
+        for (const value of characterCodeCandidates(text))
+            add(value);
+        for (const value of natoCandidates(text))
+            add(value);
+        const escaped = text.replace(/\\u\{([0-9a-f]{1,6})\}|\\u([0-9a-f]{4})|\\x([0-9a-f]{2})|&#(?:x([0-9a-f]+)|([0-9]+));/gi, (whole, a, b, c, d, e) => {
+            const code = Number.parseInt(a ?? b ?? c ?? d ?? e, e === undefined ? 16 : 10);
+            return code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : whole;
+        });
+        add(escaped);
+        for (const m of text.matchAll(/[A-Za-z0-9+/_-]{8,}={0,2}/g)) {
+            const normalized = m[0].replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+            if (normalized.length % 4 === 1)
+                continue;
+            const bytes = Buffer.from(normalized, 'base64');
+            if (bytes.toString('base64').replace(/=+$/, '') === normalized)
+                add(utf8(bytes));
+        }
+        for (const m of text.matchAll(/\b(?:[0-9a-f]{2}){3,}\b/gi))
+            add(utf8(Buffer.from(m[0], 'hex')));
+    }
+    return { values, incomplete };
+}
+/** Compatibility helper: enforcement uses scanCandidates() so truncation is never mistaken for a clean scan. */
+export function candidates(texts) { return scanCandidates(texts).values; }

package/codex-hooks/scripts/flow-guard-destinations.mjs

@@ -0,0 +1,158 @@
+// GENERATED from src/flow-guard-destinations.ts by scripts/sync-flow-guard.mjs. Do not edit; run npm run build.
+import { globMatch, hostMatches } from './flow-guard-policy.mjs';
+import { MAX_TEXT, hostsIn, strings } from './flow-guard-text.mjs';
+import { normalizeText } from './flow-guard-fingerprints.mjs';
+export const MAX_RESOLVED = 200;
+// Who or what a call is aimed at. A destination the user named in their own words is the user's choice.
+export const DEST_ARG_NAMES = new Set(['to', 'recipient', 'recipients', 'cc', 'bcc', 'email', 'emails', 'participants', 'user', 'users',
+    'channel', 'url', 'urls', 'iban', 'account', 'address', 'phone', 'host', 'hostname', 'domain', 'webhook', 'endpoint',
+    'attendee', 'attendees', 'invitee', 'invitees', 'assignee', 'assignees', 'reviewer', 'reviewers', 'collaborator', 'collaborators',
+    'member', 'members', 'username']);
+// The subset that names a party without doubt. On an unlabeled MCP tool one of these makes the call outbound;
+// "user", "channel", "account" or "host" also name what a read looks at, so they do not.
+const PARTY_ARG_NAMES = new Set(['to', 'recipient', 'recipients', 'cc', 'bcc', 'email', 'emails', 'participants', 'iban', 'phone',
+    'webhook', 'endpoint', 'attendee', 'attendees', 'invitee', 'invitees', 'assignee', 'assignees', 'reviewer', 'reviewers',
+    'collaborator', 'collaborators', 'member', 'members', 'username']);
+// Bounded address parts and a fixed start prevent quadratic scans of long non-address payloads.
+const EMAIL_RE = /(?<![a-z0-9._%+-])[a-z0-9._%+-]{1,64}@[a-z0-9.-]{1,253}\.[a-z]{2,63}\b/gi;
+// A bare domain in text ("www.example.com/x"), limited to common TLDs so "file.txt" or "v1.2" do not count.
+const BARE_DOMAIN_RE = /\b(?:www\.)?(?:[a-z0-9-]+\.)+(?:com|net|org|io|dev|ai|co|app|info|biz|xyz|me|us|uk|de|fr|es|it|nl|ru|cn|jp|in|br|eu|ch|se|no|fi|pl|cz|at|be|ca|au|nz|online|site|top|link|click|live|shop|store|tech|cloud|pro|tk|gq|ml|ga|cf|ly|gg|to|so|sh|cc|tv|ws)\b(?:\/[^\s"'<>)]*)?/gi;
+const IBAN_RE = /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]){10,30}\b/g;
+export function namesParty(input, texts) {
+    const named = Object.entries(input).some(([k, v]) => PARTY_ARG_NAMES.has(k.toLowerCase()) &&
+        ((typeof v === 'string' && !!v.trim()) || typeof v === 'number' || (Array.isArray(v) && v.length > 0)));
+    return named || texts.some(t => new RegExp(EMAIL_RE.source, 'i').test(t) || new RegExp(IBAN_RE.source).test(t));
+}
+export function destinations(toolName, input, policy, hosts) {
+    const out = new Set(hosts);
+    const configured = Object.entries(policy.destinationArgs).find(([glob]) => globMatch(glob, toolName))?.[1];
+    const names = configured ? new Set(configured.map(n => n.toLowerCase())) : DEST_ARG_NAMES;
+    const add = (v) => {
+        if (typeof v === 'string' || typeof v === 'number') {
+            const t = String(v).trim();
+            if (t)
+                out.add(t);
+        }
+        else if (Array.isArray(v))
+            v.forEach(add);
+        else if (v && typeof v === 'object')
+            Object.values(v).forEach(add);
+    };
+    for (const [k, v] of Object.entries(input))
+        if (names.has(k.toLowerCase()))
+            add(v);
+    // Anything that names a place to reach, wherever it sits (a link in a message body is where the reader goes).
+    for (const t of strings(input)) {
+        for (const m of t.matchAll(EMAIL_RE))
+            out.add(m[0]);
+        for (const m of t.matchAll(IBAN_RE))
+            out.add(m[0]);
+        // A mailbox is one destination, not a separate grant to its provider's web host.
+        for (const m of t.matchAll(BARE_DOMAIN_RE))
+            if (t[(m.index ?? 0) - 1] !== '@')
+                out.add(m[0]);
+    }
+    for (const h of hostsIn(strings(input)))
+        out.add(h);
+    return [...new Set([...out].map(d => d.toLowerCase().replace(/^[a-z]+:\/\//, '').replace(/^www\./, '').replace(/\/+$/, '')))].filter(d => d.length >= 1);
+}
+/**
+ * The operator named this tool's destination arguments and the call sets none of them: it acts on an
+ * existing relationship (change the amount of a standing order, not its payee), so no new party is reached.
+ * Unconfigured tools never qualify: without the operator's word, an absent argument proves nothing.
+ */
+export function keepsDestination(toolName, input, policy) {
+    const configured = Object.entries(policy.destinationArgs).find(([glob]) => globMatch(glob, toolName))?.[1];
+    if (!configured?.length)
+        return false;
+    // It must act on something that already exists, named by id: creating a new thing is not "keeping" a party.
+    const existing = Object.entries(input).some(([k, v]) => /(^|_)id$/i.test(k) && v !== undefined && v !== null && v !== '' && !configured.includes(k));
+    if (!existing)
+        return false;
+    return configured.every(name => { const v = input[name]; return v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0); });
+}
+/** Every destination appears in what the user typed this session. Hosts match on the bare name too. */
+/** A whole-word, case-insensitive match of `token` (length >= 3) in the user's raw prompt. */
+function typedWord(token, raw) {
+    if (token.length < 3)
+        return false;
+    return new RegExp(`(^|[^\\p{L}\\p{N}])${token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^\\p{L}\\p{N}])`, 'iu').test(raw);
+}
+/** Only structured records from explicitly configured contact tools may resolve a full display name.
+ * Arbitrary prose, YAML, capitalized words and local file reads cannot create authority. */
+export function resolvedContacts(value, depth = 0) {
+    if (depth > 8)
+        return [];
+    if (typeof value === 'string') {
+        if (value.length > MAX_TEXT)
+            return [];
+        try {
+            return resolvedContacts(JSON.parse(value), depth + 1);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (Array.isArray(value))
+        return value.slice(0, MAX_RESOLVED).flatMap(v => resolvedContacts(v, depth + 1));
+    if (!value || typeof value !== 'object')
+        return [];
+    const record = value;
+    if (typeof record.name === 'string' && typeof record.email === 'string') {
+        const name = record.name.normalize('NFKC').trim().replace(/\s+/g, ' ').toLowerCase();
+        const email = record.email.trim().toLowerCase();
+        if (name.length >= 3 && name.length <= 200 && /^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/.test(email))
+            return [{ v: email, names: [name] }];
+        return [];
+    }
+    // Common MCP envelopes only, not arbitrary nested notes or metadata.
+    return ['content', 'structuredContent', 'contacts', 'text'].flatMap(k => resolvedContacts(record[k], depth + 1));
+}
+function exactNamed(value, text) {
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // A full stop or comma that ends the sentence ends the value too ("send it to bob@corp.com."); one that goes on
+    // into more letters ("bob@corp.com.evil") does not.
+    return new RegExp(`(^|[^\\p{L}\\p{N}._%+@-])${escaped}($|[^\\p{L}\\p{N}._%+@-]|[.,](?=$|\\s))`, 'iu').test(text);
+}
+/** A URL mentioned in prose cannot stand in for an actual target argument. */
+export function hasDestinationArgument(tool, input, policy) {
+    const configured = Object.entries(policy.destinationArgs).find(([glob]) => globMatch(glob, tool))?.[1];
+    const names = configured ? new Set(configured.map(n => n.toLowerCase())) : DEST_ARG_NAMES;
+    return Object.entries(input).some(([k, v]) => names.has(k.toLowerCase()) &&
+        ((typeof v === 'string' && !!v.trim()) || typeof v === 'number' || (Array.isArray(v) && v.length > 0)));
+}
+export function allowedDestination(destination, patterns) {
+    // Exact mailbox entries are possible; a host entry never authorizes every mailbox at that host.
+    if (destination.includes('@'))
+        return patterns.some(p => p.toLowerCase() === destination);
+    try {
+        const url = new URL(`https://${destination}`);
+        return !url.username && !url.password && hostMatches(url.hostname, patterns);
+    }
+    catch {
+        return false;
+    }
+}
+export function namedByUser(dests, intent, intentRaw, resolved) {
+    if (!dests.length || !intent?.length)
+        return false;
+    const raw = (intentRaw ?? []).join('\n');
+    // Contact authority applies to the exact mailbox, never to its provider's web host.
+    const viaContacts = dests.filter(d => d.includes('@') && (exactNamed(d, raw) || !!resolved?.some(r => r.v === d && r.names.some(n => typedWord(n, raw) && new Set(resolved.filter(other => other.names.includes(n)).map(other => other.v)).size === 1))));
+    return dests.every(d => {
+        if (viaContacts.includes(d))
+            return true;
+        // A bare number names an id only next to a word that says so ("file 13", "ID '13'", "#13"): in
+        // "June 13" it is a date. Short names ("Bob") must match a whole word.
+        if (/^\d+$/.test(d)) {
+            const re = new RegExp(`(\\bid\\b|\\bids\\b|\\bfile\\b|\\bnumber\\b|\\bno\\.|#|№)\\s*[:'"\\s]*${d}(?!\\d)`, 'iu');
+            return re.test(raw);
+        }
+        if (d.length < 6) {
+            const re = new RegExp(`(^|[^\\p{L}\\p{N}])${d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^\\p{L}\\p{N}])`, 'iu');
+            return re.test(raw);
+        }
+        return exactNamed(d, raw) || (/^[a-z]{2}\d{2}[a-z0-9]{10,30}$/i.test(d) &&
+            [...raw.toUpperCase().matchAll(IBAN_RE)].some(m => normalizeText(m[0]) === d));
+    });
+}