@gethmy/mcp 3.3.0 → 3.4.1

package/src/run-hook.ts

@@ -0,0 +1,203 @@
+/**
+ * Turning one `PostToolUse` hook payload into two run events (#874).
+ *
+ * The harness fires this hook after every tool call and hands it the tool name,
+ * the input it was called with and the result it produced. That is the whole
+ * log an MCP session never had — the MCP server sees only its own tools, so
+ * Read, Edit, Bash and Grep are invisible to it and no amount of server-side
+ * work can recover them.
+ *
+ * ## Why a pair, from a POST hook
+ *
+ * The timeline correlates `tool_started` and `tool_ended` by `toolUseId` into
+ * ONE row (`deriveTimeline`, `src/lib/agentTimelineModel.ts`), and that row is
+ * what renders input and output behind an expander. `PostToolUse` fires once,
+ * after the call, holding both halves — so it emits both halves, with the same
+ * correlation id and `createdAt` timestamps one millisecond apart so they sort
+ * in the right order under the server-assigned `seq`.
+ *
+ * A `PreToolUse` hook would give a truer "started" timestamp. It is not worth
+ * it: it would double the per-tool-call hook cost, on the critical path of
+ * every `Read`, to move a bar that renders as a single row either way.
+ *
+ * ## Harmony's own MCP tools are included, deliberately
+ *
+ * A `/hmy` session calls `mcp__harmony__*` tools constantly, and it is tempting
+ * to filter them out as noise. They stay, for one reason: a DAEMON run's
+ * timeline already shows its MCP calls, because the daemon's stream parser does
+ * not distinguish them either. Filtering here would make the two runtimes'
+ * timelines disagree about what a tool call is, and the point of this card is
+ * that they should read the same.
+ *
+ * This module is pure. The process that calls it does the I/O.
+ */
+
+import { redactToolCall } from "./run-redaction.js";
+
+/**
+ * The subset of the harness's `PostToolUse` stdin payload this reads.
+ *
+ * Everything is optional because the shape is the harness's to change, and a
+ * hook that throws on an unfamiliar field would break the user's tool call —
+ * the one thing it must never do. An unusable payload yields no events.
+ */
+export interface PostToolUsePayload {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: unknown;
+  tool_response?: unknown;
+  tool_use_id?: string;
+}
+
+/** The event shape written to the spool. Matches `AgentRunEventDraft`. */
+export interface SpooledRunEvent {
+  kind: "tool_started" | "tool_ended";
+  source: "agent";
+  payload: Record<string, unknown>;
+  createdAt: string;
+}
+
+/**
+ * Pull readable text out of whatever the harness put in `tool_response`.
+ *
+ * The field is not one shape. A `Bash` result is an object with `stdout` and
+ * `stderr`; a `Read` is an object with `file`; an MCP tool result is an array
+ * of content blocks; some tools return a bare string. Rather than switch on the
+ * tool name — which would go stale the moment a tool is added — this reads the
+ * shapes, in the order that produces the most useful text.
+ */
+export function extractOutputText(response: unknown, depth = 0): string {
+  if (depth > 4) return "";
+  if (response === null || response === undefined) return "";
+  if (typeof response === "string") return response;
+  if (typeof response === "number" || typeof response === "boolean") {
+    return String(response);
+  }
+  if (Array.isArray(response)) {
+    return response
+      .map((item) => extractOutputText(item, depth + 1))
+      .filter((part) => part.length > 0)
+      .join("\n");
+  }
+  if (typeof response === "object") {
+    const record = response as Record<string, unknown>;
+    // Content-block shape: { type: "text", text: "…" }
+    if (typeof record.text === "string") return record.text;
+    const parts: string[] = [];
+    for (const key of ["stdout", "stderr", "output", "content", "result"]) {
+      const value = record[key];
+      if (value === undefined || value === null) continue;
+      const text = extractOutputText(value, depth + 1);
+      if (text.length > 0) parts.push(text);
+    }
+    if (parts.length > 0) return parts.join("\n");
+    // Nothing recognizable — serialize, so the row is not silently empty.
+    try {
+      const serialized = JSON.stringify(record) ?? "";
+      // A tool that returned nothing should render as NO output, not as a
+      // literal `{}` — an empty expander is noise a reader has to open to
+      // discover is empty.
+      return serialized === "{}" || serialized === "[]" ? "" : serialized;
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+/** Did the tool fail? Read from the flags the harness sets, never inferred. */
+export function extractIsError(response: unknown): boolean {
+  if (response === null || typeof response !== "object") return false;
+  const record = response as Record<string, unknown>;
+  if (record.is_error === true || record.isError === true) return true;
+  if (record.interrupted === true) return true;
+  if (typeof record.error === "string" && record.error.length > 0) return true;
+  return false;
+}
+
+/**
+ * A correlation id for the pair.
+ *
+ * The harness supplies one on most payloads; when it does not, a synthesized id
+ * still correlates correctly because both halves of THIS pair are built from
+ * the same call. It is prefixed so a reader can tell a synthesized id from a
+ * real one when a row looks wrong.
+ */
+function correlationId(
+  payload: PostToolUsePayload,
+  nonce: () => string,
+): string {
+  const supplied = payload.tool_use_id;
+  if (typeof supplied === "string" && supplied.length > 0) return supplied;
+  return `hook-${nonce()}`;
+}
+
+/**
+ * Build the `tool_started` / `tool_ended` pair for one tool call.
+ *
+ * Returns an empty array when there is nothing worth writing — no tool name, or
+ * a payload from a hook event this does not handle. An empty array is the
+ * caller's cue to do nothing at all, not to write an empty batch.
+ */
+export function buildHookEvents(
+  payload: PostToolUsePayload,
+  options?: { now?: number; nonce?: () => string },
+): SpooledRunEvent[] {
+  const toolName =
+    typeof payload?.tool_name === "string" ? payload.tool_name.trim() : "";
+  if (!toolName) return [];
+  if (
+    typeof payload.hook_event_name === "string" &&
+    payload.hook_event_name !== "PostToolUse"
+  ) {
+    return [];
+  }
+
+  const now = options?.now ?? Date.now();
+  const nonce =
+    options?.nonce ?? (() => Math.random().toString(36).slice(2, 12));
+  const toolUseId = correlationId(payload, nonce);
+
+  const rawOutput = extractOutputText(payload.tool_response);
+  const isError = extractIsError(payload.tool_response);
+  const redacted = redactToolCall({
+    input: payload.tool_input,
+    output: rawOutput,
+  });
+
+  const startPayload: Record<string, unknown> = { toolName, toolUseId };
+  const endPayload: Record<string, unknown> = { toolName, toolUseId };
+
+  if (redacted.withheld) {
+    // The row survives so the timeline still shows the call happened; only the
+    // bytes are gone. `withheld` is a plain payload field — the schema is open,
+    // and an unknown field is stored and ignored rather than rejected.
+    startPayload.withheld = redacted.withheld;
+    endPayload.withheld = redacted.withheld;
+    endPayload.output = `[withheld: ${redacted.withheld}]`;
+  } else {
+    if (redacted.input !== undefined) startPayload.input = redacted.input;
+    if (redacted.output !== undefined) endPayload.output = redacted.output;
+  }
+  if (isError) endPayload.isError = true;
+
+  return [
+    {
+      kind: "tool_started",
+      source: "agent",
+      payload: startPayload,
+      // One millisecond apart so the pair keeps its order when the server
+      // assigns `seq` from insert order within a batch.
+      createdAt: new Date(now).toISOString(),
+    },
+    {
+      kind: "tool_ended",
+      source: "agent",
+      payload: endPayload,
+      createdAt: new Date(now + 1).toISOString(),
+    },
+  ];
+}

package/src/run-redaction.ts

@@ -0,0 +1,461 @@
+/**
+ * What a tool call may say on a shared board (card #874).
+ *
+ * A `PostToolUse` hook sees the raw argument and the raw result of every tool
+ * call an MCP session makes, and this module decides how much of that reaches
+ * `agent_run_events`. The board is shared: a card's timeline is readable by
+ * every member of the workspace, and by anyone a card is shared with. So the
+ * question is not "can we send this" but "would we paste it into a team chat".
+ *
+ * ## Three rules, in the order they fire
+ *
+ * 1. **Withhold by path.** A tool whose input names a credential file gets its
+ *    input AND its output dropped, replaced by a reason. The row survives — the
+ *    timeline still shows that a `Read` happened — but the bytes never leave the
+ *    machine. This is the only rule that withholds rather than edits, because a
+ *    `.env` has no safe prefix to truncate to: the first line is the secret.
+ * 2. **Redact by pattern.** Anything that survives rule 1 is swept for secret
+ *    SHAPES — a token, a private key block, a URL with a password in it, a
+ *    `FOO_SECRET=` assignment. This catches the case rule 1 cannot see: a
+ *    secret that was never in a file, like `curl -H "Authorization: Bearer …"`.
+ * 3. **Truncate.** What is left is capped, so one `Read` of a 2 MB file cannot
+ *    blow the 16 KB server-side payload limit
+ *    (`MAX_RUN_EVENT_PAYLOAD_BYTES`, `_shared/run-event-validation.ts`).
+ *
+ * ## Why rule 1's list mirrors `credentialDirectories()`
+ *
+ * `packages/harmony-harness/src/run-containment.ts` already answered "which
+ * directories hold a credential" for the sandbox's `denyRead` list. The same
+ * answer applies here for a different reason — that list fences a contained
+ * run OUT of those files, this one keeps their contents OFF the board — so the
+ * two are kept deliberately parallel.
+ *
+ * "Keep them parallel" was a sentence, and a sentence did not hold: the first
+ * version of this file omitted `~/.claude`, the directory holding Claude Code's
+ * own OAuth token, which this repo has already seen a run be talked into
+ * reading. So the parallel is now mechanical — `HARNESS_CREDENTIAL_LEAVES`
+ * below transcribes the harness list, and a test walks it and asserts every
+ * entry is withheld. **When the harness list grows, grow that constant**; the
+ * test then tells you whether the rules already cover the new entry.
+ *
+ * Everything here is pure and synchronous. The hook that calls it runs on the
+ * critical path of every single tool call, so it may not do I/O, and it is
+ * table-tested rather than reconstructed from a live run.
+ */
+
+/** Cap on the serialized tool input. */
+export const MAX_INPUT_CHARS = 2_000;
+/**
+ * Cap on tool output. Matches `MAX_OUTPUT_LEN` in the daemon's
+ * `cli-agent-runner.ts`, so an MCP session's rows truncate exactly where a
+ * daemon run's rows do and the two read the same on one timeline.
+ */
+export const MAX_OUTPUT_CHARS = 4_000;
+/** Cap on any single string leaf inside a structured input. */
+export const MAX_INPUT_STRING_CHARS = 600;
+
+/** What replaces a redacted span. Distinctive on purpose — it is greppable. */
+export const REDACTION_MARK = "«redacted»";
+
+/** Reason codes, so a withheld row says WHY rather than just going blank. */
+export type WithholdReason = "sensitive-path";
+
+/**
+ * Path segments that are credential stores. A path containing any of these as a
+ * whole segment is sensitive regardless of the file name inside it.
+ *
+ * Kept in step with `credentialDirectories()` in the harness — see the module
+ * doc. `.harmony-mcp` is here for the same reason it is first there: it holds
+ * this product's own API key.
+ */
+const SENSITIVE_SEGMENTS: readonly string[] = [
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".codex",
+  ".gemini",
+  ".docker",
+  ".kube",
+  ".harmony-mcp",
+  ".password-store",
+  // `~/.claude` holds `.credentials.json`, Claude Code's own OAuth token, and
+  // this repo has already watched a run be talked into reading it and pasting
+  // the contents into a source comment (`confine-to-repo.ts`, `ci-repair.ts`,
+  // `ci-patch.ts` all record that measurement). The harness denies the whole
+  // directory for that reason; this list omitted it, so a `Read` of the token
+  // file would have reached the board in full.
+  //
+  // Matched UNCONDITIONALLY, not only under `$HOME`, and that is deliberate.
+  // A repo's own `.claude/settings.local.json` is gitignored precisely because
+  // it is personal, and the key it most often carries is `env` — tokens. So
+  // "project layer, therefore safe" is false, and anchoring on the home
+  // directory would have to be right about which of the two a path is. The
+  // cost of being unconditional is a blank row for a `Read` of a skill or a
+  // settings file; the cost of being wrong the other way is an OAuth token on
+  // a shared board. Same asymmetry `.env.example` is decided on below.
+  ".claude",
+  "gh",
+  "gcloud",
+  "op",
+  "anthropic",
+];
+
+/**
+ * The leaf names of `credentialDirectories()`, hand-transcribed.
+ *
+ * This is the mirror the module doc's "when one grows, grow the other" asks
+ * for, made mechanical: `run-redaction.test.ts` walks this list and asserts
+ * every entry is withheld, so an entry added to the harness and forgotten here
+ * fails a test instead of shipping. It was a comment before, and the comment
+ * did not stop `.claude` from going missing.
+ *
+ * Transcribed rather than imported because `@gethmy/harness` is not a
+ * dependency of the published `@gethmy/mcp` package and must not become one for
+ * a test — the same reason `agent-run-event-kinds_test.ts` hand-transcribes its
+ * list.
+ */
+export const HARNESS_CREDENTIAL_LEAVES: readonly {
+  /** Path relative to the home directory, exactly as the harness spells it. */
+  readonly path: string;
+  /**
+   * Directory or file. The harness list mixes the two — its own deny rules need
+   * `/**` for one and not the other — and the distinction matters here as well:
+   * for a directory the test must prove a file INSIDE it is withheld, which is
+   * the shape an exfiltration actually takes.
+   */
+  readonly kind: "dir" | "file";
+}[] = [
+  { path: ".harmony-mcp", kind: "dir" }, // getConfigDir()
+  { path: ".claude", kind: "dir" },
+  { path: ".claude.json", kind: "file" },
+  { path: ".ssh", kind: "dir" },
+  { path: ".gnupg", kind: "dir" },
+  { path: ".aws", kind: "dir" },
+  { path: ".codex", kind: "dir" },
+  { path: ".gemini", kind: "dir" },
+  { path: ".config/gh", kind: "dir" },
+  { path: ".config/gcloud", kind: "dir" },
+  { path: ".config/anthropic", kind: "dir" },
+  { path: ".config/op", kind: "dir" },
+  { path: ".docker", kind: "dir" },
+  { path: ".kube", kind: "dir" },
+  { path: ".netrc", kind: "file" },
+  { path: ".npmrc", kind: "file" },
+  { path: ".git-credentials", kind: "file" },
+];
+
+/**
+ * The `gh` / `gcloud` / `op` / `anthropic` entries above are single common words
+ * and would otherwise match `src/gh/…`. They count only directly under a
+ * `.config` directory, which is where the harness names them.
+ */
+const CONFIG_SCOPED_SEGMENTS: ReadonlySet<string> = new Set([
+  "gh",
+  "gcloud",
+  "op",
+  "anthropic",
+]);
+
+/**
+ * File names that are a credential whatever directory they sit in.
+ *
+ * The dot-prefixed spellings sit beside their bare ones on purpose. A basename
+ * set is an exact match, so `credentials.json` does not cover
+ * `.credentials.json` — and `.credentials.json` is the one that holds Claude
+ * Code's OAuth token. The directory rule above already withholds it; this is
+ * the second, independent catch, because a token file is worth two.
+ */
+const SENSITIVE_BASENAMES: ReadonlySet<string> = new Set([
+  ".netrc",
+  "_netrc",
+  ".npmrc",
+  ".pgpass",
+  ".git-credentials",
+  ".htpasswd",
+  ".claude.json",
+  "credentials",
+  ".credentials",
+  "credentials.json",
+  ".credentials.json",
+  "credentials.yml",
+  "credentials.yaml",
+  // Codex, and the shape several other runtimes reuse for a token cache.
+  "auth.json",
+  ".auth.json",
+  "secrets",
+  "secrets.json",
+  "secrets.yaml",
+  "secrets.yml",
+  "id_rsa",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ed25519",
+  "known_hosts",
+]);
+
+/** Extensions that are a key or a keystore. */
+const SENSITIVE_EXTENSIONS: readonly string[] = [
+  ".pem",
+  ".key",
+  ".p12",
+  ".pfx",
+  ".keystore",
+  ".jks",
+  ".asc",
+  ".gpg",
+];
+
+/**
+ * Is this path a credential?
+ *
+ * Deliberately conservative in two places. `.env.example` is withheld along
+ * with `.env`, because telling them apart means trusting a naming convention
+ * that nothing enforces, and the cost of being wrong is asymmetric: a withheld
+ * example file is a missing timeline row, a leaked `.env` is an incident.
+ * Likewise `known_hosts` — not a secret, but it enumerates the machines an
+ * operator reaches, which is not board material either.
+ */
+export function isSensitivePath(rawPath: string): boolean {
+  if (typeof rawPath !== "string" || rawPath.length === 0) return false;
+  const path = rawPath.trim().toLowerCase();
+  // Normalize both separators so a Windows-shaped path is judged the same.
+  const segments = path.split(/[\\/]+/).filter((s) => s.length > 0);
+  if (segments.length === 0) return false;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i] as string;
+    if (!SENSITIVE_SEGMENTS.includes(segment)) continue;
+    if (CONFIG_SCOPED_SEGMENTS.has(segment)) {
+      // Only when it sits directly under `.config`, per the harness list.
+      if (i > 0 && segments[i - 1] === ".config") return true;
+      continue;
+    }
+    return true;
+  }
+
+  const basename = segments[segments.length - 1] as string;
+  if (SENSITIVE_BASENAMES.has(basename)) return true;
+  // `.env`, `.env.local`, `.env.production` — and `.env.example`, on purpose.
+  if (basename === ".env" || basename.startsWith(".env.")) return true;
+  // `foo.env` reads as an environment file too.
+  if (basename.endsWith(".env")) return true;
+  if (SENSITIVE_EXTENSIONS.some((ext) => basename.endsWith(ext))) return true;
+  // `serviceAccount.json`, `service-account-key.json`, …
+  if (/service[-_]?account.*\.json$/.test(basename)) return true;
+
+  return false;
+}
+
+/**
+ * Every string in `input` that looks like a filesystem path and is sensitive.
+ *
+ * Walks the whole structure rather than reading a known key, because the key
+ * differs per tool (`file_path` on Read/Edit, `path` on Glob, `notebook_path`
+ * on NotebookEdit) and a tool this code has never heard of is exactly the one
+ * that would slip through a per-tool lookup.
+ */
+export function sensitivePathsIn(input: unknown, depth = 0): string[] {
+  if (depth > 6) return [];
+  if (typeof input === "string") {
+    return isSensitivePath(input) ? [input] : [];
+  }
+  if (Array.isArray(input)) {
+    return input.flatMap((item) => sensitivePathsIn(item, depth + 1));
+  }
+  if (input !== null && typeof input === "object") {
+    return Object.values(input as Record<string, unknown>).flatMap((value) =>
+      sensitivePathsIn(value, depth + 1),
+    );
+  }
+  return [];
+}
+
+/**
+ * Secret SHAPES, swept over any text that survives the path rule.
+ *
+ * Each entry replaces the whole match, or — where a capture group is present —
+ * keeps the group and replaces the rest, so `GITHUB_TOKEN=…` stays legible as
+ * `GITHUB_TOKEN=«redacted»`. Knowing WHICH secret was passed is often the point
+ * of the timeline row; knowing its value never is.
+ */
+const SECRET_PATTERNS: readonly { pattern: RegExp; replace: string }[] = [
+  // A PEM block, first — it spans lines and would otherwise be truncated into
+  // a still-usable prefix by rule 3.
+  {
+    pattern: /-----BEGIN[^-]*PRIVATE KEY-----[\s\S]*?-----END[^-]*-----/g,
+    replace: REDACTION_MARK,
+  },
+  // Harmony's own credentials. `hmy_at_` is the OAuth shape, `hmy_` the
+  // integration key; the longer alternative is written first so it wins.
+  { pattern: /\bhmy_at_[A-Za-z0-9_-]{8,}/g, replace: REDACTION_MARK },
+  { pattern: /\bhmy_[A-Za-z0-9_-]{8,}/g, replace: REDACTION_MARK },
+  // Anthropic / OpenAI.
+  { pattern: /\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}/g, replace: REDACTION_MARK },
+  // GitHub: classic PAT prefixes and the fine-grained shape.
+  { pattern: /\bgh[pousr]_[A-Za-z0-9]{16,}/g, replace: REDACTION_MARK },
+  { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/g, replace: REDACTION_MARK },
+  // Slack.
+  { pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, replace: REDACTION_MARK },
+  // AWS access key id, Google API key.
+  { pattern: /\bAKIA[0-9A-Z]{16}\b/g, replace: REDACTION_MARK },
+  { pattern: /\bAIza[0-9A-Za-z_-]{20,}/g, replace: REDACTION_MARK },
+  // A JWT — three base64url segments. Catches Supabase anon/service keys.
+  {
+    pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+    replace: REDACTION_MARK,
+  },
+  // `Authorization: Bearer <token>` and friends.
+  {
+    pattern: /\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+    replace: `$1 ${REDACTION_MARK}`,
+  },
+  // A URL with userinfo: https://user:password@host
+  {
+    pattern: /(\w+:\/\/)[^/\s:@]+:[^/\s@]+@/g,
+    replace: `$1${REDACTION_MARK}@`,
+  },
+  // An assignment whose NAME says it is a secret. Keeps the name.
+  //
+  // The two `[A-Za-z0-9_]` runs are bounded rather than `*`. Unbounded, they
+  // backtrack quadratically over a long alphanumeric blob — a 500 KB `Write`
+  // payload took 147 seconds and blew a 5-second test timeout. A real
+  // environment variable name is nowhere near 40 characters, so the bound costs
+  // nothing and turns O(n²) into O(n).
+  {
+    pattern:
+      /\b([A-Za-z0-9_]{0,40}(?:TOKEN|SECRET|PASSWORD|PASSWD|APIKEY|API_KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIAL|AUTH)[A-Za-z0-9_]{0,40})\s*[=:]\s*(?:"[^"]*"|'[^']*'|`[^`]*`|[^\s,;)}\]]+)/gi,
+    replace: `$1=${REDACTION_MARK}`,
+  },
+  // A command-line flag whose NAME says it is a secret.
+  {
+    pattern:
+      /(--?(?:password|passwd|token|api-?key|secret|auth)(?:=|\s+))(?:"[^"]*"|'[^']*'|[^\s]+)/gi,
+    replace: `$1${REDACTION_MARK}`,
+  },
+];
+
+/**
+ * Sweep `text` for secret shapes.
+ *
+ * Order matters and is fixed by `SECRET_PATTERNS`: the PEM block runs first so
+ * a key body is gone before any narrower pattern chews on its base64.
+ */
+export function redactSecrets(text: string): string {
+  if (typeof text !== "string" || text.length === 0) return text;
+  let out = text;
+  for (const { pattern, replace } of SECRET_PATTERNS) {
+    // Each regex is `g`-flagged and shared, so reset before reuse.
+    pattern.lastIndex = 0;
+    out = out.replace(pattern, replace);
+  }
+  return out;
+}
+
+/** Cut `text` to `max`, marking the cut so a reader knows it happened. */
+export function truncate(
+  text: string,
+  max: number,
+  originalLength?: number,
+): string {
+  const total = originalLength ?? text.length;
+  if (total <= max) return text;
+  return `${text.slice(0, max)}… [+${total - max} chars]`;
+}
+
+/**
+ * Redact, then cut to `max`.
+ *
+ * The order is deliberate and so is the pre-cap. Redacting the WHOLE of a
+ * multi-megabyte tool result before throwing 99% of it away is wasted work on
+ * the critical path of every tool call, so the sweep sees at most a small
+ * multiple of what can survive. Cutting first and redacting after would be
+ * cheaper still and is wrong: it would leave a secret that straddles the cut
+ * as a usable prefix. Anything between `max` and the pre-cap IS redacted and
+ * then discarded; anything past the pre-cap is discarded without ever being
+ * emitted, so nothing unexamined can reach the board.
+ */
+function redactThenTruncate(text: string, max: number): string {
+  const preCap = max * 4 + 64;
+  const scanned = text.length > preCap ? text.slice(0, preCap) : text;
+  return truncate(redactSecrets(scanned), max, text.length);
+}
+
+/**
+ * Redact and cap every string leaf of a structured value.
+ *
+ * Structure is preserved rather than flattened to a string, because the
+ * timeline's `ToolRow` renders an object input as a key/value list and a string
+ * as one blob — keeping the shape keeps the row readable.
+ */
+function redactStructure(value: unknown, depth = 0): unknown {
+  if (depth > 6) return REDACTION_MARK;
+  if (typeof value === "string") {
+    return redactThenTruncate(value, MAX_INPUT_STRING_CHARS);
+  }
+  if (Array.isArray(value)) {
+    // A long array is a payload risk of its own; cap the element count too.
+    return value.slice(0, 20).map((item) => redactStructure(item, depth + 1));
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(
+      value as Record<string, unknown>,
+    )) {
+      out[key] = redactStructure(item, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+export interface RedactedToolCall {
+  /** What may be sent as `payload.input`, or `undefined` when withheld. */
+  input?: unknown;
+  /** What may be sent as `payload.output`, or `undefined` when withheld. */
+  output?: string;
+  /** Set when rule 1 fired; surfaced on the event so the row explains itself. */
+  withheld?: WithholdReason;
+}
+
+/**
+ * Apply all three rules to one tool call.
+ *
+ * Returns the pair that may be published. A withheld call keeps neither half:
+ * a `Read` of a `.env` withholds the output for the obvious reason, and the
+ * input for a less obvious one — the PATH of a credential file is itself worth
+ * withholding, since it tells a reader exactly where to go looking.
+ */
+export function redactToolCall(args: {
+  input?: unknown;
+  output?: string;
+}): RedactedToolCall {
+  const sensitive = sensitivePathsIn(args.input);
+  if (sensitive.length > 0) {
+    return { withheld: "sensitive-path" };
+  }
+
+  const result: RedactedToolCall = {};
+
+  if (args.input !== undefined) {
+    let input = redactStructure(args.input);
+    // A structure can still be huge in aggregate even with every leaf capped.
+    // Fall back to a truncated serialization rather than shipping it.
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(input) ?? "";
+    } catch {
+      serialized = "";
+      input = REDACTION_MARK;
+    }
+    if (serialized.length > MAX_INPUT_CHARS) {
+      input = truncate(serialized, MAX_INPUT_CHARS);
+    }
+    result.input = input;
+  }
+
+  if (typeof args.output === "string" && args.output.length > 0) {
+    result.output = redactThenTruncate(args.output, MAX_OUTPUT_CHARS);
+  }
+
+  return result;
+}