Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / privacy-outbound-mod

Privacy outbound mod

Overview

The privacy mod is a built-in Claude plugin whose metadata lives in mods/…/plugin.json and whose hook entrypoint is declared by mods/…/hooks.json as ./register.ts. mods/…/index.ts re-exports the register module and the outbound helpers for consumers that import the hooks package directly.

mods/…/register.ts wires two engine hooks. The tool.check hook registers for shell-like tools (Bash, Monitor, PowerShell, plus host-added names in INSTALLED_SHELL_TOOLS from mods/…/shell-tools.ts), field-scoped tools (Write, Edit, NotebookEdit, WebFetch from mods/…/outgoing-text.ts), and any tool whose name matches ^mcp__. It first calls next(e) and preserves any lower deny; otherwise it inspects the tool call before approval and can replace an allow/ask verdict with { decision: 'deny', reason: REFUSAL }.

The outbound check starts by normalizing the candidate outgoing text. mods/…/outgoing-text.ts treats Write.content, Edit.new_string, NotebookEdit.new_source, and WebFetch.url as the only outgoing field for those tools; all other registered tools, including MCP tools and installed shell tools, are reduced through textOf. mods/…/text-of.ts recursively serializes strings, arrays, object values, and quoted object keys, preserving the original text and adding a second copy with line continuations, shell quotes, backticks, and backslashes stripped so obfuscated spellings such as split strings or quoted email fragments still match.

The address being protected is fetched only when needed: register.ts skips the identity read unless the call text may hold an address or the shell line names scripts. It calls $.session.identity() and uses identity.contextEmail ?? identity.email; if no address is available, the original tool verdict is returned. Matching happens in mods/…/names-user-agent.ts: holdsAddress compares the account address case-insensitively against the raw text and against one pass of percent-decoded text, while namesUserAgentWithAddress requires either the address plus an identity-declaring word somewhere in the same normalized text, or a per-line computed-address expression such as git config user.email/$GIT_AUTHOR_EMAIL beside an identity word. Identity words include User-Agent spellings and client flags, identity=/--identity/mailto=, selected SEC/EDGAR words, From: header flags, and quoted From keys when the text also names headers. WebFetch is stricter: isRefused denies when the URL itself contains the account address, without requiring an identity word. Edit is less strict for carry-over edits: a new string is refused only if the old string did not already match the same address-plus-identity test.

Shell tools get an extra script scan. For built-in shell tools, register.ts reads only the command field after removing complete git/gh command spans with GIT_COMMAND; if onlyTouches says the command line consists solely of touch/view/edit/test/format commands, no named scripts are read. mods/…/script-names.ts finds relative script-like filenames by word match, excludes absolute paths and .., de-duplicates, and caps reads at MOST_SCRIPTS (8). register.ts walks each candidate path from . with $.fs.list, aborts if any component is missing or a link, reads only final plain files with $.fs.read, treats all read/list errors as empty text, and refuses if any script text names a User-Agent/identity beside the protected address. This means the mod observes script contents before a shell command runs, but only for simple relative paths inside the working directory and only when the command is not classified as file-touching.

The second hook in mods/…/register.ts controls reads of session identity. A session.identity call from next.origin.tier === 'user' resolves to a value containing deny, not a thrown error. Built-in callers receive the full downstream identity. Other tiers receive the downstream identity with contextEmail removed when present, leaving fields such as email intact. If the identity hook registration fails, its .catch fallback returns { value: { deny: 'privacy could not read the identity' } }.

The refusal message is centralized in mods/…/refusal.ts. It tells the model to use a generic client name, ask the person for a real contact when needed, and explains that sending the protected address requires the person to set an environment variable read by the script or run the command themselves with !.

Coverage and routing

This document owns mods/privacy/**, including:

Coupling

  • If tool names or input shapes change in the engine, update mods/…/outgoing-text.ts and the registration list in mods/…/register.ts together. The hook only sees tools it registers for, and field tools only inspect the specific field named in OUTGOING_FIELDS.
  • If shell command parsing rules change, verify both GIT_COMMAND and TOUCH_COMMAND in mods/…/script-names.ts. register.ts depends on GIT_COMMAND to exclude git/gh command bodies before script discovery, and onlyTouches reuses the same pattern shape to decide when script contents should not be read.
  • If identity payload fields or caller tiers change, verify mods/…/register.ts. The protected outbound address is chosen as contextEmail ?? email, while the session.identity hook removes only contextEmail for non-built-in/non-user callers and refuses only the user tier.
  • If host builds add custom shell tools through INSTALLED_SHELL_TOOLS in mods/…/shell-tools.ts, verify whether those tools should be treated like built-in shell tools or whole-input installed tools. register.ts scans script names for both built-in and installed shell tools, but only built-in shell tools receive the command-field and onlyTouches handling.

Risks

  • mods/…/names-user-agent.ts deliberately uses broad word-level regexes instead of parsing protocol-specific requests. If an address and an identity word appear in unrelated parts of the same normalized tool input, a legitimate call can be denied; if a client expresses identity through an unlisted spelling, the call can pass.
  • mods/…/script-names.ts and the path walk in mods/…/register.ts are intentionally conservative rather than a full shell parser. Scripts reached through absolute paths, .., links, cd, imports, makefiles, aliases, substitutions hidden behind touch commands, or runtime reads can go uninspected; conversely, simple word matches can read and refuse a script that the shell would not execute.
  • The script read in mods/…/register.ts is a pre-approval filesystem observation with a race window: it rejects links found during $.fs.list, but a file can be swapped after the walk or after read failure. If that happens, the hook may allow a command whose eventual script contents differ from what was checked.