@wrongstack/tools 0.297.0 → 0.298.0

package/dist/_spawn-stream.d.ts

@@ -20,6 +20,8 @@ export interface SpawnStreamOptions {
     flushBytes?: number | undefined;
     /** Maximum chunks to buffer before applying backpressure to the child. Default 500. */
     maxQueueSize?: number | undefined;
+    /** Maximum UTF-8 bytes retained in the producer/consumer queue. Defaults to 1 MiB. */
+    maxQueueBytes?: number | undefined;
 }
 /**
  * Spawn a child process and yield `partial_output` progress events as

package/dist/_util.d.ts

@@ -32,7 +32,35 @@ export declare function safeResolve(input: string, ctx: Context): string;
  * the caller named exactly one file.
  */
 export declare function assertRealInsideRoot(absPath: string, ctx: Context): Promise<void>;
-/** `safeResolve` + symlink realpath containment check. Async. */
+/**
+ * Containment check that RETURNS the canonical path it validated (WS-048).
+ *
+ * The check resolves symlinks and then confirms the resolved target is inside
+ * an allowed root. Handing the caller back the *unresolved* path throws that
+ * work away: the caller opens a path whose components are still symlinks, so
+ * whatever the check proved about the target is no longer what the caller
+ * touches. Swapping an intermediate component between the check and the open
+ * redirects the operation, and nothing downstream re-validates.
+ *
+ * Returning the resolved path removes that gap for every component that
+ * existed at check time — those are now literal directories, not links that can
+ * be re-pointed. It is not a total TOCTOU cure (only fd-relative operations
+ * would be), but the window it closes is the one this function's own contract
+ * claims to have closed.
+ *
+ * For a path that does not exist yet — a `write` to a new file — the deepest
+ * existing ancestor is resolved and the not-yet-created tail is re-joined onto
+ * it, so the canonical form is still returned rather than the raw input.
+ */
+export declare function resolveRealInsideRoot(absPath: string, ctx: Context): Promise<string>;
+/**
+ * `safeResolve` + symlink realpath containment check, returning the CANONICAL
+ * path (WS-048).
+ *
+ * This used to return the unvalidated `abs` while validating `real`, so the
+ * header's promise of a "containment check" did not extend to the value the
+ * caller then opened.
+ */
 export declare function safeResolveReal(input: string, ctx: Context): Promise<string>;
 export declare function truncateMiddle(s: string, max: number): string;
 export declare function isBinaryBuffer(buf: Buffer): boolean;

package/dist/audit.js

