Skip to content

feat(folders): folder.steering change card for folder steering dirs - #13399

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
billygerhard:feat/folder-steering-mcp-tool
Oct 13, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
billygerhard:feat/folder-steering-mcp-tool

Conversation

@billygerhard

@billygerhard billygerhard commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

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-dashboard MCP 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

What changed

New change-card kind folder.steering (change_card_catalog.py)

  • Params {folder, steering_dirs}. steering_dirs is 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.
  • The card shows Folder, a Change row marking each added (+) and removed (−) directory, then Current and New.
  • Applying the card sends one 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.
  • Risk is computed from the diff. Adding a directory is widen; only removing directories is tighten.
  • Undo writes the previous list back while the folder still holds what the card stored.
  • The card hook arms each Apply and Undo step with the list it replaces. This uses the same request-scoped mechanism as the schedule and crewmate Undo guards, so no body field is added to the folder PATCH. The route compares it under the store lock, so a save from another tab after the card's check gets 409 steering_dirs_changed instead 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.
  • The folder PATCH joins HOOKED_ROUTES. It does not join MEMORY_ROUTES, because it is sidebar organization, not a setting.
  • The dashboard registers the kind under the Folder settings section's own label.

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_tree now renders each folder's declared list as steering=[…], 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_dirs on 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.md kind list, the docs/system-specs/modules/config.md agent-surface bullet, the session-control.md folder table, and the feature-map row.

Backwards compatibility

Additive: one new card kind, one newly hooked route, and steering=[…] in chat_folder_tree output. The person's Folder-settings PATCH is unchanged. An internal-credential steering_dirs write is now refused. No caller sends one on main.

Tests

  • test/test_change_card_folder_steering.py:
    • bad params are refused, and the kind is listed;
    • the preview shows Folder / Current / New and plans the folder PATCH;
    • adding widens and only removing tightens;
    • an unchanged list and a missing folder are refused;
    • Undo writes the previous list back, and only while the folder holds what the card wrote;
    • the PATCH is hooked but writes no memory line;
    • end to end, the agent proposes and the owner applies and undoes;
    • a card step that differs from the plan is refused;
    • an agent's create carrying steering is refused;
    • neither Apply nor Undo overwrites a save that lands after its check (409);
    • a plain folder PATCH cannot supply the expected list;
    • Apply refuses a directory swapped for a link after approval;
    • a linked directory is shown and written as the route stores it, and Undo is offered;
    • a directory the route would refuse is refused at proposal;
    • a long canonical path the route accepts (up to its 4,096-character bound) survives a card rebuild.
  • test/test_mcp_dashboard_folders.py: the tree renders steering=[…].
  • Mutation probes: dropping the internal-credential refusal fails test_agent_proposes_owner_applies_and_undoes and test_agent_create_with_steering_is_refused; dropping the under-lock compare fails test_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.
  • Locally: 922 change-card, folder and registration tests pass, along with black, flake8, mypy, the comment-history and feature-map gates, frontend typecheck, eslint, and the change-card vitest files.

Manual verification

