Skip to content

fix(side): withhold the read-only spec's KAS block on a refusing kiro-cli - #16086

Merged
chenmingwei23 merged 1 commit into
mainfrom
side-readonly-perm-gate-13074
Oct 2, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
side-readonly-perm-gate-13074

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

In-repo replacement for #13074 by @leonlaiyc, opened to run the full same-repo CI and review lanes. Original commit kept authored to @leonlaiyc with a Co-authored-by trailer. The three goal sections below are the author's own.

Problem / Motivation

Goal: Stop a side turn's derived read-only agent spec from being refused whole by a kiro-cli below the spec-permissions floor, by routing its KAS block through the shared version gate.

A side turn does not run under the user's own agent spec. side_readonly_spec
derives <agent>--readonly from it with every backend-side grant emptied —
allowedTools: [], no autoApprove, no toolsSettings allowed*/trusted*,
includeMcpJson: false, no lifecycle hooks, and the KAS policy rewritten to
an empty one — and publishes it into ~/.kiro/agents/, the only directory
kiro-cli loads selectable agents from. That is what makes every tool call raise
a permission request for the READ_ONLY gate to judge, instead of being
approved by the backend unattended.

The KAS half of that emptying never reached the shared version gate:

if "permissions" in spec:
    spec["permissions"] = {"rules": []}     # <- no CLI version gate

#12919 centralized that gate as _write_derived_permissions, "the one version
gate every generated spec writer shares"
, and routed agent.py's five
generated 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_write into the kiro agent registry, never
hand-edited — and it kept its own write.

