Repository navigation
Conversation
…-cli
`side_readonly_spec` publishes `~/.kiro/agents/<agent>--readonly.json` on
every side turn -- into the registry kiro-cli loads its selectable agents
from -- and rewrites the inherited KAS policy to an empty one:
if "permissions" in spec:
spec["permissions"] = {"rules": []}
It is a generated-spec writer like the five in `agent.py`, but it never
reached the shared version gate kirodotdev#12919 centralized. kiro-cli validates
specs with serde `deny_unknown_fields`, and it is the KEY's presence,
not its value, that a release below SPEC_PERMISSIONS_MIN_VERSION refuses
-- an empty policy is still a policy. So a base spec carrying a
`permissions` block, on a below-floor or unknown release, produced a
derived file that release refuses whole.
What is lost when it is refused is this module's entire reason to exist.
The derived spec is the side turn's read-only isolation: `allowedTools`
emptied, no `autoApprove`, no `toolsSettings` grants, no
`includeMcpJson`, no lifecycle hooks -- so that every call raises a
permission request the READ_ONLY gate judges instead of being approved
by the backend unattended.
Routed through `_write_derived_permissions`, which on an accepting
release derives `{"rules": []}` from the emptied grants -- byte-identical
to what this line wrote -- and on a refusing or unknown one removes the
inherited value. The `if "permissions" in spec` guard stays: the gate
decides whether the field may be CARRIED, not whether to add one, and
its mere presence is what makes KAS load a spec at all.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The owning spec and the function's own contract now misdescribe the behavior — side.md still promises an unconditional empty KAS block, and WatchThe diff makes [DESIGN-REVIEWED] faa1c4c |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify I grepped What this change shipsInventory (3 items) — 3 justifiedIntent: keep the side turn's read-only isolation spec loadable on a kiro-cli that refuses the
[FIRST-PRINCIPLES-REVIEWED] faa1c4c |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNothing blocks — the version gate itself is right, but the prose describing the derived spec's FINDING — src/kiro_crew/dashboard/side_readonly_spec.py:147 — FINDING — src/kiro_crew/dashboard/side_readonly_spec.py:171 — the docstring bullet FINDING — docs/system-specs/modules/side.md:289 — the owning spec still enumerates [OPUS-REVIEWED] faa1c4c |
|
Thank you for this fix, @leonlaiyc — the diagnosis that To run it through the full same-repo CI and review lanes, I opened an in-repo replacement that carries your commit (authored to you, with a Co-authored-by trailer): #16086. It is now green across CI and all review lanes. Closing this one in favour of it — all the credit is yours. |
Problem / Motivation
A side turn does not run under the user's own agent spec.
side_readonly_specderives
<agent>--readonlyfrom it with every backend-side grant emptied —allowedTools: [], noautoApprove, notoolsSettingsallowed*/trusted*,includeMcpJson: false, no lifecyclehooks, and the KAS policy rewritten toan empty one — and publishes it into
~/.kiro/agents/, the only directorykiro-cli loads selectable agents from. That is what makes every tool call raise
a permission request for the
READ_ONLYgate to judge, instead of beingapproved by the backend unattended.
The KAS half of that emptying never reached the shared version gate:
#12919 centralized that gate as
_write_derived_permissions, "the one versiongate every generated spec writer shares", and routed
agent.py's fivegenerated writers through it. This module is a sixth generated-spec writer by
every property that matters — deterministic name, regenerated from the base on
every side turn,
_atomic_json_writeinto the kiro agent registry, neverhand-edited — and it kept its own write.
kiro-cli validates agent specs with serde
deny_unknown_fields, and it is thekey's presence, not its value, that a release below
SPEC_PERMISSIONS_MIN_VERSION(2.23.0) refuses. The repository states thisdirectly: "
{"rules": []}… the key's mere PRESENCE is what makes KAS load thespec at all, so the empty policy is still a policy." So a base spec carrying a
permissionsblock, derived on a below-floor or unknown release, produced aderived file that release refuses whole.
Why it matters
The file that gets refused is the side turn's isolation boundary. Per the
repository's own account of this failure (#12919,
_write_derived_permissions),a release whose schema predates the field "refuses the WHOLE spec and falls
back to broader default grants" — which for this spec means falling back off
the very narrowing the module exists to apply.
handlers/side.pyis explicitthat a spec which cannot be produced fails closed (
ReadOnlySpecError, theturn is refused and "never runs under the base agent"); a spec that is produced
and then refused by the backend is outside that guarantee.
The trigger needs no exotic setup.
installed_kiro_cli_version()answers"unknown" whenever there is no pinned binary, or
--versionis refused, timesout or is unparseable, and its cache is keyed on the binary's path and mtime
so a
kiro-cli updatere-probes. The base spec need only carry apermissionsblock — an author's own KAS policy, or one written while an accepting release
was installed. The development box this was measured on has a real
kiro-cliat2.22.1, one minor below the floor, so the derivation was exercised against a
genuine below-floor binary rather than a stub.
What changed (motivation → approach → change)
Symptom → cause → change. The symptom is a derived read-only spec carrying
permissionson a CLI that refuses the file for it. The cause is a write thatpredates the shared gate. The change routes that one write through the gate:
On an accepting release it derives from the already-emptied
allowedTools,which is
{"rules": []}— byte-identical to what the line wrote. On a refusingor unknown one it removes the inherited value, the same withholding the five
sibling writers already do.
The
if "permissions" in specguard is kept deliberately. The gate decideswhether the field may be carried, not whether to add one. Because the key's
presence is what makes KAS load a spec at all, deriving a block for a base that
had none would change what the backend does with that agent — a widening this
change has no reason to make. Pinned by its own test on the accepting release,
where a gate that dropped the guard would write one.
Direction of the change is fail-safe. Withholding a KAS policy can only
remove backend-side auto-approvals from a spec whose whole purpose is to have
none; it cannot add a grant. Every other narrowing in the derivation
(
allowedTools: [],includeMcpJson: false) is unaffected and asserted onevery arm.
No sixth spelling of the version check, and no new layering edge: this
module already imports private names from
kiro_crew.agentfunction-locally onthis path (
_atomic_json_write,kiro_agents_dir_path).scripts/check_agent_sdk_boundary.pypasses with the diff in scope.Backwards compatibility
Compatible. On an accepting release the published file is unchanged:
derived_agent_permissions([], name)is{"rules": []}, exactly the literal theold line assigned, so the content digest — which
publish_readonly_specuses todecide whether to rewrite at all, and which
handlers/side.pybinds a livesession to — does not move. The
[accepts]arm passed before this change aswell as after.
What changes is only the below-floor and unknown cases, where the key is now
withheld instead of written. Nothing is rejected, renamed or removed: no new
required field, no stricter validator, no narrowed type, and no change to any
other derived key.
Tests
test/test_side_readonly_spec.py, asserting on the file as published to theagent registry — the bytes kiro-cli reads — rather than on the derivation in
isolation:
test_the_derived_spec_carries_a_kas_block_only_where_the_cli_accepts_it— parametrized over
accepts/refuses/unknown. A base carrying a KASblock is published through
publish_readonly_spec; the on-disk file mustcarry
{"rules": []}on an accepting release and no key on the other two.allowedTools == []andincludeMcpJson is Falseare asserted on all three,so a regression cannot trade one narrowing for another.
test_a_base_without_a_kas_block_never_gains_one— pins the guard, on theaccepting release where dropping it would show.
_pin_spec_permissions_cli+ an autouseacceptsfixture, the same helper andthe same rationale the five writers' suites already use: two pre-existing
assertions here (
derived["permissions"] == {"rules": []}andset(derived) == set(base) - {"hooks"}) would otherwise be decided by whateverbinary the test host happens to have.
RED on
2fdadc71a, before the production change:The
[accepts]arm and the guard test were green before the change too — theyare the regression guard, not the repro.
GREEN after:
test_side_readonly_spec.py+test_side.py— 40 passed;test_side.py,test_side_context.py,test_side_steer_queue.py— 68 passed.One unrelated failure is present in this module before and after the change
and was reproduced on a pristine checkout of
2fdadc71a:test_publish_never_overwrites_a_foreign_file_at_the_derived_pathraisesOSError: [WinError 1314]creating a symlink, because the Windows box it ran ondoes not hold
SeCreateSymbolicLinkPrivilege. It is environmental andunattributable to this diff.
Static gates on the committed diff:
black --check,isort --check-only,flake8,mypy --platform linux,git diff --check,scripts/check_black_formatting.pyandscripts/check_agent_sdk_boundary.py(both run after committing, so their
origin/main...HEADscope is the real twochanged files and not a vacuous zero).
Manual verification
N/A — unit coverage sufficient: the assertions read the published file itself,
under all three version verdicts the gate distinguishes, which is the artifact a
manual check would inspect.
Related Issues
Follow-up to #12919 (the shared gate and the five
agent.pywriters) and #12844(the gate itself). No issue filed.
Pattern harvest
Rule candidate:
review-promptPattern: a newly centralized runtime-version or capability gate is only central
once every mutation path is enumerated — a sibling writer that predates it
keeps its own write and silently defeats it. When a PR introduces a shared gate
and its own text says "every writer", grep the tree for other assignments to the
same field rather than only the writers that PR touched. A writer that assigns a
CONSTANT (here
{"rules": []}) rather than calling the derivation is the one acall-graph search misses.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code