Skip to content

feat(side-chat): auto-approve read-only tools and add /btw alias - #9609

Merged
iamwhatever merged 1 commit into
mainfrom
feat/side-chat-readonly
Sep 11, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
feat/side-chat-readonly

Conversation

@pepmach

@pepmach pepmach commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

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_ALL to 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 when is_read_only_bash accepts it under the deny-by-default prefix allowlist (ls, cat, grep, git status and the rest of that table; no redirects, no substitution, no backgrounding). Every other shell call is rejected. The policy is ToolApprovalPolicy.READ_ONLY in llm_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 same HookManager.on_tool_call gate Reads uses runs, asked classifier_only: the grant tiers — the operator's auto_approve_tools globs, 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 tagged ToolHookResult.read_only counts. A non-shell call is proven read-only by one fact: the host-stamped _meta.kiro.toolName names 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 the mcp_identity_trusted provenance flag set. The ACP kind and the title can narrow the verdict but never produce it. READ_ONLY with 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
Loading

🟩 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-acp permissions.allow / bypassPermissions) that neither the spec nor the gate can see, so a call it pre-approved would run with no READ_ONLY decision and no SEL row. Off the set — or with the harness unknown because the config never loaded — a side turn runs the base agent under REJECT_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.tsx reads the selected harness through the kirocrewConfig query, claims the allowance only from a loaded config, and renders a failed load through ErrorNotice — "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 allowedTools itself 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 shipped kirocrew spec pre-authorizes @kirocrew-cron/cron_remove_all and @kirocrew-core wholesale. _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: [], no mcpServers.*.autoApprove, no toolsSettings.*.allowed*/trusted*/auto* — subagent.trustedAgents and shell.autoAllowReadonly included — includeMcpJson: false, autoAllowReadonly: false, an empty KAS permissions policy) and the lifecycle hooks removed (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 trusts fs_read natively and runs it with no host decision, which the guarantee tolerates because it is a read. dashboard/side_readonly_spec.py derives 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.json atomically, 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. Its description carries 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 SEL chat.side_turn denied 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>, gen being 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.binding records 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 during get_or_create has 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 spawn cwd (where kiro-cli resolves --agent first) 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 session get_or_create reports 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, and READ_ONLY then rejects every tool call. The gate is called with the side session's own identity: side:<slot>:<gen> classifies as the dashboard surface in sel._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_BASED callers of stream_and_collect (cron, heartbeat, autonudge, Meetings) are unchanged: _resolve_permission hands the gate the same trusted _meta.kiro identity for both policies, and the one READ_ONLY-specific input is classifier_only. ToolHookResult carries read_only beside identity_grant; the two flags answer different questions (what the call does; who vouched for it) and READ_ONLY reads only the first.