@@ -78,11 +78,12 @@ function createOutputSpool(opts) {
   return {
     write(text) {
       if (finalized || !text) return;
-      totalBytes += Buffer.byteLength(text, "utf8");
+      const textBytes = Buffer.byteLength(text, "utf8");
+      totalBytes += textBytes;
       if (!stream && !failed) {
-        if (headBytes + text.length <= threshold) {
+        if (headBytes + textBytes <= threshold) {
           head += text;
-          headBytes += text.length;
+          headBytes += textBytes;
           return;
         }
         head += text;
@@ -92,7 +93,7 @@ function createOutputSpool(opts) {
       }
       if (stream) {
         if (stream.writableLength > SPOOL_WRITE_HWM_BYTES) {
-          droppedBytes += Buffer.byteLength(text, "utf8");
+          droppedBytes += textBytes;
           return;
         }
         stream.write(text);
@@ -114,6 +115,52 @@ function createOutputSpool(opts) {
   };
 }
 
+// src/_win32-resolve.ts
+import * as fs from "node:fs";
+import * as path2 from "node:path";
+function resolveWin32Command(cmd) {
+  if (process.platform !== "win32") return cmd;
+  if (cmd.includes("/") || cmd.includes("\\") || path2.extname(cmd.replace(/\//g, "\\"))) {
+    return cmd;
+  }
+  const pathext = (process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC").toLowerCase().split(";");
+  const pathDirs = (process.env["PATH"] ?? "").split(path2.delimiter);
+  for (const dir of pathDirs) {
+    const base = path2.join(dir, cmd);
+    for (const ext of pathext) {
+      const full = `${base}${ext}`;
+      try {
+        fs.accessSync(full, fs.constants.X_OK);
+        return full;
+      } catch {
+      }
+    }
+  }
+  return cmd;
+}
+var WIN32_SHELL_META = /[&|<>"\r\n\0]/;
+function assertSafeWin32ShellArgs(args) {
+  for (const arg of args) {
+    if (typeof arg === "string" && WIN32_SHELL_META.test(arg)) {
+      throw new Error(
+        'win32 cmd shim spawn: argument contains a shell metacharacter (one of & | < > ", or a newline) that could enable command injection through the .cmd/.bat wrapper - refusing to run. Offending argument: ' + JSON.stringify(arg)
+      );
+    }
+  }
+}
+function buildWin32CmdShimInvocation(command, args = []) {
+  assertSafeWin32ShellArgs([command, ...args]);
+  const line = ["call", quoteWin32CmdArg(command), ...args.map(quoteWin32CmdArg)].join(" ");
+  return {
+    command: process.env["COMSPEC"] ?? "cmd.exe",
+    args: ["/d", "/c", line],
+    windowsVerbatimArguments: true
+  };
+}
+function quoteWin32CmdArg(arg) {
+  return `"${arg}"`;
+}
+
 // src/process-registry.ts
 import { spawn } from "node:child_process";
 import * as os from "node:os";
@@ -738,60 +785,17 @@ function getProcessRegistry() {
   return _registry;
 }
 
-// src/_win32-resolve.ts
-import * as fs from "node:fs";
-import * as path2 from "node:path";
-function resolveWin32Command(cmd) {
-  if (process.platform !== "win32") return cmd;
-  if (cmd.includes("/") || cmd.includes("\\") || path2.extname(cmd.replace(/\//g, "\\"))) {
-    return cmd;
-  }
-  const pathext = (process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC").toLowerCase().split(";");
-  const pathDirs = (process.env["PATH"] ?? "").split(path2.delimiter);
-  for (const dir of pathDirs) {
-    const base = path2.join(dir, cmd);
-    for (const ext of pathext) {
-      const full = `${base}${ext}`;
-      try {
-        fs.accessSync(full, fs.constants.X_OK);
-        return full;
-      } catch {
-      }
-    }
-  }
-  return cmd;
-}
-var WIN32_SHELL_META = /[&|<>"\r\n\0]/;
-function assertSafeWin32ShellArgs(args) {
-  for (const arg of args) {
-    if (typeof arg === "string" && WIN32_SHELL_META.test(arg)) {
-      throw new Error(
-        'win32 cmd shim spawn: argument contains a shell metacharacter (one of & | < > ", or a newline) that could enable command injection through the .cmd/.bat wrapper - refusing to run. Offending argument: ' + JSON.stringify(arg)
-      );
-    }
-  }
-}
-function buildWin32CmdShimInvocation(command, args = []) {
-  assertSafeWin32ShellArgs([command, ...args]);
-  const line = ["call", quoteWin32CmdArg(command), ...args.map(quoteWin32CmdArg)].join(" ");
-  return {
-    command: process.env["COMSPEC"] ?? "cmd.exe",
-    args: ["/d", "/c", line],
-    windowsVerbatimArguments: true
-  };
-}
-function quoteWin32CmdArg(arg) {
-  return `"${arg}"`;
-}
-
 // src/_spawn-stream.ts
 var isWin = process.platform === "win32";
 async function* spawnStream(opts) {
   const max = opts.maxBytes ?? 2e5;
   const flushAt = opts.flushBytes ?? 4 * 1024;
   const maxQueue = opts.maxQueueSize ?? 500;
+  const maxQueueBytes = opts.maxQueueBytes ?? 1024 * 1024;
   let stdout = "";
   let stderr = "";
+  let stdoutRetainedBytes = 0;
+  let stderrRetainedBytes = 0;
   let pending = "";
   let error;
   const spool = createOutputSpool({ tool: opts.cmd, thresholdBytes: max });
@@ -833,6 +837,7 @@ async function* spawnStream(opts) {
     });
   }
   const queue = [];
+  let queuedBytes = 0;
   let waiter;
   let paused = false;
   const wake = () => {
@@ -843,7 +848,7 @@ async function* spawnStream(opts) {
     }
   };
   const resume = () => {
-    if (paused && queue.length < maxQueue) {
+    if (paused && queue.length <= Math.floor(maxQueue / 2) && queuedBytes <= Math.floor(maxQueueBytes / 2)) {
       paused = false;
       child.stdout?.resume();
       child.stderr?.resume();
@@ -853,11 +858,16 @@ async function* spawnStream(opts) {
     const s = c.toString();
     stdoutBytes += c.byteLength;
     emitProcessOutput({ pid, stream: "stdout", chunk: c });
-    if (stdout.length < max) stdout += s;
+    if (stdoutRetainedBytes < max) {
+      const retained = utf8Prefix(s, max - stdoutRetainedBytes);
+      stdout += retained;
+      stdoutRetainedBytes += Buffer.byteLength(retained, "utf8");
+    }
     spool.write(s);
-    queue.push({ kind: "out", data: s });
+    queue.push({ kind: "out", data: s, bytes: c.byteLength });
+    queuedBytes += c.byteLength;
     wake();
-    if (!paused && queue.length >= maxQueue) {
+    if (!paused && (queue.length >= maxQueue || queuedBytes >= maxQueueBytes)) {
       paused = true;
       child.stdout?.pause();
       child.stderr?.pause();
@@ -867,11 +877,16 @@ async function* spawnStream(opts) {
     const s = c.toString();
     stderrBytes += c.byteLength;
     emitProcessOutput({ pid, stream: "stderr", chunk: c });
-    if (stderr.length < max) stderr += s;
+    if (stderrRetainedBytes < max) {
+      const retained = utf8Prefix(s, max - stderrRetainedBytes);
+      stderr += retained;
+      stderrRetainedBytes += Buffer.byteLength(retained, "utf8");
+    }
     spool.write(s);
-    queue.push({ kind: "err", data: s });
+    queue.push({ kind: "err", data: s, bytes: c.byteLength });
+    queuedBytes += c.byteLength;
     wake();
-    if (!paused && queue.length >= maxQueue) {
+    if (!paused && (queue.length >= maxQueue || queuedBytes >= maxQueueBytes)) {
       paused = true;
       child.stdout?.pause();
       child.stderr?.pause();
@@ -881,7 +896,9 @@ async function* spawnStream(opts) {
   child.stderr?.on("data", onErr);
   child.on("error", (e) => {
     error = e.message;
-    queue.push({ kind: "error", data: e.message });
+    const bytes = Buffer.byteLength(e.message, "utf8");
+    queue.push({ kind: "error", data: e.message, bytes });
+    queuedBytes += bytes;
     wake();
   });
   const completeTelemetry = (code, signal, timedOut = false) => {
@@ -902,7 +919,13 @@ async function* spawnStream(opts) {
     if (typeof pid === "number") registry.unregister(pid);
     const exitCode2 = code ?? (signal ? 1 : 0);
     completeTelemetry(exitCode2, signal ?? void 0);
-    queue.push({ kind: "close", data: "", code: exitCode2, ...signal ? { signal } : {} });
+    queue.push({
+      kind: "close",
+      data: "",
+      bytes: 0,
+      code: exitCode2,
+      ...signal ? { signal } : {}
+    });
     wake();
   });
   const onAbort = () => {
@@ -914,7 +937,7 @@ async function* spawnStream(opts) {
       } catch {
       }
     }
-    queue.push({ kind: "close", data: "", code: 124 });
+    queue.push({ kind: "close", data: "", bytes: 0, code: 124 });
     completeTelemetry(124, "SIGKILL", true);
     wake();
   };
@@ -932,6 +955,7 @@ async function* spawnStream(opts) {
         });
       }
       const chunk = queue.shift();
+      queuedBytes -= chunk.bytes;
       resume();
       if (chunk.kind === "close") {
         if (!spawnFailed) exitCode = chunk.code ?? 0;
@@ -958,7 +982,7 @@ async function* spawnStream(opts) {
       stdout: spooled ? stdout + spoolNote(spooled) : stdout,
       stderr,
       exitCode,
-      truncated: stdout.length >= max || stderr.length >= max,
+      truncated: stdoutBytes > stdoutRetainedBytes || stderrBytes > stderrRetainedBytes,
       error,
       spoolPath: spooled?.path,
       spoolBytes: spooled?.bytes
@@ -982,6 +1006,20 @@ async function* spawnStream(opts) {
     }
   }
 }
+function utf8Prefix(text, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(text.slice(0, mid), "utf8") <= maxBytes) low = mid;
+    else high = mid - 1;
+  }
+  let end = low;
+  if (end > 0 && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+  return text.slice(0, end);
+}
 
 // src/_util.ts
 import * as path3 from "node:path";
@@ -2563,8 +2601,8 @@ async function scanDirectory(directory, depth, profiles, limits, state, extraIgn
     collectFileEvidence(directory, fullPath, entry.name, profiles, state);
   }
 }
-function collectFileEvidence(directory, fullPath, basename4, profiles, state) {
-  const lower = basename4.toLowerCase();
+function collectFileEvidence(directory, fullPath, basename5, profiles, state) {
+  const lower = basename5.toLowerCase();
   const extension = path4.extname(lower);
   for (const profile of profiles) {
     const detector = profile.detectors.find(
@@ -2575,7 +2613,7 @@ function collectFileEvidence(directory, fullPath, basename4, profiles, state) {
       candidate.evidence.push({
         kind: detector.kind,
         path: fullPath,
-        value: basename4,
+        value: basename5,
         weight: detector.weight
       });
       if (detector.kind === "manifest" || detector.kind === "config") {
@@ -3194,10 +3232,11 @@ var MAX_ARGUMENTS = 128;
 var MAX_ARGUMENT_LENGTH = 4096;
 var PACKAGE_NAME_RE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+(?:@[a-z0-9*+._~^<>=|-]+)?$/i;
 var COMPOSER_PACKAGE_RE = /^[a-z0-9_.-]+\/[a-z0-9_.-]+(?::[a-z0-9*+._~^<>=|-]+)?$/i;
-var GO_MODULE_RE = /^(?:[a-z0-9.-]+\.)+[a-z0-9.-]+\/[a-z0-9._~+/@-]+$/i;
+var GO_MODULE_RE = /^(?:[a-z0-9-]+\.)+[a-z0-9-]+\/[a-z0-9._~+/@-]+$/i;
 var PYTHON_PACKAGE_RE = /^[a-z0-9._-]+(?:\[[a-z0-9._,-]+\])?==[a-z0-9*+._!~-]+$/i;
 async function planLanguageOperation(options) {
   validateOperationOptions(options.operation, options.operationOptions?.packages);
+  validateFilterOption(options.operationOptions?.filter);
   const detection = await detectLanguageWorkspaces(options);
   const candidates = detection.workspaces.filter(
     (workspace) => workspace.capabilities.includes(options.operation)
@@ -3370,6 +3409,15 @@ function workspaceDepth(workspaceRoot, projectRoot) {
   const relative5 = path6.relative(path6.resolve(projectRoot), path6.resolve(workspaceRoot));
   return relative5 === "" ? 0 : relative5.split(path6.sep).length;
 }
+function validateFilterOption(filter) {
+  if (filter === void 0) return;
+  if (filter.startsWith("-") || filter.includes(" --")) {
+    throw new Error(`Invalid test filter (parsed as a runner option): "${filter}"`);
+  }
+  if (filter.length > MAX_ARGUMENT_LENGTH || /[\r\n\0]/.test(filter)) {
+    throw new Error("Invalid test filter (oversized or contains a control character)");
+  }
+}
 function validateOperationOptions(operation, packages) {
   if (!operation.startsWith("package-") || !packages) return;
   for (const value of packages) {

package/dist/bash.js

@@ -81,11 +81,12 @@ function createOutputSpool(opts) {
   return {
     write(text) {
       if (finalized || !text) return;
-      totalBytes += Buffer.byteLength(text, "utf8");
+      const textBytes = Buffer.byteLength(text, "utf8");
+      totalBytes += textBytes;
       if (!stream && !failed) {
-        if (headBytes + text.length <= threshold) {
+        if (headBytes + textBytes <= threshold) {
           head += text;
-          headBytes += text.length;
+          headBytes += textBytes;
           return;
         }
         head += text;
@@ -95,7 +96,7 @@ function createOutputSpool(opts) {
       }
       if (stream) {
         if (stream.writableLength > SPOOL_WRITE_HWM_BYTES) {
-          droppedBytes += Buffer.byteLength(text, "utf8");
+          droppedBytes += textBytes;
           return;
         }
         stream.write(text);

package/dist/batch-tool-use.js

@@ -2,30 +2,59 @@
 import {
   GOVERNED_TOOL_EXECUTOR_META_KEY
 } from "@wrongstack/core/types";
+var BATCHABLE_TOOL_NAMES = [
+  "read",
+  "glob",
+  "grep",
+  "tree",
+  "codebase-stats",
+  "codebase-search",
+  "language_info",
+  "tool_search",
+  "memory_for_file",
+  "memory_for_path",
+  "memory_search"
+];
+var BATCHABLE_TOOLS = new Set(BATCHABLE_TOOL_NAMES);
+var MAX_BATCH_CALLS = 8;
+var MAX_PARALLEL_BATCH_CALLS = 3;
 var batchToolUseTool = {
   name: "batch_tool_use",
   category: "Meta",
-  description: "Execute a batch of tool calls either sequentially or in parallel. Returns structured results for every call.",
-  usageHint: "ADVANCED / POWER USER TOOL:\n\n- Useful when you have a clear list of independent operations to perform.\n- `parallel: true` (default) runs them concurrently for speed.\n- `stop_on_error: true` makes it fail fast on the first error.\nUse with care \u2014 batching many mutating operations can be risky. Prefer explicit sequential steps for important work.",
+  description: "Execute a small batch of independent, read-only discovery calls. Process, mutation, browser-action, MCP, delegation, and nested meta tools are not eligible.",
+  usageHint: `BOUNDED READ-ONLY BATCHING:
+
+- Use only for a small set of independent reads or searches that are all needed now.
+- Do not wrap normal sequential reasoning or every tool call in a batch.
+- \`parallel: true\` (default) runs at most three eligible calls concurrently.
+- \`stop_on_error: true\` makes it fail fast on the first error.
+- Eligible tools: ${BATCHABLE_TOOL_NAMES.join(", ")}.`,
   permission: "confirm",
+  // Scheduling barrier: keep the outer meta-call out of ToolExecutor's
+  // non-mutating fan-out even though every eligible inner tool is read-only.
   mutating: true,
   timeoutMs: 12e4,
-  capabilities: ["tool.mutate.any"],
+  capabilities: ["tool.meta"],
   icon: "meta",
   inputSchema: {
     type: "object",
     properties: {
       calls: {
         type: "array",
+        maxItems: MAX_BATCH_CALLS,
         items: {
           type: "object",
           properties: {
-            tool: { type: "string" },
+            tool: {
+              type: "string",
+              enum: [...BATCHABLE_TOOL_NAMES],
+              description: "An explicitly batch-safe, read-only discovery tool."
+            },
             input: { type: "object" }
           },
           required: ["tool"]
         },
-        description: "Array of tool calls to execute"
+        description: `Up to ${MAX_BATCH_CALLS} independent, batch-safe read calls.`
       },
       stop_on_error: {
         type: "boolean",
@@ -48,6 +77,9 @@ var batchToolUseTool = {
         stop_on_error: false
       };
     }
+    if (input.calls.length > MAX_BATCH_CALLS) {
+      throw new Error(`batch_tool_use: calls must contain at most ${MAX_BATCH_CALLS} items`);
+    }
     const governedExecute = ctx.meta[GOVERNED_TOOL_EXECUTOR_META_KEY];
     if (typeof governedExecute !== "function") {
       return {
@@ -67,8 +99,11 @@ var batchToolUseTool = {
     let succeeded = 0;
     let failed = 0;
     if (input.parallel !== false) {
-      const promises = input.calls.map(async (call) => executeSingle(call, ctx, governedExecute));
-      const allResults = await Promise.all(promises);
+      const allResults = await mapWithConcurrency(
+        input.calls,
+        MAX_PARALLEL_BATCH_CALLS,
+        (call) => executeSingle(call, ctx, governedExecute)
+      );
       results.push(...allResults);
       succeeded = allResults.filter((r) => r.success).length;
       failed = allResults.filter((r) => !r.success).length;
@@ -93,8 +128,28 @@ var batchToolUseTool = {
     };
   }
 };
+async function mapWithConcurrency(items, limit, run) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const worker = async () => {
+    while (nextIndex < items.length) {
+      const index = nextIndex++;
+      results[index] = await run(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+  return results;
+}
 async function executeSingle(call, ctx, governedExecute) {
   const start = Date.now();
+  if (call.tool === batchToolUseTool.name) {
+    return {
+      tool: call.tool,
+      success: false,
+      error: "recursive batch_tool_use execution is not allowed",
+      executionMs: Date.now() - start
+    };
+  }
   const tool = ctx.tools.find((candidate) => candidate.name === call.tool);
   if (!tool) {
     return {
@@ -104,6 +159,14 @@ async function executeSingle(call, ctx, governedExecute) {
       executionMs: Date.now() - start
     };
   }
+  if (!BATCHABLE_TOOLS.has(tool.name) || tool.mutating) {
+    return {
+      tool: call.tool,
+      success: false,
+      error: `tool "${call.tool}" is not eligible for batch execution; call it directly. Allowed: ${BATCHABLE_TOOL_NAMES.join(", ")}`,
+      executionMs: Date.now() - start
+    };
+  }
   try {
     const result = await governedExecute(call.tool, call.input);
     return {

package/dist/browser/index.js

@@ -6,8 +6,14 @@ import * as path from "node:path";
 import { atomicWrite, ulid } from "@wrongstack/core/utils";
 var ARTIFACT_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 var sweptRoots = /* @__PURE__ */ new Set();
+var MAX_SWEPT_ROOTS = 128;
 function sweepOldArtifacts(root) {
   if (sweptRoots.has(root)) return;
+  while (sweptRoots.size >= MAX_SWEPT_ROOTS) {
+    const oldest = sweptRoots.values().next().value;
+    if (oldest === void 0) break;
+    sweptRoots.delete(oldest);
+  }
   sweptRoots.add(root);
   void (async () => {
     const cutoff = Date.now() - ARTIFACT_RETENTION_MS;
@@ -441,7 +447,7 @@ var BrowserSessionManager = class {
   constructor(options, launcher = defaultLauncher) {
     this.launcher = launcher;
     this.artifacts = new BrowserArtifactStore(options.artifactRoot);
-    this.allowPrivateHosts = options.allowPrivateHosts ?? true;
+    this.allowPrivateHosts = options.allowPrivateHosts ?? false;
     this.allowedPrivateOrigins = options.allowedPrivateOrigins ?? [];
     this.networkProxy = new BrowserNetworkGuardProxy({
       allowPrivateHosts: this.allowPrivateHosts,
@@ -1017,6 +1023,9 @@ var browserScreenshotTool = {
   description: "Capture a page or element PNG and return sensitive artifact metadata with integrity hash.",
   usageHint: "browser_screenshot({ sessionId, fullPage?, selector? })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "selector",
   mutating: true,
   riskTier: "safe",
   capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1046,6 +1055,9 @@ function selectorTool(name, description, run) {
     description,
     usageHint: `${name}({ sessionId, selector })`,
     permission: "confirm",
+    // WS-046: the element/expression acted on, not the sessionId — a trust
+    // rule must distinguish clicking one control from another.
+    subjectKey: "selector",
     mutating: true,
     riskTier: "standard",
     capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1075,6 +1087,9 @@ var browserTypeTool = {
   description: "Fill an input in an owned browser session. Use secretEnv instead of text for credentials so values stay out of tool arguments and session audit.",
   usageHint: "browser_type({ sessionId, selector, text? | secretEnv? })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "selector",
   mutating: true,
   riskTier: "standard",
   capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1109,6 +1124,9 @@ var browserSelectTool = {
   description: "Select an option in an owned browser session.",
   usageHint: "browser_select({ sessionId, selector, value })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "selector",
   mutating: true,
   riskTier: "standard",
   capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1137,6 +1155,9 @@ var browserPressTool = {
   description: "Press a keyboard key in an owned browser session.",
   usageHint: "browser_press({ sessionId, key })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "key",
   mutating: true,
   riskTier: "standard",
   capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1155,6 +1176,9 @@ var browserDragTool = {
   description: "Drag one element to another in an owned browser session.",
   usageHint: "browser_drag({ sessionId, from, to })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "from",
   mutating: true,
   riskTier: "standard",
   capabilities: [ToolCapabilities.NET_OUTBOUND],
@@ -1204,6 +1228,9 @@ var browserEvaluateTool = {
   description: "Evaluate bounded JavaScript in the page. Requires confirmation because page code is arbitrary.",
   usageHint: "browser_evaluate({ sessionId, expression })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "expression",
   mutating: true,
   riskTier: "destructive",
   capabilities: [ToolCapabilities.NET_OUTBOUND, ToolCapabilities.TOOL_MUTATE_ANY],
@@ -1226,6 +1253,9 @@ var browserUploadTool = {
   description: "Upload project-local files through a file input in an owned browser session.",
   usageHint: "browser_upload({ sessionId, selector, files })",
   permission: "confirm",
+  // WS-046: the element/expression acted on, not the sessionId — a trust
+  // rule must distinguish clicking one control from another.
+  subjectKey: "selector",
   mutating: true,
   riskTier: "destructive",
   capabilities: [ToolCapabilities.NET_OUTBOUND, ToolCapabilities.FS_READ],