docs: annotate ADR-0027 with post-v2.1.119 corrections

[maruiz93]

Summary

• Adds dated correction notes to ADR-0027 at three locations where the
  ADR claims tools and disallowedTools have no effect in --agent
  sessions
• Since Claude Code v2.1.119 (April 23, 2026), both keys ARE enforced
  but unreliable due to parsing bugs, scoping bugs, and subagent
  inheritance issues
• Annotations follow ADR template guidance (minor notes, no rewrite of
  Context/Decision/Consequences)

Related to RCA discussion #5182

Authorization

Authorized by RCA discussion #5182,
which identified the stale claims and recommended corrective annotations.
Related: #303 (harness-level enforcement tracking).

Context

The ADR's claims were correct on v2.1.118 but updated hours later
by v2.1.119. The experiment it cites ran on the last unaffected version.
Full timeline and production evidence in discussion #5182.

The decision (Option A: permissions.deny) remains correct — the
annotations only correct factual claims about tools/disallowedTools
behavior.

Test plan

• Verify annotations render correctly on fullsend.sh/docs
• Confirm no original ADR text was modified (diff is additive only)

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Annotate ADR-0027 with post-v2.1.119 behavior corrections

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Add dated correction notes clarifying tools/disallowedTools now apply in --agent sessions.
• Document known enforcement unreliability (parsing, scoping, subagent inheritance) with references.
• Preserve original ADR decision; annotations are additive and follow ADR note guidance.

High-Level Assessment

The following are alternative approaches to this PR:

1. Write a new follow-up ADR superseding ADR-0027

• ➕ Keeps the original ADR historically accurate for its point-in-time decision
• ➕ Provides a clean, coherent narrative for the post-v2.1.119 world
• ➖ More process overhead (new ADR review/acceptance)
• ➖ Readers must discover and cross-reference multiple ADRs

2. Rewrite ADR-0027 sections (Context/Decision/Consequences) instead of annotating

• ➕ Single document reflects current reality without caveats
• ➕ Avoids repeated correction notes in multiple sections
• ➖ Violates typical ADR guidance about preserving accepted decisions and context
• ➖ Harder to track what changed vs original decision record

3. Move runtime-specific behavior into a separate “Claude Code quirks” doc and link to it

• ➕ Centralizes fast-changing upstream behavior in one place
• ➕ Reduces churn in ADRs when upstream releases change semantics
• ➖ Adds another documentation hop for readers
• ➖ Requires ongoing maintenance discipline to keep the quirks doc current

Recommendation: Keep the PR’s current additive annotation approach. It preserves the ADR’s accepted decision while correcting now-invalid factual claims, and the included references (RCA + upstream issues + tracking issue) give readers the right escalation path without rewriting the ADR’s narrative.

Files changed (1) +29 / -0

Documentation (1) +29 / -0

0027-allowed-and-disallowed-tools-for-agents.mdAdd 2026-07 correction notes for 'tools'/'disallowedTools' enforcement +29/-0

Add 2026-07 correction notes for 'tools'/'disallowedTools' enforcement

• Adds three dated blockquote notes correcting ADR-0027 statements that 'tools'/'disallowedTools' are inert in '--agent' sessions. The notes document post-v2.1.119 enforcement plus known reliability bugs, and link to the RCA discussion, upstream issues, and internal tracking issue while keeping the original ADR text intact.

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md

[github-actions]

Site preview

Preview: https://2bc13556-site.fullsend-ai.workers.dev

Commit: 7fe185ab81022322912f514cc7b2ac9880c1f981

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Migrate disallowedTools from agent frontmatter to .claude/settings.json permissions.deny

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. ADR contradicts itself ✓ Resolved 🐞 Bug ≡ Correctness

Description

ADR-0027 now says tools/disallowedTools ARE enforced in --agent sessions (v2.1.119+), but the
same Context section still presents a table labeling both keys “No effect” in --agent sessions.
This leaves the ADR internally contradictory, so readers can easily take the wrong behavior as the
current truth.

