Skip to content

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

Closed
leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/deep10-side-readonly-perm-gate-20260923
Closed

leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/deep10-side-readonly-perm-gate-20260923

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

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.

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.

Related Issues

Follow-up to #12919 (the shared gate and the five agent.py writers) and #12844
(the gate itself). No issue filed.

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

🤖 Generated with Claude Code

…-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>
@leonlaiyc
leonlaiyc requested review from a team and Zedmor September 23, 2026 12:54
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed faa1c4cfe924a4435447b2ce2cab90e823ed1ea3 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] faa1c4c

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of faa1c4cfe924a4435447b2ce2cab90e823ed1ea3 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 derive_readonly_spec is no longer pure.

Watch

The diff makes derive_readonly_spec version-dependent and I/O-bearing (installed_kiro_cli_version() spawns kiro-cli --version on cache miss), but its docstring still reads "Pure: no I/O, no logging" and lists permissions → {"rules": []} unconditionally (src/kiro_crew/dashboard/side_readonly_spec.py:145, :171), and the owning spec docs/system-specs/modules/side.md:289 still states the derived spec carries "an empty KAS permissions". AGENTS.md requires the owning spec updated in the same commit; a future caller trusting the purity claim (e.g. invoking the derive on the event loop or in a test without pinning) inherits a subprocess probe and a host-dependent digest.
Clears when: the same commit updates the derive_readonly_spec docstring (purity claim + permissions bullet) and side.md's guarantee paragraph to say the KAS block is carried only on an accepting kiro-cli.

[DESIGN-REVIEWED] faa1c4c

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of faa1c4cfe924a4435447b2ce2cab90e823ed1ea3 via the fork AI-review pipeline — 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

Verify _align_permissions (src/kiro_crew/agent_capabilities.py:396) — the one remaining ungated permissions write — truly only re-derives a block the base already carried.

I grepped ["permissions"] = across src/ (12 hits): five are the gated writers in agent.py, this module was the sixth generated writer, kas_agents.py:718 is a wire projection not an on-disk spec, and agent_capabilities.py:396 never introduces the key to a spec that lacked it — so no unfixed sibling of the root cause. The fix reuses the existing gate rather than adding a sixth version check, sits at cause level (the write predating the shared gate), and its RED-on-base claim is readable from the diff: base writes the key unconditionally, so both non-accepting arms fail. The accepting arm is byte-identical by derived_agent_permissions's own contract ({"rules": []} when nothing qualifies), so the published digest does not move.

What this change ships

Inventory (3 items) — 3 justified

Intent: keep the side turn's read-only isolation spec loadable on a kiro-cli that refuses the permissions key — a FIX.

  1. On a below-floor or unknown kiro-cli, the published read-only spec omits permissions instead of carrying {"rules": []} — justified
  2. On an accepting release the published file is byte-identical, so bound sessions and digests are unmoved — justified
  3. This suite's existing tests are now pinned to an accepting CLI instead of the host's — justified

[FIRST-PRINCIPLES-REVIEWED] faa1c4c

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed faa1c4cfe924a4435447b2ce2cab90e823ed1ea3 via the fork AI-review pipeline; updated in place on each push.

Review details

Nothing blocks — the version gate itself is right, but the prose describing the derived spec's permissions was left behind in three places.

FINDING — src/kiro_crew/dashboard/side_readonly_spec.py:147 — Pure: no I/O, no logging. is now false: the added _write_derived_permissions call reaches installed_kiro_cli_version() → pin_kiro_cli() ("Sync and unbounded: it stats directories under the home directory", kiro_cli.py:465) → subprocess.run([binary, "--version"], timeout=5), so the one sentence a future caller would rely on to invoke this inline on the event loop now guarantees the opposite → Fix: replace the purity sentence with "consults the installed kiro-cli version (home-directory stat + one bounded --version spawn, cached per binary identity), so call it off the event loop".

FINDING — src/kiro_crew/dashboard/side_readonly_spec.py:171 — the docstring bullet permissions → {"rules": []} … so it is emptied, not dropped contradicts the code it documents: on a kiro-cli below SPEC_PERMISSIONS_MIN_VERSION, or one whose version cannot be established (no pin, refused spawn, 5 s timeout, unparseable --version), _write_derived_permissions does config.pop("permissions", None) — dropped, not emptied → Fix: state the conditional in the bullet (emptied at or above the floor, withheld on a refusing or unestablished release, never added to a base that carries none).

FINDING — docs/system-specs/modules/side.md:289 — the owning spec still enumerates an empty KAS permissions as an unconditional property of every derived spec, and dashboard/handlers/side.py:485 repeats it as an empty KAS policy, both now false on exactly the hosts this change exists for → Fix: replace both with the version-gated statement; the remedy lands in files this diff does not touch.

[OPUS-REVIEWED] faa1c4c

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this fix, @leonlaiyc — the diagnosis that side_readonly_spec is a sixth generated-spec writer that never reached the shared _write_derived_permissions gate, and that it is the KAS key's presence (not its value) a below-floor kiro-cli refuses, is exactly right.

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.

@iamwhatever iamwhatever closed this Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants