Agent write-safety: repo-scope + never-fabricate-id + never-suppress-write rules, runbook fix, and a portable enforcement kit (#364/#365/#366)

[ptr727]

Addresses the cross-repo comment incident (#364, #365, #366): an autonomous PR-review loop hand-fabricated a GraphQL thread node id and fired a reply mutation with output suppressed (>/dev/null 2>&1 || true). Because node ids resolve globally, the guessed id landed on a real thread in a stranger's repo (mankatcheung/job-finder #15) and the write succeeded under the maintainer's identity, while the suppressed output read as a harmless failure.

Three root causes -> three rules, applied in three guard layers.

1. Carried template rule (travels to the fleet)

New AGENTS.md section ## Repository Boundaries and Write Safety (after Foundational Principles, beside the existing never-force-push safety rules), added to the carried-sections allowlist in spec/files.json:

• Write only to the current project's own repository - a broad identity is capability, not permission.
• Never fabricate, guess, or reuse an identifier passed to a write - capture every id from a live query in the same session.
• A write is never a probe, and its output is never suppressed - a write that appears to fail is verified, not assumed harmless.

2. Runbook fix (.github/copilot-instructions.md, carried whole)

The reply/resolve example modeled the footgun: a disembodied -F threadId="PRRT_..." literal disconnected from the reviewThreads(first:100) query above it. Rewritten to capture $TID from that live query with an empty-result guard, use -F threadId="$TID", show the mutation output, and confirm isResolved before closing. Added an intra-doc cross-reference to the new section. (The requestReviews example already captured its ids from live queries.)

3. Portable per-machine safety kit (host-setup/agent-safety/, not carried)

The prose layers are necessary but not sufficient - the incident happened under a "Verification Discipline" section. This adds the mechanical backstop and makes it deployable everywhere as the first thing on a new system:

• gh-write-guard.py - a PreToolUse hook that DENIES the three write footguns (suppressed-output mutation, literal-node-id mutation, cross-origin explicit target). Reads pass through. It fires even in autonomous / bypass-permissions sessions - the exact condition of the incident. --selftest runs an 11-case decision matrix.
• claude-md-safety.md - the same rules as host-scope guidance, appended into ~/.claude/CLAUDE.md so every session on a machine inherits them, including ad-hoc work outside any project.
• install.py + thin install.sh / install.ps1 wrappers - one tested cross-platform installer: self-tests the hook before registering it, merges the settings.json entry without clobbering other keys, updates the CLAUDE.md block in place. Fully idempotent.

This is the rollout #365 tracks; its per-machine checklist becomes "run install.sh / install.ps1".

Deliberately out of scope

• Credentials stay out-of-band (per owner decision): a fine-grained PAT limited to owned repos is stronger structural defense but is per-machine credential setup, not a carried rule.
• No spec/audit.py change: section carriage is intent-checked, not mechanized; a literal-id grep on a whole-carried runbook is fragile. Raised separately: "Verification Discipline" is also absent from the carried-sections allowlist - a follow-up, not bundled here.

Verification (driven, not assumed)

• Hook --selftest: 11/11 incl. the exact incident (deny), the empty-id guard idiom (allow), reads (allow).
• Real stdin path emits hookSpecificOutput/permissionDecision: "deny" for the incident command; reads and non-Bash tools pass through; malformed input never interferes.
• Installer: fresh install, same-version re-run (idempotent), and version-upgrade replace-in-place all verified against throwaway homes; settings.json merge preserves other keys.
• spec/validate.py, markdownlint (whole-repo **/*.md), editorconfig-checker: clean.

Note on the section-name/anchor lockstep: the copilot-instructions cross-reference #repository-boundaries-and-write-safety and the spec/files.json sections entry both depend on the section title; rename them together if ever changed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds defense-in-depth guidance and tooling to prevent mis-targeted GitHub writes by autonomous agents (repo boundary enforcement, never-fabricate-IDs, and never-suppress-write-output), addressing the cross-repo comment incident described in #364/#365/#366.

Changes:

• Add a new carried AGENTS.md section ("Repository Boundaries and Write Safety") and include it in the spec’s carried-sections allowlist.
• Fix the Copilot runbook thread-reply example to require capturing thread IDs from live queries and to avoid suppressing mutation output.
• Introduce a per-machine “agent write-safety kit” (hook + installer + CLAUDE.md snippet) under host-setup/agent-safety/.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
spec/files.json	Adds the new write-safety section to the carried-sections baseline.
AGENTS.md	Introduces the repo-scope / never-fabricate-id / never-suppress-write rules as a carried section.
.github/copilot-instructions.md	Updates the reply/resolve runbook to capture IDs from live queries and to show write outputs.
host-setup/agent-safety/README.md	Documents installation and verification for the per-machine safety kit.
host-setup/agent-safety/install.sh	Bash wrapper to run the cross-platform installer.
host-setup/agent-safety/install.ps1	PowerShell wrapper to run the cross-platform installer on Windows.
host-setup/agent-safety/install.py	Cross-platform, idempotent installer that deploys and registers the hook and CLAUDE.md block.
host-setup/agent-safety/gh-write-guard.py	PreToolUse hook to deny specific high-risk GitHub write patterns.
host-setup/agent-safety/claude-md-safety.md	Marker-delimited CLAUDE.md block with the same safety rules for all sessions.
host-setup/agent-safety/.markdownlint-cli2.jsonc	Local markdownlint override for the snippet’s intentional H2 start.
.gitattributes	Pins LF endings for new shebang-executed Python entrypoints.
.editorconfig	Pins LF endings for the agent-safety kit’s Python scripts.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 11 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

host-setup/agent-safety/gh-write-guard.py:100

• The deny reason's examples don't match what the suppression detector actually blocks. _SUPPRESS also matches 2>/dev/null and || echo/|| :, so the message should describe the broader class (discarding output or forcing success) rather than listing an incomplete subset.

        return "deny", (
            "This is a GitHub write with its output discarded (>/dev/null, &>/dev/null, || true). "
            "A write's result is exactly what must be read: a mutation can succeed on the server "
            "while the client reports an error. Run it without the output-discarding tail and read "
            "the response. See AGENTS.md 'Repository Boundaries and Write Safety'."
        )

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

host-setup/agent-safety/gh-write-guard.py:12

• The docstring's example list says the discarded-output detector covers || true only, but _SUPPRESS also matches other force-success tails like || : and || echo (line 48). Aligning the docstring with the implementation avoids confusion about which patterns are denied.

  1. a state-changing gh call whose output is discarded (>/dev/null, &>/dev/null, 2>/dev/null, || true)

host-setup/agent-safety/gh-write-guard.py:100

• The deny reason lists only >/dev/null, &>/dev/null, and || true, but the suppression detector also denies 2>/dev/null and other force-success tails (see _SUPPRESS on line 48). Update the message to either include e.g. or list a representative set that matches the implementation so users understand why a command was blocked.

            "This is a GitHub write with its output discarded (>/dev/null, &>/dev/null, || true). "
            "A write's result is exactly what must be read: a mutation can succeed on the server "
            "while the client reports an error. Run it without the output-discarding tail and read "
            "the response. See AGENTS.md 'Repository Boundaries and Write Safety'."
        )

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

host-setup/agent-safety/README.md:59

• AGENTS.md requires reference-style links in Markdown docs (except AGENTS.md and .github/copilot-instructions.md). This README uses an inline link to issue #365; please convert it to a reference-style link and define the reference at the bottom of the file.

- **Per-machine.** `~/.claude/` does not travel, so run the installer on each box. This is the rollout that [#365](https://github.com/ptr727/ProjectTemplate/issues/365) tracks.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

host-setup/agent-safety/README.md:1

• Top-level heading is not in title case. AGENTS.md documentation conventions require headings to follow the title-case-with-short-bind-words rule (AGENTS.md:123).

# Agent write-safety kit

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

host-setup/agent-safety/gh-write-guard.py:100

• The deny message lists only some of the suppression / force-success patterns that actually trigger a deny. The guard also denies 2>/dev/null and || echo/|| :, so the user-facing reason should include those to avoid confusion when a command is blocked.

            "This is a GitHub write with its output discarded (>/dev/null, &>/dev/null, || true). "
            "A write's result is exactly what must be read: a mutation can succeed on the server "
            "while the client reports an error. Run it without the output-discarding tail and read "
            "the response. See AGENTS.md 'Repository Boundaries and Write Safety'."
        )

AGENTS.md:24

• This list of output-suppression examples is used as concrete guidance, but it omits other discard patterns the repo's safety kit actively blocks (notably 2>/dev/null and || :). Including them here helps keep the behavioral rule aligned with the mechanical enforcement and avoids readers treating the examples as an allowlist.

- **Write only to the current project's own repository.** Every state-changing call targets this project's `origin` and nothing else. A broad or logged-in identity is capability, not permission - a token that *can* reach another repository does not authorize writing to it. Writing to any other repository needs explicit, per-session human permission for that specific repository, and a "harmless test" write is still a write, so there is no probe exception. Reads from anywhere are fine.
- **Never fabricate, guess, or reuse an identifier passed to a write.** Every id a state-changing call consumes - a node id, a numeric id, a thread or comment id - is captured from a live query in the **same** session into a variable and passed from there. Do not hand-type an id, guess it, recall it from memory or an earlier session, or copy it from documentation or an example. Ids commonly resolve **globally**, so a wrong-but-valid id does not fail - it writes to the wrong target, in someone else's repository. If a query returns no id, stop rather than invent one to proceed.
- **A write is never a probe, and a write's output is never suppressed.** Never fire a state-changing call to see whether it works: decide it should happen, make it happen, and read the result. Never append output-discarding redirection or a force-success tail to a mutation (`>/dev/null`, `&>/dev/null`, `|| true`, `|| echo`) - the write's output is exactly what must be read. A write that appears to fail is **verified, not assumed harmless** - the operation may have succeeded on the server while the client reported an error - so confirm the actual state before retrying or moving on.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

host-setup/agent-safety/README.md:1

• The H1 heading is not in title case (repo doc convention). Update it so the hyphenated compound is capitalized and the heading reads as title case.

# Agent write-safety kit

host-setup/agent-safety/install.ps1:16

• The PowerShell wrapper falls back to running install.py with python without verifying it is Python 3. If python is Python 2 (still common on some Windows setups), the script will fail with a SyntaxError before install.py can print the friendly version check message.

} elseif (Get-Command "python" -ErrorAction SilentlyContinue) {
    & python $script @args

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

host-setup/agent-safety/gh-write-guard.py:49

• The _SUPPRESS regex is described as detecting output-discard/force-success "tails", but it currently matches these tokens anywhere in the command string. That can false-deny legitimate gh issue/pr ... --body "... || true ..." or comments containing >/dev/null in the body, even when the write itself is not suppressed. Anchoring this detector to end-of-command keeps the check focused on the actual footgun while reducing false positives.

# Output-discard / force-success tails. Bare `2>&1` is NOT here: it merges stderr into stdout, leaving
# the output visible, so it is not suppression (and denying it would break `... 2>&1 | tee log`).
_SUPPRESS = re.compile(r">\s*/dev/null|&>\s*/dev/null|2>\s*/dev/null|\|\|\s*(?:true\b|echo\b|:)")

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.