Repository navigation
docs: say how fallbackAction deny reads Windows allowedPaths entries - #38819
Conversation
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
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing to check. What this change shipsInventory (4 items) — 4 justifiedIntent: let a Windows author learn which
[FIRST-PRINCIPLES-REVIEWED] 8662e0b Description read[DESCRIPTION-READ] 2b7e45ee7ef8144b1e93600def9f708c08d15055597591673b6d76862112dba5 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Docs-only fix. The new row now says what [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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
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 assertsanchor()returns None forC:\..\..\D:\xand 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.
Problem / Motivation
Goal: A Windows author reading the
fallbackAction: "deny"clause in the agent-spec field reference learns whichallowedPathsentries cover something and which cover nothing on their host.The
toolsSettingsrow ofsrc/kiro_crew/docs/agent-spec-fields.mdsays anallowedPathsentry holding\covers nothing. On Windows that is false:allowed_paths.to_glob_pathturns\into/before the unread-character check, soC:\work\**is read asc:/work/**. The row also never says that a%USERPROFILE%\...entry or a\\server\share\...entry covers nothing on Windows, thoughparserefuses 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
allowed_paths.parseor the gate's refusal of an uncovered write.\\?\spellings (Windows: five more checks refuse the \\?\ spelling of a local path they accept plain (spec write allowlist, skill links, Bot worktree, Bot cron export, COMSPEC trust) #32690).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 thetoolsSettingsrow 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~userlist 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) callsallowed_paths.parse(entry, windows=True)for the issue's four entries (a backslashed drive-letter path is read asc:/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~usercovers nothing" text is gone and that each entry is refused withwindows=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_readchecks unread characters (allowed_paths.py:119-128), and_readrefuses%(:120-121) and a//prefix (:123-125). The doc row atsrc/kiro_crew/docs/agent-spec-fields.md:689on main62e57685a5says 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.parsereturnsNonefor%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
~usercovers 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
C:\work\**case asserts theparseresult only, not thatcovered()allows a write under that path...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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.