dsh-dlp 0.2.0 → 0.4.0

package/lib/config-writes.js

@@ -0,0 +1,215 @@
+/**
+ * The `ask` tier: files whose contents decide how the agent, the editor or CI
+ * behaves next time, and the one config *key* whose value redirects a
+ * credential.
+ *
+ * This tier is deliberately **not** on the guard floor, and that is the whole
+ * design. `ctx.tools.guard()` has no `ask` arm and cannot be overridden, so a
+ * rule that lands there must be one a developer never legitimately trips. A
+ * developer asks the agent to edit `CLAUDE.md`, add a `.github/workflows`
+ * job or extend `.vscode/settings.json` constantly. Putting those on an
+ * unoverridable floor produces a plugin that gets uninstalled, which removes
+ * the floor as well.
+ *
+ * The cost is stated rather than hidden: `tools/pre-execute` is neutralizable.
+ * A listener registered ahead of this one can return without calling `next()`
+ * and this tier never runs. Only the guard floor is order-independent.
+ * @module dsh-dlp/config-writes
+ */
+import { isReadOnlyTool, normalizeCandidatePath, pathArguments } from "./paths.js";
+import { nestedStrings } from "./redaction.js";
+/**
+ * Paths whose contents change future behaviour, and the config key whose value
+ * redirects credentials.
+ *
+ * Every path here was used in the wild. The Miasma worm wrote `SessionStart`
+ * hooks into `.claude/settings.json` and `.gemini/settings.json`, an
+ * always-apply `.cursor/rules/setup.mdc`, a `folderOpen` task into
+ * `.vscode/tasks.json`, and a hijacked `npm test` into `Azure/durabletask`;
+ * GitHub disabled 73 repositories across Azure, microsoft and Azure-Samples
+ * over it, 39 of them inside 38 seconds. See also CVE-2025-53773,
+ * CVE-2026-25725, CVE-2026-33068, CVE-2026-48124, CVE-2026-26268 and
+ * CVE-2025-59041.
+ *
+ * The rules match by name, never by what is on disk, so a file the call is
+ * about to *create* is matched exactly like one it would change:
+ * CVE-2026-25725 worked precisely because the path did not exist yet and was
+ * therefore writable without any prompt.
+ */
+export const CONFIG_WRITE_RULES = [
+    {
+        id: 'dsh-dlp/config-agent-settings',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.(claude|gemini|codex|cursor|windsurf|continue)\/settings[^/]*\.json$/i,
+        effect: 'agent settings, which can register hooks that run on every future session',
+    },
+    {
+        id: 'dsh-dlp/config-agent-hooks',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.(claude|gemini|codex|windsurf|continue)\/hooks(\/|$)/i,
+        effect: 'an agent hook, which runs on a session event without the model asking for it',
+    },
+    {
+        id: 'dsh-dlp/config-agent-instructions',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)(CLAUDE|AGENTS|GEMINI|\.cursorrules|\.windsurfrules)(\.md)?$/i,
+        effect: 'standing instructions every future session in this repository reads',
+    },
+    {
+        id: 'dsh-dlp/config-agent-rules',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.(cursor|windsurf|continue)\/rules(\/|$)/i,
+        effect: 'an always-apply rules file every future session in this repository reads',
+    },
+    {
+        id: 'dsh-dlp/config-mcp-manifest',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.mcp\.json$/i,
+        effect: 'the MCP manifest, which decides which servers the agent starts and with what environment',
+    },
+    {
+        id: 'dsh-dlp/config-editor-tasks',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.vscode\/(settings|tasks|launch)\.json$/i,
+        effect: 'editor configuration, which can run a task the moment the folder is opened',
+    },
+    {
+        id: 'dsh-dlp/config-git',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.git\/(config$|hooks(\/|$))/i,
+        effect: 'git configuration or a git hook, which runs on the next commit, checkout or push',
+    },
+    {
+        id: 'dsh-dlp/config-git-hooks-managed',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.husky(\/|$)/i,
+        effect: 'a managed git hook, which runs on the next commit or push',
+    },
+    {
+        id: 'dsh-dlp/config-ci-workflow',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)\.(github\/workflows|gitlab-ci\.yml|circleci)(\/|$)/i,
+        effect: 'a CI workflow, which runs on the shared runner with the repository\'s secrets',
+    },
+    {
+        id: 'dsh-dlp/config-shell-rc',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)(\.bashrc|\.bash_profile|\.bash_login|\.bash_logout|\.profile|\.zshrc|\.zprofile|\.zshenv|\.zlogin|\.kshrc|config\.fish)$/i,
+        effect: 'a shell startup file, which runs on every future shell this agent opens',
+    },
+    {
+        id: 'dsh-dlp/config-harness-bundle',
+        version: 1,
+        match: 'path',
+        pattern: /(^|\/)cordis[^/]*\.ya?ml$/i,
+        effect: 'a harness bundle manifest, which decides which plugins load',
+    },
+    // CVE-2026-21852: a repo-local settings file setting `ANTHROPIC_BASE_URL`
+    // sends the user's own API key to whatever host it names. This is neither a
+    // path nor a secret — it is a key whose *value* redirects a credential — so
+    // it is matched against what would be written rather than against where.
+    {
+        id: 'dsh-dlp/config-api-base-url',
+        version: 1,
+        match: 'content',
+        pattern: /\b[A-Z][A-Z0-9_]*(?:_BASE_URL|_API_BASE)\b["']?\s*[=:]\s*["']?\s*https?:\/\//,
+        effect: 'a provider base URL, which sends the credential for that provider to whatever host it names',
+    },
+];
+/**
+ * Argument keys whose values are the bytes a call would write.
+ *
+ * Deliberately separate from the floor's path-typed keys: the floor must never
+ * run its path table over file content, and this tier must run its one content
+ * rule over nothing else.
+ */
+export const CONTENT_ARGUMENT_KEYS = new Set([
+    'content', 'contents', 'text', 'file_text', 'fileText',
+    'new_string', 'newString', 'new_str', 'replacement', 'body',
+]);
+/**
+ * The strings one call would write.
+ * @param args - the pending call's parsed arguments.
+ * @returns every string under a content-typed key, at any depth.
+ */
+export function contentArguments(args) {
+    const found = [];
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (CONTENT_ARGUMENT_KEYS.has(key))
+                found.push(...nestedStrings(value));
+            else
+                walk(value);
+        }
+    };
+    walk(args);
+    return found;
+}
+/**
+ * Prompt text for one behaviour-changing write.
+ *
+ * The path is not quoted, for the same reason the floor never quotes one: this
+ * string is model-visible and a path carries tenant and customer names. What
+ * the user needs in order to answer is which tool, which rule, and what the
+ * file does.
+ */
+function configWriteReason(toolName, rule) {
+    return `dsh-dlp is asking before ${JSON.stringify(toolName)} writes ${rule.effect} (rule ${rule.id}). `
+        + 'This kind of file changes what happens on a later session, commit or CI run rather than now, so it is worth '
+        + 'one look. Approve it if you asked for this change; decline it if you did not.';
+}
+/**
+ * Decide whether one call should be confirmed by a human.
+ *
+ * Only calls that can change something are examined: a tool
+ * {@link isReadOnlyTool} classifies as query-only cannot write a hook. Shell
+ * command lines are deliberately **not** tokenised here, unlike in the floor:
+ * a command line cannot be told apart from a read of the same path, and
+ * prompting on `cat .github/workflows/ci.yml` is exactly the false positive
+ * that gets a tier switched off. A shell redirection into one of these files
+ * is therefore not covered, which README.md says beside the feature.
+ * @param exec - the pending call.
+ * @param rules - the rule table; defaults to {@link CONFIG_WRITE_RULES}.
+ * @returns the finding, or `undefined` to leave the call alone.
+ */
+export function evaluateConfigWrite(exec, rules = CONFIG_WRITE_RULES) {
+    if (isReadOnlyTool(exec.name))
+        return undefined;
+    const targets = pathArguments(exec.arguments).filter(argument => !argument.shell);
+    for (const rule of rules) {
+        if (rule.match !== 'path')
+            continue;
+        for (const target of targets) {
+            if (rule.pattern.test(normalizeCandidatePath(target.text))) {
+                return { rule, reason: configWriteReason(exec.name, rule) };
+            }
+        }
+    }
+    const written = contentArguments(exec.arguments);
+    for (const rule of rules) {
+        if (rule.match !== 'content')
+            continue;
+        for (const text of written) {
+            if (rule.pattern.test(text))
+                return { rule, reason: configWriteReason(exec.name, rule) };
+        }
+    }
+    return undefined;
+}