Two residuals are recorded in docs/system-specs/modules/side.md as accepted, both requiring a writer already running as the operator's own UID: a concurrent write into <project>/.kiro/agents between 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), and git under READ_ONLY running 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 keep web_fetch and web_search in 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 an auto_deny_tools rule 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.json and all 12 locales, pseudolocale regenerated); the empty-output fallback in side.py and the model-facing SIDE_BOUNDARY_PROMPT use 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 run pwd. /btw is an alias of /side: SIDE_RE in ChatInput.tsx matches both spellings, and SlashCommandMenu.tsx lists /btw on /side's description key so the two rows cannot drift; typing /btw opens the slash menu row that names the command and its description before anything is sent. docs/feature-map/README.md names 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 empty allowedTools, no autoApprove, no toolsSettings allowed*/trusted*/auto*, no includeMcpJson, an empty KAS policy and no lifecycle hooks, and is otherwise identical to the base once the emptied grants are put back; the shipped config/defaults.json grants (@kirocrew-cron/cron_remove_all, @kirocrew-core) are absent while tools and resources survive; 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>--readonly under READ_ONLY, never the base; on another backend the base agent runs under REJECT_ALL and 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 under READ_ONLY with the gateway's live gate by identity and session_key="side:parent:<gen>"; with no context builder it passes hooks=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 under REJECT_ALL.
  • test/test_llm_helpers_tool_gate.py (22 new, the real HookManager through stream_and_collect): a read-only shell command is approved; touch is rejected as policy, not as a security block; a host-known built-in is approved under a read, fetch or empty kind; a read kind alone, a read-looking title alone, a host-known name without trusted provenance, an MCP tool with a read kind and an execute-kind tool are all rejected; no hooks fails closed; the deny floor and a canonical mcp__server__tool deny still win; a Write* config grant and an app-own-server grant approve nothing under READ_ONLY, while auto_approve_tools=["*"] still lets the classifier approve fs_read; test_hook_based_policy_deny_floor_sees_the_canonical_mcp_tool pins that HOOK_BASED is untouched.
  • test/test_hooks.py: TestClassifierOnlyHostTrustedProof (7 tests) pins _is_host_read_only_builtin, and test_host_read_only_builtins_map_only_to_read_scopes pins that every allowlisted built-in maps to a read scope only. test/test_side_context.py pins 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.py carries ACP_BACKENDS_SIDE_READONLY in the subset table; test/test_agent_spec_hardened_reads.py registers the derived-spec module's two labelled _read_agent_spec call sites. test/test_sel.py and test/test_governance_profiles.py: side:* keys classify as dashboard, and a dashboard-bound profile governs a side turn.
  • website/src/test/SideSlashCommand.test.tsx and SideSlashCommand.steer.test.tsx: /btw and /btw <msg> intercept like /side, /btwx and /sidebar do not, and /btw <msg> bypasses steer into a side turn while a main turn runs. SideChat.multiturn.test.tsx pins the footer text once the config has loaded and the ErrorNotice when 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.json with allowedTools: [], includeMcpJson: false, no hooks, an empty permissions policy and the owner marker in its description. Proven live: /btw Run the shell command pwd … made kiro-cli raise a permission request that the READ_ONLY gate 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 call fs_write on 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 on test_llm_helpers_tool_gate.py, which drives the real HookManager through stream_and_collect. Observed along the way: an fs_read produced no permission request and no host decision row — kiro-cli trusts fs_read natively — which this body and side.md state. Verified on the same pod: /bt in the composer offers the /btw row, and /btw what is 2+2? answer in one word opens Side Chat, dispatches the turn and shows the footer below.

Screenshots / video

/bt in the composer offers the alias:

slash menu offering /btw

/btw what is 2+2? answer in one word opens 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.":

side panel opened via /btw with the read-only footer

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*, KAS permissions) 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 dist by 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

@pepmach
pepmach requested review from a team and patrigao September 9, 2026 02:30
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 9, 2026
@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

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.

Watch

The spec derivation empties an enumerated set of top-level grant fields (allowedTools, autoAllowReadonly, permissions, hooks, includeMcpJson); the toolsSettings prefix match fails closed for new keys, but a future kiro-cli top-level pre-authorization surface would survive derivation, be approved backend-side, and never raise a permission request — silently breaking the footer's "changes don't work here" guarantee with nothing in this repo going red. The PR's own pattern-harvest rule ("any backend-side pre-authorization bypasses the gate") names exactly this class, yet side.md records only the two same-UID residuals, not this schema-evolution dependency.
Clears when: side.md records the kiro-cli spec-schema coupling as a residual with an upgrade-review rule (or a derivation-time check that logs/refuses unknown grant-shaped top-level keys), so a kiro-cli bump reopens the field list deliberately.

Suggestions

  • Sweep owner-marked derived specs whose base agent or hashed project source no longer exists: <agent>--readonly-<8hex> files accumulate per checkout forever in the shared ~/.kiro/agents/ registry and surface in kiro-cli's own agent listing after the checkout is gone.

[DESIGN-REVIEWED] b25d1cf

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of b25d1cf491e6cbfe81b96511c097dcce8f61ad84 — 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.

All evidence gathered. The counts I ran: _side_session_key has 3 call sites, all passing gen (the bare legacy branch has zero callers); temp-screenshots/ is a workflow-consumed convention (PR template, ux-review.yml, cleanup workflow), so the committed screenshots are justified; and the side-readonly capability decision is spelled twice — set membership in side.py vs. an empty-string backend test in SideChat.tsx:85.

First-Principles-Verdict: CONCERNS

/btw is a second spelling of /side whose only stated harm — "there is no short alias" — is the feature restated as its requirement.

Not justified as shipped

  • 3. /btw alias — duplicate of /side: same regex, same handler; i18n: reword Side Chat footer 'Tools and MCPs are unavailable here' into plain language #8964 is about footer jargon, not an alias, so no named person was failing. The PR's own test comment concedes the cost: "must stay in lockstep with /side … or a running turn would swallow '/btw …' as steer text."
  • 10. Legacy bare side:<slot> key branch — zero consumers: all 3 call sites of _side_session_key pass gen (grepped _side_session_key, src+test); the "caller with no sidecar in hand" it is kept for does not exist.

