Skip to content

docs: say how fallbackAction deny reads Windows allowedPaths entries - #38819

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
crew/bug-resolve/fix-38532
Nov 18, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
crew/bug-resolve/fix-38532

Conversation

@CrysisDeu

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Windows author reading the fallbackAction: "deny" clause in the agent-spec field reference learns which allowedPaths entries cover something and which cover nothing on their host.

The toolsSettings row of src/kiro_crew/docs/agent-spec-fields.md says an allowedPaths entry holding \ covers nothing. On Windows that is false: allowed_paths.to_glob_path turns \ into / before the unread-character check, so C:\work\** is read as c:/work/**. The row also never says that a %USERPROFILE%\... entry or a \\server\share\... entry covers nothing on Windows, though parse refuses both.

Why it matters

A Windows author who follows the doc leaves a working backslash path out of allowedPaths, so writes it would have allowed are refused. An author who writes %USERPROFILE%\... finds nothing in the doc saying it covers nothing, and every write it was meant to allow is refused.

Not a goal

What changed (motivation → approach → change)

Symptom: the doc row and allowed_paths.py's own docstring (allowed_paths.py:22-27) disagree about Windows. Root cause: the row's clause was written for POSIX reading only. Change: the one clause in the toolsSettings row now scopes the \ rule to non-Windows hosts, says that on Windows \ is a path separator (so a backslashed drive-letter path covers what it names), and names % entries, UNC or network-share entries, and a .. that climbs off its drive as covering nothing on Windows. The [, {, $ and ~user list is unchanged.

The issue's alternatives (point the row at the docstring; add a separate Windows note under the table) lost because users read the docs page, not source, and the clause being corrected sits in the row.

Backwards compatibility

Compatible: documentation text and a new test only; no runtime behaviour changes.

Removes nothing: the diff edits one doc sentence and adds a test; no key, path, record or function is removed or tightened.

Tests

test/test_agent_spec_fields_doc.py::test_allowed_paths_clause_agrees_with_the_windows_reader (4 cases) calls allowed_paths.parse(entry, windows=True) for the issue's four entries (a backslashed drive-letter path is read as c:/work/**; %USERPROFILE%\..., \\server\share\... and $env:USERPROFILE\... are refused) and pairs each with the row sentence that states it. It also asserts the old "\, $ or a ~user covers nothing" text is gone and that each entry is refused with windows=False, matching the row's off-Windows scoping. It fails on the old row text.

Proof: not provable -- docs or config only

Manual verification

N/A — the change is doc text; the new test runs the reader and checks the text in CI.

Related Issues

Fixes #38532

Intended? / Repro

Intended? No. src/kiro_crew/platform/allowed_paths.py:22-27 (docstring) states that on Windows \ is a separator and that %USERPROFILE%, $env:, UNC and off-drive .. entries cover nothing; to_glob_path (allowed_paths.py:83-86) converts \ to / before _read checks unread characters (allowed_paths.py:119-128), and _read refuses % (:120-121) and a // prefix (:123-125). The doc row at src/kiro_crew/docs/agent-spec-fields.md:689 on main 62e57685a5 says the opposite for \ and names neither % nor UNC.

Repro (read from source on main; the reporter ran it): allowed_paths.parse(r"C:\work\**", windows=True) returns "c:/work/**" (read), while the doc row says an entry with \ covers nothing. parse returns None for %USERPROFILE%\notes\** and \\server\share\notes\**, which the row does not mention. The reporter saw the same results against installed 0.12.2 on Windows 11, 3 of 3 runs.

Sibling sweep

Swept: git grep -nF 'or a ~user covers nothing' -- . (whole repo)
Siblings: none -- the clause appears only in this one doc row

Pattern harvest

Not generalizable: one doc clause that missed a Windows branch already written in its reader's docstring.

Known limitations

  • The C:\work\** case asserts the parse result only, not that covered() allows a write under that path.
  • The new ".. climbs off its drive covers nothing" wording is not pinned by its own test case.

Blind review: 1 round, LOW-ONLY (the two Lows above).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

On Windows a backslash is a path separator, so a drive-letter entry
with backslashes is read; a % variable and a UNC share cover nothing.
Pin the clause to allowed_paths.parse in a doc-text check.

Fixes #38532
@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners November 17, 2026 23:26
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 8662e0b361f9f2c7a6020d628c4c410475ab9907 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 8662e0b361f9f2c7a6020d628c4c410475ab9907 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: let a Windows author learn which allowedPaths entries cover something when fallbackAction is deny. This is a FIX (#38532).

  1. The row no longer says a \ entry covers nothing on every host. It now says that only for hosts other than Windows. — justified
  2. The row now says a backslashed drive-letter path (C:\work\**) covers what it names on Windows. — justified
  3. The row now says % entries, UNC entries and a .. that climbs off its drive cover nothing on Windows. — justified
  4. A new test runs allowed_paths.parse on four entries, with and without windows=True, and checks that the row states each result. — justified

[FIRST-PRINCIPLES-REVIEWED] 8662e0b

Description read

[DESCRIPTION-READ] 2b7e45ee7ef8144b1e93600def9f708c08d15055597591673b6d76862112dba5

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 8662e0b361f9f2c7a6020d628c4c410475ab9907 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only fix. The new row now says what allowed_paths._read and its module docstring say about Windows, and a test that calls parse pins the wording.

[DESIGN-REVIEWED] 8662e0b

Description read

[DESCRIPTION-READ] 066bc7d958b6c8c453b87803609d1d85fb4370fe61f369d618315c67e7e1c48e

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 8662e0b361f9f2c7a6020d628c4c410475ab9907 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 8662e0b

Verdict parsed from the review's SHA-scoped output markers for commit 8662e0b361f9f2c7a6020d628c4c410475ab9907.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8662e0b361f9f2c7a6020d628c4c410475ab9907 false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 8662e0b361f9f2c7a6020d628c4c410475ab9907 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8662e0b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8662e0b361f9f2c7a6020d628c4c410475ab9907 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 18, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 18, 2026 02:14

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We checked this head against src/kiro_crew/platform/allowed_paths.py. Every claim in the new toolsSettings clause matches the reader. On Windows, a % entry is refused first. Then \ becomes /, so C:\work\** reads as c:/work/**. After that, a leading // network share is refused, and $ stays unread, so $env: is refused. anchor() refuses a .. that climbs off its drive. Off Windows, a \ still covers nothing. The new test passes against the head doc, and 4 of its 6 assertions fail against the old row text on main. The test is pure and deterministic, and no product code changes.

Well done: each sentence in the doc is paired with a real allowed_paths.parse call under both windows=True and windows=False, so the doc and the reader cannot drift apart silently.

Optional:

  • The new clause "one whose .. climbs off its drive covers nothing" has no test yet. You could add a case that asserts anchor() returns None for C:\..\..\D:\x and that the row contains this sentence.
  • Open PR #26455 edits the same single-line row. Whichever PR rebases second should keep the Windows wording from this PR.
  • The body says the reporter ran on Windows 11. The issue says only Windows.

@KiroCrewCaptain
KiroCrewCaptain merged commit 0eb2be8 into main Nov 18, 2026
97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the crew/bug-resolve/fix-38532 branch November 18, 2026 02:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

2 participants