Docs: `phone` PII redaction is NANP-only in practice but documented with no locale qualifier (and is on by default)

[jasonmx]

What happened?

redaction.pii.phone only matches NANP-format numbers, but the docs give it no locale qualifier
and it is On by default whenever PII redaction is enabled. A UK or EU user who turns PII
redaction on reasonably reads phone: true / [REDACTED_PHONE] as "phone numbers are stripped",
and for their own country's numbers it does nothing at all.

The docs are careful about this for address and silent about it for phone. From
/security#pii-redaction-optional:

Category	Default when PII is enabled	Replacement token
email	On	[REDACTED_EMAIL]
phone	On	[REDACTED_PHONE]
address (US street addresses)	Off (more false-positive prone)	[REDACTED_ADDRESS]

address says "US street addresses". phone says nothing, and it is the one that is on by
default.

The ask here is the docs caveat, not internationalisation. Internationalising this is real work and
phone formats are genuinely horrible, so it should not hold up a parenthetical that lets non-US
users see the limit before they rely on it rather than after — the same one address already has.
There is a separate feature request for coverage at the end of this issue, deliberately not a
precondition for the docs fix.

Why this is worth a docs fix rather than nothing

Checkpoints leave the machine. They are pushed to a remote by the pre-push hook and, for orgs with
mirroring on, replicated onward. For a UK or EU user that makes this a UK GDPR / GDPR question
rather than a preference: if personal data is in transcripts, they are the controller, and
"redaction is enabled" is the kind of thing that ends up written down as a technical measure under
Art. 32. [REDACTED_PHONE] appearing in their checkpoints for the occasional US number would make
that look like it is working.

The page does say "Redaction is best-effort, not a guarantee", and that is fair and prominent.
But best-effort implies some effort in the user's locale. "Zero coverage outside NANP" is a
different statement from "may miss things", and only the first one lets someone decide correctly.

Steps to reproduce

Verified on 0.9.0, phone: true, one prompt per checkpoint, read back from the raw prompt.txt
blob in the checkpoint ref rather than a rendered view. All numbers are official
drama/reserved/example ranges, so none can reach a real person.

mkdir -p /tmp/pii && cd /tmp/pii
git init -q -b main
printf 'one\n' > file.txt && git add -A && git commit -q -m "initial commit"
entire enable --agent claude-code --no-github --checkpoint-backend refs -f
cat > .entire/settings.json <<'EOF'
{
  "enabled": true,
  "checkpoints": { "primary": { "type": "git-refs" } },
  "redaction": { "pii": { "enabled": true, "email": true, "phone": true, "address": true } }
}
EOF
git add -A && git commit -q -m "chore: enable entire"
# then, per case: session-start + user-prompt-submit with the prompt below,
# a commit via `entire hooks git prepare-commit-msg`, and read 0/prompt.txt
# out of refs/entire/checkpoints/<tail>/<id>.

prompt	stored
Call 415-555-0123 about it.	Call [REDACTED_PHONE] about it.
Call (415) 555-0123 about it.	Call [REDACTED_PHONE] about it.
Call +1 415-555-0123 about it.	Call [REDACTED_PHONE] about it.
Call 555-0123 about it.	unchanged
Call 07700 900123 about it. (UK mobile, Ofcom drama range)	unchanged
Call 07700900123 about it.	unchanged
Call +44 7700 900123 about it.	unchanged
Call 020 7946 0018 about it. (UK landline, Ofcom drama range)	unchanged
Call +49 30 901820 about it. (DE)	unchanged
Call +33 1 70 18 99 00 about it. (FR)	unchanged
Call +353 1 234 5678 about it. (IE)	unchanged
Call +61 2 5550 1234 about it. (AU)	unchanged
Call +31 20 794 0000 about it. (NL)	unchanged

Not even E.164 is matched, which surprised me most — +44, +49, +33, +353, +61 and +31
all pass through, while +1 is caught. E.164 would be the cheap 80% fix if you ever want one,
since it is unambiguous and low false-positive by construction.

email is fine and locale-independent — a.person@example.co.uk redacts correctly. This is
specifically a phone issue.

Two smaller docs points, same section

1. The address qualifier does not appear where you configure it.
/guides/configuration/privacy-and-redaction is the page you land on to set this up, and it says
only:

