Repository navigation
feat(side-chat): auto-approve read-only tools and add /btw alias - #9609
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Sound gate-plus-spec design, but the read-only guarantee rests on a field-by-field denylist of kiro-cli's grant surfaces with no tripwire for new ones. WatchThe spec derivation empties an enumerated set of top-level grant fields ( Suggestions
[DESIGN-REVIEWED] b25d1cf |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of All evidence gathered. The counts I ran: First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: let a Side Chat question be answered from real files/pages instead of memory, without letting it change anything — an ADDITION (plus a footer-jargon fix, #8964).
(A few smaller items — screenshots per the temp-screenshots/ workflow convention, doc updates — omitted at the 10-item cap; all justified.) Watch
Subtractions
[FIRST-PRINCIPLES-REVIEWED] b25d1cf |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS The shipped states read well — the blind reader got both Evidence gaps
[UX-REVIEWED] b25d1cf |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsI've validated the candidate list (empty) and independently examined the core security logic: the The grant-emptying in No findings. [OPUS-REVIEWED] b25d1cf Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ human override acceptedHuman judgment by @pepmach overrides the GPT 5.6 finding for This comment is updated in place on each push. The model was not re-run because an authorized human decision supersedes it. False positive or not applicable? A repository writer can comment: |
1a5fc60 to
7ac94c5
Compare
7ac94c5 to
f6bde6c
Compare
f6bde6c to
6ca72e1
Compare
6ca72e1 to
4d84a97
Compare
|
self-added: no
|
a18b48b to
ec1a3ae
Compare
|
/ai-review override gpt ec1a3ae: four residuals, none a new exposure this PR opens. The shadow-spec race (side_readonly_spec.py) and git under READ_ONLY (side.py) both require a same-UID local writer -- one that can already write the checkout's .kiro/agents or the user's own .git/config and can therefore shadow the base agent itself under kiro-cli project-agent precedence; the shadow check refuses every static shadow spec and side.md records both. web_fetch/web_search stay in the side-chat read-only set by maintainer decision: the shipped default agent spec already auto-approves both in the main chat, so side chat adds no egress surface, and side.md records the tradeoff and its mitigations. Operator PreToolUse script hooks fire on every stream_and_collect surface today (main chat, cron, heartbeat) and are the operator's own instrumentation, unchanged by this PR. Non-kiro backends fail closed (ACP_BACKENDS_SIDE_READONLY) and the feature map is updated in this head. |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
|
/ai-review override gpt a224d9d: four residuals, none a new exposure this PR opens. The shadow-spec race (side_readonly_spec.py) and git under READ_ONLY (side.py) both require a same-UID local writer -- one that can already write the checkout's .kiro/agents or the user's own .git/config and can therefore shadow the base agent itself under kiro-cli project-agent precedence; the shadow check refuses every static shadow spec and side.md records both. web_fetch/web_search stay in the side-chat read-only set by maintainer decision: the shipped default agent spec already auto-approves both in the main chat, so side chat adds no egress surface, and side.md records the tradeoff and its mitigations. Operator PreToolUse script hooks fire on every stream_and_collect surface today (main chat, cron, heartbeat) and are the operator's own instrumentation, unchanged by this PR. Non-kiro backends fail closed (ACP_BACKENDS_SIDE_READONLY) and the feature map is updated in this head. |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
|
/ai-review override gpt a224d9d: four residuals, none a new exposure this PR opens. The shadow-spec race (side_readonly_spec.py) and git under READ_ONLY (side.py) both require a same-UID local writer -- one that can already write the checkout's .kiro/agents or the user's own .git/config and can therefore shadow the base agent itself under kiro-cli project-agent precedence; the shadow check refuses every static shadow spec and side.md records both. web_fetch/web_search stay in the side-chat read-only set by maintainer decision: the shipped default agent spec already auto-approves both in the main chat, so side chat adds no egress surface, and side.md records the tradeoff and its mitigations. Operator PreToolUse script hooks fire on every stream_and_collect surface today (main chat, cron, heartbeat) and are the operator's own instrumentation, unchanged by this PR. Non-kiro backends fail closed (ACP_BACKENDS_SIDE_READONLY) and the feature map is updated in this head. |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
|
/ai-review override gpt a224d9d: four residuals, none new to this PR. The shadow-spec race and git under READ_ONLY both need a same-UID local writer who can already shadow the base agent itself; side.md records both. web_fetch/web_search stay by maintainer decision: the shipped default agent already auto-approves them in the main chat, so no new egress. Operator PreToolUse hooks already fire on every stream_and_collect surface. Non-kiro backends fail closed. |
Human judgment recorded@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
/ai-review override gpt 7040886: four residuals, none new to this PR. The shadow-spec race and git under READ_ONLY both need a same-UID local writer who can already shadow the base agent itself; side.md records both. web_fetch/web_search stay by maintainer decision: the shipped default agent already auto-approves them in the main chat, so no new egress. Operator PreToolUse hooks already fire on every stream_and_collect surface. Non-kiro backends fail closed. |
Human judgment recorded@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
chenmingwei23
left a comment
There was a problem hiding this comment.
[code-review-sage] Deep review -- read-only side-chat tool gate + /btw alias
Assessment: LGTM with one non-blocking note. This is a security-boundary widening and the design holds up: the gate is deny-by-default and fails closed, the auto-approve allowlist maps only to read scopes, and the derived agent spec closes the backend pre-approval bypass that a stricter gate alone would miss. Nothing here blocks the merge. One pre-existing exposure is newly reachable on this surface, surfaced below as should-fix, not a blocker.
I traced the widening end to end and verified the load-bearing claims against real code rather than the description:
- The auto-approve set is genuinely read-only.
_HOST_READ_ONLY_BUILTIN_TOOLS = {fs_read, glob, grep, web_fetch, web_search}: every entry maps inplatform/governance.py:BUILTIN_TOOL_SCOPEStofilesystem.readornetwork.egressonly; the write/exec built-ins (code,fs_write,execute_bash) map tofilesystem.write/commandsand are absent.test_host_read_only_builtins_map_only_to_read_scopespins this so a write-capable built-in cannot join by mistake. - The allowlist cannot be widened by untrusted input. Under
classifier_only(READ_ONLY), proof requiresmcp_identity_trustedprovenance + a host-stamped_meta.kiro.toolName+ nomcp_server_name. The agent-influencedkindand the model-authored title can only narrow (a non-read kind refuses), never prove. An MCP-served tool carries no host-trusted read-only marker, so it is never auto-approved. Shell proof goes throughis_read_only_bash, which is deny-by-default (allowlisted verbs, rejects redirects/substitution/backgrounding, checks each pipe segment's side effects, and even defeats the$IFSargv-split evasion). - No credential/write tool can reach the auto-approve path through the gate. The deny floor, sensitive-path keystone (reads included: the
is_sensitive_path(target)branch exists precisely to block~/.aws/credentialsreads), and governance all run BEFORE the grant/classifier tiers and are unaffected byclassifier_only. The classifier auto-approve is the last branch beforeallow(). - The spec derivation closes the real bypass.
derive_readonly_specemptiesallowedTools, per-serverautoApprove,toolsSettings.{allowed,trusted,auto}*(prefix-matched so a new kiro-cli grant fails closed),includeMcpJson,autoAllowReadonly, KASpermissions, and strips lifecyclehooks: the backend-side pre-approvals that would otherwise run unattended without ever reaching the gate. Publication fails closed on a shadowing name, a foreign file, or a symlink at the derived path, and a project-scope base gets a per-source name so two checkouts never contend. - The harness gate is positive membership.
ACP_BACKENDS_SIDE_READONLY = {kiro}; every other backend runs the pre-allowanceREJECT_ALLposture. This is correct: claude-agent-acp'spermissions.allow/bypassPermissionsis a pre-approval surface neither the derived spec nor the host gate can see, so a call it pre-approved would execute with no READ_ONLY decision and no SEL row.
Findings
should-fix (yellow) -- native fs_read bypasses the sensitive-path deny floor, and this surface newly exposes that to unattended, injectable reads
src/kiro_crew/dashboard/handlers/side.py (_run_side_turn, the tools_available branch) and docs/system-specs/modules/side.md:311:
kiro-cli trusts `fs_read` natively ... a native read runs outside the gate,
and the guarantee holds because it is a read.
- Trigger, mechanism, consequence. kiro-cli runs
fs_readnatively (confirmed in the PR's own live-pod observation:fs_readproduced no permission request and no host decision row, even under the derived spec withallowedTools: []). Because the call never reachesHookManager.on_tool_call, it never hits the sensitive-path deny floor that the same module builds to block credential reads (is_sensitive_path(target); its comment names~/.aws/credentialsexplicitly). So a side turn canfs_read ~/.aws/credentialsor~/.ssh/id_rsaand get the contents back into the side transcript, with no card and no SEL row. The side prompt is assembled from parent context (_format_parent_snapshot), which can contain untrusted material (web-fetched pages, file contents), so an instruction injected there can drive this read on an unattended surface. - Pre-existing vs introduced. The native-
fs_readbypass of the sensitive-path floor is a property of kiro-cli's native trust and holds identically in the main chat today, so it is NOT introduced by this PR and is not chargeable as a regression. What this PR newly does is enablefs_readon an unattended, no-card surface whose prompt includes injectable context, which raises the reachability of the pre-existing gap (silent, model-driven, no SEL row) even though the underlying bypass is not new. - Suggestion. Either (a) note this specific case in
side.mdalongside thegit/concurrent-writer residuals: that nativefs_readreads sensitive paths outside the gate on the side surface, so the credential-read floor does not cover it and the SEL trail has a hole there, making the accepted residual explicit rather than folded into "the guarantee holds because it is a read"; or (b) if the sensitive-path floor is meant to be load-bearing for reads on this surface, route side-turnfs_readthrough a host check (the residual otherwise silently defeats a floor the rest of the system relies on). (a) is proportionate given it is pre-existing and same-UID; the point is that "it is a read" understates it, because the system elsewhere treats credential reads as protected.
Other dimensions
- Concurrency/races: the generation-keyed session (
side:<slot>:<gen>), the re-checks ofslot._side is side_at_startafter each await (derivation, rebind-destroy, acquisition), and the binding-mismatch cold-start are consistent and close the close+reopen and project-change-mid-turn races. The publish TOCTOU (shadow/foreign check then atomic write) requires an operator-UID writer into~/.kiro/agentsand is the same class already documented as an accepted same-UID residual, not chargeable here. - Error handling:
ReadOnlySpecErroris terminal per turn, never falls back to the base agent, leaves a SEL denied row, and shows a user-facing panel message. Correct fail-closed shape. - Tests: the new suites cover the gate matrix (read-only shell approved,
touchrejected as policy, host-known built-in approved only with trusted provenance,kind="read"alone / read title alone / MCP tool / no-hooks all rejected, grants approve nothing under READ_ONLY), the spec derivation (emptied grants, shadow/foreign/symlink refusals, per-source naming, fail-closed), and the session lifecycle races. Coverage matches the behavior that changed. - /btw alias:
SIDE_REmatching both spellings andSlashCommandMenukeying/btwon/side's description key so they cannot drift is a clean, low-risk change.
ship_summary: no blocking issues; one should-fix -- native fs_read reads sensitive paths outside the gate on the side surface (pre-existing bypass, newly reachable unattended), document or gate it.
Side chat ran every turn under REJECT_ALL, so even lookups were refused.
This ports the Reads approval mode's semantics into the side-chat pipe as
ToolApprovalPolicy.READ_ONLY: the deny floor runs first, then the hook
gate's existing classifiers (is_read_only_bash for shell, the {read,
fetch} ACP-kind allowlist otherwise, name-grant verification on every
auto-approve) — and where the interactive Reads mode falls back to the
approval card, this policy rejects, because side chat has no card.
The side session runs under a derived read-only agent spec,
<agent>--readonly: the resolved agent's spec with every backend-side
grant emptied (allowedTools: [], no mcpServers.*.autoApprove, no
toolsSettings.*.allowed*, an empty KAS permissions policy, an empty
hooks.auto_approve_tools) and everything else kept. kiro-cli approves a
granted tool itself and raises no permission request, so under the
parent's own spec the gate would never see the user's main-chat grants —
the shipped kirocrew spec pre-authorizes @kirocrew-cron/cron_remove_all
and @kirocrew-core wholesale. dashboard/side_readonly_spec derives the
spec from the live base (project scope first, as kiro-cli resolves
--agent), publishes it atomically into ~/.kiro/agents — the only place
kiro-cli loads agents from besides the user's checkout — only when the
content changed, off the event loop, and the turn is refused with a coded
error when derivation fails; it never runs under the base agent.
The gate is asked with the canonical, non-model-authored MCP identity
(mcp_server_name / tool_name from _meta.kiro) alongside the title, as the
main-chat path does. A governance ceiling or auto_deny_tools rule written
against a per-MCP-tool identity matches only those fields, so a tool the
ceiling forbids would otherwise classify read-only behind benign
model-authored prose and auto-approve on a turn that has no approver.
Only the classifier's verdict approves under READ_ONLY. The gate reaches
TOOL_AUTO_APPROVE by two kinds of route: the read-only classifier, a
statement about what the call can do, and the grants — the operator's
auto_approve_tools globs (title- or identity-keyed) and the app-own-server
rule — which vouch for the caller and say nothing about the call's effect.
Under HOOK_BASED the two are interchangeable because either only skips the
approval card; under READ_ONLY an honoured grant executes a mutating tool
with no approver behind it (auto_approve_tools=["Write*"] approving a
Write in the side chat). So HookManager.on_tool_call takes
classifier_only, which skips exactly the grant tiers — the classifier
still judges a call a grant would have shadowed, so a broad grant costs no
read — and the classifier's verdict carries ToolHookResult.read_only;
READ_ONLY rejects any auto-approve without the tag, so a gate that does
not carry it fails closed. HOOK_BASED and every other policy are
unchanged. docs/system-specs/modules/side.md records the contract.
The side turn consults the gateway's one live hook gate
(state.context_builder.hooks), the object the main chat consults and
Settings > Security hot-reloads, so a deny added mid-turn binds an
in-flight side turn and no per-turn manager re-reads the keystone file on
the event loop; with no context builder the turn passes no gate and
READ_ONLY rejects everything. SIDE_BOUNDARY_PROMPT tells the model the
same boundary the policy enforces, in the footer's words.
Whether a side turn may execute read-only tools at all is a harness
capability, ACP_BACKENDS_SIDE_READONLY (kiro-cli only): the derived spec
is a kiro-cli agent-spec mechanism, and another harness has its own
pre-approval surface (claude-agent-acp permissions.allow /
bypassPermissions) the gate cannot see. Off the set, or with the harness
unknown, the turn keeps the pre-allowance posture — the base agent under
REJECT_ALL — and the prompt, fallback and footer say tools are
unavailable there.
The derived name must resolve to the generated file and nothing else:
publication refuses a project-scope or second user-scope spec that
declares it and never overwrites a file without the owner marker; a
project-scope base derives <agent>--readonly-<8 hex of the project path>
so two checkouts never share a file. Each sidecar generation owns its
ACP session (side:<slot>:<gen>) and records the (agent, cwd, spec
digest) binding it was created under; a changed binding, or a live
session no binding vouches for, is destroyed and cold-started, and a turn
whose sidecar was replaced during derivation touches no session.
/btw becomes a pure client-side alias of /side: same SIDE_RE capture,
same interception, offered by the slash menu as a frontend command
sharing /side's description key so locale catalogs stay untouched.
A side turn is a dashboard-surface turn for governance. sel._infer_source
classifies side:* keys as the dashboard surface, so a dashboard-bound
governance profile binds a side turn exactly as it binds the parent slot
(governance_profiles.resolve_active_scope resolves the dashboard binding,
never the slack fallback), while the ACP session and SEL rows stay keyed
to the side session.
Under classifier_only, read-only must follow from host-trusted facts
alone: the recovered shell command judged by is_read_only_bash, or a
built-in the host knows to be read-only, named by the non-model-authored
tool name with no MCP server behind it (_HOST_READ_ONLY_BUILTIN_TOOLS).
The agent-influenced ACP kind and the title may narrow but never prove,
so a mutating tool labelled kind="read" is refused, and an MCP-served
tool, which carries no host-trusted read-only marker, is not provable.
The interactive path keeps its ACP-kind allow-list and title fallback.
The black baseline prunes three entries the touched files graduated.
|
/ai-review override gpt b25d1cf: four residuals, none new to this PR. The shadow-spec race and git under READ_ONLY both need a same-UID local writer who can already shadow the base agent itself; side.md records both. web_fetch/web_search stay by maintainer decision: the shipped default agent already auto-approves them in the main chat, so no new egress. Operator PreToolUse hooks already fire on every stream_and_collect surface. Non-kiro backends fail closed. |
Human judgment recorded@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
Problem / Motivation
Side Chat cannot look anything up. Every tool call on a side turn is refused (
REJECT_ALL), so "what does this function do?" is answered from memory, not from the file. There is no short alias for/side. The composer footer reads "Tools and MCPs are unavailable here", and "MCPs" is a word a first-time user does not know (#8964).Why it matters
A side answer that cannot read a file or fetch a page is a guess. People open Side Chat for a quick fact while the main turn is busy; a guess there costs a wrong answer or a second trip to the main chat. A footer in jargon does not tell them what the panel can do.
What changed (motivation → approach → change)
Bash moves from
REJECT_ALLto bounded unattended execution in Side Chat, and the side session runs under a derived read-only agent spec so nothing can bypass that bound. A shell call runs with no approver only whenis_read_only_bashaccepts it under the deny-by-default prefix allowlist (ls,cat,grep,git statusand the rest of that table; no redirects, no substitution, no backgrounding). Every other shell call is rejected. The policy isToolApprovalPolicy.READ_ONLYinllm_helpers.py: the dashboard "Reads" mode's classifier, with reject where Reads would show a card. The always-on deny floor runs first. Then the sameHookManager.on_tool_callgate Reads uses runs, askedclassifier_only: the grant tiers — the operator'sauto_approve_toolsglobs, title- or identity-keyed, and the app-own-server rule — are skipped, because they vouch for the caller and say nothing about what the call does, and only an auto-approve taggedToolHookResult.read_onlycounts. A non-shell call is proven read-only by one fact: the host-stamped_meta.kiro.toolNamenames a built-in in_HOST_READ_ONLY_BUILTIN_TOOLS(fs_read,glob,grep,web_fetch,web_search), with no MCP server behind it and with themcp_identity_trustedprovenance flag set. The ACPkindand the title can narrow the verdict but never produce it.READ_ONLYwith no hook manager rejects everything (read_only_policy_no_hooks).flowchart LR subgraph Before A1["side turn asks to run a tool"]:::ctx --> B1["REJECT_ALL"]:::removed --> C1["refused"]:::ctx end subgraph After A0["kiro-cli session bound to agent--readonly: allowedTools empty"]:::added --> A2["each call kiro-cli does not trust natively raises a permission request"]:::added A2 --> B2["READ_ONLY gate: deny floor, governance, read-only classifier"]:::added B2 -->|"read-only shell, or a host-known read built-in"| C2["runs, no card"]:::added B2 -->|"anything else"| D2["refused"]:::ctx end classDef added fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px classDef changed fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px classDef removed fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-dasharray:4 3 classDef ctx fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E linkStyle 0,1 stroke:#DC2626,stroke-dasharray:4 3 linkStyle 2,3,4 stroke:#16A34A,stroke-width:2px🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged
A side turn's tool call goes through the gate the Reads mode uses; a proven read runs with no card, everything else is refused, and nothing is pre-approved behind the gate's back.
The allowance is a capability of the harness, granted by positive membership.
ACP_BACKENDS_SIDE_READONLY(agent_sdk/backends.py) names kiro-cli alone: the derived spec is a kiro-cli agent-spec mechanism, and another harness has its own pre-approval surface (claude-agent-acppermissions.allow/bypassPermissions) that neither the spec nor the gate can see, so a call it pre-approved would run with noREAD_ONLYdecision and no SEL row. Off the set — or with the harness unknown because the config never loaded — a side turn runs the base agent underREJECT_ALL, the boundary prompt says tools are unavailable there, and the footer reads "Context only · Tools are unavailable here on this agent backend. Use the main chat to take action." (SideChat.tsxreads the selected harness through thekirocrewConfigquery, claims the allowance only from a loaded config, and renders a failed load throughErrorNotice— "Couldn't load the agent configuration, so Side Chat runs without tools. Use the main chat to take action." — instead of a capability claim).The derived spec is what makes "changes don't work here" true on kiro-cli. kiro-cli approves a tool on the agent's
allowedToolsitself and never raises a permission request, so under the parent agent's own spec the gate would never see the user's main-chat grants — the shippedkirocrewspec pre-authorizes@kirocrew-cron/cron_remove_alland@kirocrew-corewholesale._run_side_turn(dashboard/handlers/side.py) therefore binds the side session to<agent>--readonly: the resolved agent's spec with every backend-side grant emptied (allowedTools: [], nomcpServers.*.autoApprove, notoolsSettings.*.allowed*/trusted*/auto*—subagent.trustedAgentsandshell.autoAllowReadonlyincluded —includeMcpJson: false,autoAllowReadonly: false, an empty KASpermissionspolicy) and the lifecyclehooksremoved (shell commands the backend runs unprompted; the host's SEL audit records every side-turn decision), with everything else kept —tools,mcpServers,resources, prompt, model — so reads still work, through the gate. Every call kiro-cli does not trust natively then raises a permission request the gate judges; kiro-cli trustsfs_readnatively and runs it with no host decision, which the guarantee tolerates because it is a read.dashboard/side_readonly_spec.pyderives the spec from the live base spec on every turn (project scope first, the way kiro-cli resolves--agent), off the event loop, and publishes~/.kiro/agents/<agent>--readonly.jsonatomically, only when the content changed; a project-scope base is named after its source (<agent>--readonly-<8 hex of the project path>) so two checkouts declaring the same agent never contend for one file. It lives in the user-level kiro agent registry because kiro-cli loads agents from nowhere else besides the user's own checkout, which Kiro Crew does not write into; it is a runtime resource, regenerated when the base changes and never hand-edited. Itsdescriptioncarries an owner marker, and the name must resolve to that file alone: publication refuses a project-scope or second user-scope spec that declares the derived name (kiro-cli would load it first) and refuses to overwrite a file or symlink at the derived path without the marker. Fail closed: a turn whose spec cannot be derived or published is refused — the panel shows "Side Chat couldn't start. Try again, or use the main chat.", the log line and a SELchat.side_turndenied row carry the code (ReadOnlySpecError:unsafe_name,base_spec_missing,base_spec_unreadable,derived_name_shadowed,derived_path_foreign,spec_write_failed) — and it never runs under the base agent.Each sidecar owns its session. The side session key is
side:<slot>:<gen>,genbeing the sidecar's generation (SideState.gen), so a panel closed and reopened while a turn is still deriving its spec leaves that turn nothing to touch: it drops out before any session call, and close destroys only the closing generation's key.SideState.bindingrecords the(derived agent, cwd, spec digest)the live session was created under; a turn whose binding differs — the slot's agent or project changed, or the base spec changed — destroys the session first and cold-starts under the current derived spec, because kiro-cli read the spec at spawn. A close landing during that destroy ends the turn before it acquires anything, and one landing duringget_or_createhas the turn destroy the session it was handed, since no sidecar owns it. The turn reads the slot's project and agent once, before its first await, so the shadow scan, the spawncwd(where kiro-cli resolves--agentfirst) and the recorded binding all name one project; a project change mid-turn is picked up by the next turn's binding. The full envelope (instructions, parent snapshot, side history, boundary prompt) goes to any sessionget_or_createreports as new and not resumed — the sidecar's first turn, a rebind, an eviction after the provider died — so a fresh process is never handed a bare question; a live session gets the bare follow-up.The gate the turn consults is the gateway's one live
HookManager,state.context_builder.hooks— the manager the main chat consults and the one Settings > Security hot-reloads — so opt-outs and deny patterns apply to side turns and a deny added mid-turn binds an in-flight side turn; a host with no context builder passes no gate, andREAD_ONLYthen rejects every tool call. The gate is called with the side session's own identity:side:<slot>:<gen>classifies as thedashboardsurface insel._infer_source, so a dashboard-bound governance profile binds a side turn exactly as it binds the parent slot, while SEL rows and the ACP session stay keyed to the side session.HOOK_BASEDcallers ofstream_and_collect(cron, heartbeat, autonudge, Meetings) are unchanged:_resolve_permissionhands the gate the same trusted_meta.kiroidentity for both policies, and the oneREAD_ONLY-specific input isclassifier_only.ToolHookResultcarriesread_onlybesideidentity_grant; the two flags answer different questions (what the call does; who vouched for it) andREAD_ONLYreads only the first.Two residuals are recorded in
docs/system-specs/modules/side.mdas accepted, both requiring a writer already running as the operator's own UID: a concurrent write into<project>/.kiro/agentsbetween the shadow check and kiro-cli's spawn (the same writer can already shadow the base agent under kiro-cli's project-agent precedence, so the surface opens no new class), andgitunderREAD_ONLYrunning a program named in the repository's own unversioned.git/config(the same user, the same config the main chat's Reads mode runs under). The same file records the decision to keepweb_fetchandweb_searchin the read-only set: the shipped default agent spec already auto-approves both in the main chat, so the side chat adds no egress surface, and the gate, the unsaved side transcript, the SEL row per decision and the stripped spec bound what a fetched instruction can do; an operator who wants no egress denies the two tools with anauto_deny_toolsrule or a governance profile.The footer says "Read-only · Lookups work here, but changes don't. Use the main chat to take action." (
en.manual.jsonand all 12 locales, pseudolocale regenerated); the empty-output fallback inside.pyand the model-facingSIDE_BOUNDARY_PROMPTuse the same words, and the prompt names the read-only shell commands that run here (ls,cat,pwd,git status) because a model told only that "commands that modify anything" are refused declined to runpwd./btwis an alias of/side:SIDE_REinChatInput.tsxmatches both spellings, andSlashCommandMenu.tsxlists/btwon/side's description key so the two rows cannot drift; typing/btwopens the slash menu row that names the command and its description before anything is sent.docs/feature-map/README.mdnames both spellings and the read-only lookups on the Side chat row.Tests
test/test_side_readonly_spec.py(9 new): the derived spec has an emptyallowedTools, noautoApprove, notoolsSettingsallowed*/trusted*/auto*, noincludeMcpJson, an empty KAS policy and no lifecycle hooks, and is otherwise identical to the base once the emptied grants are put back; the shippedconfig/defaults.jsongrants (@kirocrew-cron/cron_remove_all,@kirocrew-core) are absent whiletoolsandresourcessurvive; an unsafe or over-long name is refused; publication writes the derived file beside the base, leaves the base untouched, does not rewrite an unchanged spec and regenerates (new digest) on a changed base; a project-scope base yields a per-source name and two checkouts get two files, never a write into the checkout; a missing or broken base fails closed with no file left behind; a project-scope spec that shadows the derived name, a second user-scope claimant, and a foreign file or symlink at the derived path are all refused untouched.test/test_side.py(14 new): on the kiro-cli backend the side session is created with<agent>--readonlyunderREAD_ONLY, never the base; on another backend the base agent runs underREJECT_ALLand nothing is derived; a derivation failure refuses the turn with the plain panel message, creates no session, streams nothing and leaves a SEL row carrying the code; a retained session whose binding changed is destroyed before acquisition, the cold start receives the full envelope and the next live turn the bare question; a live session no binding vouches for is cold-started; a turn from a replaced sidecar touches no session, a close during the rebind's destroy acquires nothing, and a close during acquisition destroys the session handed back; a project change during the off-loop derivation leaves derivation, binding and spawn cwd on the project the shadow check ran against; close destroys the closing generation's key; a side turn streams underREAD_ONLYwith the gateway's live gate by identity andsession_key="side:parent:<gen>"; with no context builder it passeshooks=None; the empty-output fallback carries the footer's vocabulary. The existing agent-resolution, fallback and app-agent self-heal tests assert the derived spelling of the name they resolved, and an unloadable config runs the base agent underREJECT_ALL.test/test_llm_helpers_tool_gate.py(22 new, the realHookManagerthroughstream_and_collect): a read-only shell command is approved;touchis rejected as policy, not as a security block; a host-known built-in is approved under aread,fetchor empty kind; areadkind alone, a read-looking title alone, a host-known name without trusted provenance, an MCP tool with areadkind and anexecute-kind tool are all rejected; no hooks fails closed; the deny floor and a canonicalmcp__server__tooldeny still win; aWrite*config grant and an app-own-server grant approve nothing underREAD_ONLY, whileauto_approve_tools=["*"]still lets the classifier approvefs_read;test_hook_based_policy_deny_floor_sees_the_canonical_mcp_toolpins thatHOOK_BASEDis untouched.test/test_hooks.py:TestClassifierOnlyHostTrustedProof(7 tests) pins_is_host_read_only_builtin, andtest_host_read_only_builtins_map_only_to_read_scopespins that every allowlisted built-in maps to a read scope only.test/test_side_context.pypins that the boundary prompt says lookups work and changes don't, names the read-only shell commands, and that the no-tools variant is chosen off the capability set.test/test_harness_parity.pycarriesACP_BACKENDS_SIDE_READONLYin the subset table;test/test_agent_spec_hardened_reads.pyregisters the derived-spec module's two labelled_read_agent_speccall sites.test/test_sel.pyandtest/test_governance_profiles.py:side:*keys classify asdashboard, and a dashboard-bound profile governs a side turn.website/src/test/SideSlashCommand.test.tsxandSideSlashCommand.steer.test.tsx:/btwand/btw <msg>intercept like/side,/btwxand/sidebardo not, and/btw <msg>bypasses steer into a side turn while a main turn runs.SideChat.multiturn.test.tsxpins the footer text once the config has loaded and theErrorNoticewhen the config fails to load.Run at this head: 785 tests across the touched backend test files, the suites sharing their helpers, and the repo-wide security-posture and spawn-audit guards (
-n0), 685 frontend tests (the three side-chat specs, all locale style suites and the catalog suites),tsc -b, eslint at 0 warnings,i18n:check, mypy, flake8, isort, black, docs lint, feature-map, sync-io-in-async, agent-sdk-boundary, and the black / comment-history / subprocess-encoding baseline gates. All green.Manual verification
Isolated pod of this branch (real kiro-cli, packaged pod-e2e Playwright harness, torn down clean). The derived spec was published where kiro-cli loads it:
<pod home>/.kiro/agents/kirocrew--readonly.jsonwithallowedTools: [],includeMcpJson: false, nohooks, an emptypermissionspolicy and the owner marker in its description. Proven live:/btw Run the shell command pwd …made kiro-cli raise a permission request that theREAD_ONLYgate approved as a read — SEL rows{"operation": "pwd", "tool_kind": "execute", "outcome": "auto_approved", "source": "llm_helpers"}and{"operation": "Running: pwd", "outcome": "auto_approved", "metadata": {"reason": "hook_auto_approve"}}— and the answer (…/workspace) arrived in the panel under the read-only footer. Not proven live: the gate refusing a write. The model declines to callfs_writeon a side turn under the boundary prompt, even when told the attempt is a sanctioned test, so no permission request is raised for it; the refusal of writes rests ontest_llm_helpers_tool_gate.py, which drives the realHookManagerthroughstream_and_collect. Observed along the way: anfs_readproduced no permission request and no host decision row — kiro-cli trustsfs_readnatively — which this body andside.mdstate. Verified on the same pod:/btin the composer offers the/btwrow, and/btw what is 2+2? answer in one wordopens Side Chat, dispatches the turn and shows the footer below.Screenshots / video
/btin the composer offers the alias:/btw what is 2+2? answer in one wordopens Side Chat and dispatches the turn; the footer reads "Read-only · Lookups work here, but changes don't. Use the main chat to take action.":Related Issues
Closes #8964
Closes #9842
Pattern harvest
Rule candidate: review-prompt
Pattern: a policy that gates tool calls must be paired with the agent spec the session runs under — any backend-side pre-authorization (
allowedTools,autoApprove,toolsSettings.allowed*, KASpermissions) bypasses the gate, so a "read-only" surface needs a spec with those emptied, not just a stricter gate.Rule candidate: review-prompt
Pattern: when a turn may destroy and recreate its backend session mid-conversation, the "first turn" that decides whether the model gets its framing must be judged on what the session manager did (a new, non-resumed session), not on the transcript.
Rule candidate: agents-md
Pattern: verify an i18n copy change reached
distby grepping for the OLD string's absence, not the new string's presence — an incremental vite/rolldown build can emit both values in one chunk.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)