Repository navigation
feat(board): governed agent self-tagging via a chat_tag session directive + [BOARD] context line - #7779
Conversation
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS On every upgraded install the feature ships dark: default workflow states seed human-only, and the refusal reads WatchThe upgrade path seeds the five default state ids as Suggestions
[DESIGN-REVIEWED] df9bd33 |
GPT 5.6 Review (fork) — 🔴 changes requested (blocking)Reviewed 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands. BLOCKING -- src/kiro_crew/dashboard/chat_tag_grants.py:222 -- Ephemeral secret certifies persistent grants
Adjudication (Opus 4.8) — is blocking on each finding proportionate?I've reviewed the finding, the diff for F1 —
This clears the FLAG bar: the record is complete, the loss is fail-closed and recoverable (so a wrong clearance is not unrecoverable), and the condition set is confined to an already-broken environment a human would plausibly accept. [ADJUDICATION] df9bd33 total=0 uphold=0 downgrade=0 [ADJUDICATION-FENCED] df9bd33 fenced=1 flagged=1 🏷️ Fenced finding(s) machine-flagged as likely edge caseThe security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override recorded by a repository writer, who must independently verify a rationale before recording it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop. (This lane's comment deliberately carries no override command.)
|
First Principles Review (Fable 5, fork) — 🔴 BLOCKPremise-level review of First-Principles-Verdict: BLOCK Fresh installs get agents retagging their own sessions by default — a first-class agent's default behavior, decided in issue #7774, with no RFC on the base. Not justified as shipped
What this change shipsInventory (10 items, capped — refusal codes and revision-CAS details omitted) — 8 justifiedIntent: let an agent move its own session between board workflow states under a human-controlled authorization layer — an ADDITION.
Blockers
[FIRST-PRINCIPLES-REVIEWED] df9bd33 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsBoth candidates concern Candidate 1 (add-only status tag unreachable): Traced. Candidate 2 (no-op READ path unreachable): Traced. Policy gates (lines 1574–1615) run before the Neither survives Step 1. No new finding rises to the 80+/(a)(b)(c) bar in the code I opened; the applier's list-valued-id and rebind paths are all guarded, and the write-ordering/crash-atomicity handling in the grants store and CRUD is fail-closed by construction. No findings. [OPUS-REVIEWED] df9bd33 |
60ab955 to
5a114fe
Compare
Review round 1 — all lanes addressed in
|
5a114fe to
6c7baf8
Compare
Review round 2 — GPT blockings addressed in
|
6c7baf8 to
f8026a0
Compare
f8026a0 to
3a88fc8
Compare
|
Round on F1 — agent-controlled tag IDs can reach the trusted
Test: a tag F2 — duplicate display names resolve to an arbitrary tag (FLAG, agree). Every op the collision can misdirect is already gated by the per-tag grant, the canonical id always wins the collision, and the precondition is a human giving two already granted tags the same display name. Bounded, visible, recoverable. F3 — token-key rotation discards default grants (FLAG, agree). This is the documented fail-closed rotation: store quarantined by rename, 227 across the tag/board/contract/ratchet suites, 1542 in the wider context family (one unrelated |
|
|
Security Scope Review (fork) — 🟡 CONCERNSWhich legitimate operations does the reviewer's own judgement; no confirmed regression Scope-Verdict: CONCERNS TIGHTENING: ADJUDICATED: 14 candidates, 0 confirmed newly-refused PLATFORM COVERAGE: posix (8 rows), windows (5 rows), any (1 row). The diff declares the leaf with a POSIX separator relative to two home prefixes and relies on UNADJUDICATED: Most of this change's strictness lives in guards the shell classifier cannot see; no
[SCOPE-REVIEWED] df9bd33Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. |
|
|
|
@iamwhatever — could a maintainer add |
|
Not approving for now: the Fork workflow-change guard check is failing and the "Documentation updated" checklist box is unchecked, and this adds an agent write path governed by a trust-store permission policy, which I will not sign off on with either of those open. |
|
Thanks — both mechanical items are closed on
On the substantive point — an agent write path onto board tags, governed by the grant store — I am not going to argue you into it in a comment. The design as it stands: no tag is writable by an agent unless a human minted an explicit grant row for it ( |
|
Finding. In the PATCH handler a status flip without an explicit Fix. The protected row is read before the policy is derived (it was already read afterwards as the restore point; there is now one read serving both). A status flip keeps the recorded policy whenever a protected record exists; only a tag with no record at all takes the out-of-the-box Test ( 571 across the board/directive/runner families; isort/flake8/mypy, black (baseline-aware), comment-history and brand gates green; still no |
|
F1 — taken. First-boot ordering in F2 — not taken, by design. A transient token-key read failure past the retry budget quarantines the store (bytes preserved, never deleted) and reseeds trusted constants. Distinguishing that from a real key rotation needs the old key, which is exactly what is gone; certifying an uncertified store would bless a planted one identically. Fail-closed with one authenticated PATCH to re-mint is the intended answer, and it only occurs alongside full session invalidation, which is loud. F3 — not taken. Two consecutive storage-write failures inside one PATCH (the final mint and the rollback persist) can leave the vocabulary and the grant store inconsistent, but authority only ever collapses toward 572 across the board/directive/runner families; all gates green; no |
|
|
|
Rebased onto current |
|
First-Principles BLOCK — product-shape default without an accepted RFC. Upheld as a process gap, and not something this branch can clear by itself: the fork lane wants either a non-draft RFC on
Design CONCERNS — upheld: the description described the abandoned Await Fast Gate / Coverage Gate reds were the fork-run approval wait (Fast Gate concluded PR test files + context suites 371 passed; black/isort/flake8/mypy and the black/comment-history/brand gates green on the changed files. |
|
RFC opened as #11175 ( |
|
First-Principles items 8 and 9 on |
|
Opus FINDING ( Design CONCERNS — both upheld:
GPT BLOCKING (12-hex syntax taken as dashboard provenance) — the scenario is real but its remedy is a design choice, so I am routing it to the RFC rather than changing the code under it. Path: an agent plants a 12-hex-id row with FP items — item 5 ( PR test files + registry/context suites 426 passed; black/isort/flake8/mypy and the black/comment-history/brand gates green on the changed files. |
|
GPT BLOCKING 1 (unbounded read of a planted GPT FINDINGs — both fixed: the applier's identity check now requires Design CONCERNS (layering) — upheld: GPT BLOCKING 2 (compensation failure under disk exhaustion loses a grant) — not changed: the failure mode is a 500 with the grant absent, which is the fail-closed state the store is designed to land in (every tag resolves GPT BLOCKING 3 (alias mirroring after the pinned save) — not changed this push: the ordering it proposes (mirror aliases before the pinned save, roll back if refused) touches the shared slot-save path that every directive uses, not just Design CONCERNS (no live turn showed the PR test files + registry/context/sandbox suites 1,997 passed; black/isort/flake8/mypy and all repo gates green on the changed files. |
|
First-Principles is now CONCERNS, not BLOCK (the default is "arguably product shape"); it clears with #11175 or the override. Item 6 ( Design watch 2 (store-unavailable indistinguishable from a policy denial) — upheld and fixed: Design watch 1 (upgrade leaves customized boards degraded, recovery not discoverable) — agreed and disclosed; the fix is the #7774 tag-manager control. Release-note text for the double-toggle recovery belongs with the release that ships this, so I have not put it in this diff. GPT BLOCKING (journal the cross-store transaction) — as dispositioned on the previous head: the residual state after a compensation failure is fail-closed and self-heals on the next successful PATCH; a startup journal would add a second authorization-bearing file to the trust model. Not re-arguing further here; if a maintainer wants the journal, say so and I will add it. PR test files + registry/context/sandbox suites 1,999 passed; black/isort/flake8/mypy and all repo gates green on the changed files. |
|
Design watch 2 ( GPT BLOCKING ( Remaining reds are all decisions, none of them code I can make on my own:
Until a maintainer answers those on #11175 or here, further pushes only re-run the lanes; I will rebase and follow whatever is decided. |
|
Rebased onto current |
|
GPT BLOCKING (a transient read error at boot quarantines valid grants) — upheld and fixed at class level. Design's watch (governance layer without its control surface) is decision 3 on the list above and unchanged. The hold on decision-shaped findings stands. PR suites 2,043 passed; black/isort/flake8/mypy and all repo gates green on the changed files. |
… + [BOARD] context line An agent can now move its OWN session between workflow-state tags (and add/remove ordinary tags) through a stateless chat_tag session directive, under backend-enforced governance (issue kirodotdev#7774 v1): - chat_tag MCP tool (control.py) modeled on set_project; registered in DIRECTIVE_TOOLS; applied via session_directive_apply through the existing tags_write_lock -> validate_folder_tag_ids -> save_slot_off_loop chokepoint, SEL-audited. - Per-tag agent policy (agent: add-remove | add-only | none) resolved in chat_tags.agent_tag_policy; status:True tags default add-remove so the workflow set works with no vocabulary migration; user tags default human-only. - set_state enforces workflow mutual exclusivity across all status:True tags; refuses (never silently strips) a human-only status peer. - Named refusals: tag_policy_denied / unknown_tag / no_op; success result returns the resulting tag list (first agent-readable tag surface). - Cron/subagent turns refused via _USER_SURFACE_DIRECTIVES. - [BOARD] context line injected per turn (tags + agent-writable set), resolved in chat_runner alongside folder_path. Part of kirodotdev#7774 (v1 of 2 — does not close the issue).
|
Rebased onto current |
Problem / Motivation
A user managing many concurrent sessions has no way to see at a glance what is pending on them versus what agents are still working. Agents cannot participate in board organization at all: no MCP tool can set a workflow-state tag, and an agent cannot even read its own session's tags. The board only stays truthful through manual grooming.
Why it matters
Handoff visibility is the core value of a session board: an agent that finishes its work should be able to tag its own session
Reviewon its last action, so filtering byReviewanswers "what needs me" across dozens of sessions. Without an agent write path, workflow tags rot the moment the user stops hand-maintaining them.What changed (motivation → approach → change)
Goal: let agents move their own session between workflow states — under governance, because the board is also the human's tool. Approach chosen (over a backend rules engine and over unrestricted tooling): agents own the judgment of when to move; a fixed backend authorization layer owns who may move what. "Turn ended with nothing actionable ⇒ Review" style inference was deliberately rejected — the agent must explicitly declare the transition. Design discussed in #7774.
Built (v1 of the issue's two-stage plan — self-only, tags-only):
chat_tagMCP session directive (mcp_tools/control.py, modeled onset_project; registered inDIRECTIVE_TOOLS; two-layer schema with acustom_validatorenforcing at-least-one ofset_state/add/remove). Applied insession_directive_apply.pythrough the existingtags_write_lock → validate_folder_tag_ids → save_slot_off_loopchokepoint, with freshslot.tagsreads inside the lock and SEL audit (chat.self_tag, allowed/denied).chat_tags.agent_tag_policy/agent_tag_grant, backed by the newdashboard/chat_tag_grants.py):add-remove|add-only|none, read from<data home>/tag-grants/agent-tag-policy.json— a NEW dedicated leaf, masked from sandboxed processes (sandbox._CREW_HIDDEN_LEAVES, pre-created at 0700 before every namespace spawn) and fenced from the agent file tools and shell (security._CREW_SECRET_LEAVES), so only the gateway opens the path (GPT review finding: policy fields on agent-writabletags.jsonrows could be forged and survive restart). Rows carry an HMAC provenance chain keyed undertoken_signing.key; a key rotation the gateway did not observe quarantines the store (fail closed) rather than trusting it. Writers are the authenticated dashboard tag CRUD only: create mints the out-of-the-boxadd-removefor workflow-state tags, PATCH re-mints/revokes on a status flip and accepts an explicitagentpolicy, delete revokes. The boot seed mints rows ONLY for the five code-constant default state ids — never fromtags.json, which is agent-writable and must not be promoted into authorization. Upgrade behaviour: an existing install starts with an EMPTY store, so every pre-existing tag resolves human-only until a dashboard PATCH re-mints it (a status double-toggle, or anagentvalue via the API). A hand-planted id outside the grant grammar (12-hex dashboard id or a default state id) is refused any grant (tag_id_not_grantable). Everything fails closed tonone/non-status;remove— including the implicit removal inset_state— requiresadd-remove.set_statestrips every otherstatus: Truetag, keyed on the flag rather than a hardcoded id list so custom status tags participate; a human-only status peer is refused rather than silently stripped.tag_policy_denied:<tag>,unknown_tag:<tag>,no_op) and a success result carrying the resulting tag list — the first agent-readable tag surface. A refusal the store cannot vouch for is named as such: when the grants document is unreadable, gone, or was quarantined this boot and the tag has no row, every store-derived refusal readstag_grants_unavailable:<tag>instead of a policy/status code, so the agent tells the user the store needs attention rather than reporting a reservation nobody made (chat_tag_grants.store_degraded()).chat_tagadded to_USER_SURFACE_DIRECTIVES, so cron/subagent turns are refused.[BOARD]context line (context.py+chat_runner.py): one per-turn line showing the session's tags and which are agent-writable, resolved inchat_runneralongsidefolder_pathsocontext.pystays free of dashboard/state imports. The closed grant grammar (DEFAULT_TAG_IDS,is_grantable_tag_id) lives in the dependency-freekiro_crew/board_tag_grammar.pysocontext.pycan screen the rail with it without importingkiro_crew.dashboard;chat_tag_grantsre-exports it for the mint (pinned bytest_grant_grammar_is_dashboard_free_for_context). Only grant-row-backed ids in the closed grant grammar render on this trusted rail; the agent-writable subset is listed beside them.API changes to declare:
POST /api/chat/tagsandPATCH /api/chat/tags/{id}now return400 invalid_statusfor a non-booleanstatuswhere they used to coerce (bool("false")isTrue, which would have minted authority from a mistyped string). A client that serialised the flag as a string must send a JSON boolean.400 status_requiredwhen anagentvalue is set on a tag that has no protected row and the request carries no explicitstatus— the store must record the tag's status bit from the authenticated request, never infer it from agent-writabletags.json. On an upgraded install that is every pre-existing custom tag, so the post-upgrade "grant the agent this tag" PATCH must includestatus.chat_tag set_staterefuses outright (status_identity_unprotected) when the session carries a custom status tag with no identity row in the store: the mutual-exclusivity strip would otherwise have to trust the file'sstatusflag to decide what to remove. Resolution is the same re-mint PATCH. (Default state ids get identity-only rows at boot, so this stop only hits custom status tags after upgrade.)agent: add-remove | add-only | none. In this v1 that field is API-only: the dashboard's tag manager still sends onlystatus, so a human sets a per-tag agent policy through the authenticated API. Thechat_tagtool description names the recovery (status off/on in the tag manager, or a PATCH with explicitstatus) beside thestatus_identity_unprotectedrefusal. The UI control (and a discoverable upgrade re-mint affordance) is the tracked follow-up on feat: agent-driven board organization — governed self-tagging, per-tag agent policy, and a [BOARD] context line #7774; the create-mint default and the status-flip re-mint/revoke are reachable from the existing UI.Out of scope here (v2, tracked in #7774): folder moves, conductor-over-children, propose-confirm for human-placed state, move budgets/cooldowns.
Tests
New
test/test_chat_tag_directive.py(plustest_session_directive.pyadditions):set_state reviewreplaces an existing workflow tag and returns resulting tags (mutual exclusivity).none-policy tag is refusedtag_policy_denied; anadd-onlytag adds but refuses removal (asymmetric add/drop).unknown_tag; repeated state isno_op._USER_SURFACE_DIRECTIVES.DIRECTIVE_TOOLS).state._tags_authoritative=Truemirroring real boot.TestBoardContextLineAssembly: the[BOARD]line asContextBuilder.build_messageemits it — tags plus the agent-writable subset,(none)when all are human-only, omitted when the slot has no tags, ungrantable ids dropped from the rail.tag_id_not_grantable, strict-booleanstatus(test_chat_tags.py).tag_grants_unavailable, gone → same, healthy re-seed → policy answers return; a boot quarantine sticks for the process while a re-seeded default keeps its policy answer (test_degraded_store_refuses_as_unavailable_not_denied,test_quarantine_sticks_for_the_boot).OSError) is NOT quarantined — the boot pass resolves zero grants for this boot and leaves both files untouched; only a successfully read but invalid document is quarantined; the writer path surfaces a transient key-read failure instead of minting a fresh key over the valid one (test_transient_read_error_at_boot_does_not_quarantine[key|store],test_transient_key_read_error_does_not_clobber_the_key_on_write)._read_bounded_json(regular file, size-capped) so a file planted in the leaf before the boot that creates the store cannot cost an unbounded read or parse;test_oversized_planted_files_are_quarantined_without_being_parsed.resolve_board_tagsskips a malformed vocabulary row (list-valued id) instead of raising and losing the[BOARD]line gateway-wide;DEFAULT_TAG_IDSis pinned equal to the status ids instate._DEFAULT_TAGS.Suites run locally:
test_chat_tag_directive.py,test_session_directive.py,test_chat_slot_project.py,test_mcp_tool_registry.py,test_context_management.py— 179 passed; black gate clean.Manual verification
N/A — unit coverage sufficient: the directive path, policy matrix, exclusivity, and surface gating are all exercised end-to-end at the applier; the
[BOARD]line's assembly is pinned byTestBoardContextLineAssemblyagainstContextBuilder.build_message.Related Issues
Part of #7774 (v1; the issue stays open for the per-tag policy UI control and for v2 — folder moves and conductor scope).
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)docs/architecture/mcp.md,docs/system-specs/modules/session.md