Judge shell and web tool calls for the running user's email

.github/workflows/test.yml

@@ -215,7 +215,7 @@ jobs:
     needs: dedupe
     if: needs.dedupe.outputs.passed != 'true'
     name: kani proofs
-    runs-on: ubuntu-slim
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
         with:

Cargo.toml

@@ -42,6 +42,9 @@ ignore = "0.4"
 # The engine under `grep-regex`, used directly where a pattern is matched
 # against a string already in memory rather than searched through a file.
 regex = "1"
+# Read a tool call's strings through their percent-encoding (RFC 3986 section
+# 2.1) at `uphold hook`, so a URL carrying `%40` is judged as what it decodes to.
+percent-encoding = "2"
 # Where a URL written out in prose ends and the sentence's punctuation begins,
 # for `citations-linked`. A URL pattern of our own gets that boundary wrong on
 # a trailing period, a closing parenthesis and a quote; this crate's tests are

README.md

@@ -338,6 +338,16 @@ second matcher in this binary. An unknown harness name is refused rather than
 guessed at, because where to find the text in its event cannot be derived from
 its name.
 
+The Claude Code plugin also sends `Bash`, `WebFetch` and `WebSearch` through
+the same hook. Those calls publish nothing to a forge, so a compiled-in
+`[[hook]]` table judges them only by the rules about this machine and its user:
+host identity, and the running user's own email address as git and the
+environment configure it, read through URL encoding and withheld from the
+refusal and the evidence. `git@github.com` and `react@18` are nobody's address
+and pass. This checks the arguments the harness hands over, not the request a
+client eventually sends. See
+[the shell and web tools](docs/REFERENCE.md#shell-and-web-tools).
+
 For Claude Code, enable the `uphold` plugin this repository ships, at the tag
 of the release you installed:
 

docs/REFERENCE.md

@@ -1152,7 +1152,9 @@ files.word = true
 The name says what fails: a literal describing **this machine** — username,
 home path, hostname and its identifying segments, default-route addresses —
 found in content. Sources: `running-os-identity`, `running-os-metadata`
-(identity plus route), `running-default-route`. `forbidden_literals_from`
+(identity plus route), `running-default-route`, and `running-user-email` (every
+`user.email` git resolves, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_EMAIL` and
+`EMAIL`, whose matches are always reported as `[REDACTED_MATCH]`). `forbidden_literals_from`
 names any command producing one literal per line (`label<TAB>value`, or a bare
 line as its own label):
 
@@ -3244,12 +3246,13 @@ the folder needs no install of their own:
 }
 ```
 
-The plugin's `hooks/hooks.json` holds three entries, each running
+The plugin's `hooks/hooks.json` holds four entries, each running
 `uphold hook claude-code`:
 
 | event | matcher | options |
 |---|---|---|
 | `PreToolUse` | `mcp__github__.*` | `onFailure: "block"` |
+| `PreToolUse` | `^(Bash\|WebFetch\|WebSearch)$` | `onFailure: "block"` |
 | `SessionStart` | | `async: true` |
 | `Stop` | | `timeout: 900`, `onFailure: "block"` |
 
@@ -3262,6 +3265,74 @@ remove it. A cloud session does not add marketplaces from a repository's
 `extraKnownMarketplaces`, so the plugin does not reach one through project
 settings.
 
+### Shell and web tools
+
+The `Bash`, `WebFetch` and `WebSearch` entry reaches the same judgment as every
+other call, through a compiled-in `[[hook]]` table that says these calls
+publish nothing to a forge:
+
+```toml
+[[hook]]
+tools = '^(Bash|WebFetch|WebSearch)$'
+publishes = false
+```
+
+So they are judged by the rules that mean the same against any text: the
+literal rules, and the pattern rules a policy writes for `seams = ["hook"]`.
+The guards and the prose rules are about a publication and are recorded as out
+of scope, so a private repository's name in a `cd` and an authorship marker in
+a drafted commit message are not refused here. They are refused when the text
+is published, at the shim or the forge's hook.
+
+Two literal rules run wherever the call is made, policy or none:
+`no-running-os-identity-metadata`, and at this seam only `no-running-user-email`,
+which reads `running-user-email`. The second refuses the running user's own
+address. It does not refuse every email-shaped string: an SSH remote, a package
+pin and an image digest look like addresses and identify nobody. A refusal and
+its `--junit` record name the rule and where the address was configured, never
+the address or the line it was on. Each string the call carries, except a
+title or commit subject, is also read through up to four layers of
+percent-encoding (RFC 3986 section 2.1), so `owner%40example.test` and
+`owner%2540example.test` are found.
+
+A repository changes either end in policy. Declaring a rule that reads
+`running-user-email` replaces the fallback, and like every `forbidden_literals`
+rule it needs `files.*` and is then a content rule `uphold scan` runs over
+those files too: scope it to where the address must never appear, since a
+maintainer field or a `SECURITY.md` contact carries it on purpose.
+
+```toml
+# The address in tool calls, in the docs tree, and nowhere else in the tree;
+# a shared role address the user also sends as is exempt.
+[rule.no-running-user-email]
+message = "Leave the address out."
+forbidden_literals = "running-user-email"
+ignore_literals = ["security@example.test"]
+files.include = ["docs"]
+
+# Every address, whoever's, in a tool call.
+[rule.no-address-in-tool-calls]
+message = "Leave addresses out."
+regexp = '[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}'
+seams = ["hook"]
+command.before = ["gh"]
+command.scope = "always"
+```
+
+Both rules, and the user-email fallback, also judge the GitHub MCP server's
+calls, which are the hook seam too. The shim and `--text` seams do not get the
+fallback: a `Signed-off-by` trailer at `commit-msg` is the author's decision. A
+repository that wants it there declares the rule.
+
+The check reads the arguments the harness supplies. It cannot see headers an
+HTTP client adds after the hook, shell concatenation, the contents of a script
+or an uploaded file, environment variables, or tools that never call a local
+hook. A pass is not an attestation about the request that is eventually sent.
+The Codex plugin's matcher is `mcp__.*`, so it does not send its shell tool
+here.
+
+### Installing the Codex plugin
+
 For [Codex](https://developers.openai.com/codex/), this repository publishes
 `.agents/plugins/marketplace.json`, pointing to `plugins/codex`. Add the
 marketplace at the same release tag as the installed binary:
@@ -3362,6 +3433,8 @@ shim = "gh"                # take scope and unresolved from this [[shim]] table
 # or, instead of shim:
 # scope = "public-target"  # as on [[shim]]; "always" where neither is written
 # unresolved = "refuse"    # as on [[shim]]; "run" is the opt-out
+# or, for a call that publishes to no forge, with none of the above:
+# publishes = false        # judged by literal rules and seams = ["hook"] patterns only
 ```
 
 That table is compiled in, from
@@ -3424,6 +3497,9 @@ configured for. A table in an
 the scope is right at the shim, but that scope reads an npm command line, which
 no tool call has: at the hook it is unresolved, and the refusal names the rule.
 A pattern or prose rule takes `seams = ["shim"]` to stay off the hook.
+`publishes = false` beside `skip`, `target`, `forge`, `owner`, `repo`, `shim`,
+`scope` or `unresolved` is refused: those say where a publication goes, and
+the table says there is none. See [Shell and web tools](#shell-and-web-tools).
 
 ### What runs where there is no policy
 

docs/schema/principles.schema.json

@@ -184,6 +184,11 @@
           "description": "JSON pointer (RFC 6901) into the call's input, to the owner. Not the\nempty pointer, which names the whole input: an object is never an\nowner's name.",
           "type": "string"
         },
+        "publishes": {
+          "default": true,
+          "description": "`false` where these calls publish nothing to a forge, but what they\ncarry still leaves the session: a shell command, a fetched URL, a\nsearch query. Only the rules that mean the same against any text judge\nthem -- the literal rules, which read the running host and user, and\nthe pattern rules whose `seams` names `hook`. The guards and the prose\nrules are about a forge publication and are recorded as out of scope:\na private repository's name in a `cd` is not that name published.\n`true` (the default) is every other table. Not written beside `skip`,\n`target`, `shim`, `scope` or `unresolved`, which say where a\npublication goes and which of its rules stand there.",
+          "type": "boolean"
+        },
         "repo": {
           "description": "JSON pointer (RFC 6901) into the call's input, to the repository. Not\nthe empty pointer, as for `owner`.",
           "type": "string"

plugins/claude-code/hooks/hooks.json

@@ -1,6 +1,12 @@
 {
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "^(Bash|WebFetch|WebSearch)$",
+        "hooks": [
+          {"type": "command", "command": "uphold hook claude-code", "onFailure": "block"}
+        ]
+      },
       {
         "matcher": "mcp__github__.*",
         "hooks": [

policy/hook.default.toml

@@ -101,3 +101,15 @@ forge = "github"
 owner = "/owner"
 repo = "/repo"
 shim = "gh"
+
+# A harness's own shell and web tools: Claude Code's `Bash`, `WebFetch` and
+# `WebSearch`. They publish nothing to a forge, and what they carry still
+# leaves the session -- to a process, a fetched host, a search provider. So
+# `publishes = false`: the literal rules judge them, which read this machine's
+# identity and the running user's own addresses and mean the same against any
+# text, as do the pattern rules a policy writes with `seams = ["hook"]`. The
+# guards and prose rules are about a publication and are recorded as out of
+# scope. A private repository's name in a `cd` is not that name published.
+[[hook]]
+tools = '^(Bash|WebFetch|WebSearch)$'
+publishes = false

src/config.rs

@@ -2946,6 +2946,18 @@ fn hook_defaults() -> Result<Vec<crate::hook::Written>> {
         .map_err(|error| Fatal::new(format!("the compiled-in `[[hook]]` tables: {error}")))
 }
 
+/// The compiled-in `[[hook]]` tables alone, for a hook call made where no
+/// policy is: which calls publish is a fact about the tools, and holds whether
+/// or not anybody wrote a policy where the session started.
+pub(crate) fn compiled_hooks() -> Result<Vec<crate::hook::Table>> {
+    load_hooks(
+        Path::new("policy/hook.default.toml"),
+        &[],
+        None,
+        hook_defaults()?,
+    )
+}
+
 /// Each `[[hook]]` table parsed into the shape that carries its checks, and
 /// `unresolved` held to the reading [`validate_shim_unresolved`] gives it on
 /// `[[shim]]`: written only where some scope this table's calls reach can fail

src/config/rule.rs

@@ -224,7 +224,8 @@ pub(crate) struct Written {
 #[serde(untagged)]
 pub(crate) enum Literals {
     /// A named built-in source of literals describing the running machine --
-    /// `running-os-identity`, `running-os-metadata`, `running-default-route`.
+    /// `running-os-identity`, `running-os-metadata`, `running-default-route`,
+    /// `running-user-email`.
     /// The name says what fails: a literal describing THIS machine, found in
     /// content.
     Named { forbidden_literals: String },

src/guard/mod.rs

@@ -665,7 +665,14 @@ pub(crate) fn text_refusal(
         // not a policy rule at all. Gating them on the table's scope would only
         // stand the identity check down for private destinations, which is the
         // arrangement `command.scope = "always"` on this rule exists to undo.
-        "text-literals" => crate::text::failures_in(root, policy, text, Some(kind), ledger),
+        "text-literals" => crate::text::failures_in(
+            crate::text::Seam::Guard,
+            root,
+            policy,
+            text,
+            Some(kind),
+            ledger,
+        ),
         _ => Ok(()),
     }
 }

src/hook.rs

@@ -169,6 +169,41 @@ fn drop_unsent(collected: &mut Walked) {
         .retain(|(key, text)| !(key == "commit_title" && text.is_empty()));
 }
 
+/// How many percent-decoding layers a string is read through.
+///
+/// A URL carries an address as `person%40example.test`, and a query string
+/// built from one can carry it as `%2540`. Each layer that changes the text is
+/// judged beside the text as written, so a literal or a pattern finds the
+/// value however many times it was encoded, up to this bound. Bounded because
+/// each layer is another copy of the string: past four, an encoding is not a
+/// URL any client built, and the text as written is still judged.
+const DECODED_LAYERS: usize = 4;
+
+/// Add, after the strings a call carries, each percent-decoded layer of them
+/// that differs from the one before (RFC 3986 section 2.1).
+///
+/// Here and not in `walk_strings`, which also reads the document a shim's
+/// `gh api --input` sends: that document is published as written, and what a
+/// forge stores is the undecoded text. A tool call's URL or query is decoded
+/// by whoever receives it, so what it discloses is what it decodes to.
+fn decoded_layers(prose: &mut Vec<String>) {
+    let mut layers = Vec::new();
+    for text in prose.iter() {
+        let mut current = text.clone();
+        for _ in 0..DECODED_LAYERS {
+            let next = percent_encoding::percent_decode_str(&current)
+                .decode_utf8_lossy()
+                .into_owned();
+            if next == current {
+                break;
+            }
+            layers.push(next.clone());
+            current = next;
+        }
+    }
+    prose.extend(layers);
+}
+
 /// Judge one pending tool call, read from stdin in the harness's own shape.
 ///
 /// `found` is the policy where the call was made, and it is an `Option` here
@@ -297,6 +332,10 @@ pub(crate) fn run(
     // down as set aside rather than asked.
     let named = policy.hooks.iter().find(|table| table.names(label));
     let read = named.is_some_and(|table| table.skips(label));
+    // A shell command, a fetched URL, a search query: text that leaves the
+    // session and reaches no forge. The rules about this machine and its user
+    // read it; the rules about a publication stand down, recorded as such.
+    let unpublished = named.is_some_and(|table| !table.publishes());
     let mut scoping = table::Scoping::new(named, &policy.shims, label, subject, &root);
     let destination = if read {
         None
@@ -309,6 +348,7 @@ pub(crate) fn run(
         walk_strings(subject, None, &mut collected);
     }
     drop_unsent(&mut collected);
+    decoded_layers(&mut collected.prose);
     let has_text = !collected.prose.is_empty() || !collected.headlines.is_empty();
     let text = collected.prose.join("\n");
     let headlines: Vec<text::Headline> = collected
@@ -350,9 +390,16 @@ pub(crate) fn run(
         // On a read, only a pattern rule about the tool name is in scope: the
         // text rules were set aside above, and a pattern rule about text has
         // none to read, so it is recorded as set aside rather than as a pass.
+        //
+        // On a call that publishes nothing, only the pattern rules a policy
+        // wrote for this seam are asked beside the literal rules, which are
+        // never asked for their scope: a guard or a prose rule is about a
+        // publication, and there is none.
         &mut |rule| {
             if read {
                 Ok(rule.selects_subject("tool"))
+            } else if unpublished && text::Judged::of(rule) != Some(text::Judged::Patterns) {
+                Ok(false)
             } else {
                 scoping.holds(rule)
             }
@@ -388,8 +435,10 @@ pub(crate) fn run(
     // enclosing superproject's is not borrowed. Where there is no policy the
     // guards and the prose rules have nothing to run, and saying so on stderr
     // is the difference between a check that passed and a check that did not
-    // happen.
-    if found.is_none() {
+    // happen. Not for a call that publishes nothing, where the guards and the
+    // prose rules are out of scope with a policy or without one: saying so on
+    // every shell command would be the narration that gets a matcher deleted.
+    if found.is_none() && !unpublished {
         eprintln!(
             "uphold hook: no policy where this call was made, so the guards did not run \
              and only the host-identity rules did. That is partial coverage, not a pass."