Code

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[R69-76]

+> **Note (2026-07):** Since Claude Code v2.1.119 (April 23, 2026),
+> `tools` and `disallowedTools` ARE enforced in `--agent`/`--print`
+> sessions. However, multiple bugs make them unreliable for steering:
+> scoped `disallowedTools` patterns (e.g. `Bash(sed *)`) strip the
+> entire tool instead of the scoped command; scoped `tools` patterns
+> (e.g. `Bash(gh)`) silently grant full tool access; and
+> `disallowedTools` is not inherited by subagents, making it trivially
+> bypassable via Agent delegation. See [RCA discussion

Relevance

⭐⭐⭐ High

Team repeatedly accepts fixing ADR factual inconsistencies/incorrect claims for reader clarity (e.g.
PR1688).

PR-#1688

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Context table still states tools and disallowedTools have “No effect” in --agent sessions,
while the newly added note immediately below states both keys ARE enforced in --agent/--print
sessions since v2.1.119, creating an internal contradiction in the same section.

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[57-63]
docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[69-76]
docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[195-199]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
ADR-0027 contains conflicting claims about whether `tools` / `disallowedTools` are enforced in `--agent` sessions. The PR adds a dated correction note stating they *are* enforced since v2.1.119, but leaves the primary table/prose asserting “No effect” in `--agent` sessions, so the doc reads as self-contradictory.

## Issue Context
The intent appears to be “additive-only annotations,” but the current layout keeps the outdated statement in a high-salience table while the correction is in a note below, making it easy to miss.

## Fix Focus Areas
- docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[57-88]
- docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[177-199]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Overlong Context correction note ✓ Resolved 📜 Skill insight § Compliance

Description

ADR-0027 is Accepted, but the newly added Context blockquote note is a long, detailed addition
that goes beyond a short annotation and introduces substantial new guidance. This risks rewriting
accepted ADR history instead of keeping post-hoc notes surgical.

Code

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[R69-88]

+> **Note (2026-07):** Since Claude Code v2.1.119 (April 23, 2026),
+> `tools` and `disallowedTools` ARE enforced in `--agent`/`--print`
+> sessions. However, multiple bugs make them unreliable for steering:
+> scoped `disallowedTools` patterns (e.g. `Bash(sed *)`) strip the
+> entire tool instead of the scoped command; scoped `tools` patterns
+> (e.g. `Bash(gh)`) silently grant full tool access; and
+> `disallowedTools` is not inherited by subagents, making it trivially
+> bypassable via Agent delegation. See [RCA discussion
+> (#5182)](https://github.com/fullsend-ai/fullsend/discussions/5182)
+> and upstream issues
+> [claude-code#78063](https://github.com/anthropics/claude-code/issues/78063),
+> [#6527](https://github.com/anthropics/claude-code/issues/6527).
+>
+> The decision to use `permissions.deny` remains correct. For
+> tool-level enforcement that does not depend on Claude Code's
+> parsers, the `tool_allowlist_pretool.py` PreToolUse hook provides a
+> fail-closed positive gate under fullsend's control (disabled by
+> default, opt-in per harness). Implementation of `permissions.deny`
+> in the harness schema is tracked in
+> [#303](https://github.com/fullsend-ai/fullsend/issues/303).

Relevance

⭐⭐ Medium

Mixed history: policy allows annotations (PR1966) but team blocks substantive accepted-ADR rewrites
(PR1982).

PR-#1966
PR-#1982

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The checklist restricts edits to Accepted ADR Context/Decision/Consequences to minor annotations
only. The added Context note spans many lines and adds new operational guidance and detailed
behavioral claims, which is more than a brief annotation.

Rule 1062057: Restrict modifications to accepted ADRs on main
docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[69-88]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
ADR-0027 is in `Accepted` status, but the added Context note is long and adds new guidance (bug details, hook guidance, tracking issue), which can be interpreted as a substantive update rather than a brief annotation.

## Issue Context
Compliance allows only minor annotations (cross-references, short notes, typos) to accepted ADRs; longer guidance should be moved to living docs or linked externally.

## Fix Focus Areas
- docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[69-88]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Consequences bullet has multi-sentences ✓ Resolved 📜 Skill insight ⚙ Maintainability

Description

A new multi-line note was added inside a Consequences bullet, making that bullet no longer a
single-sentence bullet point. This breaks the required Consequences formatting constraints.

Code

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[R195-199]

- `tools` and `disallowedTools` have no effect in `--agent` sessions;
  they only apply to subagents spawned via the Agent tool.
+  > **Note (2026-07):** See correction in Context section — both keys
+  > are now enforced in `--agent` sessions (since v2.1.119) but are
+  > unreliable due to parsing and inheritance bugs.

Relevance

⭐ Low

Formatting-only ADR compliance asks (shorten/reformat bullets/sections) often rejected; emphasis is
content over template strictness (PR2582).

PR-#2582

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The compliance rule requires Consequences to be 3-5 one-sentence bullet points; the added blockquote
creates multi-sentence content within a bullet.

docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[195-199]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Consequences section requires one-sentence bullet points, but the change adds a multi-sentence blockquote note within a bullet.

## Issue Context
Keep Consequences as 3-5 one-sentence bullets; any corrections/annotations should be placed as a short note outside the list or converted into a single-sentence bullet.

## Fix Focus Areas
- docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md[195-199]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough markup (~~text~~) applied to table cells (lines 61–62) and inline prose (lines 64–65) modifies the rendering of the original accepted ADR text. While the original words are still present, the visual modification constitutes inline editing rather than external annotation. No other ADR in the corpus uses strikethrough — all other correction notes append blockquote notes without altering original text. The appended blockquote notes in this PR are well-written and sufficient on their own to communicate the correction.
  Remediation: Remove strikethrough from table cells (lines 61–62) and inline prose (lines 64–65). Restore original text and rely solely on the appended blockquote notes, which already follow the established annotation pattern used by other ADRs.

Low

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The section header 'Inert in --agent sessions — subagents only:' remains unannotated while the blockquote note states these keys ARE now enforced. This is not actionable because AGENTS.md's immutability rule requires preserving original text — the blockquote note serves as the amendment, which is the correct approach.

• [redundant-notes] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:166 — Three correction notes (Context blockquote, Decision blockquote at line 166, Consequences blockquote at line 183) all redirect to the Context section. The Decision and Consequences notes are terse forward references. Placing correction notes near each outdated claim is defensible for readers who jump directly to specific sections.

Previous run

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to original table cell and prose content modifies the accepted ADR text inline. The PR wraps "No effect" in ~~No effect~~ (lines 61–62) and strikes through "only take effect when the agent runs as a subagent spawned via the Agent tool" (lines 64–65). Per AGENTS.md, accepted ADRs are point-in-time records; minor annotations (cross-references, short notes, typo fixes) are allowed but inline text modifications are not. No other ADR in the corpus uses strikethrough — all append blockquote notes without modifying original text. The appended blockquote notes in this PR are sufficient to communicate the correction.
  Remediation: Remove strikethrough from table cells (lines 61–62) and inline prose (lines 64–65). Restore original text and rely solely on the appended blockquote notes, which follow the established annotation pattern.

Low

• [annotation-pattern] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough markup (~~text~~) combined with "see note" inline references introduces a new annotation pattern not found in other ADRs. The established pattern preserves original text unchanged and adds dated correction notes in blockquote format (> **Note (YYYY-MM):**). See also: [adr-immutability-violation] finding at this location.

• [redundant-notes] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:166 — Three separate correction notes (Context section, Decision section line 166, Consequences section line 183) all redirect readers to "updated behavior notes in Context section above." The Decision and Consequences notes are terse forward references that add no new information beyond the Context section note, but placing notes near the claims they correct is defensible for readers who jump directly to those sections.

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The section header "Inert in --agent sessions — subagents only:" remains unannotated, while the Note (2026-07) blockquote states these keys ARE now enforced since v2.1.119. The contradiction is mild — the blockquote note communicates the correction — and per ADR immutability rules the header should remain unchanged.

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:179 — The Consequences bullet "tools and disallowedTools have no effect in --agent sessions" is stated as fact without inline annotation, unlike equivalent statements in the Context section which received strikethrough + "see note." The trailing blockquote note at line 183 provides the correction, following the established annotation pattern.

Previous run (2)

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to original table cell and prose content modifies the accepted ADR text inline. The PR wraps "No effect" in ~~No effect~~ (lines 61–62) and strikes through "only take effect when the agent runs as a subagent spawned via the Agent tool" (lines 64–65). Per AGENTS.md, accepted ADRs are point-in-time records; minor annotations (cross-references, short notes, typo fixes) are allowed but inline text modifications are not. No other ADR in the corpus (0002, 0033, 0034, 0054, 0066) uses strikethrough — all append blockquote notes without modifying original text. The appended blockquote notes in this PR are sufficient to communicate the correction.
  Remediation: Remove strikethrough from table cells (lines 61–62) and inline prose (lines 64–65). Restore original text and rely solely on the appended blockquote notes, which follow the established annotation pattern.

Low

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The section header "Inert in --agent sessions — subagents only:" is not annotated, while the note at line 72 states these keys ARE now enforced. The header is a structural label for the original table; the blockquote note communicates the correction. The contradiction is mild but worth noting.

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:179 — The Consequences bullet "tools and disallowedTools have no effect in --agent sessions" is not annotated inline, unlike equivalent statements in Context. The trailing blockquote note at line 183 directs the reader to the Context correction, following the established annotation pattern used in ADRs 0002, 0033, 0034.

• [content-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — The inline "see note" references in strikethrough sections are ambiguous — "see note" does not specify which note block. In practice the ambiguity is mild since the Context section has only one note block and the later notes explicitly reference "Context section." If strikethrough is removed per the immutability finding, these references become moot.

Previous run (3)

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to original table cell and prose content modifies the accepted ADR text inline. The PR wraps "No effect" in ~~No effect~~ and strikes through "only take effect when the agent runs as a subagent spawned via the Agent tool". Per AGENTS.md, accepted ADRs are point-in-time records; minor annotations (cross-references, short notes, typo fixes) are allowed but inline text modifications are not. Existing annotation practice in the corpus (ADRs 0002, 0033, 0034, 0066) appends blockquote notes without modifying original text. The appended blockquote notes are sufficient to communicate the correction. See also: [formatting-consistency] finding at this location.
  Remediation: Remove strikethrough from table cells (lines 61–62) and inline prose (lines 64–65). Restore original text and rely solely on the appended blockquote notes, which follow the established annotation pattern.

Low

• [formatting-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough formatting (~~text~~) in table cells and inline prose is not used in any other ADR in the corpus. Existing correction annotations in ADRs 0002, 0033, 0034, 0066 use blockquotes without modifying original text. See also: [adr-immutability-violation] finding at this location.

• [content-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — The inline "see note" references in strikethrough sections are ambiguous. The diff adds three blockquote notes at different locations in the document, and "see note" does not specify which note block the reader should consult. If strikethrough is removed per the immutability finding, these inline references become moot.

Previous run (4)

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to table cell content (No effect → ~~No effect~~ see note) in the Context section modifies original accepted ADR text inline. This is the only ADR in the corpus that uses strikethrough. Per AGENTS.md, accepted ADRs are point-in-time records; minor annotations (cross-references, short notes, typo fixes) are allowed but inline text modifications are not. The blockquote notes alone are sufficient to document the correction without modifying original content.
  Remediation: Remove strikethrough from table cells. Restore original No effect text and rely solely on the appended blockquote notes, which are the established annotation pattern (used in ADRs 0002, 0033, 0034, 0066).

Low

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:64 — The paragraph at lines 64–66 retains the original statement that tools/disallowedTools only take effect in subagent sessions, while the new Note block immediately after documents the corrected behavior. This is by design: the paragraph is original ADR text (which should not be modified per immutability rules), and the Note block serves as the dated correction. A reader who reads both will understand the evolution.

• [stale-behavior-reference] docs/guides/user/building-custom-agents.md:51 — The building-custom-agents guide demonstrates tools and disallowedTools in agent frontmatter without mentioning v2.1.119 behavior changes. This file is not part of the PR diff; consider filing a follow-up issue to update the guide with a note about ADR-0027's updated behavior.

Previous run (5)

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to table cell content (No effect → ~~No effect~~ see note) in the Context section. Per AGENTS.md, accepted ADRs are point-in-time records. The strikethrough modifies original content inline rather than purely appending an annotation, which goes beyond what existing annotations do. Existing annotations in ADRs 0002, 0033, and 0034 all use appended blockquotes and never modify original text.
  Remediation: Remove the strikethrough from the table cells. Leave the original "No effect" text intact and rely on the appended blockquote note (which already exists at line 69) to communicate the correction.

Low

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:166 — A 4-line annotation appended after the Decision section statement that tools/disallowedTools "have no effect." The note explains this claim "was correct when written but invalidated by Claude Code v2.1.119." The mechanism (appended blockquote) follows the established annotation pattern, but the language ("invalidated") is editorial rather than neutral cross-referencing.

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:185 — The Consequences section note uses the word "stale" to describe the original bullet, which editorializes rather than neutrally cross-referencing. The mechanism (2-line appended blockquote) is compliant.

• [documentation-style] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Two novel style patterns not established in the ADR corpus: (1) strikethrough text (~~No effect~~); (2) RCA prefix in link text (RCA [#5182]...). Other ADRs use plain [#number](url) format. See also: [adr-immutability-violation] finding at this location.

Previous run (6)

Review

Findings

Medium

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough applied to table cell content (No effect → ~~No effect~~ see note) in the Context section. Per AGENTS.md, accepted ADRs are point-in-time records. The strikethrough preserves the original text (visible through markup) rather than deleting it, and the scope is minimal (two table cells, two words each), making this closer to an inline cross-reference than a substantial rewrite. However, it does modify original content inline rather than purely appending an annotation, which is a borderline case under the immutability rules.
  Remediation: Consider removing the strikethrough from the table cells and relying solely on the appended blockquote note, or write a new superseding ADR.

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:163 — A 4-line annotation is appended after the Decision section statement that tools/disallowedTools "have no effect." The note explains this claim "was correct when written but invalidated by Claude Code v2.1.119." The mechanism (appended blockquote) is the explicitly-allowed annotation pattern, but the language ("invalidated") arguably goes beyond a neutral cross-reference.
  Remediation: Consider softening to a neutral cross-reference, e.g., "see updated behavior notes in Context section above."

Low

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The section header "Inert in --agent sessions — subagents only:" is not modified by this PR, but the correction note below now states both keys "ARE enforced." The contradiction is immediately resolved by the adjacent note but the header remains inconsistent.

• [documentation-style] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61 — Strikethrough text (~~No effect~~) is not an established pattern in the ADR corpus. No other ADR uses strikethrough markup.

• [edge-case-correctness] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:69 — The correction note claims both tools and disallowedTools "ARE enforced" post-v2.1.119, treating them as a pair. These keys have distinct code paths (allowlist vs denylist). The cited RCA discussion RCA: disallowedTools bug activation in production (Jul 6) #5182 should confirm both underwent the same enforcement change.

• [adr-amendment-scope] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:69 — The Context section note is 7 lines long with version numbers, bug characterization, and cross-references. Existing ADR annotations in the corpus (ADRs 0002, 0033, 0034) are 3–4 lines. The delta is modest and AGENTS.md does not define a strict line limit for "short notes."

• [documentation-style] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:73 — Link text uses RCA prefix (RCA [#5182]...) not seen elsewhere in the ADR corpus. Blockquote note format itself is established (ADRs 0002, 0033, 0034, 0066).

• [adr-immutability-violation] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:185 — The Consequences section note uses the word "stale" to describe the original bullet, which editorializes rather than neutrally cross-referencing. The mechanism (2-line appended blockquote) is compliant.

• [missing-authorization] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md — No formal GitHub-linked issue. The PR body cites RCA discussion RCA: disallowedTools bug activation in production (Jul 6) #5182 and issue Migrate disallowedTools from agent frontmatter to .claude/settings.json permissions.deny #303 but uses informal references rather than GitHub keywords.

---

Labels: PR modifies documentation under docs/ADRs/

---

Labels: PR modifies ADR documentation under docs/ADRs/

Previous run (7)

Review

Findings

Medium

• [internal-consistency] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The table cells at lines 59–62 still read "No effect" for both tools and disallowedTools in --agent sessions, while the correction note immediately after (line 69) states they "ARE enforced in --agent/--print sessions." The (corrected below) parenthetical in the header is easy to miss and does not resolve this visual contradiction. A reader scanning the table will take away the wrong conclusion.
  Remediation: Either update the table cells to reflect the corrected behavior (e.g., "Enforced but unreliable — see note") or add strikethrough to the "No effect" cells to make the correction visually obvious.

Low

• [documentation-style] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:57 — The inline (corrected below) annotation in the table header is not an established pattern in the ADR corpus. Existing ADRs (0002, 0033, 0034, 0066) use separate blockquote notes without modifying structural elements like headers. The blockquote that follows already serves this cross-reference purpose.
  Remediation: Remove (corrected below) from the header; the > **Note (2026-07):** blockquote below is sufficient.

• [edge-case-correctness] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:69 — The correction note claims both tools and disallowedTools are enforced post-v2.1.119. It may be worth confirming with RCA RCA: disallowedTools bug activation in production (Jul 6) #5182 evidence that the tools allowlist key (not just disallowedTools) underwent the same enforcement change, since the original ADR table groups them together but they are distinct mechanisms.

• [documentation-style] docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:72 — Link format [RCA (#5182)](url) is inconsistent with established convention. All other issue references in the ADR corpus use [#NNN](url) format.
  Remediation: Change to RCA [#5182](url) or [#5182](url).

---

Labels: PR modifies documentation under docs/ADRs/

Previous run (8)

Review

Verdict: comment · 2 findings (2 medium)

This PR adds three dated correction annotations to ADR-0027, noting that Claude Code v2.1.119 changed the enforcement behavior of tools/disallowedTools in --agent sessions. The annotations are technically accurate (verified against tool_allowlist_pretool.py source and hooks.go), internally consistent across all three sites, and use a blockquote format (> **Note (YYYY-MM):**) that is established in the ADR corpus (ADRs 0002, 0033, 0034, 0066). No original text is modified — the diff is purely additive. All external URLs point to expected github.com domains.

The decision to annotate rather than rewrite is sound. However, two process concerns are worth noting.

Findings

1. ADR amendment scope (medium)

File: docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md, line 69

The first annotation block in the Context section is 21 lines of substantive analytical content — listing three distinct bug classes, evaluating a workaround (tool_allowlist_pretool.py), and referencing an RCA discussion. Per the ADR immutability guidance, annotations adding ~20+ lines of new analytical content may exceed the threshold for "minor notes." Existing dated annotations in the corpus are typically 4–8 lines.

Suggested remediation: Consider splitting the first annotation into (a) a short note in ADR-0027 linking to the RCA discussion and noting the changed behavior (~5 lines), and (b) a companion document or new ADR that captures the detailed bug analysis, workaround evaluation, and tracking references. The second and third annotations (6 and 4 lines respectively) are well within acceptable scope.

2. Missing authorization (medium)

File: docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md

The PR adds 29 lines to an Accepted ADR but has no linked issue. Per the project's intent-coherence rules, non-trivial changes (20+ lines) to governance artifacts typically require explicit authorization. The PR body references discussion #5182 for context, but this is not formally linked as authorizing work.

Suggested remediation: Link an existing issue that tracks the need to document the v2.1.119 behavior changes, or create one. This is especially relevant for external contributors modifying Accepted ADRs.

Additional notes

• PR title docs: annotate ADR-0027 with post-v2.1.119 corrections follows conventional commits format correctly.
• No security concerns — no secrets, prompt injection, Unicode steganography, or suspicious URLs detected.
• Technical accuracy confirmed — tool_allowlist_pretool.py exists at internal/security/hooks/tool_allowlist_pretool.py and is indeed a fail-closed PreToolUse hook disabled by default, as the annotation claims.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:44 PM UTC · Completed 3:51 PM UTC
Commit: 319c8d9 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 3:54 PM UTC · Ended 3:58 PM UTC
Commit: 12bd957 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:58 PM UTC · Completed 4:12 PM UTC
Commit: 702959b · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 8:30 PM UTC · Ended 8:33 PM UTC
Commit: 12bd957 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 8:34 PM UTC · Completed 8:49 PM UTC
Commit: 1f63101 · View workflow run →

[maruiz93]

/fs-review

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 9:35 AM UTC · Ended 9:50 AM UTC
Commit: b7d92a0 · View workflow run →

[maruiz93]

Addressing review findings (commit 1f63101)

Medium — adr-immutability-violation (strikethrough, line 61): Keeping the strikethrough. The previous review round on commit 702959b explicitly recommended: "add strikethrough to the 'No effect' cells to make the correction visually obvious." The strikethrough preserves original text (visible through markup) while making the correction scannable at the table level. Removing it would reintroduce the internal-consistency finding from that same round, which flagged that "(corrected below)" was too easy to miss. This is a minimal inline cross-reference, not a rewrite.

Medium — adr-immutability-violation ("invalidated", line 163): The language is factual — the claim was invalidated by v2.1.119, released the same day as the experiment it cites. The note is a 2-line neutral cross-reference using the established blockquote pattern.

Low findings: adr-amendment-scope notes the Context annotation is now 7 lines with "modest" delta — no action needed. Edge-case-correctness (both tools and disallowedTools enforced) is confirmed by both Ben's experiment on #4437 and the RCA in #5182. Style nits (RCA prefix, "stale" wording) are acknowledged but not blocking.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:22 AM UTC · Completed 10:35 AM UTC
Commit: be083f8 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:19 AM UTC · Completed 10:33 AM UTC
Commit: fd2d529 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:34 AM UTC · Completed 10:48 AM UTC
Commit: b69d7f6 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:59 AM UTC · Completed 11:12 AM UTC
Commit: 7fe185a · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

---

Note: The following inline comments could not be posted on the diff (GitHub returned 422) and are included here instead:

• docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:61: [medium] adr-immutability-violation

Strikethrough markup applied to table cells (lines 61-62) and inline prose (lines 64-65) modifies the rendering of the original accepted ADR text. While the original words are still present, the visual modification constitutes inline editing rather than external annotation. No other ADR in the corpus uses strikethrough — all other correction notes append blockquote notes without altering original text. The appended blockquote notes in this PR are well-written and sufficient on their own to communicate the correction.

Suggested fix: Remove strikethrough from table cells (lines 61-62) and inline prose (lines 64-65). Restore original text and rely solely on the appended blockquote notes, which already follow the established annotation pattern used by other ADRs.

• docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md (file-level): Line 57 · [low] internal-consistency

The section header Inert in --agent sessions — subagents only remains unannotated while the blockquote note states these keys ARE now enforced. This is not actionable because the ADR immutability rule requires preserving original text — the blockquote note serves as the amendment, which is the correct approach.

• docs/ADRs/0027-allowed-and-disallowed-tools-for-agents.md:166: [low] redundant-notes

Three correction notes (Context blockquote, Decision blockquote at line 166, Consequences blockquote at line 183) all redirect to the Context section. The Decision and Consequences notes are terse forward references. Placing correction notes near each outdated claim is defensible for readers who jump directly to specific sections.

[rh-hemartin]

If you are having trouble finding the conversation that is not resolved you should know that sometimes the button does not work. I usually tell my agent and it does solve it using the graphql endpoint. I found this multiple times already.

[maruiz93]

If you are having trouble finding the conversation that is not resolved you should know that sometimes the button does not work. I usually tell my agent and it does solve it using the graphql endpoint. I found this multiple times already.

on it... but it's frustrating though -.-

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 1:55 PM UTC · Completed 2:10 PM UTC
Commit: 7fe185a · View workflow run →

[fullsend-ai-retro]

Retro: PR #5203 — ADR-0027 correction annotations

A 16-line docs-only PR that annotated three places in ADR-0027 where factual claims about tools/disallowedTools behavior had become stale after Claude Code v2.1.119. The PR took 6 days from open to merge despite human approval on day 2, primarily due to the review agent repeatedly re-raising the same finding.

Timeline

1. Jul 16 — PR opened. First review run (commit 319c8d9) flags the annotation as too long (21 lines). qodo-code-review flags an internal contradiction: table says "No effect" but the correction note says the keys ARE enforced.
2. Jul 16 — Author trims annotation. Second review run (commit 702959b) suggests adding strikethrough to the "No effect" table cells to make the contradiction visually obvious.
3. Jul 16-17 — Author adds strikethrough per the suggestion. Review run (commit 1f63101) flags the strikethrough as [medium] adr-immutability-violation. Author softens language per other findings.
4. Jul 17 — Author pushes commit c784795. Review again flags strikethrough as [medium] adr-immutability-violation. Author replies explaining it was suggested by a prior review round.
5. Jul 17 — Author pushes commit be083f8. Review flags the same finding a third time. Author acknowledges. Human reviewer (rh-hemartin) approves.
6. Jul 21-22 — Author rebases 3 more times. Each triggers another review run that re-raises the same findings. Author struggles with GitHub's resolve-conversation UI to clear unresolved threads for merge.
7. Jul 22 — PR merges after 12 review agent runs (8 successful, 3 cancelled, 1 failed).

Key issues

Self-contradictory recommendations (novel — see Proposal 1): The review agent suggested adding strikethrough in one round, then flagged the result as an immutability violation in the next three rounds. The root cause is that the prior-review pipeline only reads the "current section" of the sticky comment — remediation suggestions from earlier rounds are collapsed into <details> history blocks and invisible to subsequent runs.

Token cost on docs-only PRs (novel — see Proposal 2): All 8 successful review runs dispatched the full fleet of opus-tier sub-agents across all dimensions (correctness, security, intent-coherence, style-conventions, docs-currency, cross-repo-contracts). For a single-file ADR annotation, correctness, security, and cross-repo-contracts dimensions had nothing to analyze.

Re-raising acknowledged findings (already tracked): The strikethrough finding was raised 3+ times despite the author posting explicit replies each time. This provides fresh evidence for agents#106 (author reply ingestion) and fullsend#3073 (re-raising after addressing). The severity anchoring rule ("preserve severity on unchanged code") created a perpetual loop with no escape valve — additional evidence for fullsend#2816 (persistent finding cache with dismissal lifecycle).

Inline comment deduplication (already tracked): Multiple inline comments for the same finding across force pushes created unresolved conversation threads that blocked merge for days after human approval. This corroborates fullsend#5007 (inline comment dedup) and fullsend#1285 (unchanged inline comment regeneration).

Proposals filed

• Review agent should reconcile findings against its own prior remediation suggestions (in fullsend-ai/agents)
• Skip irrelevant review dimensions for docs-only PRs to reduce token cost (in fullsend-ai/agents)