Skip to content

docs(subagent): record per-host results of the shared scratch window - #20357

Merged
bolichen97 merged 1 commit into
mainfrom
docs/subagent-scratch-platforms-12802
Oct 14, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/subagent-scratch-platforms-12802

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The sub-agent spec records what host runs showed about the shared $KIROCREW_SCRATCH window 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_SCRATCH per session tree" section in docs/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.sh passes.

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

  • 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 (N/A, docs only)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 15:40
@bolichen97
bolichen97 requested a review from mbriones98 October 14, 2026 15:40
@bolichen97
bolichen97 enabled auto-merge (squash) October 14, 2026 15:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1a4b402

Verdict parsed from the review's SHA-scoped output markers for commit 1a4b40264ff5d36bafedb6c07814aa761df2c3c3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1a4b40264ff5d36bafedb6c07814aa761df2c3c3: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1a4b402

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1a4b40264ff5d36bafedb6c07814aa761df2c3c3: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 1a4b40264ff5d36bafedb6c07814aa761df2c3c3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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.

@bolichen97
bolichen97 force-pushed the docs/subagent-scratch-platforms-12802 branch from dea9b5a to 1a4b402 Compare October 14, 2026 21:03
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Closing line claims more than the macOS run showed

fixed in 1a4b402: the closing line no longer says the window "works on all three hosts".
It now says a dedicated sub-agent reached the parent's staged file on all three hosts, that only Linux has a known sandbox layer, and that the macOS and Windows runs show the path works, not that it works inside a Kiro Crew sandbox (#19601).

[operator: bolichen97]

@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 Oct 14, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 fa5d26bd13 is #12782. The #12802 body says that PR "was verified on Linux (namespace sandbox) only". The mechanism is extra_private_dirs as a second window inside the masked scratch root. That matches the sandbox.py comment 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_kiro on darwin, together with kiro_internal_sandbox_enabled(), deliberately leaves extra_private_dirs out 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:132 does the same via _build_seatbelt_profile. None of these runs sandbox-exec against the window.
  • 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.sh exit 0 ("All documentation checks passed"; the one report-only stale baseline entry is in an unrelated file).
    • check_comment_history.py and check_brand_name.py both 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

  1. Closes #12802 will 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 at src/kiro_crew/agent_scratch.py:110.
    • Raise the two shared_scratch_window drop branches from debug to warning. They are still logger.debug at agent_scratch.py:713,719.
    • Tighten the getattr(..., "work_scratch_dir") / "parent_work_scratch_dir" reads. They are still at session_background.py:771,937 and subagent_manager/run.py:2341.

    Before merge, either file them as a new issue or change Closes to Refs, so they stay tracked.

  2. 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.

Not run

  • No tests ran. The diff is docs only.
  • No macOS or Windows host run. The host results are taken from the #12802 comments and checked against source only.
  • Linux behaviour comes from #12782's record and the existing test/test_subagent_shared_scratch.py pin. I did not re-run it.

@bolichen97
bolichen97 merged commit b3faf90 into main Oct 14, 2026
102 checks passed
@bolichen97
bolichen97 deleted the docs/subagent-scratch-platforms-12802 branch October 14, 2026 23:12
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Verify the shared $KIROCREW_SCRATCH window on macOS Seatbelt and Windows

2 participants