What this change ships

Inventory (10 items) — 8 justified

Intent: 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).

  1. Side Chat runs provably read-only lookups without asking, on kiro-cli — justified
  2. Other backends / unloaded config keep a tool-less side chat with matching prompt+footer — justified
  3. /btw composer alias — duplicate of /side (no named harm beyond "no short alias")
  4. Footer relabeled "Read-only · Lookups work here…" + backend/config-error variants, 12 locales — justified
  5. A <agent>--readonly.json file now appears in the user's ~/.kiro/agents, regenerated per side turn — justified
  6. A side turn that can't derive/publish its spec is refused, never run on the base agent — justified
  7. Side session keyed per sidecar generation, rebound on agent/project/spec change, cold starts re-enveloped — justified
  8. Dashboard-bound governance profiles now govern side turns (side:* no longer falls to the slack fallback) — justified
  9. READ_ONLY policy + classifier_only gate mode + read_only result tag — justified
  10. Bare side:<slot> legacy key branch — zero consumers (count above); whole-file black reformats of 4 files ride along

(A few smaller items — screenshots per the temp-screenshots/ workflow convention, doc updates — omitted at the 10-item cap; all justified.)

Watch

  • The read-only allowance is decided twice: ACP_BACKENDS_SIDE_READONLY membership in side.py, and !(cfgQ.data?.agent?.acp_backend ?? '') in SideChat.tsx:85 (2 spellings, grepped both symbols). When a second backend joins the set, the backend grants tools while the footer still says "unavailable on this agent backend."
    Clears when: a pin ties the footer branch to the set's membership, or the footer reads the backend's own decision.
  • /btw (above). Clears when: a report or request naming the missing alias exists — or the alias is deleted.

Subtractions

  • Delete /btw: revert SIDE_RE to /side only, drop the SlashCommandMenu row and the three alias test blocks — /side already does the job.
  • Drop the gen: str = "" default and the bare-key branch in _side_session_key (side.py:59) — 0 callers use it; require gen.

[FIRST-PRINCIPLES-REVIEWED] b25d1cf

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The shipped states read well — the blind reader got both /btw and the read-only footer right — but the three new failure/fallback states were never shown.

Evidence gaps

  • The non-kiro-backend footer variant ("Context only · Tools are unavailable here on this agent backend…", SideChat.tsx) appears in no screenshot; needs a shot with a non-kiro acp_backend selected.
  • The config-load-failure ErrorNotice ("Couldn't load the agent configuration, so Side Chat runs without tools…", testId="side-chat-config-error") appears in no screenshot.
  • The refused-turn panel message ("Side Chat couldn't start. Try again, or use the main chat.", side.py) appears in no screenshot; a shot of a failed derivation would close it.

[UX-REVIEWED] b25d1cf

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

I've validated the candidate list (empty) and independently examined the core security logic: the READ_ONLY/classifier_only gate in llm_helpers.py and hooks.py, the derived read-only spec derivation and publication in side_readonly_spec.py, the generation-keyed session lifecycle in handlers/side.py, and the side: surface classification in sel.py.

The grant-emptying in derive_readonly_spec covers exactly the pre-authorization channels the governance module recognizes (allowedTools, MCP autoApprove, toolsSettings allowed*/trusted*/auto*, includeMcpJson, autoAllowReadonly, KAS permissions, lifecycle hooks); the gate fails closed on a missing HookManager, on unclassified auto-approves, and on non-host-trusted provenance; the session key carries the sidecar generation so a stale turn cannot touch a replacement's session; and the documented residuals (same-UID project-agent shadow, git config-driven programs, web_fetch/web_search egress) each match exposure the main chat already carries. No hunk introduces a reachable defect that answers (a)/(b)/(c) at the required bar.

No findings.

[OPUS-REVIEWED] b25d1cf

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

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

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ human override accepted