package/lib/detectors.js

@@ -36,6 +36,11 @@ export const DENY_SEVERITY = 'high';
  * delimiters make a match structurally unambiguous, plus PEM blocks and
  * credential-bearing URLs. Anything requiring entropy heuristics is left to
  * tier 2, where a false positive costs a redaction rather than a denial.
+ *
+ * Prefix-anchored is the whole membership criterion, and the reason this table
+ * keeps growing rather than deferring to tier 2: the `session-telemetry/record`
+ * waterfall is synchronous and cannot reach tier 2 at all, so a format missing
+ * here is exported in the clear when telemetry is on.
  */
 export const SYNC_RULES = [
     { id: 'dsh-dlp/aws-access-key-id', version: 1, severity: 'critical', pattern: /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/g },
@@ -44,9 +49,23 @@ export const SYNC_RULES = [
     { id: 'dsh-dlp/slack-token', version: 1, severity: 'critical', pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g },
     { id: 'dsh-dlp/stripe-secret-key', version: 1, severity: 'critical', pattern: /\b[sr]k_live_[A-Za-z0-9]{16,}\b/g },
     { id: 'dsh-dlp/anthropic-api-key', version: 1, severity: 'critical', pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+    // Ahead of the OpenAI rule, whose `sk-` prefix also covers this shape: two
+    // detections over the same span merge into one placeholder attributed to
+    // whichever rule the table reached first, and the specific rule is the
+    // useful attribution.
+    { id: 'dsh-dlp/openrouter-api-key', version: 1, severity: 'critical', pattern: /\bsk-or-v1-[0-9a-f]{64}\b/g },
     { id: 'dsh-dlp/openai-api-key', version: 1, severity: 'critical', pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g },
     { id: 'dsh-dlp/google-api-key', version: 1, severity: 'critical', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g },
     { id: 'dsh-dlp/npm-token', version: 1, severity: 'critical', pattern: /\bnpm_[A-Za-z0-9]{36}\b/g },
+    { id: 'dsh-dlp/gitlab-token', version: 1, severity: 'critical', pattern: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+    { id: 'dsh-dlp/huggingface-token', version: 1, severity: 'critical', pattern: /\bhf_[A-Za-z0-9]{34,}/g },
+    { id: 'dsh-dlp/groq-api-key', version: 1, severity: 'critical', pattern: /\bgsk_[A-Za-z0-9]{40,}/g },
+    { id: 'dsh-dlp/xai-api-key', version: 1, severity: 'critical', pattern: /\bxai-[A-Za-z0-9]{32,}/g },
+    { id: 'dsh-dlp/google-oauth-client-secret', version: 1, severity: 'critical', pattern: /\bGOCSPX-[A-Za-z0-9_-]{24,}/g },
+    { id: 'dsh-dlp/databricks-token', version: 1, severity: 'critical', pattern: /\bdapi[0-9a-f]{32}(?:-\d+)?\b/g },
+    { id: 'dsh-dlp/sendgrid-api-key', version: 1, severity: 'critical', pattern: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g },
+    { id: 'dsh-dlp/supabase-service-key', version: 1, severity: 'critical', pattern: /\bsbp_[0-9a-f]{40}\b/g },
+    { id: 'dsh-dlp/notion-token', version: 1, severity: 'critical', pattern: /\bntn_[A-Za-z0-9]{40,}/g },
     { id: 'dsh-dlp/private-key-block', version: 1, severity: 'critical', pattern: /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z]+ )*PRIVATE KEY-----/g },
     { id: 'dsh-dlp/json-web-token', version: 1, severity: 'high', pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
     { id: 'dsh-dlp/credential-url', version: 1, severity: 'high', pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s/@]+@[^\s/]+/gi },
@@ -58,13 +77,95 @@ export const SYNC_RULES = [
     { id: 'dsh-dlp/teams-webhook-url', version: 1, severity: 'critical', pattern: /\bhttps:\/\/[A-Za-z0-9.-]*webhook\.office\.com\/webhookb2\/[A-Za-z0-9@/_-]{10,}/g },
     { id: 'dsh-dlp/secret-assignment', version: 1, severity: 'medium', pattern: /\b(?:api[_-]?key|secret[_-]?key|client[_-]?secret|password|passwd|access[_-]?token|auth[_-]?token)\b\s*[=:]\s*["']?[A-Za-z0-9/+=_-]{16,}["']?/gi },
 ];
-/** Build one class's run pattern from its ranges, so the two cannot drift apart. */
-function unicodeRule(id, action, ranges) {
-    return { id, version: 1, severity: 'medium', action, ranges, pattern: new RegExp(`[${ranges}]+`, 'gu') };
+/**
+ * Build one class's run pattern from its ranges, so the two cannot drift apart.
+ * @param id - the rule's identity.
+ * @param action - what the scan does with a match.
+ * @param ranges - the class's ranges as a character-class body.
+ * @param quantifier - applied to the class; the default matches a whole run.
+ * @param wholeRun - whether a match must be a complete run rather than part of a longer one.
+ * @returns the rule.
+ */
+function unicodeRule(id, action, ranges, quantifier = '+', wholeRun = false) {
+    const source = wholeRun
+        ? `(?<![${ranges}])[${ranges}]${quantifier}(?![${ranges}])`
+        : `[${ranges}]${quantifier}`;
+    return { id, version: 1, severity: 'medium', action, ranges, pattern: new RegExp(source, 'gu') };
 }
+/** Variation-selector code points, shared by the isolated rule and the run rule. */
+const VARIATION_SELECTORS = String.raw `\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}`;
+/**
+ * Consecutive variation selectors at which the run stops being glyph selection
+ * and starts being a payload.
+ *
+ * One selector picks a glyph: VS15/VS16 after a base character, one selector
+ * after one ideograph in an Ideographic Variation Sequence. Two in a row have
+ * no standard meaning — an emoji ZWJ sequence separates its selectors with a
+ * joiner, so a run stays at one — and four leaves no plausible reading but
+ * "these are bytes". GlassWorm encoded executable JavaScript one byte per
+ * selector across five waves, 35,800 installs and 300+ repositories, so a real
+ * payload is hundreds of selectors long and 4 is a conservative floor rather
+ * than a tight one.
+ */
+const VARIATION_SELECTOR_RUN = 4;
+/**
+ * One terminal control sequence: the full CSI form, not only the SGR colour
+ * subset, plus the string-introducer families and the 8-bit C1 equivalents.
+ *
+ * Each alternative in order: an OSC/DCS/SOS/PM/APC introducer and its body up
+ * to a string terminator that may never arrive; a complete CSI — parameter
+ * bytes, intermediate bytes, one final byte; any other escape sequence; and a
+ * lone escape or C1 control that introduces nothing.
+ *
+ * Terminating at end of input matters: an unterminated OSC swallows everything
+ * a terminal prints after it, which is the whole trick, so the tail is part of
+ * the match rather than a miss.
+ */
+const CONTROL_SEQUENCE = [
+    String.raw `(?:\u001B[\]P^_X]|[\u0090\u0098\u009D\u009E\u009F])[\s\S]*?(?:\u0007|\u001B\\|\u009C|$)`,
+    String.raw `(?:\u001B\[|\u009B)[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]`,
+    String.raw `\u001B[\u0020-\u002F]*[\u0030-\u007E]`,
+    String.raw `[\u001B\u0080-\u009F]`,
+].join('|');
+/**
+ * Text substituted for a stripped control sequence. Visible on purpose: the
+ * lanes that strip are the ones an operator reads as evidence, and silently
+ * deleting the bytes would hide that a forgery was attempted.
+ */
+export const CONTROL_SEQUENCE_PLACEHOLDER = '[REDACTED:dsh-dlp:control-sequence]';
+/**
+ * Remove every terminal control sequence from one string.
+ *
+ * This is the `strip` half of {@link CONTROL_SEQUENCE_RULE}, applied on the
+ * lanes that must never carry forgeable bytes: an audit record and the strings
+ * an operator or an approval prompt reads back. Ordinary tool-result text takes
+ * the `report` half instead, because `git diff`, `rg` and `pytest` legitimately
+ * colourise their output.
+ * @param text - the string to clean.
+ * @returns the string with each control sequence replaced by a visible marker.
+ */
+export function stripControlSequences(text) {
+    return text.replace(new RegExp(CONTROL_SEQUENCE, 'gu'), CONTROL_SEQUENCE_PLACEHOLDER);
+}
+/**
+ * Terminal control sequences in ordinary text.
+ *
+ * `report` rather than `strip`, deliberately: a tool result carrying SGR colour
+ * codes is the normal output of half the commands an agent runs, and replacing
+ * them would corrupt every one of those results. What the class buys on that
+ * lane is the count in the audit record.
+ */
+const CONTROL_SEQUENCE_RULE = {
+    id: 'dsh-dlp/control-sequence',
+    version: 1,
+    severity: 'medium',
+    action: 'report',
+    pattern: new RegExp(CONTROL_SEQUENCE, 'gu'),
+};
 /**
  * Character classes that hide text from the reader while the model still reads
- * it, verified against the Unicode character database.
+ * it, verified against the Unicode character database, plus the terminal
+ * control sequences that show the reader something other than what is there.
  *
  * Every class is `medium`. These are injection *indicators*, not credentials:
  * the guard floor denies at `high` and above, so an argument carrying one is
@@ -88,14 +189,22 @@ export const UNICODE_RULES = [
     unicodeRule('dsh-dlp/unicode-zero-width', 'report', String.raw `\u{200B}-\u{200D}\u{2060}\u{FEFF}`),
     // Bidi marks, unlike the overrides above, appear in real right-to-left text.
     unicodeRule('dsh-dlp/unicode-bidi-mark', 'report', String.raw `\u{061C}\u{200E}\u{200F}`),
-    unicodeRule('dsh-dlp/unicode-variation-selector', 'report', String.raw `\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}`),
+    // An isolated selector is glyph selection and is left alone; a run of them
+    // is a byte string wearing the same code points.
+    unicodeRule('dsh-dlp/unicode-variation-selector', 'report', VARIATION_SELECTORS, `{1,${VARIATION_SELECTOR_RUN - 1}}`, true),
+    unicodeRule('dsh-dlp/unicode-variation-selector-run', 'strip', VARIATION_SELECTORS, `{${VARIATION_SELECTOR_RUN},}`),
+    CONTROL_SEQUENCE_RULE,
 ];
+/** Classes whose matches are a run of one character class. */
+const CHARACTER_RULES = UNICODE_RULES.filter(rule => rule.ranges !== undefined);
+/** Classes whose matches have an ASCII body and are scanned over the whole input. */
+const SEQUENCE_RULES = UNICODE_RULES.filter(rule => rule.ranges === undefined);
 /**
- * One run of any indicator class. The scan is a single pass over the input
- * with this pattern; the per-class patterns then run over the matched runs
- * only, which are a handful of characters each.
+ * One run of any character-class indicator. The scan is a single pass over the
+ * input with this pattern; the per-class patterns then run over the matched
+ * runs only, which are a handful of characters each.
  */
-const UNICODE_RUN = new RegExp(`[${UNICODE_RULES.map(rule => rule.ranges).join('')}]+`, 'gu');
+const UNICODE_RUN = new RegExp(`[${[...new Set(CHARACTER_RULES.map(rule => rule.ranges))].join('')}]+`, 'gu');
 /**
  * Find every invisible or direction-changing character in one string.
  *
@@ -107,20 +216,25 @@ const UNICODE_RUN = new RegExp(`[${UNICODE_RULES.map(rule => rule.ranges).join('
  */
 export function scanUnicode(text) {
     const findings = [];
+    const found = (rule, start, length) => {
+        findings.push({
+            ruleId: rule.id,
+            ruleVersion: rule.version,
+            severity: rule.severity,
+            start,
+            end: start + length,
+            exact: true,
+            action: rule.action,
+        });
+    };
+    for (const rule of SEQUENCE_RULES) {
+        for (const match of text.matchAll(rule.pattern))
+            found(rule, match.index, match[0].length);
+    }
     for (const run of text.matchAll(UNICODE_RUN)) {
-        for (const rule of UNICODE_RULES) {
-            for (const match of run[0].matchAll(rule.pattern)) {
-                const start = run.index + match.index;
-                findings.push({
-                    ruleId: rule.id,
-                    ruleVersion: rule.version,
-                    severity: rule.severity,
-                    start,
-                    end: start + match[0].length,
-                    exact: true,
-                    action: rule.action,
-                });
-            }
+        for (const rule of CHARACTER_RULES) {
+            for (const match of run[0].matchAll(rule.pattern))
+                found(rule, run.index + match.index, match[0].length);
         }
     }
     findings.sort(byPosition);

package/lib/images.js

@@ -0,0 +1,183 @@
+/**
+ * Neutralising remote markdown images in assistant output, on the `llm/stream`
+ * waterfall.
+ *
+ * The web UI renders any absolute `http:`/`https:` markdown image a model
+ * emits as a real `<img src>`, and the harness sets no Content-Security-Policy,
+ * so the fetch happens in the user's browser where no host-side listener can
+ * see it. This module rewrites the destination out of the assistant's text
+ * before it becomes an `assistant/chunk` or `assistant/message` session event,
+ * so the log and the rendered answer stay in agreement.
+ *
+ * Two properties this module exists to hold:
+ *
+ * - **A destination split across chunks is still caught.** The mock and real
+ *   adapters both emit text in small deltas, so `![alt](https://host/x)` is
+ *   routinely spread over several of them and the browser renders the
+ *   accumulation. Text that could still be the start of an image is held back
+ *   until it either completes or exceeds {@link MAX_HELD_CHARACTERS}.
+ * - **Only the destination is replaced.** The alt text survives, so the
+ *   sentence the model wrote still reads, and the renderer's own
+ *   non-absolute-URL arm shows that alt text instead of fetching anything.
+ *
+ * This does not close the channel. It matches inline image syntax only:
+ * reference-style images, an alt text carrying a `]`, and any destination form
+ * the pattern does not model still reach the renderer. Raw HTML needs no
+ * handling — the renderer keeps it as literal text and no HTML enters the DOM
+ * (`packages/client/ui-primitives/src/markdown/render.tsx:261-263`). The
+ * upstream fix is one `img-src` directive.
+ * @module dsh-dlp/images
+ */
+/**
+ * Destination substituted for a remote image URL.
+ *
+ * It is deliberately not a URL: `new URL()` throws on it, which is the
+ * renderer's own "not an absolute destination" arm, and that arm renders the
+ * alt text as a `<span>` instead of emitting an `<img>`.
+ */
+export const BLOCKED_IMAGE_DESTINATION = 'dsh-dlp-blocked-remote-image';
+/**
+ * One inline image: alt text, destination, optional title.
+ *
+ * The destination is either an angle-bracketed form or a run of characters
+ * with no whitespace and no parenthesis, which is what CommonMark accepts
+ * without balanced-parenthesis nesting.
+ */
+const INLINE_IMAGE = /!\[([^\]]*)\]\(\s*(<[^<>\n]*>|[^\s()]*)((?:\s+(?:"[^"]*"|'[^']*'|\([^()]*\)))?)\s*\)/g;
+/**
+ * Text that could still become an inline image once more of the stream
+ * arrives: an alt text still open, a closed alt text followed by `(`, or a
+ * destination not yet closed.
+ */
+const PARTIAL_IMAGE = /^!\[[^\]]*(?:\](?:\((?:\s*(?:<[^<>\n]*|[^\s()]*))?)?)?$/;
+/**
+ * Longest suffix held back waiting for an image to complete.
+ *
+ * Held text is text the user cannot see yet, so the wait is bounded: past this
+ * many characters the suffix is emitted as it stands and a destination that
+ * completes later is caught only by the assembled block. A protocol bound on
+ * this module's own buffering, not a deployment choice.
+ */
+export const MAX_HELD_CHARACTERS = 4096;
+/**
+ * The hostname of an absolute `http(s)` destination.
+ * @param destination - the image destination exactly as the model wrote it.
+ * @returns the hostname, or `undefined` when the destination is not an absolute HTTP(S) URL.
+ */
+function remoteHost(destination) {
+    const trimmed = destination.startsWith('<') && destination.endsWith('>')
+        ? destination.slice(1, -1)
+        : destination;
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        // The only failure mode for a string: not an absolute URL, which the
+        // renderer also refuses, so there is nothing to neutralise.
+        return undefined;
+    }
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.hostname : undefined;
+}
+/**
+ * Replace every absolute HTTP(S) inline image destination in one string.
+ * @param text - assistant text, whole or partial.
+ * @returns the rewritten text and the hosts whose destinations were replaced.
+ */
+export function neutralizeRemoteImages(text) {
+    const hosts = [];
+    const rewritten = text.replace(INLINE_IMAGE, (match, alt, destination, title) => {
+        const host = remoteHost(destination);
+        if (host === undefined)
+            return match;
+        hosts.push(host);
+        return `![${alt}](${BLOCKED_IMAGE_DESTINATION}${title})`;
+    });
+    return { text: rewritten, hosts };
+}
+/**
+ * Where the held suffix of a partially streamed string starts.
+ * @param text - everything accumulated for one block and not yet emitted.
+ * @returns the offset to emit up to; the string's length when nothing is held.
+ */
+export function heldSuffixStart(text) {
+    const marker = text.lastIndexOf('![');
+    if (marker !== -1 && text.length - marker <= MAX_HELD_CHARACTERS && PARTIAL_IMAGE.test(text.slice(marker))) {
+        return marker;
+    }
+    return text.endsWith('!') ? text.length - 1 : text.length;
+}
+/**
+ * Wrap one model stream, replacing remote image destinations in its text.
+ *
+ * Text deltas are rewritten as they pass, with a possible image start held
+ * back until it resolves, and the assembled block on `block-end` — which is
+ * what the agent loop turns into the assistant message — is rewritten too. A
+ * held suffix is always flushed as a delta before the block closes and before
+ * the terminal finish, so no text is lost and the emitted chunks still satisfy
+ * the stream grammar.
+ * @param source - the stream from the rest of the waterfall.
+ * @param onNeutralized - notified once per host per text block.
+ * @returns the rewritten stream.
+ */
+export async function* neutralizeImageStream(source, onNeutralized) {
+    const held = new Map();
+    const reported = new Map();
+    /** Report each host once per block: the deltas and the assembled block carry the same text. */
+    const report = (index, hosts) => {
+        let seen = reported.get(index);
+        if (seen === undefined) {
+            seen = new Set();
+            reported.set(index, seen);
+        }
+        for (const host of hosts) {
+            if (seen.has(host))
+                continue;
+            seen.add(host);
+            onNeutralized(host);
+        }
+    };
+    /** Emit whatever one block is still holding, so a close or a finish loses nothing. */
+    function* flush(index) {
+        const pending = held.get(index);
+        held.delete(index);
+        if (pending !== undefined && pending.length > 0)
+            yield { type: 'text-delta', index, text: pending };
+    }
+    for await (const chunk of source) {
+        switch (chunk.type) {
+            case 'text-delta': {
+                const { text, hosts } = neutralizeRemoteImages((held.get(chunk.index) ?? '') + chunk.text);
+                report(chunk.index, hosts);
+                const cut = heldSuffixStart(text);
+                held.set(chunk.index, text.slice(cut));
+                if (cut > 0)
+                    yield { ...chunk, text: text.slice(0, cut) };
+                break;
+            }
+            case 'block-end': {
+                yield* flush(chunk.index);
+                if (chunk.block.type !== 'text') {
+                    yield chunk;
+                    break;
+                }
+                const { text, hosts } = neutralizeRemoteImages(chunk.block.text);
+                report(chunk.index, hosts);
+                yield text === chunk.block.text ? chunk : { ...chunk, block: { ...chunk.block, text } };
+                break;
+            }
+            case 'finish': {
+                for (const index of [...held.keys()])
+                    yield* flush(index);
+                yield chunk;
+                break;
+            }
+            default:
+                yield chunk;
+        }
+    }
+    // Only a stream that ended without a terminal finish reaches this: the
+    // grammar forbids emitting after one, so the flush above already ran.
+    for (const index of [...held.keys()])
+        yield* flush(index);
+}