kiro-cli validates agent specs with serde deny_unknown_fields, and it is the
key's presence, not its value, that a release below
SPEC_PERMISSIONS_MIN_VERSION (2.23.0) refuses. The repository states this
directly: "{"rules": []} … the key's mere PRESENCE is what makes KAS load the
spec at all, so the empty policy is still a policy."
So a base spec carrying a
permissions block, derived on a below-floor or unknown release, produced a
derived 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.py is explicit
that a spec which cannot be produced fails closed (ReadOnlySpecError, the
turn 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 --version is refused, times
out or is unparseable, and its cache is keyed on the binary's path and mtime
so a kiro-cli update re-probes. The base spec need only carry a permissions
block — 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-cli at
2.22.1, one minor below the floor, so the derivation was exercised against a
genuine below-floor binary rather than a stub.

Not a goal

  • Not adding a KAS permissions block to a base spec that carries none — the if "permissions" in spec guard is kept so this change only gates an inherited value, never introduces one.
  • Not changing any other narrowing in the derivation (allowedTools: [], includeMcpJson: false, dropped hooks/autoApprove).
  • Not touching the shared gate _write_derived_permissions itself (fix(agent): gate generated spec permissions by CLI version #12919) or the five agent.py writers already routed through it.

What changed (motivation → approach → change)

Symptom → cause → change. The symptom is a derived read-only spec carrying
permissions on a CLI that refuses the file for it. The cause is a write that
predates the shared gate. The change routes that one write through the gate:

_write_derived_permissions(spec, spec["allowedTools"], derived_name)

On an accepting release it derives from the already-emptied allowedTools,
which is {"rules": []} — byte-identical to what the line wrote. On a refusing
or unknown one it removes the inherited value, the same withholding the five
sibling writers already do.

The if "permissions" in spec guard is kept deliberately. The gate decides
whether 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 on
every arm.

No sixth spelling of the version check, and no new layering edge: this
module already imports private names from kiro_crew.agent function-locally on
this path (_atomic_json_write, kiro_agents_dir_path).
scripts/check_agent_sdk_boundary.py passes 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 the
old line assigned, so the content digest — which publish_readonly_spec uses to
decide whether to rewrite at all, and which handlers/side.py binds a live
session to — does not move. The [accepts] arm passed before this change as
well 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 the
agent 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 KAS
    block is published through publish_readonly_spec; the on-disk file must
    carry {"rules": []} on an accepting release and no key on the other two.
    allowedTools == [] and includeMcpJson is False are 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 the
    accepting release where dropping it would show.
  • _pin_spec_permissions_cli + an autouse accepts fixture, the same helper and
    the same rationale the five writers' suites already use: two pre-existing
    assertions here (derived["permissions"] == {"rules": []} and
    set(derived) == set(base) - {"hooks"}) would otherwise be decided by whatever
    binary the test host happens to have.

RED on 2fdadc71a, before the production change:

FAILED test_the_derived_spec_carries_a_kas_block_only_where_the_cli_accepts_it[refuses]
        AssertionError: a refuses CLI must get no block
FAILED test_the_derived_spec_carries_a_kas_block_only_where_the_cli_accepts_it[unknown]
        AssertionError: a unknown CLI must get no block

The [accepts] arm and the guard test were green before the change too — they
are 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_path raises
OSError: [WinError 1314] creating a symlink, because the Windows box it ran on
does not hold SeCreateSymbolicLinkPrivilege. It is environmental and
unattributable 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.py and scripts/check_agent_sdk_boundary.py
(both run after committing, so their origin/main...HEAD scope is the real two
changed 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.

Screenshots / video

Why no screenshot: this is a pure backend change to src/kiro_crew/dashboard/side_readonly_spec.py (how the derived read-only agent spec is written to ~/.kiro/agents/) and its unit tests. It touches no user-visible frontend surface, so there is no rendered delta to capture.

Related Issues

Supersedes #13074 (original author @leonlaiyc). Follow-up to #12919 (the shared
gate and the five agent.py writers) and #12844 (the gate itself).

Pattern harvest

Rule candidate: review-prompt
Pattern: 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 a
call-graph search misses.

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

@iamwhatever
iamwhatever requested a review from a team as a code owner October 2, 2026 06:52
@iamwhatever iamwhatever self-assigned this Oct 2, 2026
@iamwhatever iamwhatever added the drive-to-green PR claimed by drive-to-green pipeline label Oct 2, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 47b1bba4296f195fa4acc9e61d640dd173af21b9 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/dashboard/side_readonly_spec.py:314 -- function-local from kiro_crew.agent import ... omits the required circular-import explanation -> Fix: add a # circular import comment naming the cycle.
[GPT-REVIEWED] 47b1bba

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

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The documented contract wasn't moved with the behavior: two in-repo descriptions still promise the KAS key is "emptied, not dropped," which the refusing/unknown arms now violate.

Watch

Doc-behavior drift on the isolation contract. derive_readonly_spec's own docstring (src/kiro_crew/dashboard/side_readonly_spec.py:251-253, three lines above the changed hunk) says "the key's presence is what makes KAS load the file, so it is emptied, not dropped", and docs/system-specs/modules/side.md:291 lists "an empty KAS permissions" as a derivation invariant — but the diff makes "dropped" the behavior on a below-floor or unknown release. AGENTS.md requires the owning spec to move in the same commit; a future reader of either text will reason that the derived file always carries the block (e.g., when debugging why KAS didn't load a spec) and be wrong on exactly the arms this PR adds.
Clears when: the derive_readonly_spec docstring bullet and side.md's emptied-grants list state the version-gated withholding, in this PR.

Suggestions

The description was truncated mid-"Tests" section at the 8000-byte capture limit — confirm the GREEN run line survived intact in the live PR body so the gate record is complete.

[DESIGN-REVIEWED] 47b1bba

Description read

[DESCRIPTION-READ] 8cf60d78c46b91ea69109ced6eb17091cf8d272bcaee9d92b8a7fcc011fa8344

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

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 47b1bba4296f195fa4acc9e61d640dd173af21b9 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

derive_readonly_spec's own docstring (side_readonly_spec.py:251-253) still says the block "is emptied, not dropped" — now true only on an accepting release.

What this change ships

Inventory (3 items) — 3 justified

Intent: FIX — stop a below-floor or unknown kiro-cli from refusing the side turn's derived read-only spec whole, by routing its one ungated KAS permissions write through the shared version gate.

  1. On a below-floor or unknown kiro-cli, the published read-only spec now omits the permissions key instead of carrying one the CLI refuses the whole file for — justified
  2. On an accepting release the published file is byte-identical to before (verified: allowed_tools_to_permissions([]) returns None, so the gate writes {"rules": []}, the old literal) — justified
  3. Pre-existing tests in this file now run under a pinned "accepts" CLI instead of the host's real binary — justified

Evidence checked: the gate pops an inherited key on refusing/unknown and rewrites on accepting (auto_approve.py:97-105), matching the five existing callers; grepped \["permissions"\] = across src/ — 10 hits, zero unfixed sibling spec-registry writers (the others are session state, wire projections, and app manifests); tests added RED-on-base per the quoted failures; no new config key, flag, or public surface.

[FIRST-PRINCIPLES-REVIEWED] 47b1bba

Description read

[DESCRIPTION-READ] 9faf45643f8e6bd79d10a22fbf78501405fe5b6a7bbebeaf9fddba8bfc45c7a7

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

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 47b1bba4296f195fa4acc9e61d640dd173af21b9 — this comment is updated in place on each push.

Review details

The gated withhold is correct; the prose that documents it — the function's own docstring and the owning spec — still states the old unconditional behaviour.

FINDING — src/kiro_crew/dashboard/side_readonly_spec.py:251 — derive_readonly_spec's docstring still promises permissions → {"rules": []} … "so it is emptied, not dropped" and "Pure: no I/O, no logging", while the added _write_derived_permissions(spec, spec["allowedTools"], derived_name) four lines below pops the key on a refusing/unknown kiro-cli and reaches installed_kiro_cli_version() → pin_kiro_cli() (home-directory stat walk) → subprocess.run([binary, "--version"], timeout=5) — two contradictions in one contract block, and the stale purity claim is what would let a future caller run the derive inline on the event loop → Fix: restate the permissions bullet as "emptied on a kiro-cli at or above SPEC_PERMISSIONS_MIN_VERSION, withheld on an older or unestablished one, never added to a base that had none", and replace "Pure: no I/O, no logging" with the blocking probe and the off-loop requirement publish_readonly_spec already states.

FINDING — docs/system-specs/modules/side.md:291 — the owning spec still describes the derived spec as carrying "an empty KAS permissions" unconditionally, and src/kiro_crew/docs/agent-spec-fields.md:387 still enumerates the gate's users as "Generated conductor and worker writers", omitting this third one, so the next author reading either doc will not know this writer is version-gated → Fix: in this commit, amend side.md's derived-spec sentence to say the KAS block is emptied only where the installed kiro-cli accepts the field and withheld otherwise, and add the side read-only writer to the permissions row in agent-spec-fields.md.

[OPUS-REVIEWED] 47b1bba

Verdict parsed from the review's SHA-scoped output markers for commit 47b1bba4296f195fa4acc9e61d640dd173af21b9.

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

…-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 #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>

Co-authored-by: iamwhatever <12429733+iamwhatever@users.noreply.github.com>
@iamwhatever
iamwhatever force-pushed the side-readonly-perm-gate-13074 branch from 182993e to 47b1bba Compare October 2, 2026 07:09
@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 2, 2026
@chenmingwei23
chenmingwei23 merged commit 6dd51f3 into main Oct 2, 2026
99 of 105 checks passed
@chenmingwei23
chenmingwei23 deleted the side-readonly-perm-gate-13074 branch October 2, 2026 15:56
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 2026
@cruisercohen cruisercohen removed the drive-to-green PR claimed by drive-to-green pipeline label Oct 2, 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.

4 participants