@crewhaus/tool-notify 0.7.0 → 0.8.1

package/dist/index.js

@@ -19,12 +19,15 @@
  *      exactly this, and no tool here opts out of it.
  *   2. **The gate is tool-http's gate.** Allow-list, SSRF refusal, IP
  *      pinning, credential stripping and byte caps all live in `./net` and
- *      every outbound byte passes through them. Recipients and SMTP hosts
- *      have their own allow-lists, equally fail-closed. See that file's
- *      header.
- *   3. **Credentials are environment variable NAMES.** A Slack or Discord
- *      incoming-webhook URL is itself a credential, so it is named rather
- *      than passed, and no refusal ever prints a webhook path.
+ *      every outbound byte passes through them. Email recipients, SMTP
+ *      hosts, SMS numbers and push targets have their own allow-lists,
+ *      equally fail-closed. See that file's header.
+ *   3. **Credentials are environment variable NAMES**, and only names the
+ *      operator listed in `allowed_secret_envs` (or a provider's own
+ *      `auth.envVar`, for that provider): a call chooses among them and can
+ *      never add one. A Slack or Discord incoming-webhook URL is itself a
+ *      credential, so it is named rather than passed, and no refusal ever
+ *      prints a webhook path.
  *   4. **Determinism, and no clock.** Listings sort, comparisons are
  *      locale-free, nothing is random — MIME boundaries are derived from the
  *      message's own content — and anything that needs "now" takes it as an
@@ -34,9 +37,11 @@
  * The one deliberate exception to "same input, same output" is the
  * idempotency ledger in `./net`: a second call carrying an
  * `idempotencyKey` that already succeeded returns the first result and posts
- * nothing. That is the point of an idempotency key, and it is the only
- * hidden state in the package.
+ * nothing — when it is the same request; the same key with a different
+ * destination or content is refused. That is the point of an idempotency
+ * key, and it is the only hidden state in the package.
  */
+import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { buildTool } from "@crewhaus/tool-builder";
@@ -44,13 +49,15 @@ import { z } from "zod";
 import { EDITABLE_PLATFORMS, THREADED_PLATFORMS, buildChatPayload, clampToPlatform, renderBlocks, } from "./lib/blocks";
 import { buildDigest, digestToBlocks, digestToText } from "./lib/digest";
 import { normalizeDomain, normalizeSelector, parseDkim, parseDmarc, parseSpf, } from "./lib/dns-records";
+import { parseOffsetInstant } from "./lib/instant";
 import { composeMessage, isValidAddress } from "./lib/mime";
 import { draftChecks, verdictFrom } from "./lib/preflight";
 import { quietDecision } from "./lib/quiet";
 import { rateLimitGate as evaluateRateLimit } from "./lib/ratelimit";
 import { formatSignatureHeader, hmacHex, signedPayload } from "./lib/sign";
 import { renderTemplate as renderTemplateValues } from "./lib/template";
-import { DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, MAX_MAX_BYTES, MAX_TIMEOUT_MS, NotifyPermissionError, applyAuth, assertNotSsrf, assertOriginAllowed, assertSenderDomainAllowed, assertSmtpHostAllowed, byString, describeFailure, json, ledgerLookup, ledgerRecord, lookupTxt, openRequest, parseUrl, readCapped, readPath, recipientAllowed, redactorFor, rejectInlineCredentials, resolveNotifyConfig, resolveSecret, safeUrlLabel, sleep, startDeadline, } from "./net";
+import { isTeamsWebhookPath } from "./lib/webhook-path";
+import { DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT_MS, MAX_MAX_BYTES, MAX_TIMEOUT_MS, NotifyPermissionError, applyAuth, assertNotSsrf, assertOriginAllowed, assertSenderDomainAllowed, assertSmtpHostAllowed, byString, describeFailure, destinationFor, destinationRefusal, excerptOf, isDotSegment, json, ledgerLookup, ledgerRecord, lookupTxt, openRequest, parseUrl, readCapped, readPath, recipientAllowed, redactorFor, rejectInlineCredentials, requestFingerprint, resolveNotifyConfig, resolveSecret, safeUrlLabel, sleep, startDeadline, substituteIntoUrl, } from "./net";
 import { resolveSafe } from "./paths";
 import { sendMail } from "./smtp";
 export { NotifyPermissionError, _resetIdempotencyLedger, _resetNotifyConfig, _setDnsLookup, _setDnsTxtResolver, _setRawFetch, __setPrivateHostsAllowedForTest, buildNotifyConfig, canonicalizeOrigin, getNotifyConfig, registerNotifyConfig, } from "./net";
@@ -82,7 +89,7 @@ const envVarSchema = (what) => z
     .string()
     .min(1)
     .max(64)
-    .describe(`NAME of the environment variable holding ${what} — never the value itself`);
+    .describe(`NAME of the environment variable holding ${what} — never the value itself; it must be listed in tool_config.notify.allowed_secret_envs`);
 const timeoutSchema = z
     .number()
     .int()
@@ -102,7 +109,7 @@ const idempotencySchema = z
     .min(1)
     .max(200)
     .optional()