On a pod built from this branch, I made a Team docs folder, and an agent in a dashboard chat called propose_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 what folders.json stored.

  • Add, then Undo: the card for [team-notes] showed a "+" chip in the Change row and kept Apply disabled until the widen box was ticked. After Apply, folders.json held the directory and the card offered Undo. After Undo, the card read "Restored" and the folder's steering was empty again.
  • Remove, then clear: with [team-notes, repo-rules] stored, a card for [team-notes] showed a "−" chip for repo-rules and no widen box, and Apply left [team-notes]. A card for [] showed a "−" chip for team-notes with New empty, and Apply cleared the folder's steering.
  • Conflict: a second card proposed [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, and folders.json still held [other].

Screenshots / video

The add card. The Change row marks the added directory, and Apply waits for the widen acknowledgement:

Add card: Change + team-notes, Current empty, New team-notes

Applied, with Undo offered:

Applied card with Details and Undo

After Undo:

Restored card after Undo

A card that removes one directory. It has no widen box, because removing only narrows what chats read:

Remove card: − repo-rules, Current team-notes and repo-rules, New team-notes

The remove card applied:

Remove card applied, with Undo

A card that clears the list:

Clear card: − team-notes, Current team-notes, New empty

A Folder-settings save landed after the card was shown, so Apply was refused and nothing was overwritten:

Conflict alert with Refresh preview

Related Issues

Follow-up to #11827.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@billygerhard
billygerhard requested review from a team and bolichen97 September 24, 2026 15:45
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 24, 2026
@dwu96

dwu96 commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

👋 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:

  • ## Problem / Motivation
  • ## Why it matters
  • ## What changed

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.

@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 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 2fbd5c1eaa36d1428c31588afa431a55ccf5d8b6 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check that a folder.steering card cannot be applied for a folder owned by an app or crew member. The new internal-credential refusal does not cover the card hook's request.

What this change ships

Inventory (8 items) — 8 justified

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

  1. Agents can propose a folder.steering change card that replaces a folder's steering list. — justified
  2. The card shows the folder, the added and removed directories, the current list and the new one, with each path written the way the route stores it. — justified
  3. Adding a directory needs the widen acknowledgement; a card that only removes directories does not. — justified
  4. Undo writes the previous list back, but only while the folder still holds what the card wrote. — justified
  5. Apply or Undo is refused with 409 if another save or a link swap happened after the card was approved. — justified
  6. chat_folder_tree now shows each folder's declared steering=[…] list. — justified
  7. Folder create and update refuse a non-empty steering_dirs on the internal MCP credential. — justified
  8. The dashboard registers the kind under the Folder settings "Additional steering" label. — justified

[FIRST-PRINCIPLES-REVIEWED] 2fbd5c1

Description read

[DESCRIPTION-READ] f1268ccc0ac4786f69a7044797073f0262fbf7870f68428798d1b99113528237

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 2fbd5c1

@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from 724b9c8 to 2cadabf Compare September 24, 2026 16:39
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 2cadabfe2 (fixes 724b9c8e8 findings):

GPT F1 — empty list bypassed the dashboard-only rule (fixed). The if wanted and not caller_key.startswith("dashboard:") guard exempted [], so a verified channel-bound app-less caller reached the endpoint with the person's authority and could erase a folder's stored steering, which keeps no prior value. The guard is now keyed on the caller alone: every non-dashboard: caller is refused before any read about the target, clearing included. Pinned by test_a_channel_bound_caller_cannot_clear_either (asserts the only GET is the identity gate's slot read and no PATCH is made) with test_the_dashboard_caller_may_clear as the contrast; mutation probe (restoring the wanted and prefix) fails the new pin. Tool description, channel.py and registration-test comments, session-control.md, config.md and the feature-map row now describe the rule as set-and-clear.

First Principles — unsupported "stated posture" claim (addressed in the body). Replaced with the concrete gap: every other dashboard folder setting already has a chat_folder_* verb; steering was the one without. Item 7 (the tree description's archived-count sentence) is now declared in What changed.

Design — tree exposes steering=[…] host paths to channel-bound callers (kept, noted). Same class of path as the project= field the same read already renders to the same callers; called out in the body.

Opus lane was verdict-less (review incomplete); the fresh sha re-rolls it.

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 2fbd5c1

@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from 2cadabf to 63b5a90 Compare September 24, 2026 17:11
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 63b5a90e1 (fixes the 2cadabfe2 finding):

GPT F1 — a Slack-linked dashboard tab passes the dashboard: prefix test (fixed). Correct: link_slack records the thread on the slot, not in the key, so a reply in a linked thread runs under dashboard:<slot> and the prefix test admitted it. The key cannot tell a thread reply from a typed turn, so the tool now refuses on the slot's recorded shape instead: after the identity gate it re-reads /api/chat/slots, finds its own row, and refuses (_refuse_channel_reachable_slot) while any channel link is on record — links non-empty (covers out links and a channel-born origin row, since a human reply there brings the session back), slack_linked, or linked_session_key — for every turn in that tab, set and clear alike. A key naming no live row is refused too rather than assumed clean. Pinned by TestTheDashboardKeyIsNotProofOfDashboardWords: four link shapes × set/clear all refused with no PATCH, the missing-row case, and an unlinked tab as the contrast; mutation probe (dropping the three shape checks) fails 8 pins. Tool description, session-control.md, config.md and the feature-map row describe the rule.

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.

@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from 63b5a90 to 69c5415 Compare September 24, 2026 18:19
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 69c5415cc (fixes the 63b5a90e1 finding):

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. _run_chat already receives the queue's _directive_channel_origin flag (set by the linked-thread intercept, never by a typed message); it now stamps that on the slot (_turn_channel_origin, transient, never persisted) as its first statement, and the slot projection reports it as turn_channel_origin ANDed with turn_running, so it describes the running turn only. _refuse_channel_reachable_slot checks that boolean first and refuses set and clear on it; the link-shape clause stays as a second, independent refusal (a linked tab is not a dashboard-only surface between channel turns, and it fails closed on a row with no stamp).

Pinned by TestTheRunningTurnsProvenanceOutranksLinkState: the exact post-unlink row (stamp True, every link field clean) refused for set and clear with no PATCH; provenance reason wins when a link is also present; only a real True counts; _ChatSlot.to_dict() reports the stamp only while a task is running (stamped-but-idle → False); and _run_chat's first statement is the stamp. Mutation probe (dropping the provenance check) fails 3 pins. test_chat_slot_facade_contract key tuple updated for the new row field.

Backend Lint red on 63b5a90e1 was a runner kill (exit 143, no black verdict emitted); the changed files are black-clean locally.

@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from 69c5415 to 85194fc Compare September 24, 2026 18:52
@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 24, 2026
@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from 85194fc to b269491 Compare September 24, 2026 19:43
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for b269491fe (fixes the 85194fcb6 finding):

GPT F1 — an app-owned dashboard session could clear (fixed as suggested). Correct: the gate's caller_app was discarded, and the endpoint refuses an app or member only a non-empty list while letting it clear a folder it owns — which only the person could have declared. The tool now refuses on a non-empty caller_app immediately after the identity gate, before any read, for set and clear alike. It also refuses a crew-member session (mode == "member" on the caller's own row, which carries no app), so both non-person principals get one rule. Pinned by TestOnlyThePersonMayClearToo: app-owned and member sessions refused for set and clear with no PATCH and no folder-list read, with the person's own clean tab clearing as the contrast; mutation probe (dropping both refusals) fails 4 pins. Tool description, session-control.md and config.md updated.

85194fcb6 was an identical-tree re-roll of 69c5415cc, whose GPT run failed in the review pipeline without publishing; Opus was ✅ there.

@billygerhard
billygerhard force-pushed the feat/folder-steering-mcp-tool branch from b269491 to d8026f2 Compare September 24, 2026 21:40
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for d8026f299 (fixes the b269491fe finding):

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.

_ChatSlot._channel_turn_seen (replacing the per-turn _turn_channel_origin) is sticky: set whenever a channel-flagged message is queued (queue_append / queue_insert) or run (_run_chat entry, which also covers the idle-slot intercept that dispatches without the queue), never cleared, persisted as channel_turn_seen in both slot-metadata writers and read back on restore, and projected as channel_turn_seen on every slot row. The tool refuses set and clear on it before the link-shape clause, which stays as an independent refusal for a linked tab before any reply has arrived. The person uses a fresh dashboard tab or Folder settings.

Pinned by TestAConversationChannelWordsEnteredIsMarkedForGood (9 cases): the marked, idle, fully-unlinked row refused for set and clear; mark reason wins over a link; only a real True counts; a channel enqueue marks and later unflagged successor/completion/typed messages plus an unlink never unmark; queue_insert marks; the runner marks a direct dispatch and has no path writing False; both persistence writers and the restore carry it. Mutation probes: dropping the tool refusal fails 3, dropping the enqueue mark fails 2. 129 persistence/queue/slot suites (8,682 tests) green locally.

@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 24, 2026
@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 0d0cca2c91 -> b775b9a2fa: the GPT finding (upheld by Opus) on 0d0cca2c91.

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 human_only steering card has none, so it showed a short label beside Allow once / Reject without the folder or directories. website/src/components/chat-input/approval.ts now always expands the bar when no tool call backs the approval. A new case in ChatInput.approval.test.tsx fails without the change and passes with it; typecheck, lint and the ChatInput suite pass.

The PR body now carries a pod screenshot of the card showing folder_id, folder and steering_dirs, and the Manual verification section describes that run.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for b775b9a2fa -> c9f0b9ea28: rebase onto origin/main to re-run three reds outside this diff. GPT, Opus and Screenshot Evidence passed on b775b9a2fa.

  • E2E: the Playwright suite ran past its 1020 s bound (main's CI hit the same E2E failure at the time).
  • Integration: test_a_second_boot_touches_only_known_module_globals flagged kiro_crew.atomic_write._default_mode; this PR does not touch atomic_write.
  • Windows shard 4: test_crew_log_emit.py::test_the_repair_is_queued_under_the_predecessor_not_the_successor; this PR does not touch crew-log code.

No code changes. 698 related tests, black, comment-history, feature-map and mypy pass on the new base.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for c9f0b9ea28 -> 6c5032b4b2: rebase onto main (one CHANGELOG-only commit), no code change.

On c9f0b9ea28 the only red was Backend Tests (Windows) shard 5: test_agent_sdk_context_bridge.py::test_context_import_orders_do_not_form_a_cycle hit its 30-second subprocess timeout while importing kiro_crew.essential_delivery / providers.base / context, modules this PR does not touch. It passes locally. Integration, E2E and the review lanes passed on that head; this push re-runs the Windows shard.

@iamwhatever

Copy link
Copy Markdown
Contributor

This PR adds a new MCP tool, chat_folder_steering_set, that lets an agent set the steering directories for a chat folder. That is a new feature and a product decision about what an agent may change in its own steering context. I am holding because the brief's HOLD rules apply. It is a new agent-facing capability, not a fix. It changes the permission and approval surface (test_approval_modes_enforcement.py, test_folder_steering_principal_gate.py, test_app_route_trust_gate.py, chat-input/approval.ts), and an agent that can redirect steering can change its own instructions. Production changes are about 700 lines across 16 files. Two lanes report CONCERNS. A maintainer should decide whether agents may set steering directories at all, and under which approval mode, before a line-level review. I checked the file list, the lane verdict counts and that no review is open. — crew-pr-reviewer

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 6c5032b4b2 -> 687d846073: rebase onto main to clear a conflict, no code change.

6c5032b4b2 was fully green. The only conflict was the Session folders row in docs/feature-map/README.md: main changed its frontend-files column, and this PR changes its feature-description and backend-files columns. I resolved it column by column, keeping main's column and re-applying this PR's two, so the file differs from main only by this PR's edits. 706 related tests, the black ratchet, the comment-history and feature-map gates, and mypy on the changed source all pass locally.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 687d846073 -> 3964c40757: rebase onto main to pick up #18580. The only red on 687d846073 was Frontend Tests (1) in focusRingContrast.test.ts, flagging AskAnswersCard.tsx (not in this diff; fixed on main by #18580); Frontend Coverage Merge, Coverage Gate and PR Readiness failed downstream of it. No code changes in this push. Locally: 706 related backend tests, the focus-ring contrast test, black, mypy, comment-history and feature-map gates pass.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 3964c40757 -> fa73a6d779: rebase onto main to re-run reds outside this diff. GPT and Design passed on 3964c40757; Opus 5.5 Review ended "review incomplete" with no verdict. Linux shard 4: test_pid_reader_ratchet.py::test_every_needle_finds_a_site hit the 120s timeout (tree scan). Windows shard 1: test_builtin_skill_sync_safety.py save-after-publish test hit WinError 5 renaming the skill directory. Coverage Gate and PR Readiness failed downstream. No code changes. Locally on the new base: 883 related tests incl. the registration/composition contracts, black, mypy, comment-history and feature-map gates pass.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for fa73a6d779 -> 960ca3a47e: rebase onto main to re-run E2E. On fa73a6d779 GPT and Opus had no blocking findings and Design passed; the only red was E2E, where member-memory.spec.ts > a legacy configured default member keeps V1 while new members receive independent V2 memory passed only on retry (this diff touches no member-memory code or spec). PR Readiness failed downstream. No code changes. Locally on the new base: 883 related tests, black, mypy, comment-history and feature-map gates pass.

@iamwhatever

Copy link
Copy Markdown
Contributor

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

@iamwhatever

Copy link
Copy Markdown
Contributor

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

@billygerhard

Copy link
Copy Markdown
Contributor Author

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 owner_only before the person-only check runs, so this PR's person-only tests accept either refusal code; the no-side-effect assertions are unchanged. 718 related tests, black, mypy, comment-history and feature-map gates pass locally.

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

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)

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 3a2d91fb0f -> 1cefdbefdc: the requested change on the approval wait.

The approval no longer holds a dashboard tool call open. An agent's steering_dirs PATCH now raises the human_only card and answers 202 pending_approval at once; the person's answer, the on-disk validation and the write run afterwards in a background task. An unanswered card no longer stalls other sessions' kirocrew-dashboard calls. A new test asserts the agent gets its answer while the card is still pending, and fails if the handler waits for the card. The longer client timeout the blocking wait needed is gone, and an agent's steering PATCH may carry no other field.

The card shows the change. It lists the folder's current_steering_dirs next to the new steering_dirs, and a clear reads "removes all N directories". The PR body has a new pod screenshot of this card, taken while the agent's call had already returned.

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.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for 1cefdbefdc -> e61723f34f.

Backend shards (wait-discipline ratchet). This PR's own tests added short fixed waits (wait_for(..., 5), a 10 ms sleep loop). They now use kiro_crew.testing.wait (await_until / async_wait_until), so a hang fails by name under the lost-run bound. The 202 test still fails if the handler waits for the card, now with a named assertion instead of a timeout.

UX block. The card names the request and the folder: it is titled [Folder steering] Change steering for "<folder>" and shows the purpose line in the bar, which a coordinator card previously had no source for. Its rows are labelled Folder, Change (on a clear), Current, New, with Folder id last so a short bar clips the id, not the name. The PR body now has pod screenshots of a change card and of the clear card ("removes all 2 directories").

GPT and Opus had no findings on 1cefdbefdc. Locally, 1,053 related backend tests pass, plus 63 message-box tests, typecheck and eslint. The new purpose-line assertion fails without its approval.ts change.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Disposition for e61723f34f -> 110602ca2f. GPT and Opus had no findings on e61723f34f. Frontend shard 2 failed in useWebSocket.frameTrace.test.ts: its golden frame trace pins the exact meta of each coordinator approval message, and this PR now carries tool_purpose there so the bar can show a coordinator card's purpose line. The five expected traces are updated to include it, with no runtime change. Also rebased onto main; the only conflict was the feature-map Session folders row, resolved per column. Locally the full frontend suite (39,645 tests), typecheck, eslint, 1,053 related backend tests, black, mypy, and the comment-history and feature-map gates pass.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Rebased onto main 63c155a582 to pick up #19485 and #19478, which fix the lint and backend-shard failures on the previous head. No code changes; the only conflict was this PR's Session folders row in docs/feature-map/README.md. Locally: black, mypy, flake8, comment-history and feature-map gates pass, plus 864 related tests. test_no_file_gains_a_short_fixed_wait also fails on bare main (test_surface_deny_notice_sites.py and test_webhook_permission_requests.py, from #19259); this PR touches neither file.

@billygerhard

Copy link
Copy Markdown
Contributor Author

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 test_the_card_has_no_deadline_of_its_own pins it (with a deadline put back around the card, it fails). Watch 2, crew-window approvals: left for now. The owner-only resolve gate is what keeps the agent from approving its own card. Suggestion (coordinator hook): not taken in this PR, to keep it small. The remaining backend red, test_no_file_gains_a_short_fixed_wait, also fails on main (test_surface_deny_notice_sites.py, test_webhook_permission_requests.py); this PR touches neither file.

@billygerhard

Copy link
Copy Markdown
Contributor Author

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 /tmp, a missing directory, a sensitive path), the person now gets a system.agent bell notification saying why nothing was saved, in addition to the audit row. The notice is redacted, because the resolved path never appeared on the card. test_an_approved_link_that_resolves_elsewhere_stores_nothing pins it: with the notice removed, it fails. Asking again with the resolved path on a second card would make the PR bigger, so it isn't in this one. Watch 2 (approval-bar rule): the change only shows the bar straight away for a coordinator approval that has no in-chat pill to mirror, instead of after the settle delay. Spawn and subagent cards gain an earlier bar and lose nothing, so it is left as is. The Windows (2) red is test_no_file_gains_a_short_fixed_wait, which also fails on main.

@billygerhard

Copy link
Copy Markdown
Contributor Author

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 409 steering_approval_pending, so an agent asking in a loop can't stack cards. _PENDING_STEERING_WRITES is now keyed by folder id, and its entry is released when the card's task ends. test_a_second_card_for_a_folder_already_asking_is_refused pins it: with the check removed, it fails. UX (missing evidence for the refusal notice): the PR body now has the bell feed and the opened notice, captured on a pod by approving a link that resolves elsewhere. UX watch 1 (New list cut off): the card now lists New above Current; see the new change-card screenshot. Purpose wording changed to "loaded into every chat in this folder". Design (approval bar reaches spawn and subagent cards): the always-on bar now applies only to a coordinator card that carries input, so cards with empty input keep the settle guard. The Windows (7) red is test_auto_research.py::...test_settlement_failure_is_logged_without_replacing_cancellation, which this PR doesn't touch.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Rebased onto main to re-roll E2E (stub ACP backend). On 7d31b2e58b all 323 browser tests passed (0 unexpected, 0 flaky), but the run took 1,020s and hit the suite's time limit. Other open PRs' E2E jobs take 14 to 17 minutes, so this was a slow runner, not a test this PR slowed down. No code changes. Locally: black, flake8, mypy, comment-history and feature-map gates pass, plus 768 related tests. Design (the human_only check sits in each resolver): the Slack resolvers it names only answer approvals mirrored to a Slack-linked session (post_linked_approval, from the ACP tool-permission path in chat_runner), and the endpoint refuses a steering write from any session a channel can reach before it raises a card, so a steering card never reaches those paths. Moving the check into resolve_approval is left out of this PR to keep it small. UX (no confirmation after a save): advisory, not taken; the folder's steering list updates in Folder settings when the write lands.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Rebased onto main to re-roll E2E. On 3cb57abd62 the only failure was member-memory.spec.ts "V2 previews and atomically edits 65 email memories across pages", which wedged the E2E gateway until the loop-stall alarm stopped it (exited with -14). That is the open flake #18632; this PR doesn't touch member memory. GPT and Opus had no findings on that head. No code changes. Locally: black, flake8, mypy, comment-history and feature-map gates pass, plus 768 related tests.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Rebased onto main to clear a conflict. Main added session_continue to the same tool lists, so with this PR's chat_folder_steering_set the kirocrew-dashboard count is now 34 (docs/architecture/mcp.md, docs index, session-control.md). The feature-map Session folders row is kept as this PR has it. No code changes. Locally: black, flake8, mypy, comment-history and feature-map gates pass, plus 1,192 related tests including test_session_control_doc.py. E2E on 1b03d3ba80: every test passed except chat.spec.ts Soft-Stop budget expiry and member-memory.spec.ts V1 automated overwrite, and the run hit the 1,020s suite limit. Neither spec touches folders or steering. GPT and Opus had no findings on that head, and Design passed.

@billygerhard

Copy link
Copy Markdown
Contributor Author

Rewrote the agent surface onto the existing change-card mechanism, per the First Principles finding. A new folder.steering card kind is proposed with propose_change and applied by the person's browser through the existing folder PATCH. The bespoke tool, the person-only approval card, the background write, the 202/409 paths and the approval-bar change are all removed. The folder routes now refuse a direct steering_dirs write from the internal credential, so the card is the agent's only route. Diff: 12 files, +421/-11 (was 26 files, +2015). Head c1f7714.

@billygerhard

Copy link
Copy Markdown
Contributor Author

f816a8a: the folder.steering card's Undo now carries the list the card stored as expect_steering_dirs, and the folder PATCH compares it under the store lock before writing, so a steering save from another tab after Undo's check gets 409 steering_dirs_changed instead of being overwritten. New test test_undo_does_not_overwrite_a_save_made_after_its_check; it fails with the compare removed.

@billygerhard

Copy link
Copy Markdown
Contributor Author

ee1b152: Apply now carries expect_steering_dirs (the list the card checked) like Undo, so a Folder-settings save that lands while Apply's PATCH is validating gets 409 steering_dirs_changed instead of being overwritten (test_apply_does_not_overwrite_a_save_made_after_its_check). Each proposed directory is also resolved the way the folder route stores it, so the card shows and writes the list the gateway actually reads, and Undo is offered on linked paths (test_the_card_shows_and_writes_a_linked_dir_as_the_route_stores_it, test_a_dir_the_route_would_refuse_is_refused_at_proposal). Each fails with its change removed.

@billygerhard

Copy link
Copy Markdown
Contributor Author

8eb0a55: folder.steering directory strings are now bounded by the folder route's own 4,096-character limit (FOLDER_STEERING_DIR_MAX, pinned equal to MAX_FOLDER_STEERING_DIR_LEN) instead of the generic 512. The resolved list is re-validated at proposal, so a card the store could not rebuild after restart is refused up front rather than dropped. test_a_long_canonical_dir_the_route_accepts_survives_a_rebuild fails with the old bound.

@billygerhard

Copy link
Copy Markdown
Contributor Author

f44d021: the expected steering list now travels as a request attribute the card hook arms on each Apply/Undo step (REQ_CARD_FOLDER_STEERING_EXPECT, beside the existing schedule and crewmate Undo guards), so the folder PATCH gains no body field and the person's own save is unchanged (test_a_plain_folder_patch_cannot_supply_the_expected_list). The Apply and Undo race tests now inject the other save just before the store lock and go through the real card step; each fails with the arming or the compare removed. The card adds a Change row marking added (+) and removed (−) directories. The PR body has new pod screenshots at this revision: the add card, applied with Undo offered, after Undo, and the conflict refusal.

… 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.
@billygerhard

Copy link
Copy Markdown
Contributor Author

2fbd5c1: on a card Apply/Undo step, the folder PATCH now refuses (409 steering_dirs_changed) when its re-validated list differs from the step's submitted list, i.e. a directory that resolves somewhere other than the path the card showed (swapped for a link after approval). Ordinary folder PATCHes are unchanged. test_apply_refuses_a_dir_swapped_for_a_link_after_approval fails with the check removed. The PR body also adds screenshots of the remove card (− chip, no widen box), it applied, and the clear card (New empty).

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

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)

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

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants