Repository navigation
docs(subagent): record per-host results of the shared scratch window - #20357
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
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: |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 1a4b402 Description read[DESCRIPTION-READ] 2aef7314ba4cd16997e6cc2bdbb14877b09497acc0837d573ef31dbc024e20ec 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 |
dea9b5a to
1a4b402
Compare
[operator: bolichen97] |
buluoray
left a comment
There was a problem hiding this comment.
Head verified: 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 (the PR's live head when read; auto-merge is on and there were no reviews, so this approval is the last gate). The change is docs only: +15/-0 in docs/system-specs/modules/subagent.md. git merge-tree against origin/main is clean. CI on this head: 87 pass, 14 skipping, 0 failing, 0 pending.
What it fixes for users
The sub-agent spec explained how the shared $KIROCREW_SCRATCH window is built, but it never said which hosts it had been seen working on. The PR adds a table at L4164-4177, inside "One $KIROCREW_SCRATCH per session tree" (L4025). The table has one row each for Linux, macOS and Windows, with what each host run showed and what it did not. A note under the table says the macOS and Windows runs prove the path works, not that it works inside a Kiro Crew sandbox.
Evidence (every claim in the added text checked)
- Linux row: "the path #12782 was built and tested on". Squash
fa5d26bd13is #12782. The #12802 body says that PR "was verified on Linux (namespace sandbox) only". The mechanism isextra_private_dirsas a second window inside the masked scratch root. That matches thesandbox.pycomment at the"scratch"entry in_CREW_HIDDEN_LEAVES(~L320-330). - macOS row. The run facts (macOS 26.7.1, arm64, same path, read the staged file, wrote a new file, ran under kiro-cli's agent server, no Kiro Crew sandbox seen above it) match bolichen97's #12802 comment of 2026-10-14 word for word in substance.
- "Fits the delegated path leaving private windows out" holds in source.
src/kiro_crew/sandbox.py~L10956-10965:delegate_to_kiroon darwin, together withkiro_internal_sandbox_enabled(), deliberately leavesextra_private_dirsout of the fallback test. - "Seatbelt carve-out pinned at profile-text level by tests only" also holds. The pin is
test/test_sandbox_private_window_in_caller_mask.py, which calls_seatbelt(..., extra_private_dirs=...)and asserts on the profile lines.test/test_overload_home_fence.py:132does the same via_build_seatbelt_profile. None of these runssandbox-execagainst the window.
- "Fits the delegated path leaving private windows out" holds in source.
- Windows row. It matches the 2026-10-12 #12802 comment: same value, marker read back, sandbox layer not surfaced, isolation differs (#19601). Source agrees: Windows also takes
delegate_to_kiro(sys.platform == "win32" and is_kiro_cli is True). - #19601 exists, is OPEN, and is titled "Sub-agent scratch isolation differs on Windows".
- Conventions.
scripts/docs-lint.shexit 0 ("All documentation checks passed"; the one report-only stale baseline entry is in an unrelated file).check_comment_history.pyandcheck_brand_name.pyboth pass against the merge-base.- The added text restates no count that AGENTS.md forbids: it has no denied-rule count and no test counts.
- The spec already cites issue numbers elsewhere (22 occurrences), so the citations follow existing convention.
Blocking items
None.
Non-blocking follow-ups
-
Closes #12802will close follow-ups that are only recorded in that issue's comments. All three are still open on this head, and a search found no other issue tracking them:- Move the owner marker out of the agent-writable tree.
OWNER_FILENAME = ".owner"is still atsrc/kiro_crew/agent_scratch.py:110. - Raise the two
shared_scratch_windowdrop branches fromdebugtowarning. They are stilllogger.debugatagent_scratch.py:713,719. - Tighten the
getattr(..., "work_scratch_dir")/"parent_work_scratch_dir"reads. They are still atsession_background.py:771,937andsubagent_manager/run.py:2341.
Before merge, either file them as a new issue or change
ClosestoRefs, so they stay tracked. - Move the owner marker out of the agent-writable tree.
-
The note scopes #19601 wider than the issue does. It says the macOS and Windows sandbox-layer question "is tracked in #19601", but #19601's body covers only Windows isolation. Add a line on #19601 that it also covers the macOS layer identity, or reword the note.
Problem / Motivation
Goal: The sub-agent spec records what host runs showed about the shared
$KIROCREW_SCRATCHwindow on Linux, macOS and Windows, and what they did not show.The spec describes the shared window but names no run on macOS or Windows. #12782 shipped it after a Linux-only check, and #12802 holds the open follow-up to try the other two hosts. Both runs are now done and posted on #12802. The spec does not say so yet.
Why it matters
A reader of the spec cannot tell which hosts the shared window was ever seen working on. They also cannot tell that the sandbox layer behind the macOS and Windows runs is still unknown. Without that line, "works" can be read as "proven under every sandbox".
Not a goal
What changed (motivation → approach → change)
The spec said how the window is built, not where it was seen to work. I added one table to the "One
$KIROCREW_SCRATCHper session tree" section indocs/system-specs/modules/subagent.md. It has one row per host, with "what the run showed" and "not verified" side by side.Linux is the check #12782 was built on. On macOS the sub-agent got the same path, read the parent's staged file and wrote a new file there. On Windows it got the same value and read a staged marker back. For macOS and Windows the table says the sandbox layer is not verified. The note under it says those runs show the path works, not that it works inside a Kiro Crew sandbox.
Backwards compatibility
Compatible: documentation only; no behaviour, config or API changes.
Removes nothing: the change only adds a table and a short note under it.
Tests
None added. This is a docs-only change.
scripts/docs-lint.shpasses.Manual verification
The macOS and Windows runs were done by hand on real hosts and are posted on #12802. The table repeats what those comments say and no more.
Screenshots / video
N/A — no user-visible UI change; the diff touches one spec file.
Related Issues
Closes #12802
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)