-    .describe("a key that makes a retry safe: the first call under this key is sent and recorded for the life of the process, and a later call with the same key returns that result without sending again. It is also passed to the provider where the provider honours one");
+    .describe("a key that makes a retry safe: the first call under this key is sent and recorded for the life of the process, and a later call with the same key and the same request returns that result without sending again. The same key with a different destination or content is refused and sends nothing — a key names one message. It is also passed to the provider where the provider honours one");
 const authSchema = z
     .object({
     type: z
@@ -132,15 +139,27 @@ function withRedaction(secrets, timeoutMs, ctx) {
         cfg: resolveNotifyConfig(ctx?.toolConfig),
         deadline: startDeadline(timeoutMs ?? DEFAULT_TIMEOUT_MS, ctx?.signal),
         redact: redactorFor(secrets),
+        secrets,
     };
 }
-/** Reject inline credentials, then attach the auth profile's secret. */
-function prepareHeaders(raw, auth) {
+/**
+ * The variable a provider's operator-written auth profile names: allowed for
+ * that provider's own calls without being listed in allowed_secret_envs, and
+ * for nothing else.
+ */
+function providerAuthEnvs(profile) {
+    return profile.auth === undefined ? [] : [profile.auth.envVar];
+}
+/**
+ * Reject inline credentials, then attach the auth profile's secret, read
+ * only from a variable `allowed` (the operator's allowed_secret_envs) lists.
+ */
+function prepareHeaders(raw, auth, allowed) {
     const headers = { ...(raw ?? {}) };
     const inline = rejectInlineCredentials(headers);
     if (inline !== null)
         return { ok: false, message: inline };
-    const applied = applyAuth(headers, auth);
+    const applied = applyAuth(headers, auth, allowed);
     if (!applied.ok)
         return { ok: false, message: applied.message };
     return {
@@ -150,7 +169,20 @@ function prepareHeaders(raw, auth) {
         secrets: [...applied.secrets],
     };
 }
-/** POST (or whatever verb) to an allow-listed URL and read a capped reply. */
+/** The `replyUnreadable` field for a result, when there is one. */
+function unreadableField(outcome) {
+    return outcome.replyUnreadable !== undefined ? { replyUnreadable: outcome.replyUnreadable } : {};
+}
+/**
+ * POST (or whatever verb) to an allow-listed URL and read a capped reply.
+ *
+ * Once `openRequest` returns, the request has been delivered and answered.
+ * A failure to READ the reply (a coding this reader will not decode, a
+ * corrupt body, the deadline while it streams) does not un-send it, so it is
+ * returned as `replyUnreadable` rather than thrown: 0.7.1's first cut threw
+ * it, the tools reported "nothing was sent" for a delivered message, and a
+ * retry under the same idempotency key delivered it again (net review).
+ */
 async function send(url, method, headers, body, prepared, maxBytes, secretHeaders) {
     const opened = await openRequest({
         url,
@@ -162,7 +194,22 @@ async function send(url, method, headers, body, prepared, maxBytes, secretHeader
         redirect: "refuse",
         credentialHeaders: secretHeaders,
     });
-    const capped = await readCapped(opened.res, maxBytes);
+    const status = opened.res.status;
+    let capped;
+    try {
+        capped = await readCapped(opened.res, maxBytes, prepared.deadline.signal, prepared.secrets);
+    }
+    catch (err) {
+        return {
+            status,
+            ok: status >= 200 && status < 300,
+            body: "",
+            excerpt: "",
+            truncated: false,
+            parsed: undefined,
+            replyUnreadable: describeFailure(err, prepared.deadline),
+        };
+    }
     let parsed;
     try {
         parsed = JSON.parse(capped.text);
@@ -174,6 +221,7 @@ async function send(url, method, headers, body, prepared, maxBytes, secretHeader
         status: opened.res.status,
         ok: opened.res.status >= 200 && opened.res.status < 300,
         body: capped.text,
+        excerpt: excerptOf(capped.text, prepared.secrets),
         truncated: capped.truncated,
         parsed,
     };
@@ -185,7 +233,9 @@ async function send(url, method, headers, body, prepared, maxBytes, secretHeader
  */
 function platformFailure(platform, outcome) {
     if (!outcome.ok) {
-        return `the service answered ${outcome.status}: ${outcome.body.slice(0, 500)}`;
+        return outcome.replyUnreadable !== undefined
+            ? `the service answered ${outcome.status}, and its reply could not be read: ${outcome.replyUnreadable}`
+            : `the service answered ${outcome.status}: ${outcome.excerpt}`;
     }
     if (platform === "slack" && typeof outcome.parsed === "object" && outcome.parsed !== null) {
         const record = outcome.parsed;
@@ -195,6 +245,31 @@ function platformFailure(platform, outcome) {
     }
     return null;
 }
+/**
+ * Slack's Web API keeps its verdict in the reply body (`ok:false` on a
+ * 200). When that verdict cannot be read, the request was delivered but
+ * whether Slack took it is unknown: said so, never "sent" and never "not
+ * sent". It cannot be read when the body could not be read at all, or, in
+ * API mode, when the body is not a JSON object: most often because it was
+ * longer than maxBytes and was cut (net attacker review: a 680-byte
+ * `{"ok":false,"error":"invalid_blocks",...}` cut at 256 bytes was reported
+ * `sent: true`, and ledgered). An incoming webhook answers with its status
+ * and a plain `ok`, and other platforms answer with the status, which is
+ * known.
+ */
+function unknownVerdict(platform, outcome, mode) {
+    if (platform !== "slack" || !outcome.ok)
+        return null;
+    if (outcome.replyUnreadable !== undefined) {
+        return `Slack answered ${outcome.status}, but its reply, which says whether it accepted the request, could not be read (${outcome.replyUnreadable}); check before trying again`;
+    }
+    if (mode !== "api" || (typeof outcome.parsed === "object" && outcome.parsed !== null)) {
+        return null;
+    }
+    return outcome.truncated
+        ? `Slack answered ${outcome.status}, but its reply, which says whether it accepted the request, was longer than maxBytes and was cut before it could be read; check before trying again, and raise maxBytes`
+        : `Slack answered ${outcome.status}, but its reply is not the JSON object that says whether it accepted the request; check before trying again`;
+}
 /** Where a platform keeps the id of the message just posted. */
 function postedMessageId(platform, outcome) {
     if (typeof outcome.parsed !== "object" || outcome.parsed === null)
@@ -203,9 +278,9 @@ function postedMessageId(platform, outcome) {
     const raw = platform === "slack" ? record["ts"] : record["id"];
     return typeof raw === "string" ? raw : undefined;
 }
-/** Resolve a webhook URL held in an environment variable. */
-function webhookUrlFrom(envVar) {
-    const resolved = resolveSecret(envVar, "the webhook URL");
+/** Resolve a webhook URL held in an environment variable `allowed` lists. */
+function webhookUrlFrom(envVar, allowed) {
+    const resolved = resolveSecret(envVar, "the webhook URL", allowed);
     if (!resolved.ok)
         return resolved.message;
     const parsed = parseUrl(resolved.value);
@@ -217,24 +292,41 @@ function webhookUrlFrom(envVar) {
 /**
  * The incoming-webhook URL shapes that ARE the credential.
  *
- * A Slack `/services/T…/B…/xxxx` or Discord `/api/webhooks/<id>/<token>`
- * path grants posting rights to whoever holds it. Passed inline it lands in
+ * A Slack `/services/T…/B…/xxxx`, Discord `/api/webhooks/<id>/<token>` or
+ * Teams `/webhookb2/…@…/IncomingWebhook/…` path grants posting rights to
+ * whoever holds it. Passed inline it lands in
  * the transcript, the trace and usually an eval report — the same reason
  * every other secret here is named rather than passed — so it is refused
  * with the variable form pointed at instead.
  */
+const SLACK_WEBHOOK_PATH = /^\/services\/T[^/]+\/B[^/]+\/.+/i;
+const DISCORD_WEBHOOK_PATH = /^\/api\/webhooks\/\d+\/.+/i;
 const WEBHOOK_CREDENTIAL_PATHS = [
-    /^\/services\/T[^/]+\/B[^/]+\/.+/i,
-    /^\/api\/webhooks\/\d+\/.+/i,
-    /^\/webhookb2\/[^/]+@[^/]+\/IncomingWebhook\/.+/i,
+    (path) => SLACK_WEBHOOK_PATH.test(path),
+    (path) => DISCORD_WEBHOOK_PATH.test(path),
+    // A Teams path is read a segment at a time: see isTeamsWebhookPath.
+    isTeamsWebhookPath,
 ];
 /** A refusal when `url` carries a credential in its path, else `null`. */
 function inlineWebhookCredential(url) {
-    if (!WEBHOOK_CREDENTIAL_PATHS.some((shape) => shape.test(url.pathname)))
+    if (!WEBHOOK_CREDENTIAL_PATHS.some((shape) => shape(url.pathname)))
         return null;
     return "that URL is an incoming-webhook URL, whose path is itself the credential — name the environment variable holding it in urlEnv instead of passing it here, where it would be recorded verbatim. (The value has not been echoed back.)";
 }
 const notSentBecause = (reason) => `nothing was sent: ${reason}`;
+/**
+ * What the idempotency ledger already says about this call, or undefined
+ * when it should go ahead: the first call's result for a retry of the same
+ * request, and a refusal for a different request under a key already used.
+ */
+function ledgerAnswer(tool, key, fingerprint) {
+    const answer = ledgerLookup(tool, key, fingerprint);
+    if (answer === undefined)
+        return undefined;
+    if (answer.kind === "replay")
+        return answer.result;
+    return notSentBecause(`idempotencyKey "${key}" already sent a different ${tool} request in this process (it differed in ${answer.differs.join(", ")}). A key names one message — use a new key for a new message`);
+}
 // ---------------------------------------------------------------------------
 // chat
 // ---------------------------------------------------------------------------
@@ -245,7 +337,7 @@ const chatTargetShape = {
         .min(1)
         .max(64)
         .optional()
-        .describe("NAME of the environment variable holding the incoming-webhook URL. The URL is the credential — a Slack /services/… or Discord /api/webhooks/… path grants posting rights to anyone holding it — so it is named, never passed, and never printed in an error"),
+        .describe("NAME of the environment variable holding the incoming-webhook URL, listed in tool_config.notify.allowed_secret_envs. The URL is the credential — a Slack /services/… or Discord /api/webhooks/… path grants posting rights to anyone holding it — so it is named, never passed, and never printed in an error"),
     apiBaseUrl: z
         .string()
         .min(1)
@@ -256,7 +348,7 @@ const chatTargetShape = {
         .min(1)
         .max(64)
         .optional()
-        .describe("NAME of the environment variable holding the bot token, for API mode"),
+        .describe("NAME of the environment variable holding the bot token, for API mode; it must be listed in tool_config.notify.allowed_secret_envs. It is sent as `Authorization: Bot <token>` to Discord and `Authorization: Bearer <token>` to Slack"),
     channel: z
         .string()
         .min(1)
@@ -264,6 +356,19 @@ const chatTargetShape = {
         .optional()
         .describe("channel or conversation id; required in API mode, ignored by an incoming webhook that is already bound to one"),
 };
+/**
+ * `text` without its trailing slashes: what `text.replace(/\/+$/, "")`
+ * returned, in one pass from the end. That pattern tries every start inside
+ * a run of slashes that is not at the end and rescans the rest of the run
+ * from each, so it was quadratic in the run's length, and an API base URL is
+ * the model's.
+ */
+function withoutTrailingSlashes(text) {
+    let end = text.length;
+    while (end > 0 && text.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return end === text.length ? text : text.slice(0, end);
+}
 /**
  * Work out which of the two ways to reach a platform this call is using, and
  * build the request that goes with it.
@@ -274,7 +379,7 @@ const chatTargetShape = {
  * configuration mistake rather than a preference, so it is refused instead
  * of resolved by precedence.
  */
-function routeChat(target, apiPath, allowWebhook) {
+function routeChat(target, apiPath, allowWebhook, allowed) {
     const hasWebhook = target.webhookUrlEnv !== undefined;
     const hasApi = target.apiBaseUrl !== undefined || target.tokenEnv !== undefined;
     if (hasWebhook && hasApi) {
@@ -290,7 +395,7 @@ function routeChat(target, apiPath, allowWebhook) {
                 message: "an incoming webhook can only create messages; editing, deleting and reacting need apiBaseUrl and tokenEnv",
             };
         }
-        const resolved = webhookUrlFrom(target.webhookUrlEnv);
+        const resolved = webhookUrlFrom(target.webhookUrlEnv, allowed);
         if (typeof resolved === "string")
             return { ok: false, message: resolved };
         return {
@@ -311,16 +416,30 @@ function routeChat(target, apiPath, allowWebhook) {
     const base = parseUrl(target.apiBaseUrl);
     if (typeof base === "string")
         return { ok: false, message: base };
-    const token = resolveSecret(target.tokenEnv, "the bot token");
+    const token = resolveSecret(target.tokenEnv, "the bot token", allowed);
     if (!token.ok)
         return { ok: false, message: token.message };
-    const url = new URL(`${base.pathname.replace(/\/+$/, "")}/${apiPath.replace(/^\/+/, "")}`, base);
+    const literal = `${withoutTrailingSlashes(base.pathname)}/${apiPath.replace(/^\/+/, "")}`;
+    const url = new URL(literal, base);
+    // The path requested must be the path built: a segment the parser would
+    // resolve (a `..` channel, message id or emoji) addresses another endpoint.
+    if (url.pathname !== literal) {
+        return {
+            ok: false,
+            message: "a channel, message id or emoji in this call would change which API endpoint is requested, not just name the item",
+        };
+    }
+    // Discord authenticates a bot token with the `Bot` scheme; `Bearer` there
+    // means an OAuth2 user token, which cannot post, edit, delete or react as
+    // the bot, so every Discord API-mode call answered 401. Slack's bot token
+    // is a Bearer token.
+    const scheme = target.platform === "discord" ? "Bot" : "Bearer";
     return {
         ok: true,
         url,
         headers: {
             "content-type": "application/json; charset=utf-8",
-            Authorization: `Bearer ${token.value}`,
+            Authorization: `${scheme} ${token.value}`,
         },
         secrets: [token.value],
         secretHeaders: new Set(["authorization"]),
@@ -345,6 +464,14 @@ function apiPathFor(platform, operation, channel, messageId, emoji) {
     }
     if (channel === undefined)
         return "discord addresses messages by channel id — set channel";
+    const dotted = [
+        ["channel", channel],
+        ["messageId", messageId],
+        ["emoji", emoji],
+    ].find(([, v]) => v !== undefined && isDotSegment(v));
+    if (dotted !== undefined) {
+        return `${dotted[0]} "${dotted[1]}" is a relative path segment, not a discord ${dotted[0] === "emoji" ? "emoji" : "id"} — substituted into the API path it would walk the request up to a different endpoint, such as the channel itself`;
+    }
     const base = `channels/${encodeURIComponent(channel)}/messages`;
     if (operation === "post")
         return { path: base, method: "POST" };
@@ -372,6 +499,14 @@ function renderMessage(platform, text, blocks) {
 }
 export const chatPost = buildTool({
     name: "ChatPost",
+    // Through an incoming webhook, the variable naming it: the webhook is bound
+    // to its channel, and the tool ignores `channel` there. In API mode, the
+    // channel on the API the call names. The webhook comes first, so an
+    // approval card names it.
+    operativeArgs: [
+        { field: "webhookUrlEnv", kind: "id" },
+        { field: "channel", kind: "recipient", service: "apiBaseUrl", ignoredWhen: "webhookUrlEnv" },
+    ],
     description: "Post a message to Slack, Discord, Microsoft Teams or a generic incoming webhook, with optional heading/paragraph/fields/divider/link blocks and a thread id where the platform threads. Use it when a harness needs to tell a room something rather than reply where it was spoken to — a nightly result, an alert, a hand-off. Every value is escaped for the platform before it is sent, so text carrying <!channel>, @everyone or a code fence can change what the message SAYS but never what it DOES; mentions are additionally suppressed at the API level. One tool covers four platforms because the payload differs and the intent does not. It takes an idempotency key so a retried call returns the first result instead of posting twice, and it will not follow a redirect — a webhook URL that moved is a configuration change, not something to chase at send time.",
     inputSchema: z.object({
         ...chatTargetShape,
@@ -399,9 +534,10 @@ export const chatPost = buildTool({
     requireJustification: true,
     execute: async (input, ctx) => {
         const args = input;
-        const cached = ledgerLookup("ChatPost", args.idempotencyKey);
+        const fingerprint = requestFingerprint(args);
+        const cached = ledgerAnswer("ChatPost", args.idempotencyKey, fingerprint);
         if (cached !== undefined)
-            return cached.result;
+            return cached;
         const rendered = renderMessage(args.platform, args.text, args.blocks);
         if (typeof rendered === "string")
             return notSentBecause(rendered);
@@ -418,7 +554,7 @@ export const chatPost = buildTool({
             apiPath = pathSpec.path;
             method = pathSpec.method;
         }
-        const route = routeChat(args, apiPath, true);
+        const route = routeChat(args, apiPath, true, resolveNotifyConfig(ctx?.toolConfig).allowedSecretEnvs);
         if (!route.ok)
             return notSentBecause(route.message);
         if (route.mode === "api" && args.channel === undefined) {
@@ -451,18 +587,33 @@ export const chatPost = buildTool({
             const failure = platformFailure(args.platform, outcome);
             if (failure !== null)
                 return prepared.redact(notSentBecause(failure));
+            const unknown = unknownVerdict(args.platform, outcome, route.mode);
+            if (unknown !== null) {
+                // Recorded like a success: the request was delivered, so a retry
+                // under the same key must not deliver it again.
+                const result = prepared.redact(json({
+                    sent: null,
+                    platform: args.platform,
+                    mode: route.mode,
+                    status: outcome.status,
+                    reason: unknown,
+                }));
+                ledgerRecord("ChatPost", args.idempotencyKey, fingerprint, result);
+                return result;
+            }
             const result = prepared.redact(json({
                 sent: true,
                 platform: args.platform,
                 mode: route.mode,
                 status: outcome.status,
+                ...unreadableField(outcome),
                 characters: rendered.text.length,
                 ...(postedMessageId(args.platform, outcome) !== undefined
                     ? { messageId: postedMessageId(args.platform, outcome) }
                     : {}),
                 ...(warnings.length > 0 ? { warnings: warnings.sort(byString) } : {}),
             }));
-            ledgerRecord("ChatPost", args.idempotencyKey, result);
+            ledgerRecord("ChatPost", args.idempotencyKey, fingerprint, result);
             return result;
         }
         catch (err) {
@@ -475,6 +626,7 @@ export const chatPost = buildTool({
 });
 export const chatUpdate = buildTool({
     name: "ChatUpdate",
+    operativeArgs: [{ field: "channel", kind: "recipient", service: "apiBaseUrl" }],
     description: "Edit a message this harness already posted, by its id, on a platform that allows it. Use it to keep one status message current instead of adding a new one every cycle — a deploy that goes queued → running → done reads better as one edited line than as three. It needs a bot token: an incoming webhook cannot edit, and Teams and generic webhooks cannot edit at all, so both are refused rather than silently reposted. An edit still notifies nobody, but the message is in front of people, so it carries the same gate as posting. The previous text is not returned, because the platform does not give it back.",
     inputSchema: z.object({
         ...chatTargetShape,
@@ -503,7 +655,7 @@ export const chatUpdate = buildTool({
         const pathSpec = apiPathFor(args.platform, "update", args.channel, args.messageId, undefined);
         if (typeof pathSpec === "string")
             return notSentBecause(pathSpec);
-        const route = routeChat(args, pathSpec.path, false);
+        const route = routeChat(args, pathSpec.path, false, resolveNotifyConfig(ctx?.toolConfig).allowedSecretEnvs);
         if (!route.ok)
             return notSentBecause(route.message);
         if (args.platform === "slack" && args.channel === undefined) {
@@ -523,11 +675,22 @@ export const chatUpdate = buildTool({
             const failure = platformFailure(args.platform, outcome);
             if (failure !== null)
                 return prepared.redact(notSentBecause(failure));
+            const unknown = unknownVerdict(args.platform, outcome, "api");
+            if (unknown !== null) {
+                return prepared.redact(json({
+                    updated: null,
+                    platform: args.platform,
+                    messageId: args.messageId,
+                    status: outcome.status,
+                    reason: unknown,
+                }));
+            }
             return prepared.redact(json({
                 updated: true,
                 platform: args.platform,
                 messageId: args.messageId,
                 status: outcome.status,
+                ...unreadableField(outcome),
                 characters: rendered.text.length,
                 ...(rendered.truncated
                     ? { warnings: ["the message was cut to the platform limit"] }
@@ -544,6 +707,7 @@ export const chatUpdate = buildTool({
 });
 export const chatDelete = buildTool({
     name: "ChatDelete",
+    operativeArgs: [{ field: "messageId", kind: "id", within: "channel", service: "apiBaseUrl" }],
     description: "Remove a message this harness posted, by its id. Use it to retract something that was wrong, or to tidy a transient status line once the run is over. Deleting does not unsend: anyone watching the channel has already seen it, and on most platforms a tombstone or an audit entry remains, so this is a cleanup tool and not a way to take something back. It needs a bot token, works only where the platform supports deletion, and cannot delete a message this harness did not post unless the token's own permissions allow it.",
     inputSchema: z.object({
         ...chatTargetShape,
@@ -563,7 +727,7 @@ export const chatDelete = buildTool({
         const pathSpec = apiPathFor(args.platform, "delete", args.channel, args.messageId, undefined);
         if (typeof pathSpec === "string")
             return notSentBecause(pathSpec);
-        const route = routeChat(args, pathSpec.path, false);
+        const route = routeChat(args, pathSpec.path, false, resolveNotifyConfig(ctx?.toolConfig).allowedSecretEnvs);
         if (!route.ok)
             return notSentBecause(route.message);
         if (args.platform === "slack" && args.channel === undefined) {
@@ -578,11 +742,13 @@ export const chatDelete = buildTool({
             const failure = platformFailure(args.platform, outcome);
             if (failure !== null)
                 return prepared.redact(`the message was not deleted: ${failure}`);
+            const unknown = unknownVerdict(args.platform, outcome, "api");
             return prepared.redact(json({
-                deleted: true,
+                deleted: unknown === null ? true : null,
                 platform: args.platform,
                 messageId: args.messageId,
                 status: outcome.status,
+                ...(unknown === null ? unreadableField(outcome) : { reason: unknown }),
             }));
         }
         catch (err) {
@@ -595,6 +761,7 @@ export const chatDelete = buildTool({
 });
 export const chatReact = buildTool({
     name: "ChatReact",
+    operativeArgs: [{ field: "messageId", kind: "id", within: "channel", service: "apiBaseUrl" }],
     description: "Add an emoji reaction to a message, as the token's own user. Use it to acknowledge something cheaply — a ✅ on the alert that has been handled says as much as a reply and adds no noise. A reaction is visible to the room and shows who left it, so it counts as putting something in front of people and takes the same gate as a post. Give the emoji by name without colons on Slack, and as the literal character or name:id on Discord; an emoji the workspace does not have is refused by the platform, not invented here.",
     inputSchema: z.object({
         ...chatTargetShape,
@@ -619,7 +786,7 @@ export const chatReact = buildTool({
         const pathSpec = apiPathFor(args.platform, "react", args.channel, args.messageId, args.emoji);
         if (typeof pathSpec === "string")
             return notSentBecause(pathSpec);
-        const route = routeChat(args, pathSpec.path, false);
+        const route = routeChat(args, pathSpec.path, false, resolveNotifyConfig(ctx?.toolConfig).allowedSecretEnvs);
         if (!route.ok)
             return notSentBecause(route.message);
         if (args.platform === "slack" && args.channel === undefined) {
@@ -638,12 +805,14 @@ export const chatReact = buildTool({
             const failure = platformFailure(args.platform, outcome);
             if (failure !== null)
                 return prepared.redact(`the reaction was not added: ${failure}`);
+            const unknown = unknownVerdict(args.platform, outcome, "api");
             return prepared.redact(json({
-                reacted: true,
+                reacted: unknown === null ? true : null,
                 platform: args.platform,
                 messageId: args.messageId,
                 emoji: args.emoji,
                 status: outcome.status,
+                ...(unknown === null ? unreadableField(outcome) : { reason: unknown }),
             }));
         }
         catch (err) {
@@ -796,13 +965,10 @@ function loadAttachments(toolName, specs) {
 }
 /** Build the message, or the readable reason it could not be built. */
 function buildMessage(toolName, args) {
-    const when = new Date(args.date);
-    if (Number.isNaN(when.getTime())) {
-        return {
-            ok: false,
-            message: `"${args.date}" is not an instant this tool can read — use ISO-8601 with an offset, e.g. 2026-09-17T09:30:00Z`,
-        };
-    }
+    const instant = parseOffsetInstant(args.date);
+    if (!instant.ok)
+        return { ok: false, message: instant.message };
+    const when = new Date(instant.ms);
     const loaded = loadAttachments(toolName, args.attachments);
     if (!loaded.ok)
         return { ok: false, message: loaded.message };
@@ -835,6 +1001,7 @@ function buildMessage(toolName, args) {
         messageId: composed.messageId,
         bytes: composed.bytes,
         envelopeTo: composed.envelopeTo,
+        attachmentDigests: loaded.attachments.map((a) => createHash("sha256").update(a.content).digest("hex")),
     };
 }
 export const emailCompose = buildTool({
@@ -857,8 +1024,42 @@ export const emailCompose = buildTool({
         });
     },
 });
+/**
+ * A retry of an EmailSend whose message can no longer be built — most often
+ * because an attachment was a temp file cleaned up after the first send —
+ * under a key that already sent a message agreeing on everything but the
+ * attachments' bytes. Answering "nothing was sent" there would read as the
+ * FIRST message being unsent, and invite a second send (net regression
+ * review). So the recorded answer is given, with a note that this call sent
+ * nothing and could not confirm the attachments are the same. Undefined when
+ * the key recorded nothing like it.
+ */
+function unconfirmedEmailReplay(args, reason) {
+    const answer = ledgerLookup("EmailSend", args.idempotencyKey, requestFingerprint({ ...args, date: undefined }), ["attachmentContent"]);
+    if (answer?.kind !== "replay")
+        return undefined;
+    const note = `idempotencyKey "${args.idempotencyKey}" already sent this message, and this is what that send returned. This call sent nothing: its message could not be built again (${reason}), so whether its attachments are the same as the ones sent is not known`;
+    try {
+        const recorded = JSON.parse(answer.result);
+        if (typeof recorded === "object" && recorded !== null && !Array.isArray(recorded)) {
+            return json({ ...recorded, replayNote: note });
+        }
+    }
+    catch {
+        // not JSON: the note goes on a line of its own
+    }
+    return `${answer.result}\n${note}`;
+}
 export const emailSend = buildTool({
     name: "EmailSend",
+    // The files attached are sent with the message: a deny or ask reads them,
+    // an allow on the recipients need not.
+    operativeArgs: [
+        { field: "to.address", kind: "recipient" },
+        { field: "cc.address", kind: "recipient" },
+        { field: "bcc.address", kind: "recipient" },
+        { field: "attachments.path", kind: "path", source: true },
+    ],
     description: "Send a message over SMTP: EHLO, STARTTLS, AUTH, MAIL FROM, RCPT TO, DATA, written out rather than delegated. Use it when the thing to report belongs in somebody's inbox rather than in a chat room. STARTTLS is required by default and the session ends before the password is written if the server does not offer it; the credential is an environment variable NAME and the transcript records the AUTH line as redacted. Every recipient must match the operator's allow-list and the SMTP host must be one an operator named, both of which deny everything when unset. The whole session is deadline-bounded and the server's replies are byte-capped. It does not queue, retry, or track bounces — a refused recipient comes back named, and re-sending is the caller's decision.",
     inputSchema: z.object({
         ...composeShape,
@@ -879,13 +1080,13 @@ export const emailSend = buildTool({
             .min(1)
             .max(64)
             .optional()
-            .describe("NAME of the environment variable holding the SMTP username"),
+            .describe("NAME of the environment variable holding the SMTP username, listed in tool_config.notify.allowed_secret_envs"),
         passwordEnv: z
             .string()
             .min(1)
             .max(64)
             .optional()
-            .describe("NAME of the environment variable holding the SMTP password"),
+            .describe("NAME of the environment variable holding the SMTP password, listed in tool_config.notify.allowed_secret_envs"),
         authMethod: z
             .enum(["plain", "login", "auto"])
             .optional()
@@ -905,9 +1106,6 @@ export const emailSend = buildTool({
     requireJustification: true,
     execute: async (input, ctx) => {
         const args = input;
-        const cached = ledgerLookup("EmailSend", args.idempotencyKey);
-        if (cached !== undefined)
-            return cached.result;
         const cfg = resolveNotifyConfig(ctx?.toolConfig);
         const everyone = [...(args.to ?? []), ...(args.cc ?? []), ...(args.bcc ?? [])];
         if (everyone.length === 0)
@@ -928,19 +1126,38 @@ export const emailSend = buildTool({
             if (args.usernameEnv === undefined || args.passwordEnv === undefined) {
                 return notSentBecause("set both usernameEnv and passwordEnv, or neither");
             }
-            const user = resolveSecret(args.usernameEnv, "the SMTP username");
+            const user = resolveSecret(args.usernameEnv, "the SMTP username", cfg.allowedSecretEnvs);
             if (!user.ok)
                 return notSentBecause(user.message);
-            const pass = resolveSecret(args.passwordEnv, "the SMTP password");
+            const pass = resolveSecret(args.passwordEnv, "the SMTP password", cfg.allowedSecretEnvs);
             if (!pass.ok)
                 return notSentBecause(pass.message);
             username = user.value;
             password = pass.value;
         }
         const built = buildMessage("EmailSend", args);
-        if (!built.ok)
-            return notSentBecause(built.message);
-        const redact = redactorFor([username, password]);
+        if (!built.ok) {
+            const replay = unconfirmedEmailReplay(args, built.message);
+            return replay ?? notSentBecause(built.message);
+        }
+        // The ledger is asked about the message that would be SENT, so it is
+        // consulted after the build. `date` only stamps the message, so a retry
+        // that re-reads its clock is still the same message; everything that
+        // says who gets what is compared, and an attachment by its bytes: a key
+        // reused after report.txt was rewritten is a different message, not a
+        // retry of the first (net review, C207). Consulting it before the build
+        // replayed the first `sent: true` for a body that was never sent.
+        const fingerprint = requestFingerprint({
+            ...args,
+            date: undefined,
+            attachmentContent: built.attachmentDigests.length > 0 ? built.attachmentDigests : undefined,
+        });
+        const cached = ledgerAnswer("EmailSend", args.idempotencyKey, fingerprint);
+        if (cached !== undefined)
+            return cached;
+        // The username is an identifier, redacted whole as 0.7.0 did; only the
+        // password is a secret whose cut start is caught.
+        const redact = redactorFor([password], [username]);
         const deadline = startDeadline(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, ctx?.signal);
         try {
             assertSmtpHostAllowed(args.host, cfg);
@@ -976,7 +1193,7 @@ export const emailSend = buildTool({
                 ...(outcome.rejected.length > 0 ? { rejected: outcome.rejected } : {}),
                 queued: outcome.queued,
             }));
-            ledgerRecord("EmailSend", args.idempotencyKey, result);
+            ledgerRecord("EmailSend", args.idempotencyKey, fingerprint, result);
             return result;
         }
         catch (err) {
@@ -1250,6 +1467,11 @@ export const emailSendPreflight = buildTool({
 // ---------------------------------------------------------------------------
 export const webhookPost = buildTool({
     name: "WebhookPost",
+    // The URL, or the variable that holds one whose path is a secret.
+    operativeArgs: [
+        { field: "url", kind: "url" },
+        { field: "urlEnv", kind: "id" },
+    ],
     description: "POST a JSON payload to an allow-listed URL, optionally HMAC-signed, retrying only on 5xx and only on a backoff the call declares. Use it to hand an event to something that is not a chat platform — a pager, an internal receiver, a partner endpoint. Signing runs over the exact bytes transmitted, in either the timestamped (Stripe-style) or body-only (GitHub-style) scheme, and the timestamp is an argument rather than a clock reading so the same call signs the same way twice. The backoff is exponential with no jitter, because unseeded randomness makes a run unreproducible, and it never sleeps past the deadline. An idempotency key makes a retry safe end to end: the key travels to the receiver and a repeat call returns the first result instead of delivering again.",
     inputSchema: z.object({
         url: z
@@ -1262,7 +1484,7 @@ export const webhookPost = buildTool({
             .min(1)
             .max(64)
             .optional()
-            .describe("NAME of an environment variable holding the URL, for an endpoint whose path is itself a secret"),
+            .describe("NAME of an environment variable holding the URL, for an endpoint whose path is itself a secret; it must be listed in tool_config.notify.allowed_secret_envs"),
         payload: z
             .union([z.record(z.unknown()), z.array(z.unknown()), z.string()])
             .describe("an object or array, sent as JSON, or a string sent verbatim — a signature covers exactly these bytes"),
@@ -1321,16 +1543,23 @@ export const webhookPost = buildTool({
     requireJustification: true,
     execute: async (input, ctx) => {
         const args = input;
-        const cached = ledgerLookup("WebhookPost", args.idempotencyKey);
+        // A signature's timestamp only stamps the delivery; the payload and the
+        // destination are what make it a different request.
+        const fingerprint = requestFingerprint({
+            ...args,
+            signing: args.signing === undefined ? undefined : { ...args.signing, timestampSeconds: undefined },
+        });
+        const cached = ledgerAnswer("WebhookPost", args.idempotencyKey, fingerprint);
         if (cached !== undefined)
-            return cached.result;
+            return cached;
         if ((args.url === undefined) === (args.urlEnv === undefined)) {
             return notSentBecause("give exactly one of url or urlEnv");
         }
+        const allowedEnvs = resolveNotifyConfig(ctx?.toolConfig).allowedSecretEnvs;
         const urlSecrets = [];
         let url;
         if (args.urlEnv !== undefined) {
-            const resolved = webhookUrlFrom(args.urlEnv);
+            const resolved = webhookUrlFrom(args.urlEnv, allowedEnvs);
             if (typeof resolved === "string")
                 return notSentBecause(resolved);
             url = resolved.url;
@@ -1346,13 +1575,13 @@ export const webhookPost = buildTool({
             url = parsed;
         }
         const body = typeof args.payload === "string" ? args.payload : JSON.stringify(args.payload);
-        const headerPrep = prepareHeaders({ "content-type": "application/json", ...(args.headers ?? {}) }, args.auth);
+        const headerPrep = prepareHeaders({ "content-type": "application/json", ...(args.headers ?? {}) }, args.auth, allowedEnvs);
         if (!headerPrep.ok)
             return notSentBecause(headerPrep.message);
         const headers = headerPrep.headers;
         const secrets = [...urlSecrets, ...headerPrep.secrets];
         if (args.signing !== undefined) {
-            const secret = resolveSecret(args.signing.secretEnv, "the signing secret");
+            const secret = resolveSecret(args.signing.secretEnv, "the signing secret", allowedEnvs);
             if (!secret.ok)
                 return notSentBecause(secret.message);
             secrets.push(secret.value);
@@ -1391,8 +1620,9 @@ export const webhookPost = buildTool({
                         signed: args.signing !== undefined,
                         ...(attempts.length > 0 ? { earlierAttempts: attempts } : {}),
                         ...(outcome.body !== "" ? { response: outcome.body } : {}),
+                        ...unreadableField(outcome),
                     }));
-                    ledgerRecord("WebhookPost", args.idempotencyKey, result);
+                    ledgerRecord("WebhookPost", args.idempotencyKey, fingerprint, result);
                     return result;
                 }
                 const retryable = outcome === null || outcome.status >= 500;
@@ -1402,8 +1632,16 @@ export const webhookPost = buildTool({
                     ...(transportError !== null ? { error: transportError } : {}),
                 });
                 if (!retryable) {
-                    return prepared.redact(notSentBecause(`${safeUrlLabel(url)} answered ${outcome.status}, which is not a retryable status: ${outcome.body.slice(0, 500)}`));
+                    return prepared.redact(notSentBecause(`${safeUrlLabel(url)} answered ${outcome.status}, which is not a retryable status: ${outcome.replyUnreadable ?? outcome.excerpt}`));
                 }
+                // Once the signal has aborted — a cancel, or the timer ahead of the
+                // clock — no retry starts: each would fail at once, count as an
+                // attempt, and spend the rest of `retries` in a few milliseconds. It
+                // is asked before the retry count, so a cancel during the last
+                // attempt reads as a cancel too, not as "all N attempt(s) failed".
+                const stopped = () => prepared.redact(`${notSentBecause(describeFailure(prepared.deadline.signal.reason, prepared.deadline))}\n${json({ attempts })}`);
+                if (prepared.deadline.signal.aborted)
+                    return stopped();
                 if (attempt >= retries) {
                     return prepared.redact(`${notSentBecause(`all ${attempt + 1} attempt(s) failed`)}\n${json({ attempts })}`);
                 }
@@ -1412,6 +1650,8 @@ export const webhookPost = buildTool({
                     return prepared.redact(`${notSentBecause(`the next backoff of ${delay}ms would outlast the deadline`)}\n${json({ attempts })}`);
                 }
                 await sleep(delay, prepared.deadline.signal);
+                if (prepared.deadline.signal.aborted)
+                    return stopped();
             }
         }
         catch (err) {
@@ -1446,7 +1686,7 @@ function buildProviderCall(cfg, providerName, values, idempotencyKey) {
     if (typeof parsed === "string")
         return { ok: false, message: `provider "${providerName}" has an unusable endpoint` };
     const headers = {};
-    const applied = applyAuth(headers, profile.auth);
+    const applied = applyAuth(headers, profile.auth, providerAuthEnvs(profile));
     if (!applied.ok)
         return { ok: false, message: applied.message };
     if (idempotencyKey !== undefined && profile.idempotencyHeader !== undefined) {
@@ -1485,23 +1725,38 @@ function buildProviderCall(cfg, providerName, values, idempotencyKey) {
     };
 }
 /** The shared execute body for SmsSend and PushNotify. */
-async function runProviderSend(toolName, providerName, values, args, ctx) {
-    const cached = ledgerLookup(toolName, args.idempotencyKey);
-    if (cached !== undefined)
-        return cached.result;
+async function runProviderSend(toolName, kind, providerName, values, args, ctx) {
     const cfg = resolveNotifyConfig(ctx?.toolConfig);
-    const call = buildProviderCall(cfg, providerName, values, args.idempotencyKey);
+    // The destination is checked first, before the ledger: a key reused for a
+    // number the list no longer admits is refused, not answered from memory.
+    // A provider that maps no `to` never sends the caller's value, so its
+    // destination is whatever the operator pinned in staticFields.
+    const profile = cfg.providers.get(providerName);
+    if (profile?.fields?.["to"] !== undefined) {
+        const refused = destinationRefusal(values["to"] ?? "", kind, cfg);
+        if (refused !== null)
+            return notSentBecause(refused);
+    }
+    // What is sent is the destination the list decided on, in the form it
+    // compared: the number in E.164 form, not the call's spelling of it.
+    const sending = { ...values, to: destinationFor(values["to"] ?? "", kind) };
+    const fingerprint = requestFingerprint({ provider: providerName, ...sending });
+    const cached = ledgerAnswer(toolName, args.idempotencyKey, fingerprint);
+    if (cached !== undefined)
+        return cached;
+    const call = buildProviderCall(cfg, providerName, sending, args.idempotencyKey);
     if (!call.ok)
         return notSentBecause(call.message);
     const prepared = {
         cfg,
         deadline: startDeadline(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, ctx?.signal),
         redact: redactorFor(call.secrets),
+        secrets: call.secrets,
     };
     try {
         const outcome = await send(call.url, call.method, call.headers, call.body, prepared, args.maxBytes ?? DEFAULT_MAX_BYTES, call.secretHeaders);
         if (!outcome.ok) {
-            return prepared.redact(notSentBecause(`${safeUrlLabel(call.url)} answered ${outcome.status}: ${outcome.body.slice(0, 500)}`));
+            return prepared.redact(notSentBecause(`${safeUrlLabel(call.url)} answered ${outcome.status}: ${outcome.replyUnreadable ?? outcome.excerpt}`));
         }
         const profile = cfg.providers.get(providerName);
         const id = profile.idPath === undefined ? undefined : readPath(outcome.parsed, profile.idPath);
@@ -1512,8 +1767,9 @@ async function runProviderSend(toolName, providerName, values, args, ctx) {
             status: outcome.status,
             ...(typeof id === "string" || typeof id === "number" ? { messageId: String(id) } : {}),
             ...(typeof status === "string" ? { deliveryStatus: status } : {}),
+            ...unreadableField(outcome),
         }));
-        ledgerRecord(toolName, args.idempotencyKey, result);
+        ledgerRecord(toolName, args.idempotencyKey, fingerprint, result);
         return result;
     }
     catch (err) {
@@ -1525,6 +1781,7 @@ async function runProviderSend(toolName, providerName, values, args, ctx) {
 }
 export const smsSend = buildTool({
     name: "SmsSend",
+    operativeArgs: [{ field: "to", kind: "recipient" }],
     description: "Send an SMS through a REST gateway the operator described in tool_config, rather than through a vendor this tool picked. Use it for the small number of notifications that must reach somebody who is not looking at a screen. The provider block names the endpoint, the auth environment variable and how the canonical fields to, body and from map onto that vendor's own names, so changing gateway is a config diff and not a release. An SMS costs money, arrives on a phone and cannot be recalled, so it is destructive, takes a justification, and takes an idempotency key that makes a retried call return the first result instead of sending a second message. It does not split a long message into parts or tell you what the carrier charged.",
     inputSchema: z.object({
         provider: z.string().min(1).max(100).describe("a name from tool_config.notify.providers"),
@@ -1532,7 +1789,7 @@ export const smsSend = buildTool({
             .string()
             .min(1)
             .max(100)
-            .describe("the destination number, in the format the provider expects (E.164 for most)"),
+            .describe("the destination number; it must be in tool_config.notify.allowed_sms_recipients, which is matched in E.164 form (+ and digits; spaces, dashes, dots and parentheses are ignored), and it is sent in that form"),
         body: z
             .string()
             .min(1)
@@ -1554,11 +1811,12 @@ export const smsSend = buildTool({
     requireJustification: true,
     execute: async (input, ctx) => {
         const args = input;
-        return runProviderSend("SmsSend", args.provider, { to: args.to, body: args.body, from: args.from ?? "" }, args, ctx);
+        return runProviderSend("SmsSend", "sms", args.provider, { to: args.to, body: args.body, from: args.from ?? "" }, args, ctx);
     },
 });
 export const pushNotify = buildTool({
     name: "PushNotify",
+    operativeArgs: [{ field: "to", kind: "recipient" }],
     description: "Send a push notification through a REST provider the operator described in tool_config. Use it to reach an app or a device when a chat message would not be seen in time. It works exactly as SmsSend does — the provider block maps the canonical fields to, title, body and data onto the vendor's names — so one configuration style covers both, and a provider with no title concept simply never receives one. A push lands on a lock screen, so it is destructive and takes a justification; the idempotency key makes a retry safe. It does not manage device tokens, topics or subscriptions, and it reports what the provider answered rather than whether anyone read it.",
     inputSchema: z.object({
         provider: z.string().min(1).max(100).describe("a name from tool_config.notify.providers"),
@@ -1566,7 +1824,7 @@ export const pushNotify = buildTool({
             .string()
             .min(1)
             .max(500)
-            .describe("device token, topic or whatever the provider addresses"),
+            .describe("device token, topic or whatever the provider addresses; it must be in tool_config.notify.allowed_push_targets"),
         title: z.string().max(200).optional(),
         body: z.string().min(1).max(4000),
         data: z
@@ -1587,7 +1845,7 @@ export const pushNotify = buildTool({
         for (const key of Object.keys(args.data ?? {}).sort(byString)) {
             ordered[key] = args.data[key];
         }
-        return runProviderSend("PushNotify", args.provider, {
+        return runProviderSend("PushNotify", "push", args.provider, {
             to: args.to,
             title: args.title ?? "",
             body: args.body,
@@ -1597,6 +1855,7 @@ export const pushNotify = buildTool({
 });
 export const deliveryCheck = buildTool({
     name: "DeliveryCheck",
+    operativeArgs: [{ field: "messageId", kind: "id", within: "provider" }],
     description: "Ask a provider what became of a message it accepted earlier, where its API answers that question. Use it after SmsSend or PushNotify to tell 'the gateway took it' apart from 'the handset got it', which are not the same thing and are reported hours apart. It reads the statusEndpoint and statusPath the operator configured for that provider, substituting the message id into the URL, and it only reads — this is the one outbound tool here that is readOnly and needs no justification. A provider with no status endpoint configured is reported as such rather than guessed at, and an unknown id is whatever the provider says it is.",
     inputSchema: z.object({
         provider: z.string().min(1).max(100).describe("a name from tool_config.notify.providers"),
@@ -1627,11 +1886,18 @@ export const deliveryCheck = buildTool({
         if (!/^[A-Za-z0-9_.:-]+$/.test(args.messageId)) {
             return "messageId must be a plain identifier (letters, digits, dot, underscore, colon or hyphen) — anything else could rewrite the URL it is substituted into";
         }
-        const parsed = parseUrl(profile.statusEndpoint.split("{id}").join(encodeURIComponent(args.messageId)));
-        if (typeof parsed === "string")
-            return `provider "${args.provider}" has an unusable statusEndpoint`;
+        if (isDotSegment(args.messageId)) {
+            return `messageId "${args.messageId}" is a relative path segment, not an id — substituted into the status URL it would read a different endpoint (a message list, or the API root), so nothing was sent`;
+        }
+        const substituted = substituteIntoUrl(profile.statusEndpoint, "{id}", args.messageId);
+        if (!substituted.ok) {
+            return substituted.why === "invalid"
+                ? `provider "${args.provider}" has an unusable statusEndpoint`
+                : `messageId "${args.messageId}" would change which endpoint the status URL addresses, not just name the message — nothing was sent`;
+        }
+        const parsed = substituted.url;
         const headers = {};
-        const applied = applyAuth(headers, profile.auth);
+        const applied = applyAuth(headers, profile.auth, providerAuthEnvs(profile));
         if (!applied.ok)
             return applied.message;
         const cfgForCall = cfg;
@@ -1648,7 +1914,7 @@ export const deliveryCheck = buildTool({
                 redirect: "follow",
                 credentialHeaders: applied.secretHeaders,
             });
-            const capped = await readCapped(opened.res, args.maxBytes ?? DEFAULT_MAX_BYTES);
+            const capped = await readCapped(opened.res, args.maxBytes ?? DEFAULT_MAX_BYTES, deadline.signal, applied.secrets);
             let parsedBody;
             try {
                 parsedBody = JSON.parse(capped.text);
@@ -1814,6 +2080,7 @@ function describeDkim(answer) {
 }
 export const deliverabilityCheck = buildTool({
     name: "DeliverabilityCheck",
+    operativeArgs: [{ field: "domain", kind: "recipient" }],
     description: "Read what a sending domain publishes about itself in public DNS — its SPF record, its DMARC policy, and the DKIM key record at each selector you name — and report what each one says. Use it to answer why mail from a domain is being refused or filtered, or to check a domain before a campaign leans on it. It reports facts rather than a score, because the facts differ in what you do next: no DMARC record at all and a DMARC record with p=none are the same score and completely different situations, and a lookup that failed is a third thing again — reported as unknown with its reason, never as 'nothing published'. It does NOT verify a message's DKIM signature: that needs canonicalisation this package does not implement, and a partial check that can answer 'pass' is worse than no check. Only domains an operator put in allowed_sender_domains are looked up.",
     inputSchema: z.object({
         domain: z
@@ -2031,11 +2298,10 @@ export const quietHours = buildTool({
     concurrencySafe: true,
     execute: async (input) => {
         const args = input;
-        const now = new Date(args.now);
-        if (Number.isNaN(now.getTime())) {
-            return `"${args.now}" is not an instant this tool can read — use ISO-8601 with an offset, e.g. 2026-09-17T03:14:00Z`;
-        }
-        const decision = quietDecision(args.schedule, now.getTime());
+        const now = parseOffsetInstant(args.now, "2026-09-17T03:14:00Z");
+        if (!now.ok)
+            return now.message;
+        const decision = quietDecision(args.schedule, now.ms);
         if ("error" in decision)
             return decision.error;
         return json(decision);
@@ -2049,7 +2315,7 @@ export const rateLimitGate = buildTool({
             .string()
             .min(1)
             .max(500)
-            .describe("what is being rate-limited: an alert name, a host, a customer id"),
+            .describe('what is being rate-limited: an alert name, a host, a customer id (any string except "__proto__", which a JSON state record cannot hold)'),
         now: z
             .string()
             .min(1)
@@ -2081,13 +2347,19 @@ export const rateLimitGate = buildTool({
     concurrencySafe: true,
     execute: async (input) => {
         const args = input;
-        const now = new Date(args.now);
-        if (Number.isNaN(now.getTime())) {
-            return `"${args.now}" is not an instant this tool can read — use ISO-8601 with an offset, e.g. 2026-09-17T03:14:00Z`;
+        const now = parseOffsetInstant(args.now, "2026-09-17T03:14:00Z");
+        if (!now.ok)
+            return now.message;
+        // The state is a JSON record, and a JSON record cannot carry this one
+        // key back: the input parser drops an own "__proto__" key, so the entry
+        // this call wrote would be gone on the next call and the gate would say
+        // "allowed" every time. Refused, so the gate never fails open.
+        if (args.key === "__proto__") {
+            return 'the key "__proto__" cannot be kept in a JSON state record, so it could never be limited — choose another, e.g. prefix it as "alert:__proto__"';
         }
         return json(evaluateRateLimit({
             key: args.key,
-            nowMs: now.getTime(),
+            nowMs: now.ms,
             windowMs: args.windowMs,
             ...(args.limit !== undefined ? { limit: args.limit } : {}),
             ...(args.mode !== undefined ? { mode: args.mode } : {}),
@@ -2120,7 +2392,10 @@ export const messageTemplate = buildTool({
     concurrencySafe: true,
     execute: async (input) => {
         const args = input;
-        const template = args.templates[args.name];
+        // Own names only: "constructor" or "toString" is not a template.
+        const template = Object.hasOwn(args.templates, args.name)
+            ? args.templates[args.name]
+            : undefined;
         if (template === undefined) {
             const known = Object.keys(args.templates).sort(byString);
             return known.length === 0