Enable it when checkpoint metadata may include personal information such as email addresses,
phone numbers, or addresses.

No locale qualifier, and it defers with "See PII redaction for categories, defaults, and
limitations". The caveat exists but is one page away from the decision. Worth repeating inline.

2. [REDACTED_ADDRESS] replaces the street line only, including for US addresses.

prompt	stored
Ship to 1600 Pennsylvania Avenue, Washington, DC 20500.	Ship to [REDACTED_ADDRESS], Washington, DC 20500.
Ship to 42 Alder Road, Bristol, BS1 4TR.	Ship to [REDACTED_ADDRESS], Bristol, BS1 4TR.
The postcode is BS1 4TR.	unchanged

"US street addresses" is literally accurate, so this is not a bug. But a reader seeing
[REDACTED_ADDRESS] in their transcript will assume the address is gone, when city, state and
ZIP/postcode remain. For the UK the postcode is the most identifying part of an address and it is
the part that survives. A sentence saying the token replaces the street line, not the whole
address, would prevent that.

Suggested wording

Only a starting point:

| phone | On | [REDACTED_PHONE] | North American (NANP) formats only. International formats,
including E.164 numbers outside +1, are not currently detected. |
| address (US street addresses) | Off | [REDACTED_ADDRESS] | Matches the street line only;
city, state and ZIP/postcode are preserved. |

Plus a line in the limitations list along the lines of: PII detection for phone and address is
US-centric. If you handle personal data from other regions, add custom_patterns for your
locale and do not rely on the built-in categories alone. That last clause is genuinely useful,
because custom_patterns already solves this for anyone who knows they need to.

Happy to open a PR against the docs if that is easier than a discussion.

Feature request, for the backlog

Separately and at whatever priority you think it deserves: please consider EU/UK phone number
coverage for phone redaction. GDPR makes this the region where users are most likely to turn
PII redaction on for compliance reasons rather than tidiness, which is exactly the case where
silent zero coverage does the most damage.

E.164 looks like the cheap first step, since +<country><number> is unambiguous and low
false-positive by construction, and it would cover every country at once for the common case of a
number written in international form. UK national formats (07xxx xxxxxx, 0xx xxxx xxxx) would
be the obvious follow-up. Happy to contribute test cases for UK, IE, DE, FR and NL formats if that
is useful — the ones in this issue are already drawn from the national reserved ranges.

Entire CLI version

Entire CLI 0.9.0 (Go go1.26.4, darwin/arm64)

OS and architecture

macOS 27.0 arm64 (Darwin 27.0.0), git 2.54.0

Agent

Claude Code

[sdshah09]

First time contributor here! I see this is about documenting that phone PII redaction only matches NANP (North American) numbers, even though it's on by default — similar to how address already says "US street addresses" — plus clarifying that address redaction replaces the street line only, and pointing people at custom_patterns for other locales. The ask is a docs caveat, not internationalizing the matcher.

Does that sound right? If so, I'd like to take it.

[jasonmx]

The primary ask is to clarify the features' scope in the docs, so that non-US users don't get tripped up. Separately, it would be great if internationalizing could also be added to the longer term roadmap, as PII redaction in Europe is a big, high-value deal.

…

On Thu, 6 Aug 2026 at 13:07, Shaswat Shah ***@***.***> wrote: *sdshah09* left a comment (entireio/cli#1909) <#1909 (comment)> First time contributor here! I see this is about documenting that phone PII redaction only matches NANP (North American) numbers, even though it's on by default — similar to how address already says "US street addresses" — plus clarifying that address redaction replaces the street line only, and pointing people at custom_patterns for other locales. The ask is a docs caveat, not internationalizing the matcher. Does that sound right? If so, I'd like to take it. — Reply to this email directly, view it on GitHub <#1909?email_source=notifications&email_token=ABYDPQWK32B6S2NKMKP7BIL5IRYIJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMRQGQ2DENRSGU22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5204426255>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABYDPQVP2RYKNAARAHRR5ML5IRYIJAVCNFSNUABGKJSXA33TNF2G64TZHMYTCMRWHA2DCOBUGA5US43TOVSTWNJQG44DAMZSGA2TLILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>