Repository navigation
feat(folders): folder.steering change card for folder steering dirs - #13399
Conversation
|
👋 Hi! This PR's description is missing some required sections from our PR template. Workflow runs won't be auto-approved until the description is updated. Missing sections:
Please update your PR description to include these sections, then push or re-save the description. The workflows will be approved on the next cycle. |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 2fbd5c1 Description read[DESCRIPTION-READ] 932e81fd181ac901ff92ce4bf91e816862d5fa15ba1d7417f74ea2897d934c44 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check that a What this change shipsInventory (8 items) — 8 justifiedIntent: let an agent ask to change a folder's steering directories, and have the person approve the exact change on a change card. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 2fbd5c1 Description read[DESCRIPTION-READ] f1268ccc0ac4786f69a7044797073f0262fbf7870f68428798d1b99113528237 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
724b9c8 to
2cadabf
Compare
|
Disposition for GPT F1 — empty list bypassed the dashboard-only rule (fixed). The First Principles — unsupported "stated posture" claim (addressed in the body). Replaced with the concrete gap: every other dashboard folder setting already has a Design — tree exposes Opus lane was verdict-less (review incomplete); the fresh sha re-rolls it. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
2cadabf to
63b5a90
Compare
|
Disposition for GPT F1 — a Slack-linked dashboard tab passes the Trade-off accepted: a person typing in a Slack-linked tab is refused as well and is told to unlink or use another tab — the honest bound, since nothing in the turn identity distinguishes the two. |
63b5a90 to
69c5415
Compare
|
Disposition for GPT F1 — link state is mutable under the read (fixed with admission-time provenance). Correct: a human unlink landing while a channel-started turn is still running cleared the link fields before the tool read them. The turn's provenance is now pinned where the finding asked for it — at admission. Pinned by Backend Lint red on |
69c5415 to
85194fc
Compare
85194fc to
b269491
Compare
|
Disposition for GPT F1 — an app-owned dashboard session could clear (fixed as suggested). Correct: the gate's
|
b269491 to
d8026f2
Compare
|
Disposition for GPT F1 — automatic successors erase channel provenance (fixed at the root). Correct, and it generalises: once a linked-thread reply is in the conversation its text stays in the context, so any later turn can act on it — the synthesis turn and the subagent-completion delivery (both dispatched without the flag, as the finding traced), and equally a turn the person types after unlinking. Threading the flag through the successor sites would close this path but not the class, so the unit is now the conversation, not the turn.
Pinned by |
|
Disposition for GPT (approval bar hides the steering change). The message-box approval bar expanded its details only when a tool call in the chat history backed the approval; the The PR body now carries a pod screenshot of the card showing |
|
Disposition for
No code changes. 698 related tests, black, comment-history, feature-map and mypy pass on the new base. |
|
Disposition for On |
|
This PR adds a new MCP tool, |
|
Disposition for
|
|
Disposition for |
|
Disposition for |
|
Disposition for |
|
This adds a kirocrew-dashboard MCP tool that lets an agent set and read a folder's steering directories, with a person approving each change. HOLD because it is a new feature that changes what every chat in a folder is told, it touches approval-mode enforcement and the folder-steering principal gate (permission paths), it has about 700 production lines, and GitHub reports mergeability as unknown. On head 960ca3a, GPT and Opus have no findings, but three whole-design lanes are CONCERNS. Design says holding the approval wait inside a tools/call on a single-worker pooled backend can stall every session's dashboard tools for up to 90s per card. First Principles says the caller and redaction refusals run twice and no issue shows anyone who needed this. UX says the approval card's header is a raw identifier and nothing explains what approving replaces. These need answers and a product decision from a maintainer first. — crew-pr-reviewer |
|
This adds a chat_folder_steering_set MCP tool, so an agent can propose a folder's steering directories, gated by a person-only approval card. I am holding because it touches approval and permission enforcement (test_approval_modes_enforcement.py, test_app_route_trust_gate.py, the folder steering principal gate, ChatInput approval). A steering directory is a host-file read handed to every chat in the folder. The PR also deliberately reverses a recorded decision that steering_dirs is "the person's call, not an agent's", and it is a new feature at about 1886 added lines, over the size bar. The Design, First Principles and UX lanes are CONCERNS. I read the description and the file list and confirmed it is mergeable on main with no change requests. A maintainer has to own the policy reversal and do a security review of the approval card's principal check and the refusal of app, crew-member, channel and cron callers before this lands. — crew-pr-reviewer |
|
Rebased onto main as 3a2d91f. One docs conflict in the feature-map Session folders row (main reworded the crew-window row above it; kept main's row, re-applied this PR's). Main's internal-auth guard on session-approval routes (#18867) now refuses an internal caller on the slot approve route with |
iamwhatever
left a comment
There was a problem hiding this comment.
This adds a kirocrew-dashboard tool that lets an agent ask to change a folder's steering directories, and the person approves each change on a person-only card. The permission design holds up. I tried to approve the card from the agent's side and could not: an internal-credential or app caller is refused on both resolve routes (sessions.py api_approval_resolve and the chat_handlers slot-approve branch), the trust/yolo sweep skips human_only cards, and trust or yolo answers on the card get a 400. The Slack resolvers only answer their own linked request ids. No path is checked on disk before approval, and after approval the resolved path must equal the approved text, so a symlink swap is refused. Head 3a2d91f is a rebase plus a test loosened to accept owner_only, so the Design lane's finding still stands, with no disposition posted. That finding is a real regression. The tool holds one PATCH open for up to 90 s (chat_folders.py _await_person_steering_approval, STEERING_APPROVAL_TIMEOUT_SECS; mcp_dashboard.py STEERING_APPROVAL_CLIENT_TIMEOUT), and kirocrew-dashboard is a pooled backend whose stdio loop runs one tool call at a time (mcp_shared.py run_mcp_stdio_loop). So one unanswered card stalls every other session's dashboard tools, conductor dispatch included, and queue overflow returns busy errors. Suggested fix: have the endpoint register the card and return "asked the person" at once, then run the post-approval validation and the store write in the card's resolve handler. Please also show the folder's current list next to the new one on the card, and say "removes all N directories" for a clear: today an agent's [] shows up as a bare steering_dirs [], which the UX lane flagged. — crew-pr-reviewer (deep re-check)
|
Disposition for The approval no longer holds a dashboard tool call open. An agent's The card shows the change. It lists the folder's Also rebased onto main: the only conflict was the feature-map Session folders row, resolved per column. 1,014 related tests pass locally, along with black, mypy, and the comment-history and feature-map gates. |
|
Disposition for Backend shards (wait-discipline ratchet). This PR's own tests added short fixed waits ( UX block. The card names the request and the folder: it is titled GPT and Opus had no findings on |
|
Disposition for |
|
Rebased onto main |
|
Design (watch 1, card dropped after 90 seconds): fixed. The steering card no longer has a deadline of its own. It stays up for the approval coordinator's ordinary window, like any tool-approval card, so a late approval is still applied. The 90-second wrapper and its constant are removed, the tool text and docs no longer promise 90 seconds, and |
|
Design (watch 1, an approved change can silently do nothing): fixed. When the check after approval refuses the write (a linked path such as macOS |
|
Opus (blocking, no count cap on steering cards): fixed. A folder holds one open steering card at a time. While one waits, a second agent PATCH gets |
|
Rebased onto main to re-roll E2E (stub ACP backend). On |
|
Rebased onto main to re-roll E2E. On |
|
Rebased onto main to clear a conflict. Main added |
|
Rewrote the agent surface onto the existing change-card mechanism, per the First Principles finding. A new |
|
f816a8a: the folder.steering card's Undo now carries the list the card stored as |
|
ee1b152: Apply now carries |
|
8eb0a55: |
|
f44d021: the expected steering list now travels as a request attribute the card hook arms on each Apply/Undo step ( |
… steering dirs Folder steering directories (kirodotdev#11827) could be set only from the dashboard's Folder settings dialog. This gives agents the same setting through the existing change-card mechanism instead of a bespoke approval path: - New change-card kind `folder.steering` (change_card_catalog.py): params {folder, steering_dirs}. The card shows Folder / Current / New, and applying it is one PATCH /api/chat/folders/{id} {"steering_dirs": [...]}, the route Folder settings uses, sent by the person's own browser through the card hook. Adding a directory is `widen`, only removing is `tighten`. Undo writes the previous list back while the folder still holds what the card stored. The folder PATCH joins HOOKED_ROUTES (not MEMORY_ROUTES: it is sidebar organization, not a setting). - An agent proposes it with the existing propose_change(kind="folder.steering") tool, so the guide's caller checks (dashboard turn the person sent, no app, subagent or channel caller) apply unchanged. No new MCP tool. - The folder routes refuse a non-empty steering_dirs on the internal credential every MCP tool call carries (403 steering_dirs_forbidden), at create and update, like an app or crew member's; the card is the agent's only path. - chat_folder_tree renders each folder's declared list as steering=[...], and chat_folder_update's description points at the card. - Frontend: the kind is registered with the Folder settings section's label. Docs: architecture/mcp.md kind list, config.md agent-surface bullet, session-control.md folder table, feature-map row.
|
2fbd5c1: on a card Apply/Undo step, the folder PATCH now refuses (409 |
iamwhatever
left a comment
There was a problem hiding this comment.
The PR has been rebuilt on the existing change-card mechanism. A new folder.steering kind is proposed through propose_change, and the person's own browser applies it with the same PATCH /api/chat/folders/{id} that Folder settings sends. The folder create/update routes now refuse a non-empty steering_dirs on the internal credential (_refuse_principal_steering_dirs(..., agent=True)). This resolves our earlier change request: the bespoke tool and its 90 s blocking wait on the single-worker kirocrew-dashboard loop are gone. The card also shows Folder, a +/− Change row, Current and New, so a clear is visible as removals. I tried to get past the gate in three ways. (1) A direct agent PATCH gets 403 steering_dirs_forbidden. (2) Pressing the card's step with the internal credential is refused by _run_card_step -> _is_owner_browser, which rejects internal_auth. (3) REQ_CARD_FOLDER_STEERING_EXPECT is a request attribute armed only on the owner card step, so no HTTP body can supply it (test_a_plain_folder_patch_cannot_supply_the_expected_list). Swapping an approved directory for a link after approval gets 409, because the re-resolved list must equal the card's list, and a concurrent save is caught by the under-lock compare in _apply. Two non-blocking notes. First, chat_folders.py still lets an internal caller send steering_dirs: [] with no card, because the refusal only fires on a non-empty list, so "the card is the agent's only route" is true for adding but not for clearing; that is no worse than main, so it is not a blocker, but say it or refuse it. Second, the open UX CONCERNS is fair: the shared widen copy ("widens permissions") should say that every chat in the folder will read the added directories. All other lanes pass on 2fbd5c1, checks are green and it is mergeable. — crew-pr-reviewer (deep re-check)
Problem / Motivation
Goal: Let an agent ask to change a folder's steering directories, with the person approving the exact change, using the existing change-card mechanism.
Folder steering directories (#11827) can be set only from the dashboard's Folder settings dialog. An agent that organizes a person's sidebar through the
kirocrew-dashboardMCP server can create, move and file folders, but it can neither read the steering a folder delivers nor ask to change it. Steering is the one folder setting that shapes what every chat in the folder is told.Why it matters
KiroCrew is operated by agents as much as by people. Without this, an agent asked to "point the
kirocrew/folder at our standards tree" cannot finish the job. Change cards already exist for exactly this: the agent proposes one registered kind of change, and the person's own browser applies it through the same route the settings page uses. This adds one kind, so steering needs no approval path of its own.Not a goal
steering_dirsdirectly. It still cannot.What changed
New change-card kind
folder.steering(change_card_catalog.py){folder, steering_dirs}.steering_dirsis the complete new list, and[]clears it. When the card is proposed, each directory is resolved exactly as the folder route stores it (_validate_steering_dirs:~expanded, links resolved), and anything the route would refuse is refused. The list you approve is the list the gateway reads.PATCH /api/chat/folders/{id}{"steering_dirs": [...]}from the person's browser through the card hook. That is the request Folder settings sends, so the route's existing path validation and person-only principal gate are the only authority.widen; only removing directories istighten.409 steering_dirs_changedinstead of being overwritten. On a card step, the route also refuses (409) when a directory now resolves somewhere other than the path the card showed, for example a directory swapped for a link after approval. The person's own Folder-settings PATCH is unchanged.HOOKED_ROUTES. It does not joinMEMORY_ROUTES, because it is sidebar organization, not a setting.Agent surface: the existing
propose_change(kind="folder.steering", params=...)tool. No new MCP tool, so the guide's existing caller checks apply unchanged: a dashboard turn the person sent, and no app, subagent or channel caller.chat_folder_treenow renders each folder's declared list assteering=[…], so the agent sees the list it would replace.chat_folder_update's description points at the card.The direct path stays closed: the folder create and update routes now refuse a non-empty
steering_dirson the internal credential every MCP tool call carries (403 steering_dirs_forbidden), as they already did for an app or crew member. The card is the agent's only route.Docs:
docs/architecture/mcp.mdkind list, thedocs/system-specs/modules/config.mdagent-surface bullet, thesession-control.mdfolder table, and the feature-map row.Backwards compatibility
Additive: one new card kind, one newly hooked route, and
steering=[…]inchat_folder_treeoutput. The person's Folder-settings PATCH is unchanged. An internal-credentialsteering_dirswrite is now refused. No caller sends one on main.Tests
test/test_change_card_folder_steering.py:test/test_mcp_dashboard_folders.py: the tree renderssteering=[…].test_agent_proposes_owner_applies_and_undoesandtest_agent_create_with_steering_is_refused; dropping the under-lock compare failstest_undo_does_not_overwrite_a_save_made_after_its_check; not arming the expected list in the card hook fails both the Apply and Undo race tests; skipping the proposal-time resolve fails the linked-directory and refusal tests.Manual verification
On a pod built from this branch, I made a
Team docsfolder, and an agent in a dashboard chat calledpropose_change(kind="folder.steering"). Every path was typed with the/home/...spelling. The pod's home directory is a link to/local/home/..., and the card showed the resolved/local/home/...spelling in the Change, Current and New rows, which is also whatfolders.jsonstored.[team-notes]showed a "+" chip in the Change row and kept Apply disabled until the widen box was ticked. After Apply,folders.jsonheld the directory and the card offered Undo. After Undo, the card read "Restored" and the folder's steering was empty again.[team-notes, repo-rules]stored, a card for[team-notes]showed a "−" chip forrepo-rulesand no widen box, and Apply left[team-notes]. A card for[]showed a "−" chip forteam-noteswith New empty, and Apply cleared the folder's steering.[team-notes, repo-rules]. Before Apply, I saved[other]for the same folder from Folder settings. Clicking Apply then showed "This changed after the card was shown. Refresh the preview and check it again." with a Refresh preview button, andfolders.jsonstill held[other].Screenshots / video
The add card. The Change row marks the added directory, and Apply waits for the widen acknowledgement:
Applied, with Undo offered:
After Undo:
A card that removes one directory. It has no widen box, because removing only narrows what chats read:
The remove card applied:
A card that clears the list:
A Folder-settings save landed after the card was shown, so Apply was refused and nothing was overwritten:
Related Issues
Follow-up to #11827.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)