Human judgment by @pepmach overrides the GPT 5.6 finding for b25d1cf491e6cbfe81b96511c097dcce8f61ad84; the recorded reason is authoritative for this commit.

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:
/ai-review override gpt b25d1cf491e6cbfe81b96511c097dcce8f61ad84: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Sep 9, 2026
@pepmach
pepmach force-pushed the feat/side-chat-readonly branch from 1a5fc60 to 7ac94c5 Compare September 9, 2026 08:38
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 9, 2026
@pepmach
pepmach force-pushed the feat/side-chat-readonly branch from 7ac94c5 to f6bde6c Compare September 9, 2026 11:32
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 9, 2026
@pepmach
pepmach force-pushed the feat/side-chat-readonly branch from f6bde6c to 6ca72e1 Compare September 9, 2026 12:01
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 9, 2026
@pepmach
pepmach force-pushed the feat/side-chat-readonly branch from 6ca72e1 to 4d84a97 Compare September 9, 2026 13:07
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 9, 2026
@pepmach

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

self-added: no

  • Drop the /btw alias: a second spelling of /side is preference-supported surface that is cheap to add and awkward to withdraw — span=d971862fd917 — rebutted

The alias stays, by maintainer ruling. /btw is a widely recognized slash command: Claude Code and Codex both ship it, and Codex ships both /side and /btw, so users arrive knowing the vocabulary — the alias removes a command to learn for them rather than adding one, which is the harm the single spelling was causing. The leading / is required (SIDE_RE in website/src/pages/chat/ChatInput.tsx is /^\/(?:side|btw)(?:\s+([\s\S]+))?$/), so "btw" as a sentence opener never matches. The user is told what will happen before anything is sent: typing / at the start of the composer opens the slash-command menu (website/src/components/ChatInput.tsx:2038), which stays open through /b, /bt, /btw (SlashCommandMenu.tsx:160-162), filters to the /btw row (:146, :181) and renders the command name beside its description (:279-280, COMMAND_DESC_KEY['/btw'] at :50, the same key as /side). Pinned by SideSlashCommand.test.tsx (/btwx and /sidebar do not intercept). Withdrawal cost is one regex alternative and one menu row.

@pepmach
pepmach force-pushed the feat/side-chat-readonly branch from a18b48b to ec1a3ae Compare September 10, 2026 11:34
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 10, 2026
@pepmach

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: keep the reason to 500 characters or fewer.

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

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: keep the reason to 500 characters or fewer.

@pepmach

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: keep the reason to 500 characters or fewer.

@pepmach

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for a224d9d049d4e8ce22ccf29485e81e8cbc42ecb8.

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.

This decision applies only to this commit. A new push requires a new judgment.

@pepmach

pepmach commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 70408861536d9cd5df34a8872798a4f78df4c8c5.

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.

This decision applies only to this commit. A new push requires a new judgment.

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

[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 in platform/governance.py:BUILTIN_TOOL_SCOPES to filesystem.read or network.egress only; the write/exec built-ins (code, fs_write, execute_bash) map to filesystem.write/commands and are absent. test_host_read_only_builtins_map_only_to_read_scopes pins 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 requires mcp_identity_trusted provenance + a host-stamped _meta.kiro.toolName + no mcp_server_name. The agent-influenced kind and 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 through is_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 $IFS argv-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/credentials reads), and governance all run BEFORE the grant/classifier tiers and are unaffected by classifier_only. The classifier auto-approve is the last branch before allow().
  • The spec derivation closes the real bypass. derive_readonly_spec empties allowedTools, per-server autoApprove, toolsSettings.{allowed,trusted,auto}* (prefix-matched so a new kiro-cli grant fails closed), includeMcpJson, autoAllowReadonly, KAS permissions, and strips lifecycle hooks: 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-allowance REJECT_ALL posture. This is correct: claude-agent-acp's permissions.allow/bypassPermissions is 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_read natively (confirmed in the PR's own live-pod observation: fs_read produced no permission request and no host decision row, even under the derived spec with allowedTools: []). Because the call never reaches HookManager.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/credentials explicitly). So a side turn can fs_read ~/.aws/credentials or ~/.ssh/id_rsa and 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_read bypass 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 enable fs_read on 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.md alongside the git/concurrent-writer residuals: that native fs_read reads 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-turn fs_read through 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 of slot._side is side_at_start after 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/agents and is the same class already documented as an accepted same-UID residual, not chargeable here.
  • Error handling: ReadOnlySpecError is 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, touch rejected 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_RE matching both spellings and SlashCommandMenu keying /btw on /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.
@pepmach

pepmach commented Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for b25d1cf491e6cbfe81b96511c097dcce8f61ad84.

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.

This decision applies only to this commit. A new push requires a new judgment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

4 participants