@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/gateway/hooks.js

@@ -1,14 +1,16 @@
 import { randomUUID } from "node:crypto";
 import { listAgentIds, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { listChannelPlugins } from "../channels/plugins/index.js";
+import { readJsonBodyWithLimit, requestBodyErrorToText } from "../infra/http-body.js";
 import { normalizeAgentId } from "../routing/session-key.js";
 import { normalizeMessageChannel } from "../utils/message-channel.js";
 import { resolveHookMappings } from "./hooks-mapping.js";
 const DEFAULT_HOOKS_PATH = "/hooks";
 const DEFAULT_HOOKS_MAX_BODY_BYTES = 256 * 1024;
 export function resolveHooksConfig(cfg) {
-    if (cfg.hooks?.enabled !== true)
+    if (cfg.hooks?.enabled !== true) {
         return null;
+    }
     const token = cfg.hooks?.token?.trim();
     if (!token) {
         throw new Error("hooks.enabled requires hooks.token");
@@ -26,6 +28,18 @@ export function resolveHooksConfig(cfg) {
     const defaultAgentId = resolveDefaultAgentId(cfg);
     const knownAgentIds = resolveKnownAgentIds(cfg, defaultAgentId);
     const allowedAgentIds = resolveAllowedAgentIds(cfg.hooks?.allowedAgentIds);
+    const defaultSessionKey = resolveSessionKey(cfg.hooks?.defaultSessionKey);
+    const allowedSessionKeyPrefixes = resolveAllowedSessionKeyPrefixes(cfg.hooks?.allowedSessionKeyPrefixes);
+    if (defaultSessionKey &&
+        allowedSessionKeyPrefixes &&
+        !isSessionKeyAllowedByPrefix(defaultSessionKey, allowedSessionKeyPrefixes)) {
+        throw new Error("hooks.defaultSessionKey must match hooks.allowedSessionKeyPrefixes");
+    }
+    if (!defaultSessionKey &&
+        allowedSessionKeyPrefixes &&
+        !isSessionKeyAllowedByPrefix("hook:example", allowedSessionKeyPrefixes)) {
+        throw new Error("hooks.allowedSessionKeyPrefixes must include 'hook:' when hooks.defaultSessionKey is unset");
+    }
     return {
         basePath: trimmed,
         token,
@@ -36,6 +50,11 @@ export function resolveHooksConfig(cfg) {
             knownAgentIds,
             allowedAgentIds,
         },
+        sessionPolicy: {
+            defaultSessionKey,
+            allowRequestSessionKey: cfg.hooks?.allowRequestSessionKey === true,
+            allowedSessionKeyPrefixes,
+        },
     };
 }
 function resolveKnownAgentIds(cfg, defaultAgentId) {
@@ -65,62 +84,68 @@ function resolveAllowedAgentIds(raw) {
     }
     return allowed;
 }
+function resolveSessionKey(raw) {
+    const value = raw?.trim();
+    return value ? value : undefined;
+}
+function normalizeSessionKeyPrefix(raw) {
+    const value = raw.trim().toLowerCase();
+    return value ? value : undefined;
+}
+function resolveAllowedSessionKeyPrefixes(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const set = new Set();
+    for (const prefix of raw) {
+        const normalized = normalizeSessionKeyPrefix(prefix);
+        if (!normalized) {
+            continue;
+        }
+        set.add(normalized);
+    }
+    return set.size > 0 ? Array.from(set) : undefined;
+}
+function isSessionKeyAllowedByPrefix(sessionKey, prefixes) {
+    const normalized = sessionKey.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return prefixes.some((prefix) => normalized.startsWith(prefix));
+}
 export function extractHookToken(req, url) {
     const auth = typeof req.headers.authorization === "string" ? req.headers.authorization.trim() : "";
     if (auth.toLowerCase().startsWith("bearer ")) {
         const token = auth.slice(7).trim();
-        if (token)
+        if (token) {
             return { token, fromQuery: false };
+        }
     }
     const headerToken = typeof req.headers["x-poolbot-token"] === "string" ? req.headers["x-poolbot-token"].trim() : "";
-    if (headerToken)
+    if (headerToken) {
         return { token: headerToken, fromQuery: false };
-    const queryToken = url.searchParams.get("token");
-    if (queryToken)
-        return { token: queryToken.trim(), fromQuery: true };
+    }
+    const queryToken = url?.searchParams.get("token")?.trim();
+    if (queryToken) {
+        return { token: queryToken, fromQuery: true };
+    }
     return { token: undefined, fromQuery: false };
 }
 export async function readJsonBody(req, maxBytes) {
-    return await new Promise((resolve) => {
-        let done = false;
-        let total = 0;
-        const chunks = [];
-        req.on("data", (chunk) => {
-            if (done)
-                return;
-            total += chunk.length;
-            if (total > maxBytes) {
-                done = true;
-                resolve({ ok: false, error: "payload too large" });
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => {
-            if (done)
-                return;
-            done = true;
-            const raw = Buffer.concat(chunks).toString("utf-8").trim();
-            if (!raw) {
-                resolve({ ok: true, value: {} });
-                return;
-            }
-            try {
-                const parsed = JSON.parse(raw);
-                resolve({ ok: true, value: parsed });
-            }
-            catch (err) {
-                resolve({ ok: false, error: String(err) });
-            }
-        });
-        req.on("error", (err) => {
-            if (done)
-                return;
-            done = true;
-            resolve({ ok: false, error: String(err) });
-        });
-    });
+    const result = await readJsonBodyWithLimit(req, { maxBytes, emptyObjectOnEmpty: true });
+    if (result.ok) {
+        return result;
+    }
+    if (result.code === "PAYLOAD_TOO_LARGE") {
+        return { ok: false, error: "payload too large" };
+    }
+    if (result.code === "REQUEST_BODY_TIMEOUT") {
+        return { ok: false, error: "request body timeout" };
+    }
+    if (result.code === "CONNECTION_CLOSED") {
+        return { ok: false, error: requestBodyErrorToText("CONNECTION_CLOSED") };
+    }
+    return { ok: false, error: result.error };
 }
 export function normalizeHookHeaders(req) {
     const headers = {};
@@ -136,8 +161,9 @@ export function normalizeHookHeaders(req) {
 }
 export function normalizeWakePayload(payload) {
     const text = typeof payload.text === "string" ? payload.text.trim() : "";
-    if (!text)
+    if (!text) {
         return { ok: false, error: "text required" };
+    }
     const mode = payload.mode === "next-heartbeat" ? "next-heartbeat" : "now";
     return { ok: true, value: { text, mode } };
 }
@@ -145,13 +171,16 @@ const listHookChannelValues = () => ["last", ...listChannelPlugins().map((plugin
 const getHookChannelSet = () => new Set(listHookChannelValues());
 export const getHookChannelError = () => `channel must be ${listHookChannelValues().join("|")}`;
 export function resolveHookChannel(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return "last";
-    if (typeof raw !== "string")
+    }
+    if (typeof raw !== "string") {
         return null;
+    }
     const normalized = normalizeMessageChannel(raw);
-    if (!normalized || !getHookChannelSet().has(normalized))
+    if (!normalized || !getHookChannelSet().has(normalized)) {
         return null;
+    }
     return normalized;
 }
 export function resolveHookDeliver(raw) {
@@ -182,23 +211,49 @@ export function isHookAgentAllowed(hooksConfig, agentId) {
     return resolved ? allowed.has(resolved) : false;
 }
 export const getHookAgentPolicyError = () => "agentId is not allowed by hooks.allowedAgentIds";
+export const getHookSessionKeyRequestPolicyError = () => "sessionKey is disabled for external /hooks/agent payloads; set hooks.allowRequestSessionKey=true to enable";
+export const getHookSessionKeyPrefixError = (prefixes) => `sessionKey must start with one of: ${prefixes.join(", ")}`;
+export function resolveHookSessionKey(params) {
+    const requested = resolveSessionKey(params.sessionKey);
+    if (requested) {
+        if (params.source === "request" && !params.hooksConfig.sessionPolicy.allowRequestSessionKey) {
+            return { ok: false, error: getHookSessionKeyRequestPolicyError() };
+        }
+        const allowedPrefixes = params.hooksConfig.sessionPolicy.allowedSessionKeyPrefixes;
+        if (allowedPrefixes && !isSessionKeyAllowedByPrefix(requested, allowedPrefixes)) {
+            return { ok: false, error: getHookSessionKeyPrefixError(allowedPrefixes) };
+        }
+        return { ok: true, value: requested };
+    }
+    const defaultSessionKey = params.hooksConfig.sessionPolicy.defaultSessionKey;
+    if (defaultSessionKey) {
+        return { ok: true, value: defaultSessionKey };
+    }
+    const generated = `hook:${(params.idFactory ?? randomUUID)()}`;
+    const allowedPrefixes = params.hooksConfig.sessionPolicy.allowedSessionKeyPrefixes;
+    if (allowedPrefixes && !isSessionKeyAllowedByPrefix(generated, allowedPrefixes)) {
+        return { ok: false, error: getHookSessionKeyPrefixError(allowedPrefixes) };
+    }
+    return { ok: true, value: generated };
+}
 export function normalizeAgentPayload(payload, opts) {
     const message = typeof payload.message === "string" ? payload.message.trim() : "";
-    if (!message)
+    if (!message) {
         return { ok: false, error: "message required" };
+    }
     const nameRaw = payload.name;
     const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "Hook";
     const agentIdRaw = payload.agentId;
     const agentId = typeof agentIdRaw === "string" && agentIdRaw.trim() ? agentIdRaw.trim() : undefined;
     const wakeMode = payload.wakeMode === "next-heartbeat" ? "next-heartbeat" : "now";
     const sessionKeyRaw = payload.sessionKey;
-    const idFactory = opts?.idFactory ?? randomUUID;
     const sessionKey = typeof sessionKeyRaw === "string" && sessionKeyRaw.trim()
         ? sessionKeyRaw.trim()
-        : `hook:${idFactory()}`;
+        : `hook:${(opts?.idFactory ?? randomUUID)()}`;
     const channel = resolveHookChannel(payload.channel);
-    if (!channel)
+    if (!channel) {
         return { ok: false, error: getHookChannelError() };
+    }
     const toRaw = payload.to;
     const to = typeof toRaw === "string" && toRaw.trim() ? toRaw.trim() : undefined;
     const modelRaw = payload.model;

package/dist/gateway/http-auth-helpers.js

@@ -1,13 +1,14 @@
-import { authorizeGatewayConnect } from "./auth.js";
+import { authorizeHttpGatewayConnect } from "./auth.js";
 import { sendGatewayAuthFailure } from "./http-common.js";
 import { getBearerToken } from "./http-utils.js";
 export async function authorizeGatewayBearerRequestOrReply(params) {
     const token = getBearerToken(params.req);
-    const authResult = await authorizeGatewayConnect({
+    const authResult = await authorizeHttpGatewayConnect({
         auth: params.auth,
         connectAuth: token ? { token, password: token } : null,
         req: params.req,
         trustedProxies: params.trustedProxies,
+        allowRealIpFallback: params.allowRealIpFallback,
         rateLimiter: params.rateLimiter,
     });
     if (!authResult.ok) {

package/dist/gateway/http-common.js

@@ -1,4 +1,14 @@
 import { readJsonBody } from "./hooks.js";
+/**
+ * Apply baseline security headers that are safe for all response types (API JSON,
+ * HTML pages, static assets, SSE streams). Headers that restrict framing or set a
+ * Content-Security-Policy are intentionally omitted here because some handlers
+ * (canvas host, A2UI) serve content that may be loaded inside frames.
+ */
+export function setDefaultSecurityHeaders(res) {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Referrer-Policy", "no-referrer");
+}
 export function sendJson(res, status, body) {
     res.statusCode = status;
     res.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -44,6 +54,18 @@ export function sendInvalidRequest(res, message) {
 export async function readJsonBodyOrError(req, res, maxBytes) {
     const body = await readJsonBody(req, maxBytes);
     if (!body.ok) {
+        if (body.error === "payload too large") {
+            sendJson(res, 413, {
+                error: { message: "Payload too large", type: "invalid_request_error" },
+            });
+            return undefined;
+        }
+        if (body.error === "request body timeout") {
+            sendJson(res, 408, {
+                error: { message: "Request body timeout", type: "invalid_request_error" },
+            });
+            return undefined;
+        }
         sendInvalidRequest(res, body.error);
         return undefined;
     }

package/dist/gateway/http-endpoint-helpers.js

@@ -14,6 +14,7 @@ export async function handleGatewayPostJsonEndpoint(req, res, opts) {
         res,
         auth: opts.auth,
         trustedProxies: opts.trustedProxies,
+        allowRealIpFallback: opts.allowRealIpFallback,
         rateLimiter: opts.rateLimiter,
     });
     if (!authorized) {

package/dist/gateway/method-scopes.js

@@ -0,0 +1,169 @@
+export const ADMIN_SCOPE = "operator.admin";
+export const READ_SCOPE = "operator.read";
+export const WRITE_SCOPE = "operator.write";
+export const APPROVALS_SCOPE = "operator.approvals";
+export const PAIRING_SCOPE = "operator.pairing";
+export const CLI_DEFAULT_OPERATOR_SCOPES = [
+    ADMIN_SCOPE,
+    APPROVALS_SCOPE,
+    PAIRING_SCOPE,
+];
+const NODE_ROLE_METHODS = new Set(["node.invoke.result", "node.event", "skills.bins"]);
+const METHOD_SCOPE_GROUPS = {
+    [APPROVALS_SCOPE]: [
+        "exec.approval.request",
+        "exec.approval.waitDecision",
+        "exec.approval.resolve",
+    ],
+    [PAIRING_SCOPE]: [
+        "node.pair.request",
+        "node.pair.list",
+        "node.pair.approve",
+        "node.pair.reject",
+        "node.pair.verify",
+        "device.pair.list",
+        "device.pair.approve",
+        "device.pair.reject",
+        "device.pair.remove",
+        "device.token.rotate",
+        "device.token.revoke",
+        "node.rename",
+    ],
+    [READ_SCOPE]: [
+        "health",
+        "logs.tail",
+        "channels.status",
+        "status",
+        "usage.status",
+        "usage.cost",
+        "tts.status",
+        "tts.providers",
+        "models.list",
+        "agents.list",
+        "agent.identity.get",
+        "skills.status",
+        "voicewake.get",
+        "sessions.list",
+        "sessions.preview",
+        "sessions.resolve",
+        "sessions.usage",
+        "sessions.usage.timeseries",
+        "sessions.usage.logs",
+        "cron.list",
+        "cron.status",
+        "cron.runs",
+        "system-presence",
+        "last-heartbeat",
+        "node.list",
+        "node.describe",
+        "chat.history",
+        "config.get",
+        "talk.config",
+        "agents.files.list",
+        "agents.files.get",
+    ],
+    [WRITE_SCOPE]: [
+        "send",
+        "poll",
+        "agent",
+        "agent.wait",
+        "wake",
+        "talk.mode",
+        "tts.enable",
+        "tts.disable",
+        "tts.convert",
+        "tts.setProvider",
+        "voicewake.set",
+        "node.invoke",
+        "chat.send",
+        "chat.abort",
+        "browser.request",
+        "push.test",
+    ],
+    [ADMIN_SCOPE]: [
+        "channels.logout",
+        "agents.create",
+        "agents.update",
+        "agents.delete",
+        "skills.install",
+        "skills.update",
+        "cron.add",
+        "cron.update",
+        "cron.remove",
+        "cron.run",
+        "sessions.patch",
+        "sessions.reset",
+        "sessions.delete",
+        "sessions.compact",
+        "connect",
+        "chat.inject",
+        "web.login.start",
+        "web.login.wait",
+        "set-heartbeats",
+        "system-event",
+        "agents.files.set",
+    ],
+};
+const ADMIN_METHOD_PREFIXES = ["exec.approvals.", "config.", "wizard.", "update."];
+const METHOD_SCOPE_BY_NAME = new Map(Object.entries(METHOD_SCOPE_GROUPS).flatMap(([scope, methods]) => methods.map((method) => [method, scope])));
+function resolveScopedMethod(method) {
+    const explicitScope = METHOD_SCOPE_BY_NAME.get(method);
+    if (explicitScope) {
+        return explicitScope;
+    }
+    if (ADMIN_METHOD_PREFIXES.some((prefix) => method.startsWith(prefix))) {
+        return ADMIN_SCOPE;
+    }
+    return undefined;
+}
+export function isApprovalMethod(method) {
+    return resolveScopedMethod(method) === APPROVALS_SCOPE;
+}
+export function isPairingMethod(method) {
+    return resolveScopedMethod(method) === PAIRING_SCOPE;
+}
+export function isReadMethod(method) {
+    return resolveScopedMethod(method) === READ_SCOPE;
+}
+export function isWriteMethod(method) {
+    return resolveScopedMethod(method) === WRITE_SCOPE;
+}
+export function isNodeRoleMethod(method) {
+    return NODE_ROLE_METHODS.has(method);
+}
+export function isAdminOnlyMethod(method) {
+    return resolveScopedMethod(method) === ADMIN_SCOPE;
+}
+export function resolveRequiredOperatorScopeForMethod(method) {
+    return resolveScopedMethod(method);
+}
+export function resolveLeastPrivilegeOperatorScopesForMethod(method) {
+    const requiredScope = resolveRequiredOperatorScopeForMethod(method);
+    if (requiredScope) {
+        return [requiredScope];
+    }
+    // Default-deny for unclassified methods.
+    return [];
+}
+export function authorizeOperatorScopesForMethod(method, scopes) {
+    if (scopes.includes(ADMIN_SCOPE)) {
+        return { allowed: true };
+    }
+    const requiredScope = resolveRequiredOperatorScopeForMethod(method) ?? ADMIN_SCOPE;
+    if (requiredScope === READ_SCOPE) {
+        if (scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE)) {
+            return { allowed: true };
+        }
+        return { allowed: false, missingScope: READ_SCOPE };
+    }
+    if (scopes.includes(requiredScope)) {
+        return { allowed: true };
+    }
+    return { allowed: false, missingScope: requiredScope };
+}
+export function isGatewayMethodClassified(method) {
+    if (isNodeRoleMethod(method)) {
+        return true;
+    }
+    return resolveRequiredOperatorScopeForMethod(method) !== undefined;
+}

package/dist/gateway/net.js

@@ -135,19 +135,44 @@ function stripOptionalPort(ip) {
     }
     return ip;
 }
-export function parseForwardedForClientIp(forwardedFor) {
-    const raw = forwardedFor?.split(",")[0]?.trim();
-    if (!raw) {
+function parseIpLiteral(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const stripped = stripOptionalPort(trimmed);
+    const normalized = normalizeIp(stripped);
+    if (!normalized || net.isIP(normalized) === 0) {
         return undefined;
     }
-    return normalizeIp(stripOptionalPort(raw));
+    return normalized;
 }
 function parseRealIp(realIp) {
-    const raw = realIp?.trim();
-    if (!raw) {
+    return parseIpLiteral(realIp);
+}
+function resolveForwardedClientIp(params) {
+    const { forwardedFor, trustedProxies } = params;
+    if (!trustedProxies?.length) {
+        return undefined;
+    }
+    const forwardedChain = [];
+    for (const entry of forwardedFor?.split(",") ?? []) {
+        const normalized = parseIpLiteral(entry);
+        if (normalized) {
+            forwardedChain.push(normalized);
+        }
+    }
+    if (forwardedChain.length === 0) {
         return undefined;
     }
-    return normalizeIp(stripOptionalPort(raw));
+    // Walk right-to-left and return the first untrusted hop.
+    for (let index = forwardedChain.length - 1; index >= 0; index -= 1) {
+        const hop = forwardedChain[index];
+        if (!isTrustedProxyAddress(hop, trustedProxies)) {
+            return hop;
+        }
+    }
+    return undefined;
 }
 /**
  * Check if an IP address matches a CIDR block.
@@ -202,7 +227,7 @@ export function isTrustedProxyAddress(ip, trustedProxies) {
         return normalizeIp(candidate) === normalized;
     });
 }
-export function resolveGatewayClientIp(params) {
+export function resolveClientIp(params) {
     const remote = normalizeIp(params.remoteAddr);
     if (!remote) {
         return undefined;
@@ -210,7 +235,20 @@ export function resolveGatewayClientIp(params) {
     if (!isTrustedProxyAddress(remote, params.trustedProxies)) {
         return remote;
     }
-    return parseForwardedForClientIp(params.forwardedFor) ?? parseRealIp(params.realIp) ?? remote;
+    // Fail closed when traffic comes from a trusted proxy but client-origin headers
+    // are missing or invalid. Falling back to the proxy's own IP can accidentally
+    // treat unrelated requests as local/trusted.
+    const forwardedIp = resolveForwardedClientIp({
+        forwardedFor: params.forwardedFor,
+        trustedProxies: params.trustedProxies,
+    });
+    if (forwardedIp) {
+        return forwardedIp;
+    }
+    if (params.allowRealIpFallback) {
+        return parseRealIp(params.realIp);
+    }
+    return undefined;
 }
 export function isLocalGatewayAddress(ip) {
     if (isLoopbackAddress(ip)) {
@@ -347,3 +385,30 @@ export function isLoopbackHost(host) {
     const unbracket = h.startsWith("[") && h.endsWith("]") ? h.slice(1, -1) : h;
     return isLoopbackAddress(unbracket);
 }
+/**
+ * Security check for WebSocket URLs (CWE-319: Cleartext Transmission of Sensitive Information).
+ *
+ * Returns true if the URL is secure for transmitting data:
+ * - wss:// (TLS) is always secure
+ * - ws:// is only secure for loopback addresses (localhost, 127.x.x.x, ::1)
+ *
+ * All other ws:// URLs are considered insecure because both credentials
+ * AND chat/conversation data would be exposed to network interception.
+ */
+export function isSecureWebSocketUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "wss:") {
+        return true;
+    }
+    if (parsed.protocol !== "ws:") {
+        return false;
+    }
+    // ws:// is only secure for loopback addresses
+    return isLoopbackHost(parsed.hostname);
+}

package/dist/gateway/node-invoke-system-run-approval.js

@@ -1,4 +1,4 @@
-import { formatExecCommand, validateSystemRunCommandConsistency, } from "../infra/system-run-command.js";
+import { resolveSystemRunCommand } from "../infra/system-run-command.js";
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return null;
@@ -20,24 +20,10 @@ function clientHasApprovals(client) {
     const scopes = Array.isArray(client?.connect?.scopes) ? client?.connect?.scopes : [];
     return scopes.includes("operator.admin") || scopes.includes("operator.approvals");
 }
-function getCmdText(params) {
-    const raw = normalizeString(params.rawCommand);
-    if (raw) {
-        return raw;
-    }
-    if (Array.isArray(params.command)) {
-        const parts = params.command.map((v) => String(v));
-        if (parts.length > 0) {
-            return formatExecCommand(parts);
-        }
-    }
-    return "";
-}
-function approvalMatchesRequest(params, record) {
+function approvalMatchesRequest(cmdText, params, record) {
     if (record.request.host !== "node") {
         return false;
     }
-    const cmdText = getCmdText(params);
     if (!cmdText || record.request.command !== cmdText) {
         return false;
     }
@@ -90,25 +76,18 @@ export function sanitizeSystemRunParamsForForwarding(opts) {
         return { ok: true, params: opts.rawParams };
     }
     const p = obj;
-    const argv = Array.isArray(p.command) ? p.command.map((v) => String(v)) : [];
-    const raw = normalizeString(p.rawCommand);
-    if (raw) {
-        if (!Array.isArray(p.command) || argv.length === 0) {
-            return {
-                ok: false,
-                message: "rawCommand requires params.command",
-                details: { code: "MISSING_COMMAND" },
-            };
-        }
-        const validation = validateSystemRunCommandConsistency({ argv, rawCommand: raw });
-        if (!validation.ok) {
-            return {
-                ok: false,
-                message: validation.message,
-                details: validation.details ?? { code: "RAW_COMMAND_MISMATCH" },
-            };
-        }
+    const cmdTextResolution = resolveSystemRunCommand({
+        command: p.command,
+        rawCommand: p.rawCommand,
+    });
+    if (!cmdTextResolution.ok) {
+        return {
+            ok: false,
+            message: cmdTextResolution.message,
+            details: cmdTextResolution.details,
+        };
     }
+    const cmdText = cmdTextResolution.cmdText;
     const approved = p.approved === true;
     const requestedDecision = normalizeApprovalDecision(p.approvalDecision);
     const wantsApprovalOverride = approved || requestedDecision !== null;
@@ -171,7 +150,7 @@ export function sanitizeSystemRunParamsForForwarding(opts) {
             details: { code: "APPROVAL_CLIENT_MISMATCH", runId },
         };
     }
-    if (!approvalMatchesRequest(p, snapshot)) {
+    if (!approvalMatchesRequest(cmdText, p, snapshot)) {
         return {
             ok: false,
             message: "approval id does not match request",