Skip to content

Latest commit

 

History

History
5583 lines (5179 loc) · 383 KB

mcp.md

File metadata and controls

5583 lines (5179 loc) · 383 KB

MCP Server Architecture

How MCP (Model Context Protocol) servers are configured, merged, probed and loaded, plus the two invariants every new Kiro Crew MCP tool must satisfy: it ships as an MCP tool (not only a CLI command), and it holds no per-caller state.

Async spawn receipts declare supported parent-work delivery (dashboard/handlers/messaging.py::parent_work_supported). See the subagent contract for the enforced limits and model-only value judgments.

Related: the CPP extension-point seam this doc reads from is platform-context; the governance ceiling that filters auto-approve is governance; the computer-use server's own gate model is computer-use.

Design invariant: Kiro Crew does NOT write to provider globals. ~/.kiro/settings/mcp.json is user-owned. Kiro Crew reads it and never mutates it. Kiro Crew's own additions go into the per-agent file it fully owns, ~/.kiro/agents/kirocrew.json. That keeps tools scoped to Kiro Crew out of every interactive kiro-cli and Kiro IDE session the user runs outside Kiro Crew. If kirocrew-core / kirocrew-cron ever appear in a provider global, that is leftover state from an older install: clean it from the dashboard MCP panel, or run kirocrew setup, whose setup path calls the narrowly scoped mcp_cleanup.clean_stale_managed_mcp() helper.

Config file hierarchy

File Owner Purpose Read by
~/.kiro/agents/kirocrew.json Kiro Crew gateway (agent.rebuild_agent_config) The rendered Kiro agent: model + tools + merged mcpServers kiro-cli, when spawned as the kirocrew agent
~/.kiro/settings/mcp.json User Kiro global MCP servers kiro-cli for all agents; merged into Kiro Crew's agent file at render time
~/.kiro/crew/mcp.json User, via the dashboard MCP panel specific to Kiro Crew additions and per-server tool disables Kiro Crew gateway only

Kiro Crew reads every MCP config file (~/.kiro/crew/mcp.json, ~/.kiro/settings/mcp.json, and every seam-contributed scope global) as JSONC: comments and trailing commas are tolerated (user_json.loads_user_jsonc), so a commented-out server never discards the rest of the file. The dashboard MCP panel's writers emit plain JSON, so a save over a file that holds comments or trailing commas is refused with a 409 mcp_config_has_comments (_refuse_commented_config / McpConfigHasComments) rather than rewriting the file and dropping them; edit such a file by hand, or remove the comments first.

rebuild_agent_config() writes exactly one file, ~/.kiro/agents/kirocrew.json. There is no second rendered agent file: Kiro Crew's provider is ACP-only, and non-kiro ACP harnesses consume projected configuration rather than another Kiro agent file.

Provider-global scopes come from the platform seam, not the core

A provider-specific global (Claude Code's ~/.claude.json, for example) is not read by this build. It is contributed at call time by the CPP extension point McpToolingProvider.extra_mcp_scopes() (platform/interfaces.py), and the public DefaultMcpToolingProvider (platform/defaults.py) returns []. So in this repo:

  • agent._extra_mcp_scope_globals() yields no paths, so the rebuild merges the Kiro global only.
  • mcp_discovery._extra_scope_sources() yields no extra scopes, so discovery scans the two core files only.
  • dashboard/handlers/mcp.py's apply and uninstall paths (with mcp_config_purge.py) write the Kiro scope only.

The three stay symmetric on purpose. If discovery scanned a file that apply and uninstall could not manage, a server would show up in the dashboard that the dashboard could never remove, and the rebuild would keep re-merging it into sessions. agent._CC_MCP_JSON and mcp_discovery.SCOPE_CC_GLOBAL are retained as the canonical constants for a companion edition and for tests, not as evidence that the core reads that file.

Merge order in rebuild_agent_config()

The existing ~/.kiro/agents/kirocrew.json is the merge base when one exists and clean=False, so any server the user already customized survives (autoApprove edits, hand-edits, servers added with kiro-cli mcp add --agent kirocrew). Onto that base:

  1. App-contributed servers (_collect_app_mcp_servers()), keyed {app}:{server}, are assigned first so an app's namespaced entry outranks a same-named leftover in a shared file. Assignment, not setdefault: the manifests are authoritative and are re-derived on every rebuild, so keeping the previous rebuild's entry would preserve an autoApprove grant this pass had just stripped.
  2. ~/.kiro/settings/mcp.json (Kiro global). An absent name is added. A name a PREVIOUS rebuild left behind is reconciled: the transport-independent keys the source owns (timeout, disabled) are overwritten, and one the source has since dropped is removed, so an edit to the source reaches the generated spec instead of losing to the value the first rebuild froze. Every other key on the entry is the user's and survives by omission, autoApprove included. Reconciling retires the name, so a lower-priority scope cannot reconcile it again. command/url and headers are NOT reconciled — see the fallback's as-a-unit rule below. args and env ARE, but only onto an entry whose command names the same program the source declares (the discovery module's _commands_diverged, which reads the entry's resolved /…/bin/npx as the source's bare npx): the two are written for one program, so a source that kept its command and added an env variable or an argument later must reach the server it already runs, while a source that switched programs keeps the entry's old command/args/env pairing whole rather than lending its new env to the old command. The unit is projected, not merged: a key the source dropped is removed.
  3. Seam-contributed provider globals, so they can only fill gaps the Kiro global did not: a name step 1 or step 2 already claimed in this pass has been retired, so it is left alone. Empty in this build.
  4. ~/.kiro/crew/mcp.json via update() on an existing entry, so Kiro Crew's command/args/env win while user-set fields such as autoApprove survive.

Kiro global outranks any seam-contributed provider global because Kiro Crew is kiro-cli-only. Managed servers are skipped by every merge loop: their command/args are set by _refresh_dynamic_fields() and must not be overwritten by a stale global entry.

Resolution-aware fallback. The same server can be defined in several sources with different commands. If the merged winner's command does not resolve (a bare command whose binary is not on the rebuild PATH), the rebuild retries the same server's spec from the other sources in priority order (kirocrew, then kiro-global, then provider-global) before dropping it. When it falls back to a different source it adopts that source's command, args and env as a unit, so one source's command is never paired with another's arguments. Resolution, the dashboard probe, and the env.PATH written into the agent config all go through the same env.spec_env_path(), so a server cannot probe healthy on the dashboard while being silently dropped from the agent config — or launched from it with a PATH the probe never validated.

A spec's env is applied per key by the consumer that spawns the server, so a declared PATH replaces the child's inherited one rather than extending it. A spec that names one directory to add would therefore hand the server a PATH holding only that directory. spec_env_path() expands a declared env.PATH into the full effective PATH — the spec's own entries first, then the augmented inherited PATH, deduped — before it is written out. A forwarded declared PATH reaches a pooled backend the same way: gatewayd composes it through env.mcp_search_path, so the spec's entries LEAD that backend's PATH rather than being the whole of it. Consequence to know about: the emitted value is a snapshot of the rebuild-time environment, so it encodes this host's directories (mise data dir, installed Node version bins, the running interpreter's bin) and is not portable to another machine.

includeMcpJson is pinned false

{
  "includeMcpJson": false,
  "mcpServers": {
    "kirocrew-core":     { "command": "…", "args": ["mcp-core"] },
    "kirocrew-cron":     { "command": "…", "args": ["mcp-cron"] },
    "kirocrew-computer": { "command": "…", "args": ["mcp-computer"] }
  }
}

The gateway already merges the Kiro global into the agent file, so the agent file is the superset. With includeMcpJson: true kiro-cli would merge the global a second time at session start, producing duplicate entries and letting a stale path in the global shadow the fresh path the gateway just resolved. Kiro Crew forces false on every agent it manages (the primary agent, every generated agent spec, every recorded fork, and every app agent). Plain kiro-cli agents outside Kiro Crew keep kiro-cli's own default.

The generated specs and the fork refresh get the pin from one shared step, auto_approve.write_governed_spec, which every spec writer under agent_materialization calls instead of writing the file itself. Besides the pin it applies the governance ceiling to allowedTools, strips an ungoverned autoApprove and sets the KAS permissions block. It derives that block for a generated spec, seeds it on a fork only when the fork has none, and writes none for a spec that mounts nothing. The research spec, which is built from the operator's agent.json and has always carried its block, gets the derivation plus that block's deny and ask rules, so a denial written there still holds; its allow rules are dropped. The pin matters because an operator's agent.json reaches every spec built from build_agent_config, and every filter in the step reads mcpServers alone: a server arriving through the global merge would pass all of them. test/test_governed_spec_tail.py fails if any writer in the package calls the write primitive directly.

A crew's fork of a custom template gets the same pin on every refresh. A server such a fork reached only through the global mcp.json is therefore not loaded for it: list that server in the fork's own mcpServers instead. Setting includeMcpJson back to true in the fork does not stick, because the next refresh sets it to false again. Each time a refresh turns the merge off on a fork whose includeMcpJson was true or unset, the gateway logs a warning that names the fork and writes a fork_mcp_json_merge_disabled SEL record with the same text. A fork already at false records nothing.

Managed servers

agent._MANAGED_MCP_SERVERS holds the ten servers the gateway owns end to end: the always-on kirocrew-cron, kirocrew-core, kirocrew-guide and kirocrew-mate, the gated kirocrew-computer, and the opt-in kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-debug and kirocrew-panel. Every emitted or explicitly granted entry is refreshed on every rebuild by _refresh_dynamic_fields(), which rewrites command/args from the live kirocrew binary, strips stale remote-transport fields (url, headers) left by older builds, and re-pins env.KIROCREW_HOME to the home the gateway is actually running under while preserving the user's own env keys. User customizations are preserved, autoApprove included: a list the owner wrote by hand is a deliberate statement about their own tools and survives the refresh, which is what mcp.honour_auto_approve (on by default) decides. It is worth knowing what it costs, because the cost is not obvious from the key's name: kiro-cli approves those tools locally, so Kiro Crew never sees a permission request for them and its own tool gate does not run. Turn the setting off to drop every verb no server spec declares and put those tools back through the gate. A verb a managed or edition spec declares is unaffected either way, and a governance ceiling strips the key whatever the setting says.

Only the OWNER's own list is honoured. An app's <app>:<server> entry is granted by its manifest rather than chosen by the owner; an agent config materialized for an app declines the opt-in for its whole map, since an app's keys arrive from the manifest, the shipped spec and the per-agent policy and need not be namespaced; and an entry carrying the x-kirocrew provenance marker is Kiro Crew's own. All three stay on the strict floor, as does a value that is not a list[str], which kiro-cli's strict parsing would reject with no rebuild able to repair the file. On that app map a verb a server spec DECLARES still survives.

Ownership is judged by the entry's shape -- its name and provenance marker -- never by who wrote the file, so a plainly-named entry an agent appended reads as the owner's.

On KAS the key has no slot, and the projection drops it from the server entry. The verbs strip_ungoverned_auto_approve keeps for the kiro-cli route travel instead as @server/tool entries in the allowedTools input the permissions block is derived from (acp/kas_auto_approve.py), so they meet the same per-entry ceiling and PreToolUse-hook withholding as any other grant. A verb that is not one literal tool name prompts. ~/.kiro/settings/mcp.json is therefore on the write-protected tier of the file-tool floor: an agent's file-edit tools cannot write it. The shell route is not fenced by that floor; governance.md owns that residual.

For KAS native managed servers, session projection supplies the actual gateway listener port and the allocation-time caller session key. These values come from the gateway rather than the editable agent environment. Native tools keep their own session identity and reach the serving instance on a non-default port; third-party servers receive neither value.

An entry may also carry a spec_gate — a predicate consulted at spec EMISSION time. kirocrew-computer is the one row that has one, and the distinction it draws is the difference between a capability that advertises no tools and one that costs nothing: emitting the entry is what makes kiro-cli spawn the backend, so an in-process enable check can only ever refuse work in a process that is already resident (~109 MB, per chat process, including every spawn_run subagent). While the gate is closed the server appears in neither mcpServers nor tools, so nothing is spawned at all. Both loops that write specs honour it, and asymmetrically on purpose:

  • build_agent_config() withholds the entry and pops one arriving from the user override file — a platform gate exists because there is no driver on this OS, and an override must not smuggle a server past it;
  • _refresh_dynamic_fields() retracts an entry a previous pass wrote while the gate was open, because a skip-only refresh would mean turning a feature off never reclaims the process turning it on started;

kirocrew doctor is a third, read-only consumer: its MCP sections resolve the same registry gate (cli_doctor._spec_gate_closed) so a gated-off server's absence reads as informational rather than as a missing entry, so doctor never demands what emission deliberately omits. The @server refs in tools / allowedTools are left exactly as they are. Withholding the entry is the whole control: a @server ref resolves against the agent's own mcpServers plus the global mcp.json, so with no entry in either there is nothing to launch — the ref names nothing and mounts nothing.

Preserved the user's tools and allowedTools refs, verbatim — including a mount hand-narrowed to a single @server/tool
NOT preserved the entry's autoApprove and user env keys. An off/on cycle resets these; the operator re-applies them

Stripping the refs as well is the tidier-looking design and it is where a whole class of defects came from. The removed set is not reconstructible from the server name — a user can narrow tools to ONE @server/tool ref while the re-enable path re-adds the BARE ref — so anything that prunes must also stash and restore, and every way that stash can fail silently widens the mount: an unwritable stash, a stash cleared before the spec write landed, a rebuild path that skipped the restore. Leaving the refs alone has none of those states, and the only place a stash could live is a sidecar the agent itself can write.

That last point is why the entry's own fields are still dropped rather than stashed: a restored autoApprove would be an agent-authored value that a later rebuild installs into the spec, and kiro-cli approves an auto-approved MCP tool locally — no permission request is emitted, so hooks.on_tool_call (deny floor, sensitive-path check, governance ceiling) and the SEL audit are never reached. For tools that can click and type into an already-authenticated application that is a self-granted gate bypass. Losing an approval is the safe direction; restoring one from a file the agent can write is not.

Withholding is recorded to SEL as mcp_server_withheld, derived from the gate plus the shipped template rather than from a config delta — nothing in the spec changes shape when a gate closes, so there is no delta to observe, and the audit trail would otherwise have no record that a shipped server was deliberately not emitted.

The gate decision is snapshotted once per rebuild and threaded through both emit loops, so a keystone flip landing mid-rebuild cannot produce a spec that emits one server's entry under the old decision and another's under the new one.

Under an enterprise MCP registry, _refresh_dynamic_fields() also maintains a "type": "registry" marker on these managed entries — added when agent.mcp_registry_mode is declared, and REMOVED when it is not. The marker is maintained rather than preserved because it tracks the account the gateway is signed in to, not a user preference, and because the client's filter is symmetric: outside registry mode a marked entry is the one that gets dropped. command/args stay either way, since the registry path is not the only consumer of this spec (doctor's handshake probe and the CC sidecar sync both launch from it — though doctor skips the probe for a server whose spec gate is closed, since no emitted spec defines it). See ../guides/enterprise-mcp-governance.md.

A user entry that is a bare registry pointer — "type": "registry" with no command and no url in any source, the shape Kiro IDE and kiro-cli write when a server is installed from the catalog — is carried into the emitted spec verbatim by resolve_mcp_servers instead of taking the generic "no command" drop (#3308). The spec pins includeMcpJson: false, so that copy is the only route by which kiro-cli sees the pointer, and kiro-cli is the only party that can resolve it. Its @ref then goes through sync_shared_server_refs and the auto-approve gate like any other shared server. The readiness probe's structural check (kiro_prerequisite._unlaunchable_mcp_servers) accepts the same pointer as launchable, since kiro-cli supplies its transport; without that exemption every governed host would land behind the "agent specs rejected" gate. Nothing else changes: a marked entry with an unresolvable local command is still dropped, and the Claude session array, the KAS projection and the pooled broker stubs still withhold marked entries. In discovery, _server_from_spec flags the same shape as registry_pointer; list_servers and probe_server report it as status registry — never spawned, never cached, no quarantine verdict — and the dashboard renders it as the muted "Not verified" badge with a hint naming kiro-cli mcp list.

kirocrew-computer carries no autoApprove key and none may ever be added. kiro-cli approves an auto-approved MCP tool locally and emits no permission request, so hooks.on_tool_call (the PreToolUse deny floor, sensitive-path check and governance ceiling) is never reached for it. For a tool that can click and type into an already-authenticated application, that would be a complete gate bypass. Its stdio shim answers an empty tools/list while the keystone enable is off — retained as defence in depth for a mid-session disable, on top of the spec_gate above that keeps the process from existing in the first place.

The final ref reconcile

tools and allowedTools hold @server and @server/tool refs, and kiro-cli mounts only what mcpServers declares, so a ref naming a name absent from the final map mounts nothing. Several passes narrow that map without touching either list: the resolution pass replaces mcpServers wholesale and drops unresolvable servers by OMISSION, and the locked app re-merge deletes entries whose app is not confirmed enabled. Because the merge base is the previous rendered config, a ref outlives the server it named — across a rename, an uninstall or a disable.

One prune_dangling_tool_refs() pass over the FINAL map therefore runs at the single funnel every write path goes through, after the passes that mutate allowedTools and before the auto-approve filter below. Reconciling the final map rather than each narrowing pass is what keeps a pass added later safe by default.

The two lists take separate exemption sets, because they fail in opposite directions. declared names servers whose absence this rebuild EXPECTS a later pass to reverse and governs tools; declared_grants governs allowedTools. Keeping a mount ref too long costs one mount attempt against a name that holds nothing, while dropping one can unmount a server for good, since an existing config deliberately never re-adds a template ref. Keeping a GRANT too long hands the next server on that name an auto-approval nobody granted, on the one list that never reaches the PreToolUse gate, while dropping one costs an approval a human can give again. So a name this rebuild is UNSURE about is exempted as a mount and not as a grant: the mount survives the doubt and the grant does not. A caller with no such doubt passes one set and both lists read it.

Three classes populate the mount set: a server whose command did not resolve on this pass, a gated-off shipped server whose entry is withheld while its ref is retained by design, and a name some readable source still declares. A @ name in RESERVED_TOOL_NAMESPACES addresses a kiro namespace rather than a server — @builtin carries the whole built-in tool surface plus the tool_search loader — so it is never in the map and is never a leftover.

An unresolved disabled source deliberately denies grants across its complete alias family: the canonical alias and every numeric-suffixed sibling whose final dash segment contains only digits. It removes those refs from allowedTools and blocks the rebuild from adding them again, while leaving tools and mcpServers intact. The collision allocator can hand any family alias to a distinct live server, so a stale grant on that name must not auto-approve the replacement. Prefix-sharing aliases outside the numeric-suffix family keep their grants.

App-contributed names are read twice, before and after the rebuild's work. A {app}:{server} key is minted by an app manifest, so a disabled app's grant must not outlive it; but an ownership read that FAILED cannot be told from one that found no owner, and only the second is safe to treat as unowned. An app's enablement is read as a tri-state so that a metadata read fault is not recorded as a deliberate disable. Ownership only ever decides the GRANT: the reconcile never unmounts on an ownership answer, because mcp_server_alias() is many-to-one and a collision is resolved by suffixing, so which claimant a base-2 sibling came from is a guess that is unrecoverable by the next rebuild — dropping its tools ref on that guess deletes a server nothing re-adds, while keeping a ref costs one mount attempt against an empty name. The grant requires positive evidence a guess cannot supply: a name an app claims EXACTLY keeps its grant only while its own claimant is readably switched on, and family membership never lends a sibling an enabled owner's answer. A name a readable source still declares outranks a switched-off app's claim on it, since the rebuild's own ref sync would otherwise re-add the pruned per-tool grant as a WHOLE-server one.

Both outcomes are recorded where an operator can see them. Revoking a grant emits mcp_auto_approve_revoked to SEL, the same feed as the withhold above, because it is a permission decision and no config delta records it. Dropping a mount ref is logged at WARNING, which the shipped agent.log_level default shows: the ref named nothing, so the tool was already unreachable, but a misclassified absence is unrecoverable and an operator debugging a tool that stopped being offered should not have to raise the log level first.

The final auto-approve pass

allowedTools is kiro-cli's blanket auto-approve list, and it is the one path that never reaches the PreToolUse gate. Builtin grants (fs_read, execute_bash, …) arrive straight from the shipped agent template, so no per-writer path re-touches them. The last thing rebuild_agent_config does before writing is filter the whole assembled allowedTools list through one predicate: a ref the governance ceiling has an opinion about loses its blanket grant and its calls go through the gate, where the per-argument rule actually applies; a ref the ceiling is silent about is kept. mcpServers[*].autoApprove gets the same treatment on the final map, with one difference: an owner-written verb is KEPT, because mcp.honour_auto_approve is on by default, and only a real false there drops every verb no server spec declares. tools is deliberately left intact, because mounting a tool is not auto-approving it. Both outcomes are recorded in SEL, mcp_auto_approve_withheld when a grant is taken away and mcp_auto_approve_honoured when an owner-written one is kept, so an operator can see both why a template tool prompts and which calls are skipping the gate.

Servers the operator asked to confirm

A user-added server is granted in allowedTools as soon as it is mounted, so steering prose such as "confirm before making changes" is the only thing between the model and its write tools. hooks.confirm_tools in config.json is the structural opt-in: a list of tool patterns in the auto_approve_tools spelling (@server, @server/tool*, Running: @server/*, or * for every MCP server the agent's spec grants, Crew's own @kirocrew-* servers included; a builtin app agent's calls to its own app-scoped server are approved by the gate's app-own-server tier, which runs before this list is read, so * does not reach them). The static side withholds a server's grant whenever a pattern could match any of the gate's identity spellings for a call on it (@server, @server/tool, Running: @server/tool, case-insensitive, wildcards spanning /), judged from the pattern's literal prefix, so it errs toward a prompt and never keeps a grant the gate would refuse. A pattern that names a call only by its title acts at the gate alone. may_skip_gate_now, the chokepoint every static grant writer calls (the rebuild's shared-server sync and final pass, the dashboard enable paths, app-agent materialization and doctor's repair), answers "no" for any @server or @server/tool ref on a server a pattern names. The server stays in tools, gets no allowedTools grant and no autoApprove from any writer, and each of its calls raises a permission request that reaches the PreToolUse gate. The writers record that as their usual mcp_auto_approve_withheld event. At the gate a confirm_tools match outranks an auto_approve_tools grant, and the read-only classifier does not settle a confirm-listed MCP call: not from its ACP kind or title, which are agent-influenced, and not from the bash classifier when kiro-cli labels an MCP-served frame as shell, since that tool runs outside the agent sandbox. Deny tiers are unchanged, and a session in Trust or YOLO mode still approves what the user told it to.

The gate side follows the live hooks section. The spec side is decided when a writer runs, so a grant already in kirocrew.json is withdrawn at the next rebuild (a gateway restart) or the next dashboard enable of that server. The schema declares hooks.confirm_tools with restart=True, so a saved change reports that a restart is needed rather than claiming it applied. With the key unset, both the spec and the gate behave as before.

When the load could not read the settings (a read that raises, a load that stood in defaults for an unparseable config.json or config.local.json, a hooks section that is not an object), its values cannot show the list is empty or set, so the files on disk decide. If a config file does not read as written now (it cannot be read, does not parse as an object, or holds a non-object hooks) and some config file names the confirm_tools key, or a file cannot be read at all, the list is unknown. The static writers then withhold every MCP grant, Crew's own included, and the boot and reload HooksConfig carries confirm_tools_unknown, so the gate withholds every auto_approve_tools grant too, whatever list the load kept: a torn overlay can drop its confirm_tools while the base file's grants and list survive the load. A confirm_tools that is present but not a list is unknown as well; validation keeps it (_FAIL_CLOSED_PATHS) rather than repairing it to absent. If no file names the key, the operator never asked for a prompt, and everything behaves exactly as with the key unset (a trailing comma in a config.json without the key changes nothing). The loader keeps a degradation flagged for the life of the process; once every file reads as written again the flag is stale and the loaded values are used, so the next rebuild or dashboard enable writes the grants back.

A grant ref is a pattern too. A ref with a wildcard in its server segment, such as *, @* or @ser*, covers servers the writer cannot list. While any confirm_tools pattern is set (or the list is unknown), every writer withholds that ref, so the agent gets no namespace-wide allowedTools entry. Refs that cannot begin with @, such as fs_*, cover no MCP call and are left to the builtin floor.

Two writers, one lock

~/.kiro/agents/kirocrew.json has two independent writers: this whole-file regenerator and the app-MCP registration path (apps.bridges._register_mcp_servers), which does a read-modify-write of the same file under bridges._mcp_lock. A register landing between the rebuild's app-server snapshot and its write would be silently erased by the full-file regeneration, so the rebuild takes that same lock across a final re-read and merge of the app-namespaced servers. An app server is dropped only when its app is confirmed no longer enabled; absence from the on-disk map is not by itself proof (a clean rebuild starts from an empty map, and dropping on that basis made an enabled app's tools vanish).

Discovery and probing

Source: mcp_discovery.py, a mirror facade (kiro_crew._facade_mirror) over sibling owner modules, so every name they define still reads and patches as mcp_discovery.<name>. The facade keeps the discovery passes: probe_all, with the quarantine exclusion, and the discover-and-sync step (sync_discovered_servers, register_servers_for_cc). New work goes to the owner of its responsibility:

Owner Owns
mcp_discovery_server_info.py McpServerInfo, the scope names and config-source tables, and redact_mcp_headers / redact_mcp_error
mcp_discovery_probe_state.py the protocol revision every client handshake offers and steps down to, the probe timeouts and error cap, the once-only warning ledgers, and the probe-result cache
mcp_discovery_managed.py the managed servers' subcommand and tool-module tables, managed_server_is_session_bound, the in-process tool read, and stale-command repair
mcp_discovery_config.py loading the agent config and the mcp.json sources per scope, and list_servers
mcp_discovery_remote.py _probe_remote: the SSRF vet and pinned connection, the HTTP handshake, header expansion, and the authorization checks
mcp_discovery_probe.py probe_server: refusing a disabled server, and the stdio handshake of a local server spawned in the sandbox on a private loop, with its temp refusals

list_servers() reads ~/.kiro/agents/kirocrew.json, then each scope file with provenance, re-resolves stale managed commands, and overlays cached probe results. Every returned McpServerInfo carries a presence dict so the dashboard can render per-scope badges. The kirocrew badge is the effective state after the merge minus every entry in ~/.kiro/crew/mcp.json whose disabled is present and anything but a literal false (mcp_cleanup.mcp_entry_is_muted, which fails closed); the other badges are raw membership in that scope's file.

Probes run from POST /api/mcp/probe:

  • stdio servers are spawned and driven through an MCP initialize handshake followed by tools/list.

  • HTTP servers get the same two JSON-RPC calls over POST. The configured url is first SSRF-vetted off the event loop through link_unfurl.vet_unfurl_url (the vet the link preview, calendar, WeCom and OAuth-discovery fetches share) and the connection is pinned to the vetted address, so a server url resolving to a link-local address or the cloud metadata endpoint (fd00:ec2::254 included) is refused before any POST — a configured entry cannot make the gateway reach the metadata service the agent's own shell is fenced from and reflect the reply onto the row. Two opt-ins fit the vet to a configured endpoint: allow_any_port (a server on :8443 / :8000 / :3000 probes) and allow_private (a loopback or LAN server, such as an app backend on 127.0.0.1, probes, as kiro-cli itself connects to it). Redirects are not followed, so a server cannot hand the handshake to an address the vet never checked; a redirect reports as its status and the target it names (scheme, host, port and path only), so a server whose url needs a trailing slash says which url to configure. The remote probe offers MCP_CLIENT_PROTOCOL_VERSION (2025-06-18) in initialize. A -32602 refusal of that offer whose data.supported lists an older revision makes it retry once with the newest such revision. Every request after initialize carries MCP-Protocol-Version set to the revision the server answered with. The connection L1 smoke test (connections/l1_smoke.py) imports the same helpers, so both paths negotiate the same way. The stdio probe and the gateway's stdio backend handshake (send_initialize) offer the same revision and take the same one step down.

  • Disabled servers are never spawned. probe_all() returns a muted row as an unprobed status: "disabled" placeholder with no error text, keeping the tools of its last real probe, and writes nothing to the probe cache.

  • Names that start the same process are probed one at a time. One server is often configured under several names, and probing them together starts the same heavy process several times at once; the copies can each miss the probe timeout and build a quarantine streak against a server that works. probe_all() keys every local row by _spawn_fingerprint (command plus args; env is left out, because a different token still starts the same package) and holds one lock per key, taken before the shared PROBE_MAX_CONCURRENCY slot, so rows with different keys still run in parallel. Remote rows get no key. Each name still gets its own probe, env and verdict, and the quarantine rule is unchanged. The cost: a pass with n names of one slow server takes up to n full probe durations for that server instead of one, and one probe of a stdio server can last nearly two timeouts (initialize and tools/list each get a fresh one) plus teardown. The boot gate in service_boot.py waits mcp_probe_timeout_secs + 15 for the first pass and then starts sessions anyway, so a large alias group of a slow server can outlast it; the pass still finishes in the background and fills the cache.

  • Both calls must succeed for ok. An initialize that answers and a tools/list that does not (no response, an error reply, a non-200) is a server no session can get a tool out of — the badge certifies "tools usable", so that combination reports as an error naming tools/list, not as ok with an empty list.

  • Every result carries probedAt (wall-clock seconds of the probe that produced the status) and probeMode (handshake for a real round trip, declared for the managed in-process fallback below). Both ride the cache into the API payload, so the UI can say when a status was true — the caches legitimately serve results up to their TTL, and an undated "Online" reads as "now". A remote result may additionally carry authChallenge and, when the grant lookup produced a verdict, authGrantPresent. Both ride the same cache and are described with needs_auth below.

  • Timeout is dashboard.mcp_probe_timeout_secs (default 15s; _PROBE_TIMEOUT_SECS is the fallback if config is not loaded yet). Results are cached for _PROBE_TTL_SECS (1800s), after which status reads as "outdated" — with probedAt preserved, because when it was last true is the most useful thing an outdated row can say.

  • The cache is keyed by server name, and each entry also records a fingerprint of the config it was probed under (_probe_identity: command, args as the probe spawns them, and non-secret env for a local server; url and header names for a remote one). An entry whose fingerprint does not match the current config reads as NOT cached (unknown, no tools, no probedAt) rather than outdated: an expired entry was true of this server, a mismatched one describes a different target. Every reader that takes an entry by name applies that check: list_servers() compares the fingerprint for tools and authChallenge, and the handler-side readers call cached_probe_is_current (GET /api/mcp's handler-cache overlay, GET /api/mcp/probe, and the shareability verdict). A failed probe after an edit does not inherit the previous target's tools.

  • The handshake response is kept, not just the tool names: advertised capabilities, the protocolVersion the server ANSWERED with, serverInfo, and per-tool annotations. These feed the shareability verdict (below); the probe already paid for the round-trip, so reading them costs nothing.

  • client_info overrides the identity sent in the handshake. The shareability pre-flight uses it to ask one server under two identities; such a run is excluded from the shared per-name probe cache, because a synthetic-identity handshake is a diagnostic and not the canonical observation the dashboard renders.

  • Remote header VALUES may carry ${VAR}/${env:VAR} references — the documented config form kiro-cli resolves at session runtime. The probe resolves them through the gateway rewriter's declared-env expander (mcp_gateway.rewriter._expand_env_placeholders): same regex, same credential-filtered source view, and an unresolved reference stays literal — so the probe presents the credential a session presents instead of sending the reference as text and reporting the server's correct rejection as a failing row. Probe-error redaction keys on the resolved values the probe actually sent.

  • A remote server that answers the handshake with 401 — or with 403 carrying a WWW-Authenticate challenge — and whose sent headers carry no static Authorization credential gets status needs_auth and an empty error, not error. An Authorization value still carrying an unresolved ${VAR} reference (a missing or credential-filtered variable) supplied nothing, so it does not count as a static credential here. The probe holds no OAuth token, because kiro-cli owns token custody (design-notes/mcp-oauth-ownership.md), so the status code alone carries no verdict on the server: an unauthorized server and one the runtime calls successfully both return it.

    Two pieces of evidence split that ambiguity, and the wording follows what they support rather than the status code. The probe parses the challenge (a Bearer challenge carrying a scope list or an https resource_metadata URL sets authChallenge), and it stats kiro-cli's paired grant artifacts for the url to set authGrantPresent. Three wordings follow, one per answer the pair supports:

    Evidence Badge Why
    challenge, authGrantPresent false Sign-in required "Nobody has signed in" is observed, so the row names the action and states where it happens.
    challenge, authGrantPresent true Signed in (muted) A grant artifact exists. The badge reports THAT, never that the server answers — the probe holds no token, so validity is the one thing it cannot check, and the hover says so. Toned muted rather than warn: amber is the panel's "act now" colour, and a resolved row wearing it is indistinguishable by colour from one that still needs a sign-in.
    no challenge, or authGrantPresent absent Not verified An older gateway, or a bare 401. Naming any state here would assert more than the probe observed.

    The middle row is what gives the guided sign-in an ending: without it a user who followed the instruction landed back on the same badge they started from. It is deliberately not "Online" — a stored grant is evidence a sign-in happened, not proof it has not since been revoked, and only a probe carrying the runtime's token could close that gap.

    Reaching that ending is a VISIBLE instruction, not a hover. The panel is served from the probe cache for the whole TTL, so a user returning from a completed sign-in meets a row that still reads "Sign-in required"; if the "probe to refresh" step lived only in the badge's title it would reach neither a keyboard nor a touch user, at the moment of highest doubt. The cell carries one clause, and the title carries the longer form naming the control and the state the row lands in.

    Grant-key derivation, paired artifact paths, and presence checks live in the leaf mcp_grant module. The probe, connection mint, and persisted connection status all consume that shared layout so a kiro-cli cache change cannot make those surfaces disagree with one another. Its origin serialization matches the Rust URL runtime at the byte boundary: Unicode domain names are IDNA-encoded and IPv6 literals retain their brackets before hashing.

    grant_presence() is the single tri-state, and there is deliberately only one spelling of it. Each paired artifact is stat-ed exactly once and classified by errno — the ENOENT family is a definitive absence, any other OSError is "unknowable" — then the pair combines: either artifact definitively absent decides it, any remaining failed stat makes it unknowable, otherwise present. It is not built on Path.is_file(), and that is load-bearing rather than stylistic: from Python 3.14 that method swallows every OSError and answers False, so a permission error or a stalled mount would be indistinguishable from "nothing was ever written". This package declares requires-python >= 3.12 with no ceiling, so a build on 3.14 would silently collapse the middle answer and tell the owner of an authorized server to sign in again — the exact harm the three-valued design exists to prevent. Two spellings over the same artifacts is how one of them loses that answer, which is why the probe and the status module resolve through this one function.

    The grant stat is SEL-audited on whichever answer its caller acts on. The mint and the status module poll for a grant to appear, so only the positive moves anything and only the positive is recorded — auditing each poll would write one critical event per iteration of a single flow. The probe reads once and renders either answer, and an absent pair is exactly what produces "Sign-in required", so it passes audit_absence=True and the access leaves a trail as success or missing. Opting in is the caller's, not the default's, so a future polling caller cannot silently flood the log.

    Absence in the payload is meaningful, and the UI gates on an explicit false. authChallenge is omitted when the probe learned nothing about authorization. authGrantPresent is omitted for that reason too, and also when the grant lookup could not answer at all — a cache home that raises, such as a permission error or a broken mount. Reporting an unanswerable lookup as false would tell the owner of an already-authorized server to sign in again, so the three-valued result is preserved to the wire rather than flattened. Each probe clears both fields before it runs, and list_servers() re-attaches them from the cache only when the entry's config fingerprint matches, so a row whose url was edited does not inherit the previous endpoint's verdict from either side.

    One degradation is NOT covered by that, and the limit is worth stating. The lookup mirrors kiro-cli's own cache-key derivation and artifact layout, both undocumented internals. If kiro-cli re-keys them, the stat succeeds against a path that is simply absent, so the answer is false rather than unanswerable and an authorized server reads "Sign-in required". That row does not recover on its own: a second sign-in mints artifacts under the NEW key while Crew keeps stat-ing the old one, so it goes on asking for a sign-in until the mirror here is corrected. The recorded-hash tests pin the mirror only against itself, so the drift would not fail in-repo either. Detecting it needs an observation of an artifact kiro-cli actually wrote.

    A 401 on an entry that DOES carry a static Authorization header stays error: a supplied credential was rejected, which is a real fault. The challenge is still recorded there, because "this server wants OAuth, so no static header can satisfy it" is the actionable part of that failure. The GRANT is not: authGrantPresent is read only by the "Sign-in required" wording, which is gated on needs_auth, so looking it up on an error row would run a stat — and let grant_observed write a critical SEL event — for an observation nothing reads.

  • A probed stdio child that ignores a closed stdin costs _PROBE_TEARDOWN_WAIT_SECS twice (graceful wait, then again after SIGKILL) before the process-group reap, which is why that budget is a named constant tests can shrink.

  • A probe that could not RUN is reported as a probe limitation, not a server fault. SandboxUnavailableError is caught ahead of the generic handler: probe_server spawns through sandboxed_spawn_argv(mode="standard"), which fail-closes on a host with no OS sandbox backend (any Windows host, macOS >= 26). But kiro-cli launches these servers from the agent config without going through this probe, so the servers work while the probe cannot spawn them. Reported as an ordinary error, every row rendered red with "0 tools" and sent the user debugging a server that was fine. server.error therefore leads with the machine-readable mcp_probe_sandbox_unavailable: prefix (mirroring the code field on dashboard JSON error bodies), states that the server itself may be fine, and names the agent.sandbox_allow_unsandboxed_exec remedy (on Windows this refusal means the key is declared false or a governance floor is pinned, since the platform default permits the spawn). Because the cause is the HOST, it recurs identically for every server on every discovery cycle, so the remedy paragraph warns once per server name (_warn_probe_sandbox_unavailable_once) and demotes repeats to DEBUG.

    • A managed server FALLS BACK to its declared tool list when — and only when — the sandbox refuses. Every server in mcp_discovery._MANAGED_SERVER_TOOL_MODULES declares its tools statically in this package (the same _list_tools() functions the stdio shims answer tools/list from), so _managed_tools_in_process can serve the listing with no subprocess at all. That is what removes the agent.sandbox_allow_unsandboxed_exec opt-in for a read-only listing on a backendless host.
      • Fallback, never primary. When a backend exists the real spawn still runs, because it is the only thing that proves the server can start. _fix_stale_managed_command exists precisely because that invocation goes stale ("command not found: kirocrew; the built-in cron/core tools then never load"), and the probe is the one surface that catches it. Short-circuiting on the server name would report ok for a managed server that cannot run, silently changing what ok means in the shared _cache_probe store.
      • Why the import is acceptable only here. Reading the declaration imports package code into the gateway process, which the gateway does not otherwise do (these modules are absent from sys.modules at boot). The package directory is writable by the same uid the agent runs as and is not on the sensitive-path floor, so on a host where the sandbox works, importing would beat the isolation the spawn provides, which is why this is never the primary path. Reaching the fallback means the sandbox could not confine anything anyway, so the import concedes nothing the refused spawn had not already conceded.
      • The substitution is logged at WARNING, once per server: ok here means "this package declares these tools", not "the server answered", and the default log level is WARNING, so at info it would be invisible on exactly the hosts where it always happens. The result also carries probeMode: "declared" into the cache and the API payload, and the dashboard renders it as a warn Declared badge rather than a green Online — colour carries the distinction, because a scan of a dozen rows reads colour long before it reads small print. Third-party servers have no declaration to read and keep the honest mcp_probe_sandbox_unavailable error.
      • Modules are imported lazily (they pull in the validation/artifacts graph, which cannot be imported at mcp_discovery import time). Any failure returns None and the original refusal is reported, so a bad read never invents a result. An empty list is a real result: mcp_computer._list_tools() returns [] by design while the keystone enable is off.
  • An MCP command that does not resolve is a stable fact, so it warns once per (server, command) and demotes the repeats to DEBUG. Timeouts and handshake errors stay at WARNING every time: a server that newly starts timing out is news, one whose binary is absent is not. The ledger self-heals, so the warning returns if the command later resolves and then breaks again.

GET /api/mcp also kicks off a background re-probe when it sees a server that is not in the probe cache yet, so a freshly added server transitions from "Unknown" on the next page load rather than waiting out the TTL. It and GET /api/mcp/probe do the same for a server whose config was edited since its last probe, once per edit: the arming is keyed on the stale entry's fingerprint, so a row probe_all never re-probes (a quarantined server) cannot re-arm the fan-out on every request.

_fix_stale_managed_command() rewrites a managed server's command and args on every list_servers() call, because the stored absolute path goes stale after an update. The invocation comes from agent._kirocrew_mcp_invocation, the one source of truth for every install layout. It is cached per server and resolved again only when the cached absolute command no longer exists on disk.

A managed server that keeps running after an update pruned the install it was imported from checks for that before each tools/call, because anything it imports later would fail. It refuses the call with JSON-RPC error -32000 and a SEL rejected_install_pruned record. When the gateway pool can respawn it (KIROCREW_MCP_POOLED_BACKEND is set and KIROCREW_MCP_POOLED_RESPAWN_COMMAND still resolves), the refusal asks for a retry, every queued call gets the same answer, and the process exits with status 75 so the pool relaunches it from the current install. Otherwise nothing would bring it back, so it keeps its transport and refuses each call with a message to restart Kiro Crew.

Servers that ask the person (MCP elicitation)

An MCP server the agent calls may gate a tool on a human answer -- a confirmation, a short form, a link to visit -- by sending its agent an elicitation/create. Kiro Crew is the ACP CLIENT of that agent, so the ask reaches it as a server->client request (elicitation/create on a standard harness, _kiro/mcp/elicitation on KAS) and is put to the person as a card; no trust tier answers it, and a session with no person reachable declines. The wire shapes, the fail-closed parse, the consumer opt-in and the dashboard route are in acp-client.md, MCP elicitation. This is distinct from everything else in this document, which is about the MCP servers Kiro Crew itself SERVES to the agent.

Shareability verdicts

GET /api/mcp-gateway/servers returns a recommendation per row: whether the server looks safe to stub, and separately whether its backend looks safe to share. The verdict is derived on this host from evidence ranked observation > measurement > declaration, and a server the gateway has WATCHED behave per-client while shared is never offered again. Nothing about which servers a machine runs ships with Kiro Crew and nothing leaves the host.

Full contracts — the two on-disk records, the reason-code vocabulary, what the pre-flight can and cannot decide, and the seed-once rule — live in docs/system-specs/modules/mcp-shareability.md.

Dashboard MCP management

The Connections page's MCP panel aggregates the scope files into one view with per-scope badges. Clicking a badge stages an intent; the page accumulates staged changes and exposes Apply / Discard. Only Apply performs writes.

Add Server search reports every attempted provider. GET /api/mcp/discover keeps its existing results and providers fields and adds provider_outcomes: [{name, status}], where status is ok, timeout, or error. The additive field keeps older clients compatible. A short availability probe attempts no provider and returns an empty outcome list. The Add Server modal keeps results from responsive providers and shows one inline incomplete notice when any sibling provider fails. When every attempted provider fails, it shows the shared ErrorNotice instead of the zero-match empty state. Retry runs the whole search again; per-provider retry and provider-cache refresh are not part of this contract.

POST /api/mcp/apply takes a batched payload and applies it in a fixed order:

  1. Uninstalls first. _purge_server_config() removes the entry from ~/.kiro/crew/mcp.json, the Kiro global, every seam-contributed scope, and directly from ~/.kiro/agents/kirocrew.json. That last targeted delete is required: the rebuild uses the existing agent file as its merge base, so without it the additive merge would resurrect the server. Every step is a read-modify-write that no-ops when the entry is already absent, so re-running the purge changes nothing.
  2. Scope adds write the spec into the target scope file.
  3. Scope removes strip it. If the server would no longer be inherited into Kiro Crew but the user kept the Kiro Crew badge on, the full spec is first copied into ~/.kiro/crew/mcp.json (the preservation rule), which is why "I removed it from the Kiro global and it came back" is correct behavior.
  4. Per-tool overrides update disabledTools on the entry.
  5. One rebuild at the end re-renders the agent file from the new on-disk state.

Each change is applied to the one raw config key its row stands for: the row's exact key, else the single raw key whose alias it is (npm:@playwright/mcp for the row playwright-mcp). A name that is the alias of several raw keys is refused with 409 and "code": "mcp_server_name_ambiguous" before any write, both by POST /api/mcp/apply (uninstalls included) and by POST /api/mcp/toggle.

Listing and probe rows say why a server is off. disabledIn is "kirocrew" for a disable in Kiro Crew's own store, which the Kiro Crew badge plus Apply lifts, and "shared" for a disable in a config this panel does not write, such as the Kiro global mcp.json or a provider global; it is null when the row is enabled. disabledInFile names the file to edit when the shared flag is the Kiro-global one. disabledReason is "invalid" when the mute comes from a non-boolean disabled value, so the table asks for the value to be repaired rather than toggled.

No scope metadata is persisted. Apply does one-shot edits and forgets; state is re-read from disk on the next page load, so external edits (kiro-cli mcp remove, hand-edits) are picked up naturally.

Apply does not restart sessions. Scope changes take effect at the next session spawn; the Connections page header's Apply & Restart calls POST /api/sessions/restart to drain the warm pool of pre-spawned processes carrying the old config, so a freshly installed server is mounted on the next session rather than the one after it. The response carries mcp_sync_ok, and RestartButton READS it: a reconcile that failed is reported in the danger tint instead of the usual "sessions restarted, config applied". Honesty that lives only in a JSON body no user sees is not honesty — the sessions did restart, but against a config that may not match the sources, and that is the one thing the caller needs told.

Per-template MCP additions

A server the user approves for an agent template on a change card is recorded in template-mcp-additions/additions.json under the data home (src/kiro_crew/template_mcp_additions.py): owner-only, every write atomic, every read-modify-write under its own lock. It is kept outside every spec file because a spec is not where it would survive: the conductor installers rebuild their map to exactly the Crew servers on every pass, and a third-party installer may rewrite its own spec. One record keyed by template name.

  • Mount-only for the default agent and the worker. kirocrew.json holds every server installed through the MCP page, whose add also approves every tool, and kirocrew-worker mirrors it. So the record takes a default-agent addition only with mount_only: true, under kirocrew, and refuses a plain one and any addition under the worker (DEFAULT_TEMPLATES, DEFAULT_REASON); a hand-edited default entry without the flag is skipped on read. The rebuild merges it with reconcile_default_spec (stamp, Undo removal) and sync_shared_server_refs withholds its bare grant (see Asking for an MCP server mid-chat). A crewmate's own service templates are refused (CREWMATE_REASON): a crewmate's servers change through its own capabilities. Every other template Kiro Crew writes (agent_files.OWNED_KIRO_AGENT_FILES: the heartbeat, which copies a fixed server list, and the background agents) is refused with BUILT_IN_REASON. A refused template is never merged, even from a hand-edited record.
  • No launch line from the agent. An entry is the gateway-resolved server entry (command/args/env or url/headers, type, timeout) plus who approved it, when, and the card id. The caller builds the entry; the record only stores it.
  • No trust. autoApprove, allowedTools and every key outside ENTRY_KEYS are refused on write and skipped on read. A merge adds the server and its @server mount in tools, never a grant, so its tools prompt until the user grants them separately and every grant still passes _filter_auto_approve (POLICY ∩ PROFILE unchanged).
  • One merge, ADD-only. merge_into / merge_into_spec is the only path: a name the template already declares keeps its own entry. The exception is an entry that declares no transport, only a restriction (a checkout's or the dashboard's switch-off keys, RESTRICTION_KEYS): the approved entry is its launch and the restriction is layered on top, so it narrows the server instead of withholding it. It runs in the conductor installers, right after _conductor_mcp_servers (the deprecated kirocrew-ledger-conductor alias reads and writes its successor's record), and at spawn for every template Kiro Crew does not write (merge_at_spawn, never written to the file): in every branch of the KAS read (user level, crewmate folder, project checkout after its key filter, keeping only its switch-off keys for an approved server, a bound app agent) and in the array hosts' read.
  • Where it reaches. A conductor is supported on every backend that runs a spec's servers (agent_sdk.drivers.acp.backend_delivers_spec_servers) and refused with NO_SPEC_SERVERS_REASON on pi, whose projection is broker-only. A template Kiro Crew does not write is reached at spawn only on ACP_BACKENDS_TEMPLATE_ADDITIONS_AT_SPAWN (KAS, claude, codex). kiro-cli loads such a template from its own file with no per-session channel, and Crew never writes a spec it does not own, so addition_support(template, backend) answers unsupported there with UNSUPPORTED_REASON and the card refuses.
  • Reach and removal. addition_reach names every template one addition reaches (the goal conductor and its deprecated alias share one record; a refused template answers ()). remove_addition(..., card_id=...) takes away only that card's approval. kirocrew doctor lists each template's additions.
  • Applying it. The record adds no reload path. After a write, the caller rebuilds the specs and applies the change to running sessions through the gate below (live_sessions_apply_mcp_live); a session that cannot apply it live picks it up on the next session.

Live reconcile: when no restart is needed at all

kiro-cli 2.10.0+ watches ~/.kiro/agents and mcp.json and reconciles a RUNNING session against an edit: only the changed servers restart, the conversation is kept, and the change applies at the next turn boundary. That makes the restart above redundant on that harness — it exists only to make kiro-cli re-read a file it already watches. kiro_crew/mcp_hot_reload.py owns the gate, and it is keyed to the processes actually running, never to the binary on disk: every live provider — the registered sessions plus the warm pool the reset would drain — must declare LLMProvider.mcp_config_hot_reload as a literal True (default False, harness-parity H14). AcpProvider answers it from membership in ACP_BACKENDS_MCP_CONFIG_HOT_RELOAD (kiro-cli only — KAS gets its servers injected on session/new and applies a change by re-injection, below; claude reads no agent file) AND the agentInfo.version its own process reported at initialize being at or above MCP_HOT_RELOAD_MIN_KIRO_CLI_VERSION. That floor is 2.21.0 — the release the reconcile semantics were observed on — not 2.10.0, where the watcher first shipped: a release in between keeps the always-correct reset until it is verified, because granting the skip to one that reconciles differently fails invisibly, and lowering the floor later is one line. The handshake version is what each process runs; after an in-place kiro-cli upgrade the file on disk is newer than every process spawned before it, so probing the file would answer for a version nothing is running. The gate fails CLOSED: one provider that has not handshaked, is below the floor, sits on another harness, or has not declared the capability at all resets every session. POST /api/mcp/sync consults it and, when it holds, touches no session — sessions_reset: 0 is the observable outcome. With no live process at all there is nothing a reset could reach, so the answer is also to skip. POST /api/sessions/restart stays the unconditional manual path.

KAS satisfies the same gate by a SECOND mechanism, its own membership (ACP_BACKENDS_MCP_WIRE_REINJECT, declared as LLMProvider.mcp_config_wire_reinject by AcpSessionProvider, read through AcpProvider): nothing in that engine watches a file, because its servers travel inside the projected agent (_meta.kiro.customAgents), and the engine registers a session's batch exactly once -- a session/set_mode re-sent with a new batch is answered {} and ignored, and a session/load of a session the engine still holds is ignored the same way. What it does take is session/close on the resident session, session/load of the SAME session id carrying the new batch, then session/set_mode: the engine replays the conversation it kept, the _kiro/tools/didChange after the activation lists the added server's tools (and no longer lists a withdrawn one's), and the model's next turn reaches the new tool while recalling the earlier turns. Measured on KAS 0.66.62 behind kiro-cli 2.34.0: test/fixtures/acp_frames/kas/mcp-live-apply-live.jsonl (an added server, with the refused re-injection in the same session) and mcp-live-remove-live.jsonl (a withdrawn one). The bundle route runs the same engine over the same wire. So the gate is live_sessions_apply_mcp_live -- every live provider hot-reloads OR re-injects -- and when it holds, _mcp_hot_reload_active MARKS each re-injecting provider (mark_mcp_config_changed, a flag, never on the wire) in the same call that skips the reset. The provider applies the mark at its next turn boundary, under the shared-turn claim and before the prompt (acp/session_provider_mcp_reinject.py): AcpRuntime.evict_session (the standard session/close, which keeps the stored record -- unlike KAS's own teardown verb _kiro/session/delete, which removes it), then AcpRuntime.load_session on the same id, which re-reads the spec, re-projects the batch, re-declares the broker stubs, hoists the managed servers and activates the mode with every guard the first load had. The new handle replaces the provider's first, and a pinned model is re-applied last, as new_conversation does -- a cancel during that round trip leaves a usable session on the engine's restored model. The mark is consumed before the first await and never cleared after one, so a Settings write that lands while the load runs marks the provider again and that mark survives the apply: the next boundary re-loads from the spec as it is then. Never mid-turn: a close on a running prompt would cut it, so a mark landing during a turn waits for the next one. The load runs inside AcpRuntime.keep_record_on_teardown: every failure arm of load_session (an activation refusal, a stale spec, a timed-out set_mode) ends the session through terminate_session, whose KAS verb _kiro/session/delete removes the stored record -- the conversation the apply exists to keep -- and inside the scope that call is the record-keeping evict_session instead. A failed load restores the mark and refuses that turn with the restart remedy, so the next boundary retries; a close of an id the host does not hold is an error the evict ignores, which is what makes a half-done apply converge. The warm pool is marked too: a pre-spawned KAS session applies the change at its first turn rather than being drained -- and a fill IN FLIGHT, whose provider sits between its start() and its enqueue in neither snapshot, is reached through SessionManager.mark_mcp_config_changed, a generation fence the gate bumps in the same call and the fill loop compares across its start, marking that provider at its enqueue re-check.

Strands satisfies the gate by a THIRD mechanism, its own membership (ACP_BACKENDS_MCP_RELAUNCH_RELOAD, declared as LLMProvider.mcp_config_relaunch_reload by AcpProvider for its direct AcpClient). The Strands CLI reads its servers once, from the --mcp-config file the adapter writes at each spawn, so a running process cannot take a new one. Crew relaunches it instead: at the session's next turn boundary, before the prompt and never while a turn holds the lock, the marked client is replaced through the disposed-session path (acp/relaunch_reload.py): the old process is killed, the new one launches with a freshly written --mcp-config, and session/load of the same id brings the conversation back. Measured on Strands CLI 0.2.3: test/fixtures/acp_frames/strands/mcp-relaunch-add-live.jsonl (an added server's tool offered and called, the earlier turns kept) and mcp-relaunch-remove-live.jsonl (a withdrawn server's tool no longer offered). The launch clears the mark right before it reads the spec, so a client still starting needs no second relaunch, and a mark set after that read survives. A failed relaunch, or one whose replacement opened a different session, refuses that turn with a plain message and leaves the load owed: every later turn is refused until a replacement serves the same session id, so no turn runs in a conversation the chat never had.

The skip is inferred from that declaration, not observed: kiro-cli's _kiro.dev/mcp/server_initialized notification is the signal that a reconcile actually spawned the server, and the gate does not yet consult it. A watcher that fails at runtime therefore reads as success with nothing red; the troubleshooting entry below and the manual restart are the recovery, and confirmation-based hardening is a named follow-up.

What the reconcile keys on shapes what the dashboard writes. An added, removed, or edited mcpServers entry is acted on; disabled: true stops the server's process and disabledTools hides a tool. A @server ref ADDED to tools is honoured from the next turn — so the sync's write order (entry, then ref) is fine. But a ref REMOVED while the server keeps running leaves its tools mounted, so dropping the ref is not a disable. The dashboard's disable path (_sync_mcp_to_agent, single and batch) therefore writes disabled: true onto the agent-file entry as well as removing the ref from tools and the ref and every per-tool @server/tool grant from allowedTools (mcp_utils.without_mcp_refs; the / boundary keeps a prefix-sharing @serverx), and the enable path lifts it. The disabled in the kiro-global file cannot stand in: includeMcpJson is pinned false, so kiro-cli never reads that file. The marker also helps a cold session — a disabled server is no longer spawned only to sit unmounted.

A probe that FAILS after the sanitizer stripped a declared env key names the key in its error (_note_denied_env). The sanitizer's own WARNING goes to the gateway log, which is not where someone staring at a red badge is looking: a Python server configured through env.PYTHONPATH fails the probe while working in a session, and unexplained that reads as a probe bug rather than the launcher boundary it is.

Managed servers that follow kirocrew-core

When kirocrew-core is in the stub set, Kiro Crew's other caller-aware managed servers join it (config.integration_sections.MANAGED_STUB_FOLLOWERS), so each is one shared backend instead of one process per session. They already need no launch approval (managed launch), get the per-session token from gatewayd, and consume the injected caller block. kirocrew-computer stays out (tenant-nonce gated), and so does kirocrew-cron (outside what this layer was measured on). Joining the stub set mounts nothing: only servers a spec already declares are wrapped. An operator can turn any one off in MCP Management; that choice is stored as an override and survives later kirocrew-core toggles.

Stub launch approval

A stub roster entry selects routing, while ~/.kiro/crew/mcp-launch-approvals/approvals.json authorizes the exact resolved command and arguments together with the derived effective-environment hash that gatewayd may run outside a session sandbox. Command and environment hashes are stored and checked as one pair, so values from two approvals cannot be combined. The approved fingerprint hashes the declared environment with its ${VAR} references unexpanded. When that declared launch is approved and only an expansion changed, a rewrite pass whose environment sidecars all publish records the new pair and drops the older expansion of the same launch: the values come from the gateway environment (the operator's shell and the crew .env), which no agent can write. A sidecar publication failure drops every rebind from that pass, so gatewayd refuses the changed expansion and the next boot retries. A changed command, argument or declared env text is still refused. Both halves of the fingerprint fold exactly three gateway-computed spellings (hashing.install_aliases), each in the ONE slot the gateway's own writer (apps/bridges_mcp.py) emits it in: sys.executable (what the rewriter substitutes for a manifest's bare python3 and for the kirocrew host CLI) folds only as the command, the absolute path of the deps_boot shim folds only as an argument (hashing.launch_token_bytes, which takes the slot's role from the caller), and the directory holding the kiro_crew package folds only as an os.pathsep segment of the declared PYTHONPATH (hashing.env_value_bytes, which takes the key). Each hashes by role rather than by the versioned directory a release places it in, so the approval survives the upgrade that moves that install. Matching is raw-string equality -- no containment, no case folding, no path parsing -- so an agent-written token is folded only when it is byte-identical to a string the gateway computed from its own interpreter and package location AND sits where the gateway puts it; any other spelling, including a case variant or a sibling file under the same prefix, and the same spelling in any other slot (the package directory as a --plugin-root value, or under another env key), hashes literally and is a changed launch. Every process that hashes a launch (the rewriter, gatewayd, the broker stub) computes the table from itself and they agree because they run from one install; the one spelling they can disagree on is Windows' 8.3 short name, which the stub is launched through when the install path holds a space (rewriter._cmd_safe_command), so on Windows each of the three also enters under its long name (GetLongPathNameW of the process's own path, never of a token; no link is followed). An approval whose digest was recorded without this encoding reads as changed_needs_reapproval and needs one re-approve in Customize → Connections → MCP Servers (MCP Management, reachable without developer mode). No digest without the encoding is accepted. Two installs sharing one data home (the desktop app and a dev venv, say) therefore admit each other's approvals of a python3-pinned launch, since each reads the alias as its own interpreter; that widens nothing, because each gateway already runs as the user on that interpreter. An absent or empty store approves nothing. A stub without a matching fingerprint stays on the session's unpooled, sandboxed launch path. A queued cold spawn reloads the store after admission and resolves the same command and environment identity again immediately before the fork, so revoking an approval while it waits prevents the process from starting. A stub with no recorded approval needs one in Customize → Connections → MCP Servers before it pools. Cached recommendation seeding may add a stub route, but it grants no launch approval; the seeded row stays on the session-sandboxed path until the operator approves it.

The MCP Management toggle resolves the launch at the time of the operator's choice. Every stub: true is a compare-and-set on the launch read at that moment (expected_launch), the first approval of a name included: the UI reads GET /api/mcp-gateway/servers/launch?name=<name>, which returns name, commands, envs, complete and, only when the resolution is complete, expected_launch. This scrubbed, bounded GET follows the other dashboard read routes and does not require owner identity; the POST that records the choice remains owner-only. The bulk review reads every candidate at once with the owner-only POST /api/mcp-gateway/servers/launch and a names list of up to 200 servers. It resolves the whole list in one rebuild and rewrite pass, plus one more pass for each extra name sharing a target_stem with another (foo-mcp and FOO_MCP), because one pass would merge their launches under the stem. It returns launches (the same display per name as the GET, through the shared launch_resolve.launch_preview) and errors (a code per name: invalid_server_name, launch_over_cap or launch_unresolved). POST /api/mcp-gateway/servers/stub refuses a missing token with 409 expected_launch_required, a truncated resolution with 409 launch_display_incomplete, and a token that no longer matches the resolution with 409 launch_changed_since_display. A batch stub: true returns 400 batch_stub_requires_individual; batch stub: false is accepted. Turning a stub off revokes the approval first, and restores it when the config write does not commit. The approval also stores the redacted, bounded display of the approved launch, so a changed_needs_reapproval refusal carries approved_commands and approved_envs beside the new commands and envs; an approval recorded without a display omits both fields. The refusal record carries each command argv with its redacted declared environment, scrubbed and bounded before they enter it, but the dashboard does not display them: the page shows only that a server needs approval, not the command it would run. Status polling only reads that record; it does not rebuild or resolve agent specs. Every identity serialized into expected_launch has exactly one command and one environment behind it, so an approval covers the exact launch the gateway resolved, pinned by expected_launch, whether or not any command was shown. One click on the row -- or a confirm in the bulk review -- approves the launch read at that moment, sending back the stored command/effective-environment pair for the row. The handler compares it with both the stored refusal and a fresh resolution before any write; a changed launch returns 409 and preserves both stores. A matching launch replaces the fingerprint and clears the refusal. A changed command, arguments, or declared environment requires the same re-approve flow.

On the page, the hero card holds the page-wide sharing switch and the measured memory figures (GET /api/mcp-gateway/footprint, owner only, PSS read from /proc; hidden when any process cannot be read). Turning that switch on asks first and names every server it shares: the ones enabled by hand, and the shareable ones nobody chose for, each pinned to the launch read for it. It never enables a server turned off by hand (a false entry in stub_overrides), a credential vendor, or a server waiting for approval.

Under Advanced, each row's control is one switch, Enable MCP sharing. Turning it on reads the launch, then sends the stub write carrying that expected_launch. Turning a row's switch off turns a share off. A row refused as changed_needs_reapproval reads Paused · command changed. It runs nothing shared, so its switch reads off; pressing it writes nothing and moves focus to Approve update, which is the only control that approves the new launch, pinned to the refused launch's own expected_launch. A row refused as added_outside_dashboard reads Paused · not approved yet and behaves the same with Approve. A marked row that cannot share (a refusal with no approvable identity, or an env a shared copy would withhold) has no switch, only a Remove button that takes the mark off. A row's Details shows the launch in the gateway's display-safe form (argv, env key names, never a value), with the approved launch beside the new one for a changed command, the changed arguments and env names said once above them and marked in the new one. Review and approve opens a dialog over the waiting servers only, one Approve per server, the same pinned write; there is no approve-all. Enable all shareable lists the candidates by name and shares on one more press.

The gateway-owned mcp/resolved/ store is sealed read-only in session sandboxes because its record chooses the entry point substituted for an approved npm launcher. Resolve-once therefore gives sandboxed npm a private prefix below the sealed runtime parent, using the existing validated carve-out that accepts only self-derived runtime directories. After validating the completed tree, the gateway process renames it into mcp/resolved/ before committing the record. The carve-out cannot cover the sealed store.

Which mcp_gateway.* knobs a config write reaches

Two knobs are resolved per use rather than captured at boot, so a config.json write applies with no broker restart:

  • resolve_once_refresh_hours — _mcp_resolve_refresh_secs() reads the live snapshot (falling back to a fingerprint-cached load before the watcher has primed), so the pre-resolve loop's per-iteration re-read is a real re-read: a longer or shorter window takes effect on the next pass. It is read in the GATEWAY process, which is where the config watcher runs.
  • apps_enabled — retired as a preference (nothing writes it; see mcp-apps.md), but a stored false is still an opt-out. The MCP Apps gate reads it on every call through the fingerprint-cached KiroCrewConfig.load(), so the opt-out applies with no daemon restart, and an unreadable config fails closed.

enabled is neither per-use nor boot-only. POST /api/mcp-gateway/enable writes it and applies it in-process: the broker is stopped and, while any server is still stubbed, restarted so every stub is re-emitted with or without --poolable, and sessions are relinked. A write that bypasses that endpoint takes effect at the next gateway start.

response_spill_threshold_bytes is read in the BROKER process (gatewayd), which runs no config watcher — config.live.snapshot() is always None there — so a per-use read of the live snapshot would be inert and the field stays boot-only (RESPONSE_SPILL_THRESHOLD_BYTES, resolved once at import: env pin KIROCREW_MCP_SPILL_THRESHOLD → config key → built-in 256 KiB), marked restart=True like the rest of the section. read_buffer_limit_bytes is boot-only for a second reason as well: it is handed to asyncio readers as limit= when they are CONSTRUCTED and cannot be changed afterwards. The stub reads no config: the rewriter resolves the config value (ignoring the environment) and stamps it onto each stub's argv as --read-limit, and the stub resolves its ceiling as KIROCREW_MCP_READ_LIMIT, then the flag, then the config key, then the 64 MiB default. Because the value rides the overlay, read_buffer_limit is an input to the rewrite fingerprint, so changing the key regenerates the overlays. test_mcp_gateway_stub_import_budget.py pins the module set a running stub holds, which is what keeps the config package out of it. socket_path, overlay_dir, idle_timeout_secs, max_backends, prewarm_count, stub_servers, poolable_servers, stub_overrides, pool_identity_env, forward_declared_env, spawn_concurrency_initial, spawn_concurrency_min, spawn_concurrency_max, spawn_queue_wait_secs, initialize_timeout_secs, host_budget_max_procs, host_budget_max_rss_mb and host_budget_max_fds ride the daemon's command line or size structures built once at spawn, so they too are marked restart=True in the config schema and apply to a broker started after the change.

What partitions the pool, and what deliberately does not

PoolKey (mcp_gateway/pool.py) is the sharing boundary: two stubs whose keys hash equal get one backend process. Its rule is that every attribute which changes backend behaviour must be a dimension, or two sessions can see cross-tenant state. The six dimensions are server_name, command_args_hash, effective_env_hash, work_dir, binary_version and os_uid.

The rule has a second edge that matters just as much: an attribute which does NOT change backend behaviour must stay out. The hash is injective over every field, so a difference in one that isolates nothing still forks a process.

Read the cost carefully before tuning the pool from it. A field is only as expensive as the number of distinct values that reach it, and agent_name is not a dimension: the agent never reaches the backend process, so two agents declaring one server identically asked for the same process and now get it. What the agent name was still reached for is answered per call or by content instead — app_call governance resolves the acting agent from the call's own session key and denies when it cannot, and a private backend's declared-env sidecar is content-addressed by server plus the effective_env_hash the key already carries. config_snapshot_hash is not a dimension either: the stub sends a constant run of zeros for it, so it partitioned nothing at all.

Four fields a stub reports under a "security boundary" label are in that class and are not dimensions: sandbox_mode, autoapprove_set_hash, approval_mode, trust_all_tools.

  • The sandbox is not applied to a pooled backend at all. gatewayd spawns backends outside any mount namespace, as an accepted and documented risk (backend.spawn_backend's security-boundary note, and security.md under MCP Gateway). The per-session sandbox wraps kiro-cli, not a gateway-spawned server. Two sessions configured for different sandbox tiers therefore get processes confined identically, so splitting them buys a second unsandboxed process rather than a second sandbox. The compensating controls that do the real work here — the target command coming only from the rewriter's KIROCREW_MCP_TARGET_<SERVER> vars, credential-env scrubbing before gatewayd inherits, and backends running as the invoking user — are all per-host, not per-key.
  • Approval is decided before a call reaches the gateway. Tool visibility, the autoApprove list, the approval mode and trust-all are kiro-cli's own per-agent decision, taken against that agent's overlay entry. What arrives at the stub is a tools/call kiro-cli has already authorised. A backend never receives these values and cannot act on them, so they cannot change its behaviour. The rewriter deliberately preserves autoApprove on each wrapped entry (_build_stub_entry) precisely so that per-agent surface survives pooling; the stub's --auto-approve / --approval-mode / --trust-all flags feed only the register payload.

os_uid stays a dimension. The cross-OS-user boundary is real, and it is independently enforced as well (the broker socket is 0600 and the daemon checks the peer uid), so the dimension costs nothing it does not also deliver.

The four fields are still accepted on a register payload and ignored — the same wire-compat treatment user_identity and channel_id get. A stub and a daemon are upgraded separately, and an adopted daemon predating the change runs a PoolKey.from_register that hard-requires all four, so a stub omitting them would have every register rejected as malformed and the whole install silently un-pooled. test_mcp_gateway_poolkey.py pins both halves: the field set is asserted explicitly, so adding or removing a dimension is a deliberate test change, and a payload carrying any value for the four still registers to the same key.

Admission before allocation

The daemon bounds how many backend processes it FORKS AND INITIALISES at once, and how many it is answerable for in total, before anything is allocated. Two objects, built once in run_gatewayd beside the pool (mcp_gateway/admission.py, mcp_gateway/host_budget.py) and threaded into every spawn path -- pooled, connection-private, mid-call respawn and prewarm -- through _acquire_backend:

  • HostBudget charges a fixed per-backend estimate (procs, rss_mb, fds) BEFORE the fork and releases it only when process.wait() returns, so a backend that survives SIGKILL stays charged until it is really gone. Pooled, private and fallback backends are charged identically: exclusivity is a topology property, not a budget exemption, and a stub's per-session exec after a compat/isolation rejection is one more process on the host, charged by the daemon when it sends the rejection and released when that connection reaches EOF (a new stub keeps the socket inheritable across its exec so EOF is the backend exiting). Ceilings come from mcp_gateway.host_budget_max_*; 0 derives processes from the available-memory sample the supervising gateway passes on argv (never below max_backends) and descriptors from the daemon's own RLIMIT_NOFILE, and leaves memory unbounded.
  • SpawnGate is one daemon-wide count of spawn+initialize windows in flight, FIFO past that. Fixed capacity from spawn_concurrency_initial (default 4), clamped to [spawn_concurrency_min, spawn_concurrency_max] (1/8, the ceiling raised on the daemon's argv to the subagent ceiling when that is higher, so a fan-out the subagent cap admits is not queued behind eight backend initializations); set_capacity(n) is the seam the adaptive controller plugs into. A Permit covers the fork and the backend's first initialize: ready is sent to the stub before the handshake arrives (the stub forwards kiro-cli's first frame), so the spawn path never awaits it inline -- a detached watcher on _init_done_event, bounded by Backend.initialize_timeout_secs (a constructor field fed from mcp_gateway.initialize_timeout_secs, not a module setter), settles the permit success (ready), failure (handshake failed; the permit is then held until the process is reaped) or neutral (no handshake ever arrived -- an unused prewarm or a client that never initialised is not congestion). settle is exactly-once and separate from release, which is idempotent and settles neutral on its own; cancellation at any boundary is neutral. Prewarm settles neutral the moment the fork returns; it also re-reads the queue depth BEFORE EACH KEY and stands that key down while any stub is queued (_PrewarmStoodDown, logged and skipped like any other prewarm failure), and takes its wait with a _PREWARM_SPAWN_WAIT_SECS deadline. Both because a pass lasts as long as its spawns: a once-per-pass check leaves a stub that arrives during one queued behind the rest of it, and the gate has no priority lane, so what bounds a stub sitting behind a prewarm that already enqueued is that deadline. An unbounded prewarm wait would also park under _prewarm_lock, which the credential-rotation re-warm has to take.
  • BackendPool.reserve_resident_slot moves the max_backends check in front of the fork: a slot is claimed (or PoolAtCapacity raised with nothing to reap) before spawn_backend, and add consumes it. Private backends take none.

Acquisition order inside _acquire_backend's spawn closure -- after the per-key _spawn_locks dedup and after CircuitBreaker.allow, so a permit is never held during a breaker cooldown and no pool lock is held while queued -- is SpawnGate → HostBudget → resident slot → fork, released in reverse on any failure before the fork. Deadlock argument: the budget and the slot never wait (they succeed or raise), so the only wait is the gate's FIFO, and a gate waiter holds nothing another waiter needs; a holder of resource k only ever waits for resource k+1, so the wait-for graph is acyclic. That is why the gate is first and not last. A charge taken before the wait prices a process that does not exist for as long as the wait lasts -- up to spawn_queue_wait_secs, 600 s by default -- so a queue of ten reaches the ceiling with nothing running and the eleventh stub is refused capacity on an idle host, a refusal that deliberately authorises no fallback. Taken after the permit, the budget and the slot are read against the host as it is at the moment of the fork. The daemon's drain closes admission FIRST -- queued waiters fail with SpawnGateClosed, watchers are cancelled (releasing their permits neutral), charges are dropped -- then proceeds with the existing teardown.

Wire. The registered reply carries the daemon's code_fingerprint. A stub whose --server names one of Kiro Crew's own MCP servers and whose target argv names its managed subcommand also puts its stub_code_fingerprint on the Register frame and requires the two values to match exactly before it keeps the broker connection. A missing value identifies a pre-fingerprint daemon; a different value identifies another installed code generation. Either condition closes that connection. At cold start the stub takes its normal per-session fallback_exec, so a package upgrade cannot leave current MCP servers consuming stale caller-identity or directive frames. On a mid-session reconnect no exec remains (initialize is long consumed), so the stub refuses that generation terminally -- the same exit as the poolable_ack and tenant_nonce refusals -- rather than retrying a daemon that is up and will keep answering the same way for the whole reconnect budget. This is a protocol compatibility check, not an authorization proof. Third-party targets send no stub_code_fingerprint and retain their existing binary-version pooling and old-daemon compatibility.

Fallback identity. fallback_exec keeps the stub's session token (KIROCREW_STUB_SESSION_TOKEN) only when the target passes the same _spawns_own_control_plane vetting gatewayd applies before it hands a pooled backend the token: control-plane name, managed binary by real path, exact args, no loader or PYTHON* overlay in the child env (Kiro Crew's own pinned UTF-8 values excepted), and no import root shadowing kiro_crew. A kept token also gets PYTHONSAFEPATH (and PYTHONNOUSERSITE unless user-site holds this package). Every other target has the token removed, so a third-party binary never inherits it. Without the token a fallback control plane relies on the kernel peer check alone, which cannot name the session on a runtime hosting several sessions or over TCP, and every policy read is refused identity_unattested.

REGISTERED_CAPABILITIES carries spawn_queue. A stub that saw it sends {"type": "ensure_backend", "wait_budget_secs": N} and the daemon queues the spawn for min(N, spawn_queue_wait_secs) LESS _QUEUE_REFUSAL_MARGIN_SECS (capped at half, so the subtraction is strict for any N), writing {"type": "queued", "position": p, "capacity": c, "in_flight": i, "waited_secs": w} every 5 s; a stub that did not negotiate it sends the bare frame, never sees queued, and its gate wait is bounded at 20 s so its own 25 s pre-flight timer still governs. The margin is the same property as that 20 s: the daemon has to give up first. The stub starts its timer before it writes the frame and the daemon starts its own only after reading it, so equal budgets -- which is what the shipped defaults are, 600 s on each side -- expire on the stub first, and a stub whose budget expires runs the per-session fallback_exec that a capacity refusal exists to withhold, charged to nothing. Raising spawn_queue_wait_secs above the stub's constant is harmless for the same reason: what the stub asked for caps the answer before the margin is taken off it. While any acquire or respawn waits, the connection handler keeps reading (_await_answering_pings): bridge pings get their pong at once and any other frame is parked and processed in order afterwards, so the stub's liveness monitor never declares a queued daemon dead -- bounded in both dimensions by _MAX_PENDING_FRAMES / _MAX_PENDING_BYTES, the same guard class as backend._STUB_INBOX_MAXSIZE in the reverse direction, because only the main loop drains the park and it cannot run until the wait returns; past either bound the pending acquire is cancelled and that ONE connection is dropped so co-pooled sessions survive. rejected frames carry class: capacity (resident pool full, host budget exhausted, wait budget spent, breaker OPEN, a fork refused for memory/descriptors) with retry_after_secs; compat (a pooled target this daemon cannot run or map); isolation (a private target it cannot launch). fallback: true rides compat/isolation and NOTHING else, on every wire shape: it authorises the stub's own per-session exec, and a stub that never negotiated spawn_queue closes its socket before exec'ing, so the charge _reply_rejected takes is released at that EOF -- before the process it pays for exists -- and N simultaneous capacity refusals would leave N backends the host budget never sees, which is the unbounded fan-out admission exists to end. The compatibility cost is deliberate and falls on the pre-spawn_queue stub alone. It cannot read class, so it reads the untagged refusal as terminal and exits 1 with initialize unanswered: kiro-cli reports that server as failed and that ONE session loses its tools until the retry, where before it would have run an unaccounted copy. The bound is on the refusal ARRIVING inside that stub's own pre-flight window, which is 25 s in the pre-upgrade binary: a refusal later than that reaches a stub which has already given up waiting and exec'd on a path that reads no frame, so the exec is unaccounted however the frame is tagged. What keeps the daemon inside the window is _LEGACY_SPAWN_WAIT_SECS, pinned strictly under 25 s. It bounds the GATE wait only, so a refusal raised after the permit — a full pool or an open breaker, past up to _MAX_SPAWN_DRAIN_RETRIES spawn-and-initialize rounds — can still exceed it; that residual is the reason the pin exists rather than a claim it removes. The refusal is recorded on both sides -- _audit_pool_rejected on the daemon, a terminal: line in stub_fallback.jsonl that fallback_counts() keeps separate from real fallbacks in the stats reply -- so the degradation is observable rather than silent. A stub that DID negotiate spawn_queue pays nothing: it keeps its transport and answers -32001 below. compat is not refused with it, because there the host is fine and the exec is the topology the connection asked for; refusing it would strand every session behind a daemon whose target map drifted. The stub (stub.py) negotiates spawn_queue on all three of its paths -- cold-start ensure_backend, the _reconnect replay (which pre-flights before replaying initialize, and retries a capacity answer within its remaining budget) and the bridge (where a queued frame during a respawn counts as proof of life like a pong) -- and renews a 25 s SILENCE timer on queued/keepalive/pong rather than running a fixed deadline, bounded by its 600 s reconnect budget -- inside which the daemon's own wait always ends, per the margin above. The capacity rejection that ends the wait is answered to kiro-cli as JSON-RPC error -32001 with data.class and data.retry_after_secs on every request, the stdio transport left open (_serve_capacity_refusal): the session is told the gateway is full, not that the server crashed, and no exec is run. The stats frame carries an admission snapshot (gate capacity/in-flight/queued/outcomes, budget counters).

Windows target command spelling

A bare Windows command resolved through shutil.which has its on-disk basename restored before it is spawned or persisted. which can append uppercase .EXE from PATHEXT even when the file is named demo-mcp.exe. Windows can open that path, but a launcher that dispatches by its own basename with a case-sensitive lookup can reject it. The repair (kiro_crew.env.resolved_command_casing) scans the resolved path's parent directory and substitutes the unique case-insensitive basename match instead of canonicalizing the full path.

The three MCP server command resolvers share it, next to the mcp_search_path they already share: the agent-config resolver (agent._resolve_command), the dashboard probe (mcp_discovery) and the rewriter. The respawn lookup of a gateway restart in cli_server (_own_console_script and the PATH fallback in _spawn_detached_gateway) uses it too. Other resolvers of Kiro Crew's own binaries stay outside it: the kirocrew lookup in agent._resolve_kirocrew_bin, and the kiro-cli resolver, whose discovery in kiro_cli.py does its own Windows realpath. So do the ACP adapter ladders in acp/launch.py and acp/harness/{claude,pi}.py, which call acp/launch.py's _normalize_exe_casing. The agent-config resolver is the one that matters most: its result is written as the spec's absolute command, and an absolute command is accepted verbatim on every later pass, so an uppercase spelling persisted once would look operator-authored to the rewriter forever. Repairing at the resolver rather than at the write site also keeps the provenance record's emitted value repaired, so command_is_ours still recognises the entry and re-derivation stays enabled.

That narrow lookup preserves the lexical parent route (including a directory junction) and a file symlink's own name. Explicit absolute commands retain the operator's spelling, with one exception: kiro_crew.env.saved_command_casing heals an absolute command whose stem matches the directory entry exactly and whose extension differs only in case (demo-mcp.EXE -> demo-mcp.exe). That is the spelling an older build persisted from PATHEXT, so it repairs itself on the next rebuild; a stem written in different case is kept. Empty or unresolvable commands remain unwrapped; an OSError while reading the parent, or an ambiguous case-insensitive match in a case-sensitive directory, keeps the which result. POSIX paths are unchanged. The normal cache-hit and transient-keep checks compare the same normalized bare-command probes, so a case-only rename invalidates a cached resolution without changing its alias route. The normalized spelling is a rewriter fingerprint input, so a cached overlay carrying another spelling is regenerated. Stub argv and the daemon target map therefore consume the same command string.

Stub argument transport

Generated overlays carry backend arguments as a base64url-encoded UTF-8 JSON string list in --target-args-b64. Pool-identity environment names use the same codec in --pool-identity-env-b64. The encoded alphabet contains no shell metacharacters: a Windows CLI can reparse the launch through cmd.exe without turning a delimiter into a pipeline. Empty arguments, Unicode and literal pipes retain their original boundaries. This is encoding, not encryption; arguments remain visible on the command line, and the longer representation still counts against the host's command-line length limit. On Windows, generation warns with the server name and command length when the base stub command reaches cmd.exe's 8,191 UTF-16-unit limit; it never logs the argument payload or rejects a launcher that can use a longer command. Per-session additions can grow the command further.

The stub decodes before both fallback launch and command hashing. The rewriter's daemon target map decodes identically, preserving the hash used to select a backend. Encoded flags take precedence when present; malformed payloads fail rather than falling back to different arguments. Legacy --target-args, --pool-identity-env and --target-args-sep remain readable, and a cached delimiter-based overlay fails the rewriter fingerprint and is regenerated. The rewriter and stub must come from the same package; a stub that predates the encoded flags cannot consume them.

Encoding the backend arguments alone leaves the rest of the stub's metadata raw: the target executable path, work dir, socket, env sidecar path, server and agent names and the autoApprove JSON. cmd.exe expands %NAME% for any NAME set in its environment inside any of these, quoted or not, and offers no escape for it on a /c command line -- measured natively, python%X%.exe reached the stub as pythonexpanded.exe and the tool name read%X% as readexpanded, so the stub launched a different executable and registered a different approval hash than the daemon computed from the operator's spec. The overlay therefore carries the stub's whole flag list as ONE envelope, --stub-flags-b64, using the same codec; inside it the flags keep their plain spelling. stub._parse_args and the rewriter's _collect_target_env splice the envelope back through hashing.expand_stub_flags before reading, so a plain-flag overlay written by an older rewriter parses through the same path and hashes identically. The per-session --channel-id appended by session_servers rides its own envelope. A cached plain-flag overlay fails the rewriter fingerprint and is regenerated. The interpreter path in the entry's command is the one value the codec cannot cover: the CLI runs it, not the stub.

Overlay scope: user-level agents only

The rewriter reads ~/.kiro/agents/ and writes one overlay per agent NAME, so the overlay directory describes user-level agents and nothing else. kiro-cli also resolves --agent against <project>/.kiro/agents/, which means a session can be running an agent of that same name from a different file. session_servers therefore takes the session's checkout: an agent the checkout declares has no overlay, the lookup answers nothing, and the session launches the servers its project spec declares.

Injecting the user-level stub instead handed that session servers the project never declared, and left the project's own declaration of a same-named server unlaunched, because a session-injected entry outranks the spec entry it shadows. The scope reaches pooled_session_servers and injection_server_names through one guard, because the second is what a mirror withholds from its own projection: a name withheld but not injected costs the session that server entirely. Which names a checkout declares is read from agent_discovery.project_agent_files and project_agent_name, the same pair acp/session_mcp.py resolves the session's agent spec through, so the two cannot disagree about which file the session runs.

Those servers run unpooled -- outside the pool, outside caller-identity attribution, outside broker governance -- the same direction every other unvouchable stub takes here, and the lookup says so at WARNING rather than debug: this is an ordinary configuration rather than an error path, so at debug the governance downgrade would be exactly as silent as the defect it replaces. Brokering them instead is not an overlay change: gatewayd resolves a backend command from KIROCREW_MCP_TARGET_<SERVER> in its OWN process env, written at daemon launch from the rewriter's target_env, and a stub never tells the daemon its target. An overlay written for a project agent after launch therefore has no target the daemon can resolve, so closing that half needs a channel for a target the daemon was not started with.

One host is the exception, and for it the scope must NOT be applied. KAS projects the agent spec itself (acp/harness/kas.resolve_projected_spec), nearest-first, but a checkout's spec never supplies a server there: a name the user level declares resolves to the user-level spec, and a project-only agent gets no servers, so the user-level servers ARE the ones a KAS session runs even when the checkout declares that name. Scoping its lookup would collapse the stub set to empty, the projection would declare the user-level servers un-subtracted, and they would run outside the broker while the operator has the gateway switched on -- the governance loss inverted. Membership lives in ACP_BACKENDS_USER_LEVEL_AGENT_SPECS_ONLY and is read through agent_sdk.backends.overlay_project_scope rather than as "is KAS", so a host added later that reads the user level alone joins the set instead of needing a branch. The KAS harness's own call passes work_dir=None for the same reason, which keeps both halves of that session -- what is injected and what is withheld -- on one answer.

The checkout is only half of that scope. project_agent_files scans the *.json and *.md spec forms alike, because whether a checkout's spec may be projected is a governance question for its consumers rather than a question of form; this lookup is narrower, since it is deciding whether the agent the session RUNS came from the checkout. kiro-cli discovers *.json in a checkout, so a project foo.md with no JSON twin must not suppress a user-level foo.json's stubs: that would leave the servers kiro-cli does activate running with no pool, no caller-identity attribution and no governance, which is the same loss this scope exists to prevent, reached from the other side. overlay_project_scope therefore answers in keywords -- the checkout together with markdown_specs -- and every call site splats that one mapping, so no site can take the checkout without its format rule.

markdown_specs is has_mirror, the same registry read both call paths already use to decide whether a projection happens at all, because the hosts genuinely disagree and each answer is right for the host holding it. A MIRRORED host's array is composed by Crew from a spec acp/session_mcp.py resolves through project_agent_files, which honours the markdown form: a project foo.md declaring gitlab comes back from _agent_spec_for with that server. For those hosts the markdown file IS the agent running, so its shadow must suppress the overlay -- otherwise the user-level foo.json's stub survives, outranks the project's own declaration, and mounts that stub's command and credentials under the checkout's agent. A host with no mirror resolves no project spec through Crew at all, so it takes the JSON-only answer for the same reason kiro-cli does.

ACP_BACKENDS_MARKDOWN_AGENT_SPECS -- a host reading the markdown form from a checkout itself -- is deliberately not OR-ed in, because its only member also reads the user level alone and leaves with no checkout, so the term would have no caller able to reach it. test_agent_sdk_capabilities pins that containment, so a host which breaks it fails there naming the decider.

That kiro-cli discovers project *.json and not project *.md is MEASURED on the shipped binary rather than read off a document, because the documents disagree: the vendored upstream reference describes the IDE 1.0 / CLI 3.0 schema and says the filename without .json or .md becomes the agent name, while agent_spec_format's own header records markdown as the v3 engine's form. On kiro-cli 2.22.0, kiro-cli agent list run inside a checkout holding both probe-json.json and probe-md.md lists exactly one workspace agent, probe-json; probe-md does not appear. A newer CLI that does discover project markdown would make this backend a member of the markdown set, which is the condition the containment pin names. That measurement is not a one-off: the KIROCREW_E2E_REAL_KIRO_CLI-gated suite pins it beside the session/new precedence guard, and its failure message names the set to join, so an upgrade that adds project markdown discovery reports the remedy rather than silently reopening the defect.

The parse requirement travels with the form set, because both answer one question: WHICH RESOLVER decides this session's spec. A mirrored host's spec comes from session_mcp._project_spec_path_for, which scans both forms and matches on project_agent_name -- filename fallback included -- and which, once it matches a project file, returns that file's read without falling back to the user level. So a malformed project spec leaves a mirrored session with NO spec: no tools allowlist, no project servers. The overlay must not fill that gap with the user-level agent's stubs, so a mirrored host takes dispatchable_only=False and suppresses on the malformed file. kiro-cli resolves the checkout itself, reports a malformed spec as an error and runs the user-level agent instead, so it takes dispatchable_only=True and keeps the stubs that belong to the agent it is actually running. The two hosts take OPPOSITE answers on the same file, and overlay_project_scope computes both facets from one has_mirror read so neither can be set without the other.

A project spec that does not PARSE is not a shadow for a kiro session either. project_agent_name falls back to the filename stem for a malformed file, so a broken foo.json matched foo and withheld a good user-level agent's stubs, while kiro-cli reports that file as an error and offers no such mode -- measured the same way: a malformed project spec yields Error: Json supplied at ... is invalid and zero workspace agents. _project_shadow_of takes dispatchable_only for that, and its default is unchanged so the governance refusal in agent_materialization/worker_agent.py, for which a file in any state is a claim on the name, keeps refusing.

How app agents reach MCP servers

An app declares MCP servers in its manifest, and apps.bridges._register_mcp_servers() writes them into Kiro Crew's agent config under a {app}:{server} namespace rather than into the shared Kiro global, because that global is read by Kiro IDE and every other kiro-cli agent, so an app's private tools would leak into surfaces that never installed it.

An HTTP MCP server whose backend port cannot be resolved live is not written at all, and any stale entry for it is scrubbed. A manifest's illustrative fixed port written verbatim while the backend is down is a reachable-looking but dead URL, and kiro-cli connects to every server in the agent config on each request, so one dead entry surfaces as a transient 5xx and then a hard error for all requests, not just that app's. The enable path re-registers with the real port once the backend is up.

Connection and tool exposure are separate. An entry in mcpServers is still connected even when it has no matching @server reference in tools; omitting the reference hides that server's tools from the agent but does not avoid the process or connection cost. Isolation and feature gates that must avoid that cost therefore remove the server entry itself as well as its tool reference.

An app agent that references a host-managed server (@kirocrew-core, @kirocrew-cron) in its tools gets the launch spec copied in by _materialize_managed_refs(). kiro-cli resolves a @server ref against the agent's own mcpServers plus the global mcp.json, and managed specs live in the host agent's config only, so without that copy the ref dangles and the tool silently never mounts.

Containment for app agents has three layers:

Layer Mechanism Where enforced
Agent config managedToolPolicy renders as disabledTools; a neutralize entry re-declares a server with every tool disabled and does not add it to tools Written at registration, no network
kiro-cli Reads disabledTools and filters before the model sees the list In-process, no network
MCP server GET /api/session-tool-policy returns the calling session's managedToolPolicy.exclude, and the server filters tools/list and tools/call. A spec that sets managedToolPolicy.honourToolRefs: true also gets an include entry for each Kiro Crew managed server it grants only through @<server>/<tool> refs (include: {"kirocrew-dashboard": [...]}): that server lists only those tools and refuses any other call (rejected_not_included). Each server named in managedToolPolicy.excludeServers is answered as an empty include entry (include: {"<server>": []}), overriding any per-tool entry: that server lists nothing and refuses every call; a present excludeServers that is not a list of server names makes the policy unreadable. A malformed include is unresolved like a malformed exclude. When that read fails the policy is unresolved: tools/call refuses with an audited error, tools/list still lists everything Gateway round-trip

Which session that third layer asks for is resolved by mcp_shared._policy_session_key in the same order the strict resolver uses — the gateway's per-call caller, then the protected member binding, then the signed per-session token, then KIROCREW_SESSION_KEY and the pid sources. The RESOLVED session is what rides the request's X-Session-Key and what keys the per-session policy cache, so the answer returned and the answer stored are the same session's. Keyed on the gateway identity instead, every caller the gateway could not name shared one entry, and the cache has no TTL: two sessions on one process took each other's policy and a rekeyed session kept its predecessor's for the life of the process. The 5s startup-race window is keyed the same way: it remembers the identity it was opened for ("" for "no key yet", or the key the gateway answered 404 for) and answers only for that identity, so a tools/call that resolves a real key mid-window is asked for, not told no_session_key — a reason tools/call does not refuse on.

managedToolPolicy and includeMcpJson are in bridges._FRAMEWORK_OWNED_AGENT_KEYS, so they are refreshed from the template on every boot rather than preserved as user preferences. Preserving them is wrong in both directions: a template that later tightens exclude would never reach an already-enabled install, and anything that edits the agent file could drop the exclude list, which the framework would then faithfully preserve forever.

neutralize uses explicit tool lists rather than a wildcard, because the app discovers the real tool names, so a server that grows a tool cannot quietly slip past a stale pattern.

The third layer is defense in depth for hosts that ignore disabledTools. When the policy cannot be read, what it does depends on WHY, because the reasons differ in kind and its two consumers carry different risk.

It runs only in Kiro Crew's own servers. mcp_shared.serves_managed_tools checks where the loop's tools/call handler is defined: under the kiro_crew package (the control plane and the builtin apps) the policy applies; anywhere else -- a user-installed app that serves its own tools through run_mcp_stdio_loop -- the loop answers "nothing excluded" without a read. The policy names managed tools, so it has nothing to say about an app's own, and on the shared ACP runtime such a server is never handed a session token (identity rides only the control plane), so the read could only refuse every call. The app's tools stay gated by its spec's tools / allowedTools and kiro-cli's disabledTools. The check runs inside the server's own process and is not a boundary against the app; what it must not do is let a Kiro Crew server out, so a handler whose code location cannot be read keeps the policy.

tools/call fails closed on the four reasons in _UNRESOLVED_REFUSES_CALL (mcp_shared_policy.py): policy_unreadable, identity_unattested, identity_unattestable and resolution_failed. Each means "an operator exclusion may exist and this process could not read it". policy_unreadable is the gateway's 409 whose body carries "code": "policy_unreadable": a spec for this session exists and its policy could not be determined. identity_unattested is the gateway's 409 whose body carries "code": "member_identity_unavailable": the gateway could not establish the execution identity behind the declared X-Session-Key. Usually the request carries no X-Session-Token, or one that vouches for another key; an attested key whose execution record cannot be read, or a cron: key the scheduler has no record for, answers the same way. In every case the spec was never consulted, so whatever it excludes is unknown here. The two share a status, so the MCP side tells them apart by the body's code; a 409 whose body cannot be read or carries no code takes the policy_unreadable arm, the status's meaning for the unreadable-spec condition, so an unknown 409 is never read as anything narrower. The call is refused with an error naming the reason -- the identity_unattested text names the missing token, its usual cause, the policy_unreadable text the agents directory, and says the gateway answered so the cause is not a connection problem -- and audited as rejected_policy_unresolved; the read that produced identity_unattested is itself audited as tool_policy.unattested, whose resources carry the asking process's pid and ppid. A control-plane backend (CONTROL_PLANE_BACKENDS in mcp_gateway/daemon/control_plane.py) is handed the token per frame in the caller block and the policy read sends it, so its calls do not land there. The test for admitting a reason here is that it means ONE thing, because a refusal derived from an ambiguous reason is wrong for half the callers it hits.

identity_unattestable is decided before any request. A session key resolved locally -- no gateway caller_session, no X-Session-Token to send with it, and no KIROCREW_SESSION_KEY in the environment -- carries nothing the gateway could attest, so the dial is skipped, the read is audited as tool_policy.unattestable_key, and the call is refused with text that names the missing session token without claiming a gateway read. It is a separate reason from identity_unattested only for that text.

One missing identity reaches a reader through three refusals -- this identity_unattested text when a key is declared, the strict-identity diagnosis behind memory_recall and every other reflexive tool when none is, and the lesson writers' (learn_add, learn_remove) answer to the gateway's 400 missing_session_key (mapped onto the same established-session refusal instead of echoing the header name). When the process carries neither the session token nor a launcher host pid (mcp_shared.spawned_without_gateway_identity), nothing the gateway does at spawn happened to it, and all three append the same mcp_shared.external_client_identity_note: a server started outside a Kiro Crew session (an editor's own MCP config) has no identity channel and its identity-bearing tools are not supported; KIROCREW_SESSION_KEY is a gateway-injected fallback, not a credential, and set by hand it turns the partial refusals into identity_unattested on every call; the read-only tools work without it; the supported editor direction is connecting into a Kiro Crew session rather than spawning the server, and that server's entry in ~/.kiro/settings/mcp.json is the leftover state the design invariant at the top of this document names. The note decorates a denial and never grants: which calls are refused is unchanged, and a server the gateway did spawn keeps its existing wording (token present, or the quoted spawn denial below).

resolution_failed -- no usable answer, meaning nothing came back, a 5xx said the gateway is broken, or the resolve itself raised -- passes that test and refuses. Every 4xx returns before that arm, decided by status class, so the reason means the policy could not be READ and never that the gateway made a decision about this caller. An operator exclusion may exist while the process holding it cannot answer for it, so the empty set that arrives with this reason is unknown rather than permissive, and serving it as a permission is exactly how an excluded tool runs. The refusal is bounded at both ends: a session that resolves its policy once is served from the per-session cache and never reaches a failure path again, and for one that has not, the refusal lasts at most the 60s negative-cache window.

The other reasons stay permissive, each because no operator exclusion is known to exist for that caller or because refusal would be permanent rather than a window that closes. agent_not_resolved is the 404, returned both for a session still registering (a policy may exist) and for a caller the gateway can never map to an agent (no policy can exist); refusing denies the second class forever. no_session_key is the same gap inside the MCP process, where no agent is named at all. policy_forbidden is ANY 4xx: the gateway answered and made a decision about this caller, which for 403 member_session_unverified is the steady state of a session claiming a private memory store without a verifiable proof. A boundary the gateway is enforcing is not a boundary it failed to read. The test is deliberately the status class and not a list of codes -- a list is only as complete as its author's knowledge of the endpoint, and a status it never learned would be refused as though it were an outage. Each call through one of these windows is audited as tool_policy.unenforced_call, so they are visible instead of silent. Closing the 404 needs the endpoint to distinguish registering from unmappable.

tools/list never filters on an unresolved policy at all, whatever the reason: kiro-cli calls it once at session start and caches the answer, so hiding tools on a transient failure would leave that session permanently believing the server has no tools, unrecoverable without a restart. A listed tool that refuses when called is not a hole; an unlisted tool that runs is. Each unfiltered listing is audited as tool_policy.unfiltered_listing.

A session that has ever resolved its policy is served from the per-session cache and never reaches these paths again, so a refusal only affects a session whose policy has never been read once.

A missing session key is not cached as a policy (a startup race must be retryable, and it clears in milliseconds); a resolved key whose policy call fails gets a 60s negative cache so a persistently unreachable gateway does not add a 5s timeout to every tool call. That negative cache reports the reason of the clock it hit -- the short window an identity race, the long window resolution_failed -- so a cached read lands in the same class its live form would. Serving one shared reason would repeat the conflation the resolver exists to undo, one level down. The gateway side is deny-by-default in the same sense: a caller that cannot prove its identity gets a 400/404, never an empty policy.

An empty body from that endpoint means one thing only: this agent genuinely declares no exclusions. A spec that EXISTS and cannot be read -- unparseable, valid JSON that is not an object, a managedToolPolicy of the wrong shape, or two specs declaring one agent name -- answers 409 with "code": "policy_unreadable" in the body and a SEL denied record. A .md file with no opening --- fence is plain markdown, not a spec (agent_discovery.plain_markdown_document): it cannot declare a policy, so a fence-less <agent>.md answers {} and a fence-less file elsewhere in the directory is skipped. A fenced document that fails to parse, and a head that is not UTF-8 (a UTF-16 or UTF-32 BOM included) or carries a NUL, still answer 409. Sharing the empty body with those cases would make an unreadable deny indistinguishable from no deny on the wire, so no caller could tell them apart however carefully it fails closed. The MCP side maps a 409 carrying that code to unresolved="policy_unreadable" and does NOT negative-cache it, nor its identity_unattested sibling: the answer is immediate so there is no timeout to debounce, and both negative clocks are process-global, so caching one session's malformed spec there would refuse calls for every sibling session in a pooled backend.

The 409 body's reason names the file. Every policy_unreadable refusal the gateway writes -- the directory-wide guard (_refuse_if_any_spec_is_unreadable), the direct <agent>.json/.md read, the two shape checks on a direct read and the duplicate-name arm (_ambiguous_spec_reason, built from AmbiguousAgentSpecError.paths) -- carries the offending spec's filename (repr'd: it is untrusted input from a user-writable directory and the text reaches a terminal), the failure kind in words (not valid JSON, not UTF-8 text, markdown frontmatter the spec parser refuses, an AppleDouble sidecar, larger than the spec size cap, resolves to a path the spec reader refuses, not a plain readable file for the pinned open's refusal, unreadable (...) for any other OSError) and one remedy sentence: move, fix, remove or rename that file in the agents directory, no restart needed. Never str(exc) verbatim, and never the directory's path: the strict reader's own messages and the duplicate-name exception's message quote the full path, and this text crosses the wire into the model-visible refusal. Two arms have no file to name: the directory walk itself raised (class-name-only text, as before), and a wrong-shape managedToolPolicy in a spec the declared-name scan resolved -- the scan returns a parse, not a path, so that refusal names the agent (managedToolPolicy for '<agent>' is <type>, not an object), which identifies the spec since exactly one declares the name, and carries the same remedy. The SEL denied row carries the same reason (the duplicate-name arm's row keeps the exception's full-path message: the audit trail is local); the gateway log carries the FULL path at WARNING, once per (path, mtime) -- the client re-asks on every tools/call, so a line per refusal would repeat for as long as the file stays broken. The MCP side reads reason off the body into ToolPolicy.detail (text only; the decision is the status and code, unchanged); the one client-side policy_unreadable -- a 200 whose exclude is malformed -- fills detail with its own shape diagnosis. The refusal appends detail to the policy_unreadable refusal as Gateway reason: ... after neutralize_markers, redact_via_context and redact_local_paths (the credential redactor has no path rule, and an older gateway's duplicate-name reason quotes full paths) -- then bounds the scrubbed result at _POLICY_DETAIL_MAX_CHARS. The bound comes AFTER the scrubbers: a cut made first can land inside a token, and the fragment left behind fails the length-floored credential patterns and would be echoed. With no reason in the body -- an older gateway -- the refusal is byte-identical to what it was.

The MCP-first rule

A new LLM-facing capability MUST ship as an MCP tool, not only as a CLI command. kiro-cli calls MCP tools reliably and may refuse to run a CLI command via bash. CLI commands stay for human use; the model uses the MCP twin.

Do NOT add regex to match natural-language variants of a command. The LLM does the interpreting. Handler keywords are only for instant user-typed commands that need no model round-trip (cron list, spawn list).

Server and tool inventory

Managed servers, registered by agent._MANAGED_MCP_SERVERS and installed into ~/.kiro/agents/kirocrew.json:

Server Process Tools
kirocrew-cron kirocrew mcp-cron (mcp_cron.py + mcp_cron_*.py) cron_add, cron_list, cron_update, cron_remove, cron_remove_all, cron_pause, cron_resume, cron_trigger, cron_secret_request
kirocrew-core kirocrew mcp-core (mcp_core.py + mcp_core_parts/ + mcp_tools/) spawn/subagent, learn, task, messaging, artifact, workflow, knowledge and session-directive tools (see below)
kirocrew-computer kirocrew mcp-computer (mcp_computer.py) computer_list_apps, computer_launch_app, computer_get_state, computer_click, computer_drag, computer_type_text, computer_press_key, computer_set_value, computer_scroll, computer_perform_action, computer_end_turn
kirocrew-dashboard kirocrew mcp-dashboard (mcp_dashboard.py + mcp_dashboard_*.py) chat_folder_tree, chat_folder_create, chat_folder_move, chat_folder_update, chat_folder_move_session, chat_folder_delete, chat_tag_list, chat_tag_create, chat_tag_update, chat_tag_assign, chat_tag_column_list, chat_tag_column_create, chat_tag_column_move, session_move_to_column, chat_session_pin, chat_session_pin_move, session_create, session_fork, session_stop, session_end_wait, session_retry, session_continue, session_set_model, session_reload, session_rename, session_generate_title, session_set_color, session_close, session_revive, session_history_list, session_send, session_broadcast, session_status, session_adopt, session_handoff, session_release, session_read_message, session_summary
kirocrew-work kirocrew mcp-work (mcp_work.py) work_brief, work_report, work_ledger_read, work_ledger_rebuild, work_ledger_record
kirocrew-crew-log kirocrew mcp-crew-log (mcp_crew_log.py) crew_log_list, crew_log_read, crew_log_projection
kirocrew-debug kirocrew mcp-debug (mcp_debug.py) debug_gateway, debug_refusals, debug_threads, debug_processes, debug_snapshots
kirocrew-panel kirocrew mcp-panel (mcp_panel.py) panel_publish, panel_templates, dashboard_fields, dashboard_types, dashboard_write, dashboard_templates, dashboard_preview, dashboard_apply, dashboard_rollback, dashboard_snapshot
kirocrew-guide kirocrew mcp-guide (mcp_guide.py) guide_list_actions, guide_start, guide_status, guide_cancel, list_change_kinds, find_setting, get_member_capabilities, diagnose_settings, propose_change, get_change_status, search_docs, find_ui
kirocrew-mate kirocrew mcp-mate (mcp_mate.py) update_self, set_model, set_approval_mode, find_capabilities, request_capabilities, goal_read, set_goal, set_key_results, key_result_progress, save_goal_report, save_notes
kirocrew-secrets kirocrew mcp-secrets (mcp_secrets.py) call_api_with_secret

kirocrew-guide is a platform capability: it is always emitted (not opt_in), so the default kirocrew template, every mate built from it, the worker derived from it, and every dashboard session on them mount it, deferrable by Tool Search like any other MCP server. The conductor and background templates (agent_materialization/conductor_agents.py, the knowledge, research and heartbeat agents) keep their own narrow server sets and do not mount it: they are driven by patrols and dispatch, not by a person at the dashboard, so they have no one to show a guide or card to. It is its own server because the server is the unit of assignment, authorization and governance: an operator or a policy can withhold the whole set at once. A fresh build references it from the shipped defaults; an existing default spec gains the @kirocrew-guide ref and the grants once (guide_platform.grant_guide_platform_once, recorded by the guide_platform_granted.json marker after the spec is written), and keeps whatever its owner does with them afterwards. Its entry carries no autoApprove, and doctor never mints a whole-server allowedTools grant for it (cli_doctor._NO_BLANKET_ALLOW_MCPS). Exactly the twelve tools in agent._GUIDE_AUTO_GRANTS are exact allowedTools grants, each through the same auto_approve._apply_allowed_tools_ceiling path every grant passes, so a governance ceiling that denies one keeps it out and the user is asked instead: the reads (find_ui, search_docs, guide_list_actions, guide_status, list_change_kinds, find_setting, get_member_capabilities, diagnose_settings, get_change_status), the offers (guide_start, propose_change), which change nothing until the user presses the card's own button, and guide_cancel, which only removes this conversation's pointer. A tool added to the server later is not in the tuple and asks first. KAS permissions derive from that final filtered list. A harness whose projection does not carry the server reports it through the ordinary unresolved-ref doctor row (agent host contract); nothing special-cases its absence. kirocrew-mate (mcp_mate.py) is the mate's own record, mounted on the same specs on the same terms (always emitted, no autoApprove, its own server so the set is withheld as one and the guide set stays the user's help with the dashboard; an existing spec gains the ref and agent._MATE_AUTO_GRANTS once, mate_platform_granted.json). Its tools are named for what they do and act on the CALLING mate only, never on a name passed in, in two tiers that follow who owns the field. update_self writes the presentation the mate owns (its display name, description and ghost face, members.SELF_EDITABLE_FIELDS) at once through POST /api/member/self/update: the gateway resolves the member from the caller's pinned-thread slot, cleans each value by its own rule (members.update_member_self), publishes the record, writes member/config to the member's event log, keeps the previous values in its own bounded in-process record (dashboard/member_self_changes.py) and draws one card row of surface self in the mate's conversation (chat_cards.record_self_change) with the faces and labels to show and an Undo. The undo is the user's click, POST /api/members/{slug}/self-changes/{id}/undo with {"slot"} naming the conversation the page is showing, owner-only cookie auth off the strict prefix: it restores from the gateway's record, never from the row (the transcript is agent-writable, so a row copied into another mate's chat with its id and slug intact is refused: the record must have been made in the conversation the button was pressed in, and a request naming none is 400 slot_required), and marks the row undone; a record the gateway no longer holds answers 410. The record is kept, and the change undoable, only while every retained value fits members.MEMBER_DESCRIPTION_MAX_CHARS (a string by its length, as the write path measures it; an avatar mapping by its serialized length). set_model, set_approval_mode and request_capabilities are the card tier: POST /api/member/self/propose fixes the kind (crewmate.update, crewmate.capabilities) and the member and runs the same propose body propose_change runs (handlers.change_cards.propose_for_caller), so the mate names the ask and the user presses the same card; the outcome reaches the mate on its next turn, as every card outcome does. A set_approval_mode for the mode the thread already runs in (a record pinning none opens in MEMBER_APPROVAL_MODE_UNSET_EFFECTIVE) is refused no_change rather than drawn as a card from an empty value. find_capabilities is a read for the crewmate's conductor: POST /api/member/self/capabilities (handlers/member_capability_catalog.py) answers what the crewmate's worker has (mate_worker.resolve_worker_spec), the servers and skills this gateway has loaded that it lacks, and, for a query, the MCP registry search the MCP page runs (mcp_discover.search_registry, external text redacted). Data only, never a transport. A request_capabilities draft that names additions has them resolved by the gateway into the card's operations (additions_to_draft): a gateway server's own entry, an official registry install plan (mcp_discover.official_install_plan, the spec /api/mcp/discover/install would write), or a loaded skill; the card states where each comes from and which tools would run without asking, and pressing it writes the crewmate's own file in place (crew-mode.md, "Conductor and worker"). The worker mounts neither tool (MATE_WORKER_EXCLUDED_TOOLS). The crewmate's goal (member_goals.py, member-records/member-goals/<slug>.json, never member-rules/) splits the same way. set_goal and set_key_results are card asks (crewmate.goal, crewmate.key_results, applied and undone through PUT /api/members/{slug}/goals/long-term|key-results with an expected compare-and-set; a goal card adds a goal, or replaces one by goal_id, and the Undo of an added goal removes exactly that one). goal_read, key_result_progress and save_goal_report are direct reads and writes through /api/member/self/goals/* (dashboard/handlers/member_goals.py). save_goal_report files a weekly report or monthly review under Crewmates/<name>/Reports, as markdown or as html (one self-contained printable page, one of the two), and sends one notification linking it. save_notes replaces the crewmate's own briefing (members/<slug>/briefing.md, its [CURRENT ASSIGNMENT] section) through /api/member/self/notes (member_notes.write_member_notes, the read side's pinned, no-follow open), under the same admission as the goal writes. These goal operations are deliberately NOT in _USER_TURN_OPERATIONS: the check-in turns of dashboard/goal_reminder.py are gateway-authored hidden turns in the mate's own thread, and recording readings and filing reports is what they are for. Every other admission check below still applies. Three card asks are admitted without a turn the user sent: any turn in the mate's own pinned thread (a check-in, a sub-agent's result coming back, the goal-setup nudge of dashboard/goal_setup.py) may call set_goal, set_key_results and set_check_ins. _resolve_agent_caller(..., own_goal=True) (passed only by member.propose_self) admits such a turn when the slot is a mate DM thread and marks the request REQ_OWN_GOAL_TURN; a channel turn is still refused. The route then refuses every other request (model, approval_mode, capabilities) with not_user_turn. Each is a card: nothing changes until the user presses it, so the mate may raise its own goal, milestones and check-ins whenever its work calls for it. The workspace, memory store, member id, key and template are not the mate's to change or to ask for. Its guide and card tools, and every kirocrew-mate tool, work only for a turn the user sent from the dashboard. The gateway's admission (dashboard.handlers.guide._resolve_agent_caller, shared by the card and member routes) first requires the session key the call names to be attested by the transport (member_memory_auth.session_key_is_attested: the socket peer, or the shim's signed per-session token; else 403 unattested_caller), then resolves the caller's session key to its slot and then reads the provenance the turn runner recorded: the slot must be executing a turn now (turn_running), and that turn must not have been opened by a messaging channel (_turn_channel_origin, set from _run_chat's _directive_channel_origin at the turn's start and cleared at its end) nor have taken a channel steer since (_turn_channel_narrowed). Starting something on screen (guide_start, propose_change), changing the calling mate's own record (update_self, its card-backed asks), or taking find_ui's live observation (guide.observe) also needs the turn to be one the person sent (_turn_user_sent, set from _directive_user_origin the same way): a loop wake, a cron or app injection, a session_send, a subagent completion and a mate's hidden first-welcome kickoff are refused with 403 not_user_turn, while their reads still answer. A Slack or Discord conversation is mirrored into a dashboard slot, so a live slot alone is not enough: a message from the channel, whether the gateway runs it on the mirrored slot or on the channel's own session, is refused, while the user typing into that same slot in the dashboard is admitted. Every other caller without a dashboard turn (the CLI, a schedule, a subagent, an app, or an identity the shim cannot verify strictly) is refused too, and each refused tool answers one line -- Error: <tool> needs the dashboard: <reason>. Nothing was shown and nothing changed. ... (mcp_guide._off_dashboard, keyed on the gateway's no_live_slot/no_dashboard_turn/channel_caller/subagent_caller/ unattended_caller/app_caller/app_scoped_caller/missing_session_key/ not_user_turn codes) -- while find_ui and search_docs still answer in text, every result live: not_observed. guide_start only offers a card the user must press Start on, and guide_cancel only stops this conversation's guide, undoing nothing the user saved. A conversation has at most one live guide, and a new guide_start replaces it rather than being refused: once the new offer validates, the unfinished one is cancelled with reason superseded and broadcast before the new offer's row lands, and the answer's superseded lists its id, so the agent never checks for or cancels a guide first (GuideStore.start_superseding; an invalid offer leaves the old guide alone, and only a guide whose save is in flight refuses the new offer as 409 guide_saving). A refused guide_start returns its error followed by a line saying no guide card was shown, and an offer no tab received (delivered_clients: 0) carries a next that forbids describing a card as on screen, so the reply cannot claim a card the chat does not hold. A find_ui search whose results include a guide_ref returns a next naming that result and telling the agent to pass it to guide_start before writing, even when the result carries a blocker. A guide_ref ranked below a find_ref wins only when its own words matched the question more closely (match: exact label, label phrase, search term or phrase, then tokens); otherwise the better-ranked find is offered. An ambiguous search gets that next only when its tie settles on facts (_tie_pick): tied results that are one location or whose guides lead to the same place are guided to the first; otherwise the tied control the user's tab shows now (live pointable/offscreen) wins, else the tied results on the feature's own page (a page result itself, or a control whose id namespace names the page it is drawn on: the Mates page's "New mate" over the one on Customize), first-ranked. A tied result with no guide at all (a page the rail has no entry for) never wins over a tied control that has one: the Settings Webhooks tab is guided, not the Webhooks page. Candidates on two different pages, or a pick that removes something or sits under the agent's own ceiling (guide_catalog.is_trust_root), are answered with alternatives instead: their next says no guide is offered and that the reply must not refer to a guide, a card or a highlight until guide_start has returned one ("the guide above" with no card on screen). A channel's Settings page (settings.sub.channels.*) gets its guide with a note that its token fields are credentials: the walk ends on the page, and the reply describes the fields in words, never guiding to one or asking for a value. A preview feature's next also rules out any reply option that offers to take the user to the Developer settings. The server's instructions (mcp_instructions.GUIDE) and find_ui's description both tell the agent to write no text before these calls: every word it writes is shown, so a "Let me check the real layout first" line reaches the user ahead of the guide. guide_start also takes the agent's own plain words: an optional intro (at most 200 characters, shown on the offer card and the first step) and an optional note per action (at most 160, shown under that action's final step). The gateway refuses, never truncates, text with links, markup or control characters; the dashboard still draws its own template line for every step and attributes the words to the agent (learn-cron-dashboard). There is no server-wide grant or autoApprove entry. Session checks, browser acceptance and owner-only save controls remain in force. It lets an agent offer the human a non-modal pointer through a REGISTERED dashboard action (guide_catalog.ACTIONS: settings.show, crewmate.create, mcp.open_add, ui.show, ui.find); the agent sends an action id and parameters, never a selector or code (ui.find names a page of the index and a control's on-screen name; see "Pointing at a control by its name"). ui.show {location_id} points at one indexed UI location: the gateway accepts the id only when the packaged ui-index.generated.json carries a version-2 guide_plan for it (guide_catalog.ui_show_plans), or, for an auto: id, when the build-time auto tier the bundle ships names this very index (base_input_digest and base_build_digest) and gave the id a guidable guide_policy (point or caution) and a single-step plan (guide_catalog.ui_auto_tier; no file or another build: unknown_location). An auto record also carries that plan as auto_plan and the auto tier's own build_digest, which only a bundle stamped by the same generator run carries (see "Auto locations a guide may point at"). It stores every placement's step ids (placements: {<placement id>: [<step id>, ...]}, plan_version: 2, step_count: null) on the guide's action record. The claim names the placement the tab walks (POST /api/guide/claim placements, one entry per action: the ui.show action's viewport placement id, null for any other action; missing for a ui.show action is 409 placement_required, an id the plan lacks 400 unknown_placement), and under the claim's own revision bump the gateway records that placement, its step_ids, step_count and step kinds (all ui) from the record's own plan (guide_catalog.claim_placement), so step kinds are read per record (record_step_kind), not from the static catalog. A progress report on such an action must carry the current step's recorded step_id (else 409 wrong_step), and a recovery to an earlier step its resume_step_id; a fixed action's report carries none (400 invalid_step_id). A takeover may re-pick the placement only for an action the guide has not started (a later one, or the current one at its first step); otherwise a different placement is 409 placement_locked. A replay forgets the recorded placement. Version-1 plans (one step_count shared by every placement) were migrated in one go: the generator, the packaged index, the gateway and the bundle all moved to version 2 together, and a version-1 plan in an index is treated as malformed and left out. The record also carries the index's build_digest; the browser resolves the same plan from the generated uiLocations/guidePlans.gen.ts and refuses the guide with build_mismatch when the bundle's GUIDE_BUILD_DIGEST differs, reporting it on POST /api/guide/refuse (only the guide's reason moves). See "Guide plans" and "Live observation" under find_ui. The shim is stateless and sends the strictly resolved session key to the strict-internal /api/guide/agent/* routes, which derive the caller's slot only from that key against the LIVE slot table and refuse apps, subagents, unattended tabs and a key with no open slot. All guide state lives in the gateway (dashboard/guide_runs.py, in memory, 30-minute TTL, 45-second tab lease, revision compare-and-set); the owner's browser reads and advances it through the cookie-authed, owner-only /api/guide/* routes and receives owner-only guide_update frames. A browser advances only UI steps. A mutation step completes only through handlers/guide.run_guided_crewmate_create, which wraps the existing owner-only POST /api/agents: the tab names the guide in X-Guide-Id/X-Guide-Tab/X-Guide-Revision, the request is associated before the handler runs, and the guide advances only from that handler's own 200 response (the new mate's member_id). A cancel or expiry in between retires the association. A step whose target does not appear within the tab's bounded wait is reported target_missing; that status is the gateway's and is recoverable: when the owning tab sees the SAME step's target again (the human came back to its page, by the panel's "Go back to this step" -- the action's own enter navigation -- or any other way), it reports target_found and the gateway returns the guide to active on that step without advancing it. When the page instead comes back at an EARLIER step of the same action (a form that keeps its step in local state, like the Mates wizard, starts over once remounted), the tab reports target_found with resume_step_index and the gateway moves the guide back to that step -- never forward, never across a pending save (invalid_resume_step). A tab whose current target is absent while an earlier step's target shows counts the step missing after 1.5 s rather than the full bound. An observed, target_missing or recovery report that fails is offered again every 2 s, up to five times (an offer made while the previous report is still in flight is not sent and does not count), and its error clears once a report lands; only when the step's reports have run out of attempts does the panel say the guide stopped (a first failure, or an unrelated one such as a lease heartbeat, never does), and it then offers "Go back to this step", which starts the tracker afresh even on the same page. A guided save waits (up to 3 s) until the owning tab's guide is on that action's commit step before it reads the guide headers, so a fast Create is credited at the step the gateway moved to. When the guide does not get there in time (a report still in flight, failed, or not sent yet), the save goes ahead uncredited and, on success, the tab ends the guide with cancel reason saved_without_guide (the only reason besides the default cancelled_by_user a browser may give; anything else, including a non-string, is 400 invalid_reason). The close is pinned to that guide: a 409 (a late report moved its revision) re-reads it and retries at the new revision once that re-read has landed (never on a timer alone), up to three attempts within 15 s, only while it is still the same live guide of this tab on the same action. The crew log's guide/finished entry carries the same reason. Its result reads "Your change was saved; the guide ended without confirming it", never "completed" without the gateway's evidence and never a bare "cancelled"; the reason is kept on the conversation row (meta.card.reason), so the line reads the same after the store has forgotten the guide. A save the server refuses outright (a 4xx) clears the step's "submitted" state, and the guide stays on crewmate.create's one step, the New mate card's Create, so the person can press it again. target_found is a no-op on an active guide, is refused on a terminal one, and needs the owner tab, so a cancelled, expired or completed guide never resumes; a reloaded tab (a new tab id) takes the guide over explicitly, which walks it back to the step's page. Every browser route sweeps before it acts, so the old tab's lease can lapse inside the takeover's own request: a claim made at the revision that lapse moved the guide on from is accepted while nothing else has moved it (lapsed_from_revision), and no other write is. A claim or a lapse keeps a missing step's reason (ambiguous_target, not_found, gate_off, ...), so the tab that takes it over draws why the step is missing instead of a bare "stopped". The person's Cancel (cancelled_by_user) always succeeds: from any of their tabs, at any revision, and on a guide that already ended (answered as it stands); only the automatic saved_without_guide close keeps the revision and owner-tab checks. A refused write is said from the catalog by its code (components.guideLayer.error_moved / error_ended / error_generic), never with the gateway's English error text. A tab that already showed a step's target and then navigates off that action's page says so at once ("You left this step", with the same way back) instead of waiting out the bound; that state is the tab's own and reports nothing. mcp.open_add takes no parameters and has only UI steps: it points at the existing MCP servers tab, its Add Custom button, and then the form's server JSON box (where the command, args and env go), and completes when the person presses Done there -- never when a server is saved. A ui.find whose label is the name of a page its route opens is refused (no_entry): such a page has no entry in the navigation rail (Logs, Webhooks), the guide never opens a page itself, and its path is given in words. A page the rail draws (a registry row, an app's own row, or a NavItem App.tsx draws by hand, which the generator reads as collectNavItemPaths: Discover, Library) is indexed entry_kind: rail, and its find_ref names that entry with no route, so the guide stays where the person is. The tab still honours a page: true find (the link outlined while away, a last step bound to the page by ack.at), but the gateway no longer emits one. A ui.find for a control the index plans a ui.show walk to (another page, behind a pick or an editor section) is replaced by that walk before the guide is offered. Settings credential and security-ceiling controls are excluded from the catalog.

The same server carries change cards. propose_change(kind, params, reason?) names one REGISTERED kind (change_card_catalog.KINDS: setting.change, schedule.create/.update, crewmate.create/.update/.capabilities, template.update, mcp.install/.add_custom/.toggle, connection.connect, secret.save, trust.app, denied_command, folder.steering, workflow.save/.update); trust-root files have no kind. template.mcp_server is not one of them: its server entry is the gateway's own, so only request_server raises it (see Asking for an MCP server mid-chat). setting.change takes a Settings-registry setting_id (found with find_setting(query), which returns up to ten matches with writable, the current value and the allowed values, never a credential value) or a raw config path. find_setting matches a query word at the start of a word in a setting's id, label, help or config key, after dropping question words such as how, do and I (kept when nothing else is left); a setting ranks by the words it holds, a word in its id or label counting three times, and a word found on many settings counting for little. The write target is resolved from data: the dashboard-config controls in change_card_catalog.DASHBOARD_SETTINGS (Response Verbosity and the other Chat toggles) write PUT /api/dashboard/config with a one-key partial body, a registry configKey the config route accepts writes PATCH /api/config/kirocrew, and anything else is refused no_write_path with a pointer to the settings.show guide. The value must be one of the control's own options. A string-list setting (change_card_catalog.DASHBOARD_LIST_SETTINGS: Selectable Models' hidden models) takes op (add/remove) and one item instead of value, and writes the Settings page's own one-item delta key (model_picker_hidden_models_add/_remove) to PUT /api/dashboard/config; find_setting reports it as value_type: "string_list", its undo is the reverse delta, and its risk is normal. schedule.create takes exactly one of cron_expr (recurring) or at (one-time: a local ISO-8601 date-time with no offset, read in the card's timezone, else the configured zone). For at the gateway resolves the instant (change_cards.one_shot_context; a time already gone is refused at_in_past), sends it as epoch at to the same POST /api/crons, which creates a single-fire job deleted after its run, and marks the card record once: true with run_at_local, so the dashboard can show "Runs once"; undo deletes the job as for a recurring card. The gateway validates the parameters, reads the current state itself, and derives the card's title, the changes rows, the risk (normal/tighten/widen/ code_exec, computed from the diff, never from the kind) and the ordered request plan against the EXISTING settings-page routes. risk is the single worst label the badge shows, but the "grants something the member runs without asking" acknowledgement is carried as its own widen flag beside it, because a crewmate.capabilities draft can both launch code and expand auto-approval at once: code_exec wins the label while approval_expanded still sets widen, so the acknowledgement a plain-widen draft requires is not dropped. Every other kind leaves widen False and the gate stays driven by risk == "widen". The browser requires the acknowledgement on card.widen === true || risk === "widen", and an old signed record missing the field derives it from the capability impact on rebuild rather than reading it as False (rebuild_record skips the widen comparison when the record predates it). A setting whose VALUE is a command this machine then runs is code_exec whatever its before/after (_CODE_EXEC_SETTINGS, today dashboard.terminal.shell, the shell the dashboard terminal launches): a free-form command string has no widen/tighten direction, so the diff order is not consulted for it. The agent's reason is stored separately as plain text, and refused (400 invalid_text) when the exfiltration-URL scrubber or the credential redactor would change it (guide_catalog.needs_redaction, the same rule guide_start's intro and notes follow): it is shown as written, so it is never stored redacted. The same rule covers every agent-supplied parameter: change_cards.check_param_text walks the validated params (every nested string and dict key -- a schedule message, an MCP server's args, env, url and headers) and refuses the proposal with 400 invalid_text naming the offending path, because the card shows the parameters and Apply sends them as written; the plan is never rewritten at publication. An ordinary server URL is not exfiltration-shaped and passes. Because of that, an mcp.add_custom card shows everything Apply sends: the full launch line (shlex.join of command and args, or the url; the row wraps), every env and header value (KEY=value, Name: value), and any other spec field, each passed through the credential redactor as a second line of defence. list_change_kinds, find_setting, get_member_capabilities, diagnose_settings, propose_change and get_change_status are exact allowedTools grants on every agent (agent._GUIDE_AUTO_GRANTS) because none of them can change anything: the strict-internal /api/cards/agent/* routes use the guide's caller checks and only create or read a card in the caller's own slot. search_docs(query? | page, offset?) on the same server is a read of the packaged user docs (kiro_crew/docs/*.md, pages named from the directory's own listing so no caller string becomes a path; up to 5 results with 3 matching lines, pages in 12,000-character chunks). A query is matched word by word at the start of a word, after dropping question words such as how, do and I (kept when nothing else is left) and one common ending (reminder finds reminders and remind, reply and replies find each other; _ starts a word, so cycles finds max_cycles). A page ranks by the query words it holds, each worth more the fewer pages hold it, twice as much in the page name and half again in its opening lines, then by how often it says them; a word found on nearly every page (use, set) counts for little. The word itself, with a common ending (updat + e, automatic + ally), counts full; only the start of a longer word (mode in model, run in runner) counts half. A tie goes to the shorter page name. It calls no gateway route, needs no caller identity, and is granted as part of agent._GUIDE_AUTO_GRANTS; so is find_ui, the read of the packaged dashboard location index described in find_ui and the UI location index. diagnose_settings (GET /api/cards/agent/diagnose[?topic=]) is a pure read: every config and dashboard-config key whose value differs from its KiroCrewConfig() default, joined to the Settings registry, with credential-like keys (the find_setting predicate, also split on _) reduced to {set: bool} and nested credential keys scrubbed the same way, plus the newest 50 "Dashboard: ..." lines from Global memory history -- unless the caller's memory reads are disabled (a Temporary session, the same _shared._blocks_reads_session test the recall route refuses on): then history is never read, recent_changes is [] and recent_changes_withheld: "memory_reads_disabled" says why, while the findings and settings, which are not memory, are still answered; output is capped at 48,000 characters. Its findings come from diagnose_probes.run_probes(app, topic): twelve symptom probes run on a bounded worker pool (4 s each, 8 s in all; a probe that raises or overruns reports unknown), each strictly read-only -- no _doctor_* call, no repair path, memory.db opened mode=ro while its -wal exists (so committed but uncheckpointed rows count) and mode=ro&immutable=1 otherwise, the crew log through crew_log.read -- with strings redacted and lists capped, and never a secret value, token or whole MCP spec. The read-only kirocrew-crew-log server stays an opt-in set no template mounts by default; an agent granted it in its own spec reads under the routes' own scope. The owner's browser renders it, re-reads a stale one through POST /api/cards/{id}/preview (a new revision), and applies it by sending each plan step to the real route with X-Card-Id/X-Card-Revision/ X-Card-Op/X-Card-Step. The card hook (handlers/change_cards.change_card_middleware, innermost middleware, active only on change_card_catalog.HOOKED_ROUTES) refuses any caller that is not the dashboard owner (internal-secret, app and agent callers included), requires method, path and canonical body to equal the step (a user fill such as a secret's value is never read or stored; a step fill must equal what an earlier step's real response returned, and one marked in: path replaces its placeholder segment in the path only with a plain identifier, change_card_catalog.PATH_FILL_VALUE), re-reads the state before the first write (409 changed_since_preview; changed_since_apply for undo), runs the handler unchanged and records the step only from its own 2xx. A card applies once; undo restores the state before the change, and is refused once the thing the card made was edited afterwards: the post-apply snapshot carries a revision fingerprint (a mate's config entry and its spec's editable fields, a created schedule's configuration (never what running it updates), an MCP server's definition in each scope an uninstall would delete it from (env/headers values as keyed digests under a vault subkey; an unreadable scope is never read as absent), a secret's stored ciphertext entry -- never its value). A crewmate.create Undo deletes the mate it made through DELETE /api/agents/<name>, and that route is name-scoped, so it checks the immutable member_id the card's own create returned (step 0 evidence) against the live crew's own: after_shows_the_write offers the Undo only while they are still equal, and the delete re-reads the raw agents[<name>]["member_id"] the locked config read returns and refuses before the del when it differs or is absent (undo_identity_guard.identity_mismatch; None on either side is not a match). An owner who deleted and recreated the same name between apply and Undo leaves a different mate wearing it, so the Undo answers 409 changed_since_apply and keeps the replacement and its crew log. The check is armed on the owner-authed Undo step alone and runs inside update_config_locked against the cross-process advisory file lock -- never against the in-process KiroCrewConfig.load() snapshot, which serializes only same-loop callers and would wave through a same-name recreate landing from another process. That same Undo's first inverse step deletes the schedule the create made, as a crewmate.create /api/crons/<id> DELETE, under the same after.schedule fingerprint compare the schedule.create Undo uses (below); a cron DELETE in an Undo that recorded no fingerprint fails closed on an impossible sentinel rather than deleting unconditionally. This identity re-read guards the two name-scoped deletes above (the mate's member_id, the schedule's fingerprint). Every other card whose inverse is a delete offers no Undo: an MCP add or install (uninstall), a connection connect (disconnect), a trusted app (revoke) and a denied-command addition (rule delete) reach stores that take no revision or fingerprint, so an Undo could not tell the entry the card wrote from one put back under the same name since. change_card_catalog.offers_no_undo names them; their preview and result carry undo_unavailable_reason: no_identity_check, Apply is unaffected, and the change is reversed from its settings page. A schedule.update offers no Undo for the same reason: its inverse is a cron PATCH that writes unconditionally, so it could overwrite an edit another tab saved. A crewmate.update Undo writes the old fields back with a PUT /api/agents/<name> armed with the member_id its apply snapshot recorded; the update route compares it with the live crew's under the config lock it saves under and answers 409 changed_since_apply when a different mate now wears the name. A template card that changes skills snapshots the editor's skill mapping (projected from resources) and a fingerprint of resources, so Undo restores the prior mapping and a later skill edit makes it stale. An apply interrupted between two writes (a reload, a dropped connection) or left waiting on an approval poll stays applying and publishes resume ({step, responses}: the step the gateway expects next -- the poll step itself while waiting -- and the identity fields earlier steps returned); the card then offers Continue, which sends the remaining steps only. An Undo that stopped between its steps publishes undo_resume the same way, and pressing Undo again continues it; every Undo step after the first re-checks what it still removes (the mate's revision; a capability Undo's second step is held by its own preview token and revision) before it runs. The card's body carries no free-text editor: a different value is a new card. Cards persist in <data home>/change_cards.json (24h proposal expiry, finished cards pruned after 7 days). That file is a VISIBLE crew-home leaf the agent can write, so nothing read back from it is trusted as written: each record carries an HMAC-SHA256 under the vault subkey change-card-store (the vault is HIDDEN in every sandbox mode), and a record without a valid one -- forged, edited, or written while the vault key was unavailable -- is dropped with a warning on load; then every field the browser displays or executes (title, risk, changes, scope, the apply plan, an applied card's undo plan) is rebuilt from kind + params through validate_params / build_preview / build_undo with the record's own preview inputs, a record whose stored copy differs is dropped too, and execution reads only the rebuilt plan (change_cards.rebuild_record). The MAC is what makes the non-derivable inputs -- the preview snapshot an undo restores, the identities earlier steps returned -- trustworthy; a rollback to an older signed copy of the file is the residual it does not stop. CardStore.warm() loads the store once and, until it succeeds, refuses read or key failures: an unreadable file, invalid UTF-8, or an unavailable verification key raises 503 store_unavailable rather than leaving the store silently unloaded, so the caller never retries disk I/O on the event loop. Malformed JSON retains the existing empty-store behavior. The owner-authed card routes warm() INSIDE their try, so that 503 is returned to the caller rather than escaping as a 500. Execution is persist-before-you-publish: a write step's admission is written (CardStore.flush(strict=True)) before its route runs, and one that cannot be saved runs nothing (503 checkpoint_failed); a step whose route answered 2xx but whose result cannot be saved is never published as applied -- the card settles partial with error.code: checkpoint_failed and no undo, and the step answers 503. A record loaded with a write step still in flight never reported back, so it may or may not have taken effect: it loads partial with error.code: interrupted and no undo, and Apply answers with that record rather than running the route again (a poll -- a repeat GET -- is simply admitted again). A write step whose route raises or is cancelled (a gateway shutting down mid-request) after it started gets the same verdict at once, never a retryable reset: the card settles partial with error.code: interrupted, saved and broadcast under asyncio.shield, and the exception is re-raised. A route that raises an HTTP error (web.HTTPException, 4xx/5xx) is recorded like one that returns it. Only a step that demonstrably never reached its route (a check or read before it raised) or a poll is withdrawn and may be sent again. Every other transition -- propose, preview, cancel, dismiss, a refused step's verdict, a poll's verdict (an approval completing the card) -- is saved strictly before it is broadcast; when the save fails the record is put back to its state before the transition (a proposal is discarded), nothing is broadcast, and the request answers 503 checkpoint_failed. Expiry and the retirement of a closed conversation's proposals are derived again on load; they too are broadcast only once saved. Retiring a proposal cancels something nobody can confirm, so it fires only on POSITIVE closure evidence: no card retires until the open-tab restore has run (open_slots_restored), because before that the live slot set is not authoritative; after it, a proposal's slot retires only on a close tombstone (channel_slots.slot_closed_since, recorded on the event loop when the slot was popped) or a persisted closed flag read off-loop through get_metadata_status for exactly the pending cards' slots (_slot_is_open, _closed_on_disk). A slot merely ABSENT -- never recorded closed, a budget-skipped reopen, an unreadable metadata record -- reads OPEN and keeps its proposal; there is no fallback to get_slot or slot_exists, whose absence a restore-window read would misread as closure. Cards reach owners as card_update frames, and their outcomes reach the proposing slot's next turn as a [CHANGE CARD RESULTS] block. Each card (and each guide_start offer) is also a card row of the proposing slot's transcript, at the point it was proposed, patched in place as its status moves, with matching card/* / guide/* entries in that session's crew log; the row is display-only and names only (history.md, "Card rows"). Every owner mutation through the hooked routes, card or manual, appends one names-only line to Global memory history.

Every kind shares one card layout (website/src/cards/ChangeCard.tsx). The header row holds the kind on the left and the card's clock on the right, in the same muted 12px text: when it is due for a one-shot reminder, else when it expires, worded as what runs out: "Answer within 22h" (answerWindow, one truncated narrow unit). The kind beside it is not what expires, so the line names the answer, and it carries no second sentence. A narrow card wraps the clock under the kind; it never sits alone under the title. The change rows, the scope, the kind's own body and the proposer's reason are rows of ONE label | value grid (kindBodies.CardRow), so the reason uses the same label column and divider as Goal or Affects. Its label names the card's proposer, read from the card rather than the page showing it: a card whose slot_key is a crewmate's own chat (the roster row bound to that slot) reads "'s reason" (cardAuthor.cardProposer, {{name}}'s reason in each catalog); a card from the main assistant, or one whose roster row is not loaded yet, keeps the page's author, "Kiro Crew" outside a crewmate chat. The Affects row is left out when it would only repeat the title: the gateway marks its one member as the card's own subject (scope.only_this_member) and the title names that member (cardRegistry.scopeRepeatsTitle). An unmarked scope (a template's users, whose name can equal the template's) or one reaching more members keeps its row. A failed read of the crewmate list shows an inline notice under the card, which stays usable with the page's author. A row whose previous value is absent or would only print "(empty)" is an add and shows the new value alone (CardChanges.isAddChange); a real edit shows old → new, and a field that names its empty value (an inherited effort) keeps its old side. The decline button is a bare verb ("Decline", catalog key components.changeCards.cancel) unless the kind names its own (decline in cardRegistry), so it has the same short shape as the kind's accept label.

kiro_crew/change_card_catalog.py keeps the evidence, undo and result code (extract_evidence, build_undo, result_summary) and the manual-change memory lines (describe_manual_change, HOOKED_ROUTES, MEMORY_ROUTES), and is a mirror facade (kiro_crew._facade_mirror) over two sibling owners, so every other name still reads and patches as change_card_catalog.<name>. New work goes to the owner of its responsibility: change_card_catalog_kinds.py (the kind ids, the KINDS table, the risk and limit constants and the parameter validation) and change_card_catalog_plans.py (the plan steps and fills, the stores and dashboard setting tables, the display helpers and build_preview).

kirocrew-panel is opt-in and reaches a crew member's DM session the way kirocrew-dashboard does: as a session-level mcpServers entry carrying that session's identity (members.member_panel_session_server), plus @kirocrew-panel in tools and _MEMBER_PANEL_GRANTS in allowedTools on the KAS projection. Neither the Capabilities editor nor any emitted spec can grant it -- that list is built from configured connections, and an opt-in managed server is not one -- so this mount is the only path to it. The operator ceiling is agent.crew_panel; see the session-control module spec for the grant reasoning and the fail-closed behaviour.

kirocrew-dashboard is one transport carrying two authorization models, which is what makes its assignment decision larger than its name suggests. The chat_folder_* verbs are bounded by RESOURCE ownership — a folder created by an app carries it in owner_app, and an app may reshape only its own. The session_* verbs are bounded by CALLER class instead, and one of them (session_send) writes a turn into another session's conversation; session-control.md is their spec and carries that reasoning.

The consequence to know before granting: an agent handed the whole server for folder organization has the session verbs too. Whether they prompt depends on how the grant is spelled — _mcp_pattern maps a bare @kirocrew-dashboard entry to a one-level glob, so it auto-approves every tool the server advertises, while naming tools individually leaves the rest to hooks.on_tool_call. _CONDUCTOR_DASHBOARD_GRANTS and _MEMBER_DASHBOARD_GRANTS (agent_parts/spec_grants.py) are the shipped examples of the individual form, and they differ from each other on exactly this axis: the member's list includes session_send, session_broadcast, session_stop and session_retry because authorize_target refuses a member caller on any session it did not create, and the conductor's withholds them because it has no such fence.

CLI commands and their MCP twins:

CLI command MCP tool Server
kirocrew cron add cron_add kirocrew-cron
kirocrew cron list cron_list kirocrew-cron
kirocrew cron update cron_update kirocrew-cron
kirocrew cron remove cron_remove kirocrew-cron
kirocrew cron pause cron_pause kirocrew-cron
kirocrew cron resume cron_resume kirocrew-cron
kirocrew cron trigger cron_trigger kirocrew-cron
kirocrew spawn run spawn_run kirocrew-core
kirocrew spawn list spawn_list kirocrew-core
kirocrew learn add learn_add kirocrew-core
kirocrew learn list learn_list kirocrew-core
kirocrew learn remove learn_remove kirocrew-core
kirocrew run TASK.md task_run kirocrew-core
kirocrew computer apps computer_list_apps kirocrew-computer
kirocrew knowledge dedup knowledge_dedup kirocrew-core
kirocrew knowledge stats knowledge_list_sources kirocrew-core

cron_remove_all and cron_secret_request have no CLI twin: kirocrew cron remove takes one job id, and no kirocrew cron subcommand files a secret request.

The last row is the one place a twin does not share its command's name, and it is a placement decision rather than an oversight. A tool in kirocrew-core costs context in every request of every session for as long as the session lives, so a fifth knowledge tool would be advertised forever to answer a question knowledge_list_sources was already 90% of: it opens the same store, over the same active-items rule, to serve the same "what is in this library" purpose. The aggregate is a strict superset of what its own query already computed, so it lands as a leading totals line on that tool instead, and the CLI verb and the tool render ONE aggregate_stats() call.

The rule the MCP-first section states is that the model must get a structured tool rather than a bash-shaped CLI command — the model has one. Two conditions have to hold for that reading to be honest, and both are checked in test_knowledge_stats.py: the tool must actually surface the numbers (its descriptor advertises them, so deferral still selects it), and the capability must not be one an agent should be granted SEPARATELY, which would make it a kirocrew-dashboard-shaped opt-in server instead. It is not: anyone who may list sources already reads this data from that store, so the counts add no reach.

kirocrew-core tools with no CLI twin, grouped by concern (authoritative list: kiro_crew.mcp_tools.build_tool_list(), which is what mcp_core._list_tools answers tools/list from):

  • Subagents: spawn_status, spawn_continue, spawn_steer, spawn_release, spawn_sub_agents, wait

  • Messaging and notification: send_message, send_notification, delete_message, update_message, file_send, read_slack_profile. send_message is the agent's only proactive egress to a NEW destination — update_message rewrites a Slack message the bot itself already posted, on the same gate ladder (strict identity, channel-agent containment, capabilities.messaging and the channels scope for "slack"), because an edit publishes new text to an audience rather than retracting what it has. send_message names its destination rather than inferring one: session="slack" / channel / user / thread_ts are the Slack fields, and channel_type is the non-Slack one — the transport of the conversation the calling session already belongs to. Exactly one of the two families may appear per call. The routing ladder and the fail-closed contract behind channel_type are in messaging § Proactive sends. Two things to know before adding a destination to it:

    • The governance gate must name the transport the message actually leaves over. The channels scope is a per-transport allowlist, so vetting "slack" for a Telegram send evaluates a Telegram denial against Slack's rule — and refuses a permitted Telegram send whenever Slack is denied.
    • channel_type is the one send_message argument that requires strict identity (via require_strict_session_key). It posts into one specific conversation, which is the "targets a specific session" case below; the lenient walk climbs process ancestors, so a sub-agent would resolve to its parent and deliver into the parent's chat window. An unresolvable identity refuses the call rather than guessing.
  • Capability requests: request_server (any template session asks the user for an MCP server it lacks; see Asking for an MCP server mid-chat)

  • Session-bound directives (session_directive.DIRECTIVE_TOOLS): nothing_to_do, suggest_followup, monitor_start, monitor_watch, monitor_update, monitor_stop, autonudge_stop, set_project, reset_conversation, chat_tag. ask_question is not one: it blocks and returns the answers as its own result (see the stateful-tool model below).

  • Memory recall (V1 and V2): memory_recall resolves authenticated session identity once through require_strict_session_key and passes that same identity to the gateway. Missing identity returns the shared gate's refusal and installation diagnosis. It accepts a task query, never a store selector. The gateway resolves the caller's bound V1 or private V2 memory and returns bounded context with evidence; unavailable identity or memory refuses the call. The MCP response keeps each selected body once in a trusted reference context, with body-free evidence carrying stable references, scores, provenance and truncation flags. UI previews are not model output. A call-local projection and final serializer enforce the 3,000-character context limit and 16 KiB memory-result budget after redaction, including nested JSON escaping and TextContent overhead with a 1 KiB reserve for normal RPC framing/IDs. This projection retains no caller or session state in the MCP process. Arbitrarily large caller-supplied IDs are outside that bound. Prompt construction does not perform embedding search; the tool is called when earlier facts or experiences are needed. Owner-selected copying is a dashboard action, not an MCP capability. The full contract is in memory.

  • Monitor read: monitor_inspect (strict authenticated session identity only; no ancestor fallback; reports a structured monitor or a legacy timer loop's presence reading, whichever the session holds)

  • Crew routing: route_crew, select_crew

  • Session work ledger: session_ledger_read, session_ledger_record

  • Sessions and history: list_sessions, get_chat_session, search_chat_history

  • Artifacts: artifact_list, artifact_get, artifact_save, artifact_update, artifact_delete, artifact_move, artifact_versions, artifact_revert, artifact_folder_list, artifact_folder_create, artifact_folder_rename, artifact_folder_move, artifact_folder_delete, artifact_get_comments, artifact_post_comment, artifact_reply_comment, artifact_delete_comment, artifact_mark_review, deploy_artifact

  • Knowledge and skills: local_knowledge_search, knowledge_add_document, skill_discover, skill_search, skill_fetch. (knowledge_dedup and knowledge_list_sources have CLI twins — see the table above.)

  • Workflows and hooks: workflow_author, workflow_run, workflow_library_list, workflow_status, workflow_result, workflow_list, workflow_cancel, workflow_rerun_subtree, register_hook

  • App bridges: issue_radar_record_investigation, ops_mission_control_api, design_tweak_update_thread, pod_up, pod_restart, pod_down, pod_status, pod_ls, issue_radar_crew_read, issue_radar_crew_record. Listed only while the app each one reaches is enabled — see § An app's tools follow the app's enablement below.

  • Browser: browser

  • Diagnostics: resource_status, kiro_cli_logs — a redacted tail of kiro-cli's own mcp/lsp protocol logs, so the agent can self-diagnose a rejected turn. Reads log files only: never the fenced identity/token stores, and never the conversation-bearing sources (kiro-chat.log, session transcripts), each of which is one shared host file per gateway that would disclose another session's conversation. That scope holds only while mcp.log / lsp.log record protocol traffic rather than full frame bodies, since they share the chat log's single-fixed-path, all-sessions-interleaved shape and an MCP tools/call frame carries conversation-derived arguments. Measured on kiro-cli 2.21.1: mcp.log is empty across a session of continuous MCP tool calls, every lsp.log record is a single-line <timestamp> ERROR <module>: <message> with no JSON-RPC envelope and a longest line of 313 bytes, and sentinel strings passed as tool-call arguments appear in neither file. Because that measures one version of a component this repo does not pin, a source whose text carries serialized frames is REFUSED whole and visibly, so a kiro-cli that starts logging payloads surfaces as a refusal instead of a silent widening

    Member scope does not prohibit these ordinary diagnostic reads. Credential redaction, source allowlisting and refusal of conversation-bearing logs remain independent data-retention and credential protections. Protocol-log and chat-history tools resolve ordinary strict session identity once before reading, independently of memory version or database availability; workspace filtering, audit attribution and summary requests reuse that key.

  • App bridges (credentialed): ops_mission_control_api — the MCP server process holds the gateway's internal secret and forwards only a frozen (method, path) allowlist of Ops Mission Control routes; the agent never sees a credential (same shape as issue_radar_record_investigation). design_tweak_update_thread — the same shape for the Design Tweak app: the server forwards a single route (POST /apps/design-tweak/api/thread, the gateway's app reverse-proxy path) so the agent can mark a batched visual-edit comment in progress or done as it applies it. status is restricted to done (forward progress only — no clear/dismiss), and the gateway admits only that one path for internal-secret callers, never the app's state-mutating routes. The tool is the app's own data: its agent_tools.py declares the descriptor, the fields, the route and the body, and the core builds the tool from that declaration and runs it with one handler of its own (mcp_tools/apps.py builtin_agent_tool; see app-kit-platform § 30.1)

Server instructions travel with the server

A Kiro Crew server can describe its own tools in its MCP instructions, the initialize result field the spec calls a hint the client MAY add to the system prompt. mcp_shared.run_mcp_stdio_loop(..., instructions=...) returns the text, and kiro_crew/mcp_instructions.py holds it, one entry per server in BY_SERVER: kirocrew-cron, kirocrew-guide, kirocrew-dashboard (session control) and kirocrew-computer. Text in config/prompt.md reaches only the default-named agents, whatever they mount; as instructions it reaches every agent that mounts the server, on every harness, and nothing reaches an agent that does not. The harness places it in its own system prompt, so it is not part of what a compaction drops and Kiro Crew re-injects.

The prompt keeps only what a server cannot say about itself: that an expected server is missing. Today that is the Computer Use pointer, the slot a closed spec gate resolves to.

Each text opens with a one-line summary of at most MAX_SUMMARY_CHARS (250) and stays within MAX_INSTRUCTIONS_CHARS (4,096), measured 2026-10-27 (#24859):

Harness Where the text lands Limit
KAS system prompt, under MCP SERVER INSTRUCTIONS (untrusted ...) not seen
Claude Code system message # MCP Server Instructions 4,096 chars, then … [truncated]
Codex the tool namespace's description not seen
opencode system prompt <mcp_instructions> not seen
goose system prompt ### Instructions not seen
DeepSeek Harness system prompt ### MCP server: <name> 32,768 bytes, over it session/new fails
pi nowhere for a direct server (only the first line, for deferred/codemode) 250 chars
kiro-cli, v2 engine (acp without --agent-engine v3) nowhere —

The v2 engine is deprecated and gets no fallback: a session on it, including one a KAS default or member backend degrades to (apply_kas_cli_floor), runs without these servers' usage text. That is the maintainer's recorded decision on #24869.

So pi is handed the text by Crew: pi_mcp_handoff_payload seals the entries of the servers the session mounts beside the servers themselves, and the pi gate extension appends them to each run's system prompt in before_agent_start, skipping a server pi's own mcp.json shadows. Text that is a rule rather than a tool's usage stays in the prompt: KAS frames instructions as untrusted hints that cannot override the agent's own rules.

A pooled backend's initialize result is cached and replayed to every later stub (backend_handshake._deliver_cached_initialize), instructions included, and a respawned backend's result replaces the cache. Pinned by test_pooled_stubs_get_the_backends_instructions_after_a_respawn_too and test_mcp_instructions.py.

A kirocrew-core tool's own rules live in its description

kirocrew-core passes no instructions yet. Its per-tool text is split by when it matters:

Rule Lives in Why
How the call behaves: results, errors, refusals, limits the tool's description a deferred tool is loaded before it is called, so the description is in front of the model exactly when the rule applies
When to reach for the tool one line in config/prompt.md a deferred tool shows only its name, so a trigger kept only in its description is unseen until the tool is already chosen
Policy across tools (turn-end contract, the spawn default, Rules) config/prompt.md not any one tool's usage

test_moved_tool_rules_live_in_their_own_descriptions pins the moved rules to their descriptions.

Asking for an MCP server mid-chat (request_server)

A session on any agent template (the default kirocrew, a custom or third-party agent, the worker, a conductor) asks for a server it lacks with request_server on kirocrew-core, the one server every session carries (mcp_tools/server_request.py). The user approves one template.mcp_server change card, and the server is written to the template's additions record (template_mcp_additions), never into the spec file. A crewmate keeps request_capabilities, which edits its own file.

  • The agent names a server, never a launch line. The tool sends {server?, source, registry_id?, reason?} and nothing else; the route answers 400 invalid_body to any other field (a command, url, entry, template or session). The gateway builds the entry (member_capability_catalog.resolve_server, shared with request_capabilities): source: "gateway" copies a server this gateway runs and has switched on, source: "registry" takes the official registry's install plan. A gateway entry that carries env, headers or credential arguments is refused carries_settings, because a card's params reach the agent that asked; such a server is added on the MCP page, where secrets come from the existing store. The entry then passes template_mcp_additions.validate_entry, so no autoApprove, allowedTools or other trust key can ride on it. propose_change cannot raise the kind at all (change_card_catalog.GATEWAY_RESOLVED_KINDS, 403 use_request_server), and list_change_kinds leaves it out.
  • The caller and its template come from the attested session. POST /api/cards/agent/request-server sits under the strict /api/cards/agent prefix and resolves the caller with handlers.guide._resolve_agent_caller; cards.request_server is a user-turn operation. A subagent, a schedule or workflow slot, a messaging-channel turn, and any turn the user did not send (a patrol or loop wake, a session_send, a subagent's result) are refused with a reason that says what to do instead (subagent_caller, unattended_caller, channel_caller, not_user_turn). Unlike the crewmate route there is no own-thread exemption: a card nobody sees is never raised. The template is the caller's execution record's template_id; the record folds an alias onto its target on every read and write.
  • The default agent and the worker get a mount-only card. Both normally take their servers from the MCP page (template_mcp_additions.DEFAULT_TEMPLATES), whose add also approves every tool of the server; a mid-chat request must not be a second path to that grant. So a request from either is recorded on the default kirocrew template with mount_only: true (the worker mirrors the default spec, so one record reaches both). The rebuild merges the entry into mcpServers, adds the @server ref to tools, and writes no allowedTools grant: its calls still ask. The record keeps that disposition across every rebuild, including one where the same server is also on the MCP page: the bare @server grant is withheld, while a per-tool grant the user wrote stays (the card lists it under "Already approved"). Because kirocrew.json is rebuilt on top of itself, the merged entry is stamped x-kirocrew-card-addition (template_mcp_additions.reconcile_default_spec); a stamped entry whose record is gone, after the card's Undo, is removed with its bare @server refs on the next rebuild, unless an MCP page scope launches that name (an entry with a command or url; a page toggle's stub such as {} does not count, page_launched_names). A per-tool @server/tool ref is kept: it reaches nothing without the server, and a failed Undo that puts the record back then returns the server with the grants it had. For the default agent the card reads the outcome from kirocrew.json itself (template_server_request._default_spec_mounts): Add server succeeded when the spec holds the stamped entry, Undo when it no longer does. A rebuild that reports failure for another reason (a held conductor spec, another installer raising after the default spec was committed) is not rolled back, because restoring the record over a committed spec would land after the rebuild pruned the server's per-tool refs; an Add server whose launcher did not resolve is rolled back instead of shown as applied. The grant pass uses the mount-only set from the same read of the record as the merge. The stamp can only make a rebuild remove an entry, never grant one.
  • A harness that cannot apply it is refused with the record's reason. template_mcp_additions.addition_support(template, backend) answers for the caller's backend; a template Crew does not own on a harness that loads its agent off disk (kiro-cli) is refused 409 unsupported with UNSUPPORTED_REASON.
  • The card lists the whole reach and grants nothing. Its rows name every template the addition reaches (template_mcp_additions.addition_reach: an addition to the goal conductor also reaches its deprecated alias, labelled as its old name) and the crew members built from them; the tool names this gateway last saw the server advertise (mcp_discovery_probe_state.probe_metadata), or that they are not known yet; and, as its Affects line, every open session on those templates; whether running sessions pick it up at their next turn (the live gate, mcp_hot_reload.live_sessions_apply_mcp_live) or restart; and that it adds no tool approval while existing permissions on the agent still apply (TEMPLATE_SERVER_TOOLS_NOTE). The card makes no promise that each tool asks: a harness's own allow rule can approve a tool the card cannot see. An allowedTools grant any reached template already holds for that server is named, with its template, on an "Already approved" row. A registry server reads code_exec.
  • Only the owner applies it, and its Undo removes only its own record. The apply step is POST /api/agents/detail/{name}/mcp-additions and the Undo is DELETE /api/agents/detail/{name}/mcp-additions/{server}?card_id=<card>, both card-hooked routes that refuse any internal caller 403 owner_only; the POST also refuses a request with no card (403 card_required), so the only entry ever recorded is one a card showed. The Undo calls remove_addition with the card id, so a later approval of the same server on another card survives it. The Apply records with only_if_absent=True too: a server another card added after this card's own check answers 409 already_added and is left as it is. Each write rebuilds the agent specs and then applies live or resets sessions, as an MCP page change does. The card writes only the record, under the record lock, and asks for one ordinary rebuild; it owns no spec write and no rebuild lock. Every rebuild, the MCP page's included, merges the record, so a concurrent rebuild that commits an older snapshot is corrected by the next rebuild. Only a conductor (alias resolved) reads an addition from a spec the rebuild writes; every other covered template reads the record at spawn, so for those a declined rebuild is not a failure. For a conductor, a rebuild that raises, is refused, or holds a conductor spec back leaves a spec that disagrees with the record, so the write is put back (an Undo's restore only while the server is still absent, decided under the record lock by add_addition(only_if_absent=True), so a newer card's approval is never overwritten), the specs are rebuilt once more from the restored record (so a spec the failed rebuild already wrote converges back), and the step answers 503 spec_not_rewritten: the card stays as it was (an Undo stays available to retry).

A kirocrew-core tool has two halves

Each tool is declared twice in the same per-domain module under kiro_crew/mcp_tools/ (learn.py, artifacts.py, workflows.py, …), and nothing at runtime notices when only one half lands:

  • Its descriptor — name, model-facing description, JSON Schema — is returned by that module's schemas(). build_tool_list() concatenates every domain's, and mcp_core._list_tools answers tools/list from it. A domain may narrow what it ADVERTISES with an advertised() function, which build_tool_list() reads in place of schemas() on the full build when it exists; schemas() stays the full declaration, and advertised() may only omit a declared descriptor, never add or reshape one (test_a_domain_advertises_only_what_it_declares). The names-only build (build_tool_names, the in-process discovery read) takes schemas() and never consults advertised(). apps is the one domain that defines one, below.
  • Its handler is an entry in that module's HANDLERS map, called as handler(name, args). dispatch() finds it by name and mcp_core._call_tool_inner delegates to that.

A descriptor with no handler advertises a tool that answers with the dispatcher's fallthrough; a handler with no descriptor is unreachable, because the model is never told the name. test/test_mcp_tool_registry.py fails when either half is missing, when the two halves land in different domains, or when a name is claimed twice. Parity is read from schemas(), the declaration — not from build_tool_list(), which may legitimately omit a declared tool whose app is switched off.

Two domains keep their code in an owner package beside the module: control.py and spawn.py are mirror facades (kiro_crew._facade_mirror) over mcp_tools/control_parts/ and mcp_tools/spawn_parts/. Both halves are still read as control.schemas() and control.HANDLERS, and every name an owner defines reads and patches as control.<name> or spawn.<name>. The packages are not domains — DOMAIN_MODULES names the facades — and new code goes to the owner of its responsibility:

Module Owns
control.py task_run, wait and its deferred step, route_crew, select_crew, register_hook, ask_question and its card wait, HANDLERS
control_parts/schemas.py every control descriptor, and the structured-arming and runtime-ceiling reads that shape one
control_parts/directive.py _emit_directive, and the tools whose effect is one directive: nothing_to_do, set_project, reset_conversation, chat_tag, suggest_followup
control_parts/monitor.py monitor_start, monitor_watch, monitor_inspect, monitor_update, monitor_stop, autonudge_stop, and their context and preflight refusals
spawn.py spawn_run with its deferred step and receipt, spawn_continue, spawn_steer, spawn_release, resource_status, HANDLERS
spawn_parts/schemas.py every spawn descriptor, the agent roster hint and the parent allowlist filter
spawn_parts/listing.py spawn_list, spawn_status and the queued-wait wording
spawn_parts/wave.py spawn_sub_agents with its deferred step and resume hold, and the audit owner

An app's tools follow the app's enablement

The ten apps-domain tools each reach one built-in app — Issue Radar (issue_radar_record_investigation, issue_radar_crew_read, issue_radar_crew_record), Dev Fleet (pod_up, pod_restart, pod_down, pod_status, pod_ls), Ops Mission Control (ops_mission_control_api) and Design Tweak (design_tweak_update_thread) — through gateway routes that refuse the call with HTTP 403 while the app is disabled, on kiro_crew.apps.manager's read of the app's installed.json. The refusal body differs per app — Dev Fleet's routes and the app reverse proxy Design Tweak sits behind (handle_app_api_proxy) name it app_not_enabled (#10742), Ops Mission Control app_disabled, Issue Radar carries no code — so nothing here keys on a code; the predicate behind all four is the same is_app_enabled read. tools/list advertised every one of them regardless (#16099), so a session with none of the apps enabled was told about tools that could only refuse — and because kiro-cli reads tools/list once per session and Crew's own servers are exempt from tool_search deferral, each one cost its full schema in every request of that session.

mcp_tools.apps.advertised() therefore emits a tool's descriptor only while its app is enabled, and the decision reads the same record the call refusal reads: TOOL_APPS names the installed app behind each tool (pinned to the apps' own APP_NAME constants by test_mcp_apps_tool_gate), and the listing reads that app's installed.json through kiro_crew.apps.manager, the module the route's is_app_enabled reads it through. One file, one module, two readers: the route's binary is_app_enabled treats an unreadable record as disabled and refuses, while the listing's tri-state app_enabled_state hides only on a readable False. So a hidden tool is always one whose call would be refused, and a listed tool is not always one whose call would succeed — an unreadable record lists tools the route refuses, for the reason the fail-open bullet below gives. The MCP server process reads the data home directly here as it already does for the computer-use keystone, the skills tree and the knowledge store; the sandbox masks specific app data leaves, not apps/<name>/installed.json.

Four details of the shape:

  • Hiding is a product decision, not an enforcement point. The route stays the gate, as it does for the computer-use tools (mcp_computer._list_tools returns [] while the keystone is off). dispatch() of a hidden tool is unchanged: the handler runs and surfaces the route's own refusal — a hidden tool is not an unknown one.
  • Fail-OPEN on a read fault, as the per-session policy filter does. The listing reads the tri-state app_enabled_state and hides only on a definite False (not installed, or installed and switched off); None — corrupt JSON, a dangling link, a directory in the file's place — lists the tools, and so does a read that raises: advertised() guards each app's read, because an exception escaping the descriptor build would withdraw every tool of the pooled server for every session (spawn._agent_roster_hint and control.schemas() keep the same rule for their own reads). The once-per-session tools/list cache that motivates hiding would make hiding on a transient fault permanent for the session's whole life, while a listed tool whose call the gateway refuses is not a hole. is_app_enabled cannot express this (it collapses unreadable into False), which is why the listing reads the tri-state twin in the same module rather than a third reader.
  • Enabling an app mid-session does not surface its tools until the session restarts — kiro-cli caches the listing — and disabling one mid-session leaves them listed and refusing, both exactly as the computer-use tools behave. schemas() and HANDLERS keep naming every app tool whatever the enablement, so a disabled app never reads as registry drift.
  • The names-only build skips the gate, so nothing is charged to the gateway's loop. mcp_discovery._managed_tools_in_process reads tool names in-process on a host whose sandbox refuses the probe spawn, on the gateway's event loop, through build_tool_names() — the names_only path of build_tool_list() that already keeps spawn.schemas and control.schemas from their live reads. That path takes each domain's schemas() and never consults advertised(), so no installed.json is read there and a disabled app's tools still appear by name in the discovery inventory (rendered under the "Declared" badge). The stdio server that answers a model's tools/list takes the full build, so the gate applies where the listing is observed.

Handlers reach the server's shared plumbing — _post/_get, the identity resolvers, the governance vets — as attributes of mcp_core, not as direct imports. That is deliberate: an attribute lookup resolves at call time, so a test that rebinds one (patch("kiro_crew.mcp_core._post"), setattr(mcp_core, "sel", …)) still intercepts the handler. A direct import would bind at import time and silently escape every such patch. mcp_core._HANDLER_SURFACE names the bindings that exist only for this purpose, so an import cleanup cannot quietly delete one.

mcp_core.py keeps the server itself — tools/list, the call path and its call context, directive capture, the knowledge cache, _send and the five verbs — and is a mirror facade (kiro_crew._facade_mirror) over the owners in mcp_core_parts/, so every name they define still reads and patches as mcp_core.<name>. New plumbing goes to the owner of its responsibility:

Owner Owns
identity which session is calling: the lenient and strict resolvers, require_strict_session_key and its diagnosis, REFLEXIVE_TOOL_MODULES, the Slack identity classification
gateway where a call goes: the port, base URL and unix-socket caches, one request's target, the refused-target replay and re-verification, the internal secret, the identity headers, and _send's retry schedule, failure text and error body
governance channel-agent containment and the messaging, browse, channel and memory-write vets
crew Crew Mode's route_crew and select_crew bodies
history the chat-history search tools' scoping, redaction and snippet helpers
radar_crew the Issue Radar crew tools' identity, ledger view and write scrubbing

mcp_cron.py keeps the cron server itself — argument validation, the call path, the caller's identity and ownership checks, the tool bodies (_call_tool_inner) and the stdio entry point — and is a mirror facade over four sibling owners, so every name still reads and patches as mcp_cron.<name>. New cron-server code goes to the owner of its responsibility:

Owner Owns
mcp_cron_shell_scan the lexical scanners the cron shell gate runs: the protected-path and secret-environment matchers, quote states, $ expansions, extglob and brace expansion, and whether a glob can reach a credential directory
mcp_cron_vet the cron gate: the governance, command and script vets, the fire-time re-vet vet_job_at_fire_time, the storage-time denial audit, and the folder cron_add names
mcp_cron_tool_list the tool catalogue tools/list returns
mcp_cron_list_render cron_list's full, compact and JSON renderings and the run-history fold

The remaining upward dependency is known: the plumbing could move to a module the handlers own, which would make mcp_tools a leaf. That is a separate change — it has to retarget every patch site, which is mechanical but touches far more test code than moving the handlers did.

mcp_shared.py, the stdio plumbing every managed server shares, keeps the server's entry -- run_mcp_stdio_loop, the process identity it declares (set_internal_caller) and its hard-exit signal handlers -- and is a mirror facade (kiro_crew._facade_mirror) over four owners, so every name they define still reads and patches as mcp_shared.<name>. New work goes to the owner of its responsibility:

Owner Owns
mcp_shared_wire the JSON-RPC wire: the framing the first frame decides, the private stdout fd, respond and notify, the frame size limits, the Windows stdin pump
mcp_shared_calls a tool call's life: the queued, parked and cancelled-call bounds, DeferredTool with drive_deferred and map_deferred, the step pool, ToolCancelled, and the audited call_tool_with_logging
mcp_shared_policy which tools a session may list and call: _resolve_tool_policy with its cache and failure backoff, _UNRESOLVED_REFUSES_CALL, ToolPolicy, the identity notes, serves_managed_tools
mcp_shared_dispatch _run_stdio_dispatch_loop, the loop run_mcp_stdio_loop runs, with its worker, wake pipe and tunables

A global the family rebinds at run time (the framing, the stdout fd, the policy's failure state) lives in the one owner that rebinds it, beside every reader of it, and the owners log as kiro_crew.mcp_shared. test/test_mcp_shared_facade.py pins the contract.

Descriptors carry no per-caller state and are rebuilt per call, not cached: some quote a live value (the concurrent sub-agent cap), and a cache would pin the first reading for the life of the server process.

A kirocrew-dashboard tool is one row

kirocrew-dashboard is built on mcp_tools.table.ToolTable: each tool is one Tool row in mcp_dashboard.TABLE carrying its descriptor, its identity ("strict" for the session-control verbs, "attribution" otherwise), the dashboard routes it may reach ("METHOD /api/path/{id}"), and its _run_<tool> body. TABLE.list() answers tools/list; TABLE.call(name, args, ctx) is one tools/call frame: argument validation against MCP_DASHBOARD_SCHEMAS and the SEL invocation record (call_tool_with_logging), the unknown-tool reply, the strict gate for a "strict" row, a second validation pass (a second sanitize pass can still compose a string the first exposed), then the body.

A body reaches the gateway only through ctx.client, the DashboardClient port in mcp_tools/dashboard_client.py. LoopbackDashboardClient is production: each verb is the matching mcp_core helper, read at call time. InMemoryDashboardClient answers from a route table and records every request; it is what the dashboard tool tests drive. Both raise DashboardError for a reply carrying a truthy error, and the client the table hands a body refuses, before sending, any route its row did not declare. The caller is a port too: ctx.caller is GatewayCaller (mcp_core's resolvers) in production and a fixed Caller.strict(key) / Caller.unverified(...) in tests.

A new dashboard tool is one more row in the family function it belongs to (_folder_tools, _tag_tools, _board_tools, _session_tools), a body taking (args, ctx), and its validation schema in MCP_DASHBOARD_SCHEMAS. test_mcp_tool_registry.py holds the rows to those three, and test_mcp_call_site_auth_coverage.py checks every declared route against the internal allowlists.

mcp_dashboard.py keeps the folder, tag and board rows, TABLE with its strict gate and SESSION_CONTROL_TOOLS, and the stdio entry point (_call_tool, run_mcp_server). It is a mirror facade (kiro_crew._facade_mirror) over flat sibling owners, and binds every name they define, so each still reads and patches as mcp_dashboard.<name>. New code goes to the owner of its responsibility:

Owner Owns
mcp_dashboard_folder_tree the folder tree as the sidebar draws it: the sort-mode read, the order and name keys, sibling and render order, the free order slot, human paths, and each group's pinned-first session order
mcp_dashboard_references resolving a folder, session, tag or board-column reference to an id, and _get_rows, the list read those resolve against
mcp_dashboard_caller_scope what a caller may see or shape: _caller_app_scope, _visible_chat_slots, _refuse_tree_shaping_if_unverifiable, the caller's own slot, the channel: board-write refusal, _is_messaging_caller, SERVER_NAME
mcp_dashboard_session_tools _session_tools, the session-control rows (the board's session_move_to_column row is in _board_tools)
mcp_dashboard_session_runs the body behind each _session_tools row, and the folder filing session_create, session_fork and session_revive share
mcp_dashboard_folder_runs every _run_chat_folder_* body
mcp_dashboard_tag_runs the tag, pin, pin-move, board-column and move-to-column bodies, and the tag and board renderers

External servers a user may install (a Slack server, anything else) are ordinary user-added servers: they live in one of the scope files and are merged into the agent config at render time. They are not managed, so a mcp_server_alias normalization pass rewrites slash-containing keys to kiro-safe aliases: kiro-cli splits an agent @server reference on /, so a slash-containing key is mis-parsed as @server/tool and exposes none of the server's tools.

Browsing has one core MCP entry point. The browser tool forwards one operation to the dashboard's native Browser panel. It accepts public HTTP(S) navigation only; localhost, private, and link-local targets stay on the approval-gated playwright-cli path. When no native panel is attached, or the operator disables it, the tool returns fallback guidance rather than starting a second browser. Full CLI snapshots and accessibility trees still stay on disk. See browser.

find_ui and the UI location index

find_ui(query, lang?, surface?) (or find_ui(area, lang?, offset?), see Browsing an area) on kirocrew-guide answers "where is X in the dashboard?" from src/kiro_crew/docs/ui-index.generated.json plus, when the dashboard bundle is built, its auto tier static/dist/ui-index.auto.json, and nothing else (kiro_crew/ui_index.py). Like search_docs it is dispatched before the session lookup, reads packaged files only (cached per mtime and size of both, one entry, build data only), and never loads config, contacts the gateway, reads user state or opens a path a caller names: lang and surface are validated tags, and an unknown surface is refused. The search itself says what this build draws, not what the user's screen shows. Two bounded asks of the gateway add to it: which language the user's dashboard renders, so labels match the screen (see "Labels in the dashboard's language" below), and, for a search's curated results, a live field (see "Live observation" below). Both need the strictly resolved session key; without one, or without a fresh answer within 1.5 s, the labels stay in lang and every result carries live: {status: "not_observed"} and availability: "not_observed". A placement in the app shell (the top bar's Search Everywhere trigger) has no route or parent path: find_ui returns on_every_page: true for it and keeps it under any surface filter.

kiro_crew/ui_index.py keeps the tool's surface -- find_ui, browse_ui and its areas, the guide bindings authoritative_find and planned_find, and setting_labels -- and is a mirror facade (kiro_crew._facade_mirror) over three sibling owners, so every other name still reads and patches as ui_index.<name>. New work goes to the owner of its responsibility: ui_index_match.py (the shared constants, the question vocabulary and the matcher), ui_index_load.py (reading, validating, merging and caching the packaged index) and ui_index_records.py (one location's answer record: labels, requirements, guide and find references). The owners sit beside the facade because INDEX_PATH and AUTO_INDEX_PATH resolve from their module's own directory.

The index is generated by website/scripts/gen-ui-index.mjs (npm run gen:ui) from registries the dashboard already renders, never a parallel route table. Its logic is scripts/lib/ui-index.mjs, the one import path, which assembles the index and re-exports its three owners' public names: ui-index-source.mjs reads dashboard source (render-site markers and their labels, literal lists, the route table, interactive candidates), ui-index-auto.mjs maps files to pages and decides each auto site's id and guide policy, and ui-index-guide.mjs compiles the ui.show guide plans. New logic goes to the owner of its responsibility, and no owner imports ui-index.mjs. The inputs:

  • pages: src/surfaces/surfaceData.ts (the data half of every built-in surface, spread by builtins.tsx) and commandPalette/providers/pagesData.ts (Search Everywhere's extra pages). hiddenFromNav, appOnly, pinnable and previewFlag survive as entry_kind and requires;
  • tabs: the Settings tab list (SettingsPage.tsx buildTabs), the Settings sub-pages (railItems in the Chat, Display and Notifications panels, Security's SECTION_LABEL_KEY, the channel list), the Customize tabs and the Developer page's tabs (DeveloperPage.tsx buildTabs, as tab.developer.<key> at /developer?tab=<key>), read by a bounded AST adapter that accepts only literal key/label objects;
  • settings: every entry of the committed settings extraction (settingsRegistry.gen.ts joined by stable id to settings-registry.generated.json, whose route buildAgentRegistry built), so the index cannot describe a different set of controls than settings search. The generator first runs the same extraction in memory (scripts/settingsExtract.ts over src/pages/settings/*.tsx) and refuses when it does not reproduce both committed files byte for byte, so a renamed Settings label fails --check rather than riding along in a stale registry; the panel sources and the manual/route/type modules are digested too;
  • registered controls: a {...uiLocation('<id>')} marker at the render site plus one entry in its area file, src/uiLocations/areas/<area>.ts, aggregated by src/uiLocations/descriptors.ts (see below).

Every emitted route is checked against the router itself: the <Route path> table in src/App.tsx, read by a bounded AST adapter (collectRouteTable) that records each route's pattern, its catch-alls (*, a leading parameter such as /:builtinApp/*) and, when the element only redirects (<Navigate to> directly, or a same-file component that renders nothing else), the static target. A route must match a non-catch-all, non-redirect route (most static segments win, as the router ranks them), or be an appOnly surface served by the built-in-app arm; anything else, including an empty route, is an error. A Search Everywhere extra page whose route only redirects (/mc-agents, /tasks, /instances) is never returned as a destination: LEGACY_PAGE_CANONICAL in descriptors.ts names the location the redirect lands on, by explicit tab where the bare target would restore a remembered tab (/mc-agents -> Customize > Mates at ?tab=crews), and the page's title becomes an alias_keys entry of that location, which keeps its own route and prerequisites (Tasks keeps the Task Runner page's app_enabled). The generator refuses a redirecting page with no mapping, a mapping whose location is not where the redirect lands, and a mapping for a page that no longer redirects.

Labels are the 12 shipped catalogs (no en-XA; English is en.json under en.manual.json), referenced keys only, deduplicated per locale; a product name such as a channel brand is stored as a literal: key. A location stores label_key, never copy. Placements are alternatives, each with the full parent_ids chain, a canonical route, entry_kind and structured requires (viewport, shown_by another location, preview_flag with the Settings control that enables it from PREVIEW_FLAG_ENABLERS, and condition ids). The condition ids and reveal states are one pure-data table, src/uiLocations/conditions.ts, which the descriptor types import and the generator copies into the index as conditions / reveal_states (id -> description). A shown_by with when is a conditional reveal: the step applies only while that state holds (Older Sessions needs Show sessions sidebar only while the sidebar is collapsed; with no open sessions it is forced open and the toggle is not drawn). find_ui returns it with when, only_if (the description), otherwise: "already visible; skip this step", and the revealing control's own non-viewport requirements as nested requires (the toggle's has_open_sessions and full_dashboard), taken from its placement for the same viewport. A condition is returned with its description. Registered placements are resolved whole and in dependency order, whatever order the descriptors are declared in: a child picks the parent placement on its surface whose viewport does not conflict with its own, inherits that placement's chain, route and requirements, and must name parentPlacement when two compatible parent placements differ. The index's input_digest is a digest of the committed index's own content (never a clock or a git hash), so an edit to an input that changes nothing in the index, such as a label no location uses, leaves the committed file byte-identical and does not stale it. npm run gen:ui -- --check regenerates in memory and byte-compares the COMMITTED index (generated and curated tiers only; the auto tier below is never compared); it runs in frontend-ratchets and as the first step of npm run build, the build every packaging path (make frontend, build-wheel.yml) runs. Only a release build and a PR that made a fresh base stale fail on it; everywhere else a stale index warns. See "The find_ui index is strict only where the PR caused it, and at release" in docs/ci/ci-and-reviews.md. Pass --report <file> for a coverage report: which file holds which tier, core control coverage (curated + auto), registered controls, unregistered interactive candidates with their resolved label keys, unresolved candidates per file, and missing translations.

Each location is searched by its labels, its alias_keys and its curated search terms (terms: {locale: [...]}, the words a newcomer uses: "old chats" and "历史对话" for Older Sessions, "dark mode" for the Mode setting). A term hit reports match: "search_term". Matching is NFKC + casefold; space-separated scripts match whole phrases first, then label token coverage, and CJK scripts match whole phrases only (with a bigram-coverage tier that requires three quarters of the label), never single characters. Every candidate must also cover the question: question words (English, plus the form's own language for the other space-separated locales; whole question phrases such as 在哪里 for CJK) are dropped from both sides, and the content left must overlap by at least 0.6 (token Jaccard; CJK character share). Words the location's ancestors explain leave the question first: the labels of every parent_ids entry (in the searched locale, else English) are context, so "voice model" is Settings > Voice

Model and "chat model" is Settings > Chat > Model, while "model" alone stays ambiguous. Context only helps coverage, never the score: a location must still match by its own label or term, and every question word no ancestor explains must still be explained by it ("chat about dinner" is no_match). So one shared word is not an answer: "where are my old chats" does not return Settings > Chat, and "where are my keys" is no_match rather than three API-key settings. Ancestors can reorder target matches but never create one, and anything under the score floor or the coverage floor is dropped, so a weak hit never comes back alone as ok. Ties sort by id, set ambiguous, and carry tied (how many leading results share the top score). Statuses: ok; no_match (not in this build's index, which is not "the feature does not exist"); unavailable (missing, unreadable, over 4 MiB, unknown-schema or structurally invalid index, or a best match too large for the cap). The index is validated whole at load: every location needs a nonempty id (unique), a label key present in English (or literal:), nonempty placements whose routes are absolute, whose parent_ids and shown_by/preview_flag locations all exist, and whose when names a known reveal state; catalogs, conditions and reveal states must map strings to strings. Any failure answers unavailable for every query, never an exception or a partial answer. At most 8 results within 6 KiB of complete JSON records; dropped records set truncated; when not even one fits, the answer is a fixed, metadata-free unavailable that fits any cap of at least its own size. A setting carries setting_id, and guide_ref: {action_id: "settings.show", params} only when guide_catalog.guidable_settings() admits it. A registered control's own guide binding is validated against the page's guide registry (resolveGuideAction in guide/guideActions.ts) at generation, and again against guide_catalog.validate_actions (action, params and guidable settings) before find_ui hands it out; a refused binding is omitted. A curated location with a guide_plan and no binding of its own carries guide_ref: {action_id: "ui.show", params: {location_id}}, again only when guide_catalog.validate_actions accepts it. Every location carries a guide_policy: point; caution (a destructive control a guide may point at with a warning; the result says caution: true); search-only (find_ui answers with it, no guide is offered); or deny (a control of the agent's own ceiling, never guided). A curated one is caution when GUIDE_CAUTION_IDS lists it, search-only when it opts out, deny when GUIDE_DENY_IDS lists it or a placement sits under a TRUST_ROOT_PARENTS tab, else point; only a point or caution location ever gets a guide_ref. An auto result with a guidable policy carries the same ui.show ref (tier: auto stays on the result); a denied one carries none. A result with no guide_ref (a search-only auto control, a curated one without a plan, a generated tab) carries find_ref: {action_id: "ui.find", params: {route, label, role, location_id?, opener?, caution?}} instead (ui_index._find_ref): its own label in the dashboard's language, its first placement's route (none for the shell), the role its kind implies and, for a control guide_catalog.ui_find_location_ids lists, its location id, plus, when that placement is a menu entry under another listed control, that control as opener (the notifications bell for Mark all as read, the Mates header "+" for its New mate item), as guide_catalog.ui_find_opener gives it: never a control that removes something (a caution policy or an English label REMOVAL_LABEL_RE matches, ui_find_cautions) and never a trust-root control. Never for a setting, a denied location, a page the rail has no entry for or a list, nor for a description-labelled location other than the few opted in by ui_index._DESCRIBED_FINDS (the model chip, the goal/monitor button), which are named by their first alias ("Model") and matched by id; the approval-mode picker is described too and stays out, and only when guide_catalog.ui_find_params_ok accepts it (no trust-root page, a route the index knows, no ceiling-widening label). next names it for guide_start when no result has a guide_ref. A search hit grants no guide or change authority. An agent offers a caution: true guide only when the user asked for that very action, and says what it removes and that it cannot be undone.

Guide plans

gen:ui gives a registered location a guide_plan (guidePlanFor in scripts/lib/ui-index-guide.mjs), deny by default: only a curated location (its render-site marker proven), whose every placement requires only viewport, shown_by, preview_flag and the conditions described below, whose placements each take at most 7 steps (six pointing steps plus a preview gate; GUIDE_MAX_STEPS; placements may differ in length), with one placement per viewport, and which is not denied. GUIDE_CAUTION_IDS lists the destructive or data-replacing controls (mate delete, app uninstall, backup import, notification clear-all, schedule delete and cancel-run, stop monitor, sessions clean-up): each is planned like any other, and its last step carries caution: true. GUIDE_DENY_IDS lists the registered controls of the agent's own ceiling (the composer's approval-mode picker and the mate Permissions button today; the Security, Computer Use and Secrets tabs are refused whole by TRUST_ROOT_PARENTS, the tabs settings.show refuses too). The script fails when either list names an id that is not registered, or one id is on both; a descriptor opts out with guide: false (search-only). A location with its own guide binding, a description-labelled location and every generated location (settings use settings.show) get no plan. A plan is {version: 2, label_key, placements: [{id, route, viewport?, steps}]}: the placement id is its viewport or any, and each step is {id, location, label_key, when?, scope?, requires?, caution?} with id = <placement id>:<location>, unique in the plan. The steps are each registered ancestor's reveal steps, the ancestor itself (a menu button, a sub-tab), the location's own reveal steps, then the location; a reveal control must sit on the same route (or the shell) with one placement for that viewport. route is null for shell chrome.

Every step but the last names the reveal SCOPE it opens, compiled by compileRevealScopes: a shown_by with when: <state> uses the scope declared for that state in UI_REVEAL_SCOPES (uiLocations/conditions.ts, one per reveal state, e.g. chat.sessions-sidebar for sessions_sidebar_collapsed); a shown_by without when is reveal:<revealer>; a registered parent opens tab:<id> when its children are reached as a tab, menu:<id> when any is a menu entry, else open:<id> (a sheet, a panel). The index lists them under reveal_scopes ({kind, revealer, state?}). The generator refuses a reveal state used with no declared scope, a declared id with a colon, two scopes for one state, one state revealed by two different controls, a parent reached both as a tab and as a container, a cycle through a shown_by (parent-only loops are the existing parent-cycle error), and a placement needing two viewports or two opposite conditions (UI_CONDITION_OPPOSITES). A reveal control's OWN runtime conditions (the sessions sidebar toggle needs has_open_sessions and full_dashboard) travel with its step as requires, when every one is in the closed UI_RUNTIME_PREDICATES vocabulary (one browser evaluator each in guide/guidePredicates.ts; the index lists them as runtime_predicates); a condition outside it leaves the location search-only (no plan, no guide_ref). The target's own runtime predicates still deny a plan unless an earlier step carries them, a select step comes before it, or it is a page fact its page reports whenever it is mounted (PAGE_FACT_PREDICATES in the generator: has_crewmates, and phone_connect_available, which the shell reports from the same flag that draws Connect your phone); such a predicate travels on the last step and an unmet one is that step's blocker. mouse_input (reported by the chat box: the "+" menu is drawn for a mouse, while on touch the paperclip opens the file picker directly) is what lets the "+" menu and its items, Reference a file among them, be planned behind the open session. A predicate the owner of the target's opener reports (OPENER_FACT_PREDICATES in the generator, mirrored by UI_OPENER_FACT_PREDICATES in conditions.ts: goal_loop_running and monitor_running, both reported by the goal and monitor button's popover owner) moves onto the opener's step instead, and the tab does not point at an opener whose such predicate is unmet: Pause and Stop monitor are planned behind the goal button, and with nothing running the guide's blocker says so before the panel is opened.

Selection and gate conditions become steps of their own, outermost first (after the page): one gate step per gate the path needs, then one select step per selection, then the reveal and menu steps, then the location. A gate is a condition in UI_GATES (developer_mode turned on by developer.developer-mode, terminal_enabled with no setting to name) or a preview flag, compiled to preview_flag:<flag> with the enabler from PREVIEW_FLAG_ENABLERS; its step is {id, kind: "gate", gate, setting_id?} and points at nothing. A selection is a condition in UI_SELECTION_SCOPES (session_open at sessions.list, crewmate_selected at members.roster-list, job_open and one_job_checked at schedule.job-list, crewmate_editor_open at agents.crew-list, each a registered kind: list picker that find_ui search never ranks); its step is {id, kind: "select", location: <picker>, label_key, selection, entity, requires?}, after the picker's own reveal steps. The index lists both vocabularies as guide_selections and guide_gates; the generator refuses a gate on an unknown setting, a picker that is not registered, and a condition in two vocabularies. A location drawn at every width whose path differs by viewport (the session picker is in the sidebar on a desktop, the drawer on a phone) is planned once per viewport. Step ids are <placement>:<key>, the key (gate:<id>, select:<id>, a location id) being the same in every placement. The same plans are written to website/src/uiLocations/guidePlans.gen.ts, together with GUIDE_BUILD_DIGEST, GUIDE_OBSERVABLE_IDS (the curated ids), GUIDE_REVEAL_SCOPES and its key type GuideRevealScopeId (the only ids a scope owner may report); the index carries the same digest as build_digest (guideBuildDigest: SHA-256 over the curated ids, the scopes and every plan), and gen:ui -- --check compares both files.

Live observation

find_ui asks POST /api/guide/agent/observe {targets: [...]} (strict-internal, same caller checks as the other /api/guide/agent/* routes) for the curated ids among its results. The gateway (dashboard/guide_observe.py) validates them against guide_catalog.ui_build_manifest() (curated ids only, at most 16; an unknown id is 400 unknown_target), adds the reveal scopes those ids' plans name (at most 8) and the runtime predicates their steps carry (at most 8), and picks ONE tab: the running guide's owner tab, else the tab that sent the slot's latest chat message (the owner's POST /api/chat carries X-Guide-Tab), else none (not_observed, no_tab). The sender is recorded when that request arrives, before the busy-slot check, so a message queued behind a running turn (a scheduled run's, say) is drained later with the same tab and X-UI-Lang the idle path would have had. It sends an owner-only guide_observe frame {request_id, tab_id, targets, scopes, predicates} and waits at most 1.2 s for that tab's POST /api/guide/observe (owner-only, like every browser guide route) carrying exactly {tab_id, request_id, build_digest, document_epoch, sequence, targets: [{id, status}], scopes: [{id, state}], predicates: [{id, state}]}: the asked ids each once, status one of pointable, offscreen, hidden, unmounted, disabled, ambiguous, unknown; a scope state open, closed or unknown (no owner mounted); a predicate state met, unmet or unknown (no reporter mounted; an id the bundle has no evaluator for is unmet). Any other field or value refuses the reply whole, so no page text can cross. A reply from another tab, for an ended request, with a changed document_epoch or a non-rising sequence is refused (409); a reply whose build_digest differs is answered not_observed with build_mismatch. A request with no answer in time is not_observed with stale_tab, and when it was the guide's owner tab the guide's reason becomes stale_tab (no revision bump; its next heartbeat clears it). Requests, senders and tab sequences live in memory, bounded and expiring; an answer is returned once and never stored. Replies from several tabs are never merged.

When the answer is observed, find_ui also gives a result a blocker from the reported facts alone, outermost first: gate_off with gate and setting_id (null when no setting turns it on) for a gate on the plan that is unmet; needs_selection with selection for an unmet selection; predicate_unmet with predicates (another predicate on the location's plan is unmet); else, for a hidden or unmounted control, hidden_in_scope with scopes (a scope on its plan is closed); unknown is never a blocker and a pointable or offscreen control has none. Selections and gates travel in the observation's predicates (the manifest's predicates is the union of runtime_predicates, guide_selections and guide_gates), so a tab says only whether one entity is picked, never which. A result with no fresh answer carries blocker: {kind: "not_observed", reason?}.

Reveal scope owners and the guide's live checks

A scope owner is <GuideRevealScope id open> (guide/GuideRevealScope.tsx), placed OUTSIDE the conditional it controls so it reports closed while the contents are unmounted; the scope chain reaches portalled children through React context. The shared primitives own one through an optional prop: DropdownMenu guideScope, Popover guideScope (controlled or not) and TabsContent guideScope (selected = open); there is no shared disclosure primitive in components/ui, so a disclosure's owner is the shared useGuideDisclosureScope(locationId, open) at its call site, reporting the open:<id> scope the generator compiles for every registered kind: disclosure (Older Sessions in ChatSidebar). A container that IS its own owner reports through useGuideRevealScope(id, open). Wired today: the sessions sidebar and drawer (SessionsSidebarChrome), the chat side panel (ChatPage), the message box (composer.box, ChatInput), the navigation rail (shell.nav-rail, RailBrandToggle), the docked terminal panel (shell.terminal-panel, BottomTerminalPanel), the phone menu (menu:shell.mobile-menu, App), the mate roster on a wide screen and on a phone (members.roster, members.roster-phone, MembersPage), the mate's profile card (members.profile, MembersPage, the scope of the header pill that reveals its Permissions row, members.permissions), menu: scopes of the sessions list and create menus, the artifacts add menu, the terminal and side-panel menus, the mates add menu and switcher, App Store sources, the composer add menu, the notifications sheet, and the Connections MCP tab (open:connections.mcp-servers-tab). A scope with no owner mounted reads unknown and a step on it keeps its reach fallback (a later target on screen). A reporter of a runtime predicate is useGuidePredicate(id, value) (ChatPage reports both sessions-toggle predicates, App reports not_on_sessions_page, SchedulePage reports schedule_list_view). While a step's target is absent and one of its predicates is unmet, the guide shows a blocker naming what is needed instead of pointing, reports target_missing with detail predicate_unmet after the 1.5 s settle (the guide's reason becomes predicate_unmet), and recovers only once the predicates hold and the target is drawn.

A gate's reporter is useGuideGate(id, on) (App reports developer_mode and terminal_enabled); a preview flag is read from storage. A gate step that is on is observed at once; off, the guide shows the gate's line ("Turn on “Developer Mode” in Settings first…"), points at nothing, and after the settle reports target_missing with detail gate_off; the guide's reason becomes gate_off and its public record carries blocker: {kind: "gate_off", gate, setting_id} from the record's own plan (step_meta). It recovers (target_found) only once the gate is on. A selection's reporter is useGuideSelection(id, {selected, available, name?}) in the page owning the picker (ChatPage, MembersPage, SchedulePage, KiroCrewAgentsPage): two booleans reported, plus the picked entity's name kept in the tab (the same string its row is registered with by guidePick(name)) to bind a pick and name the entity in the confirm line; which entity never reaches the gateway. A select step points at its picker and is observed ONLY when the page reports selected, never because a later control is drawn. A pick already made at the step's first report passes the step at once, unless a later step of the same action carries caution (today schedule.delete, whose job pick precedes Delete): then the step is held (useGuideStepTracker's onPreselected) and the panel says "This job is already open. Pick a different one in the list, or press Next to go on with it" under a line naming the job actually open (or, with the list folded away, points at nothing and says Next goes on with it), and only Next reports observed; with available false it shows "There's no yet", never points at a create control, and reports selection_empty (reason needs_selection, blocker: {kind: "needs_selection", selection}). The gateway accepts either detail only from a step whose plan entry is that kind (400 invalid_detail otherwise). The agent is told one thing about it: on gate_off, propose the setting_id with propose_change (settings.show when it is not writable); the guide never flips a setting.

When the owning tab's viewport class changes mid-guide, it asks POST /api/guide/replan {guide_id, tab_id, revision, action_index, placement} (owner-only, revision-checked, once per guide revision and placement) to walk the current ui.show action by the new viewport's placement. The gateway (GuideStore.replan) allows it only at a step boundary both placements share: the steps already walked are the same keys in the new placement, which also has a step at the current index; it then records the new placement's step ids, keeps the index, returns a missing guide to active and sets reason replanned. Anything else is 409 replan_not_at_boundary and nothing moves, so the guide shows its target missing as before. Nothing here ever opens, clicks, selects or enables anything. With lang the requested locale and English are searched; with none, English plus whole-phrase matches in every shipped locale, and labels are returned in English with locale_source: "fallback".

Labels in the dashboard's language

lang is the language of the QUESTION; the labels follow the language the user's dashboard tab renders, which can differ (a Chinese question on an English dashboard must be answered with the English labels the screen shows). Every POST /api/chat from the owner's tab carries X-UI-Lang (the SPA's activeLocale(), beside X-Guide-Tab), and the gateway keeps it per slot, in memory, for the sender TTL, only when context.normalize_ui_language_tag admits it as a shipped catalog (ObservationHub.note_ui_lang; a send without the header keeps the last value). Before searching, find_ui asks GET /api/guide/agent/language (strict-internal, the same caller checks; {ui_lang, source}, source tab, else setting from the configured dashboard.language, else unknown with ui_lang: ""; handlers/guide.caller_ui_locale) with a 1 s budget, and passes the tag as label_lang to ui_index.find_ui / browse_ui: the question is then read in its own locale, the dashboard's and English, and every label and path is in the dashboard's locale with locale_source: "dashboard" and a prose_note saying to quote labels unchanged and translate only the condition prose. A refusal, no identity, an unknown language or a timeout leaves the labels in lang, as before. find_setting rows get the same treatment on the gateway side (change_cards.localize_setting_rows, through ui_index.setting_labels): a setting the index holds carries its on-screen label, its Settings path and label_locale; any other row keeps its registry label.

Browsing an area

Search recall, not coverage, is what a novice question usually misses on: in a 100-question demand corpus (EN and zh-CN, ten areas) most misses targeted a location the index already had, under words the question did not use. So find_ui has a second mode on the same tool, chosen over a separate tool to keep the surface at one where-is tool with one grant: pass area instead of query (both or neither is an error; surface is search-only, offset browse-only) and it lists every entry of that area, browse_ui in ui_index.py. The area vocabulary is ui_index.AREAS, stable ids over the index's own structure, also listed in the tool description: sessions, composer, crewmates, schedule, artifacts, apps, connections, customize, notifications, shell, settings, developer. A location is in an area when it is one of the area's anchor locations, when a placement's path runs through one, or when it matches the area's id prefixes or surface; areas may overlap, and sessions excludes composer. settings is split: its listing names one settings.<tab> sub-area per Settings tab (sub_areas, with the localized tab label and a count) and lists only what no sub-area holds. An area may name related areas (Settings and Customize; Connections and Settings, whose Agent Harness tab holds the model sign-in; Shell and Sessions, whose chat side panel holds the built-in browser).

Each entry is compact: id, label (or description for a live-data label), path as one A > B > C string, tier, states (when > label) for a flipping label, on_every_page for the shell, ways when there are several placements, and needs, the first placement's prerequisites as short English phrases (desktop only, after <label> if <state>, preview: <label>, a condition id); find_ui with an entry's id as query returns the full ones. Proven entries come first in path order, auto entries after them, and an auto entry whose label is one word in the response locale is left out (as find_ui never answers with one) and counted in omitted_one_word_auto. The listing obeys the same 6 KiB cap as a search: whole entries per page, and when more remain truncated: true with next_offset to pass back as offset, so an area is paged, never cut; a cap that cannot hold one entry is the fixed unavailable answer. It has find_ui's security posture: packaged files only, no gateway, config or caller identity, and the area id is a validated shape (an unknown well-formed id is told the vocabulary; a malformed one is refused without being echoed).

test/test_find_ui_browse.py carries the demand corpus verbatim, maps each intended task to its location id, and pins recall@area (the location is in the listing of the area the row names, or a related one for the three named RELATED_ONLY exceptions), lists the tasks with no indexed location as coverage gaps (one today: an app's settings, since an app's detail page draws only a read-only Configuration card and an app's own settings live on its own page), keeps the ten out-of-scope negatives no_match, and checks every area's pages in EN and zh-CN fit the cap and list each member once.

The auto tier is built, not committed

Beyond pages, tabs, settings (tier: "generated") and registered controls (tier: "curated"), find_ui knows tier: "auto" entries: unregistered controls whose one static label key and pages the generator proves from the module graph. A file drawn by one page's route and no other (an app or an unindexed route aside) is that page's (or, when proven, one tab's); a file only the app shell draws (the rail, the top bar, shell dialogs) is surface_id: "shell" with no route and no path, returned on_every_page: true like a registered shell control; a file several indexed pages draw (or a page and the shell) is a SHARED control, auto:shared:<label key>, with one placement under each of those pages in page-id order (the shell's, when it draws it too, last). Where on the page they sit and what must be true for them to show is unknown, so each carries conditions_unknown: true and no search terms, and the agent relays them hedged. A control's label is its first label attribute (aria-label, title, label) or its text; an icon-only control (no text of its own, only elements or an icon-picking call) whose first attribute is dynamic but a later one is one static key (aria-label={copyOutcome(...)} beside title={t('copy')}) is labelled by that key.

Every new static-label button changes this tier, so it is not in the committed index: committing it made any frontend PR that added a button stale gen:ui --check. npm run build starts with node scripts/gen-ui-index.mjs --check --warn-if-stale --auto-out node_modules/.cache/kc-ui-auto/ui-index.auto.json --sites-out node_modules/.cache/kc-ui-auto/sites.json, and the ui-auto-stamp Vite plugin emits that artifact into the vite output (see "Auto locations a guide may point at"), so the shipped tier is the one the stamps were cut from. It then ships wherever the dashboard bundle does, because every packaging path copies the whole website/dist tree to src/kiro_crew/static/dist: make frontend, the build.yml/build-wheel.yml/ci.yml/docker-smoke.yml/nightly.yml/ gui-user-test.yml staging steps, install.sh/setup.sh/minimal_install.sh, packaging/build-desktop.sh (both desktop targets), frontend.py's staged swap, pod provisioning, and the dev symlink ensure_dev_dist_symlink makes to website/dist. The wheel carries it through BuildWithFrontend (setup.py copies static/dist) and the sdist through recursive-include src/kiro_crew/static *; the Docker image installs that wheel. ui-index.auto.json is gitignored everywhere, and --auto-out refuses src/kiro_crew/docs/.

The artifact (buildAutoArtifact in scripts/lib/ui-index.mjs) holds only the auto locations and the labels they use, plus base_input_digest, the input_digest of the committed index it hangs off, and the build-time core coverage numbers. The committed index's digest no longer carries anything the auto tier derived. ui_index_load.py merges the artifact at load only after checking all of it: schema, artifact: "auto", base_input_digest equal to the committed index's, the same locales, only tier: auto entries (each validated like any location, conditions_unknown: true and no terms), new ids whose paths run through committed pages and tabs (or are empty: a shell-only control), and labels that never redefine a committed key. If the file is missing (a source checkout with no frontend build), unreadable, malformed or built against a different index, only the auto tier is unavailable. The committed tiers answer as usual, and every response says auto_tier: "unavailable" with an auto_tier_reason. With the tier loaded it says auto_tier: "available" and coverage adds its scope. A committed index that itself carries tier: auto entries is refused whole (unavailable), so the tier never has two sources.

A search term that is one content word once question words are dropped ("get an app" is {app}) answers only when the whole term is in the question: matched by word coverage, "app settings" ({app}) came back as Discover > Install.

An auto entry answers only when its whole label is in the question and explains all of it (question words and its page's words aside), only when no generated or curated location matches at all (curated always wins), never as the sole-control answer to " button", and never with a label that is one word in the locale it matched in. A label is one word when it folds to one token ("Back", "Name", "Save"; "Sign-in" and "Re-run" are two) or, in CJK, when it is at most two characters (返回, 名称, 名前), the length of one common word. Those are look-alike controls on many pages, and an auto entry has no terms and no place to tell them apart. So "back" and "name" are no_match, while "copy redirect URI", "download tailscale", "下载 Tailscale" and "show pairing code" still answer from the auto tier. The rule leaves generated and curated locations alone.

Coverage is still computed at build time: the generator's summary and --report print core control coverage as (curated + auto) / interactive elements in core sources, and the artifact records the same numbers. Python goldens never read a built dashboard: test/test_find_ui_auto.py pins the loader on synthetic file pairs, and runs the real generator with --out and --auto-out into tmp_path when node and website/node_modules are present (otherwise those tests skip). The backend CI lanes have neither, so CI's frontend-ratchets job, which has both, runs exactly those two tests after gen:ui --check, with KIROCREW_UI_GENERATOR_REQUIRED=1 turning the skip into a failure. The other test_find_ui*.py files point AUTO_INDEX_PATH at a missing file, so they test the committed tiers whatever the checkout's build holds.

Auto locations a guide may point at

An auto location is search-only by default. The generator (buildAutoLocations) gives each auto candidate a render-site id from ONE pure function, autoSiteIds: auto:<page|tab|shell|shared>:<file stem>:<label key>, with :2, :3 for later sites under one parent that would share it (ordered by file and position, so the ids depend only on the tree, never on scan order). Search grouping stays as before (one location per parent and English label, id auto:<parent>:<label key>); a location remembers every site it groups. autoSitePolicy then decides per site. deny is the agent's own ceiling only: a site or location in GUIDE_DENY_IDS (which may name auto: ids; the script fails on one this tree does not have), a site under a TRUST_ROOT_PARENTS tab (Security, Computer Use, Secrets: the tabs settings.show refuses too; Instances, the user's own Remote Crew setup, is an ordinary tab), or a site in a file one of those tabs' panels reaches, whoever else draws it (buildPageMap's tabFiles). A site is guidable only when drawn by a REVIEWED PRIMITIVE (AUDITED_PRIMITIVES: Btn, SendBtn, IconButton, Toggle from src/components/ui.tsx, TabsTrigger from src/components/ui/tabs.tsx, DropdownMenuItem from src/components/ui/dropdown-menu.tsx, each imported under that name and each forwarding a stamped data-ui-auto to the element pointed at, pinned by guide/autoTargets.test.tsx), with no prop spread, outside every closed container (a menu, popover, dialog, sheet, disclosure, tab panel; so a menu item stays search-only until its menu is registered) and with a well-formed id. A guidable site is caution only when it removes something: an English label CAUTION_LABEL_RE matches (delete, remove, uninstall, erase, reset, wipe, purge, destroy, clear all / data / history / ...), or a site or location in GUIDE_CAUTION_IDS. A danger style alone does not make it caution: a danger-styled control that removes nothing (Sign out, Deny, Deploy anyway, Clear selection) is a plain point, since the caution line says what it deletes is gone for good. It is search-only when its label only trips the ceiling-label lint (SENSITIVE_LABEL_RE: approve, grant, trust, allow, autopilot, yolo; listed in the --report, it never promotes anything), else point. Everything else is search-only. A location is guidable only when it groups exactly one site, that site is guidable, and none of its placements has a prerequisite; it has one placement, or, for a shared control, one per page; deny on any site wins. Only a guidable location gets a plan, single-step and in the build-time artifact only: {version: 2, label_key, placements: [{id: "any", route, steps: [{id: "any:<location id>", location: <site id>, label_key, caution?}]}]} (route null for the shell). A shared control's plan has one placement per page, ids pa, pb, ..., every one pointing at the same site; the page claims the placement of the route the person is on when it is one of them (the shell's when the shell draws it too), else the first, never re-plans it on a viewport change, and points only when exactly one instance of the site is visible there (otherwise ambiguous, as for any target). The artifact also carries base_build_digest (the committed index's build_digest) and its own build_digest over that and every auto plan (autoBuildDigest), and counts auto_point, auto_caution, auto_search_only and auto_denied in its coverage.

The marker: npm run build runs the generator first with --auto-out node_modules/.cache/kc-ui-auto/ui-index.auto.json --sites-out node_modules/.cache/kc-ui-auto/sites.json. sites.json (autoStampManifest) lists, per source file, the sha256 of the exact text the generator scanned and, per guidable site, the offset right after its tag name, the end of its opening tag, its tag and its site id. The kirocrew-ui-auto-stamp Vite plugin (scripts/lib/ui-auto-stamp.mjs, enforce: 'pre', before JSX is compiled) inserts data-ui-auto="<site id>" there, on the dev server too. It never parses a file or derives an id: it checks the hash (a changed file fails a build and is left unstamped on the dev server), checks that the tag ends at the offset, and skips an opening tag that already carries data-ui-location or uiLocation( (curated wins). It defines __UI_AUTO_BUILD_DIGEST__ (the manifest's digest, the artifact's) and emits the artifact into the build output as ui-index.auto.json, refusing one whose digest differs from the manifest's. Nothing strips the attribute in production. Under Vitest the plugin does nothing, so the bundle's auto digest (uiLocations/autoBuild.ts) is empty and every auto guide is refused.

In the browser, a {kind: 'location'} target whose id is an auto site id resolves to an element registered as that curated location OR as that auto site; a curated id never resolves to an auto registration. A reviewed primitive (Btn, SendBtn, IconButton, Toggle, TabsTrigger, DropdownMenuItem) registers the element it draws under the data-ui-auto prop it was handed (autoSiteRef), so the site id comes from the stamped source, never from the page. The live registry keeps the exactly-one rule (uiLocationCopies, soleShown) for both, but the guide points an auto site's step at its first visible copy, one inside the viewport first (firstShown, repeated on the target): one render site is drawn once per list row, and any row shows the control. A destructive (caution) step keeps the exactly-one rule, so the person is never shown another row's delete. resolveUiShow walks an auto location's plan only from the guide record's auto_plan, only when the record's build_digest equals the bundle's auto digest (else build_mismatch), and only when every placement is one pointing step at the same site id (several placements only for an auto:shared: id; guide_catalog._auto_plan_site applies the same rule). The live registry reports an auto site's status when the bundle was stamped. The observe channel accepts an auto location id only when the auto tier made it guidable (UiBuildManifest.auto_sites); the gateway asks the tab for its site id and names the answer back by location id. find_ui's live hint covers those ids too.

The trusted target registry

Every resolver a guide uses (the live registry, findUiLocation, findOpenerLocation, findGuideAnchor, the pick helpers, resolveStepTarget's ownership check, findByName's identity of a match, findTargetPolicy's identity check, recovery and the outline and arrow placement that follow from them) reads only uiLocations/targetRegistry.ts, never the DOM attributes. The registry maps kind and id to the elements React mounted through a registering helper: uiLocation(id) (location), a reviewed primitive's data-ui-auto prop (auto), guideTarget(id) for a shared primitive's row (target), guideAnchor(name) (anchor), guidePick(name) (a picker item), guidePickOf(name) (a container that belongs to one item, such as a tile's portalled menu), guidePickControl(kind) (an item's own pick control), guidePickAlias(name) (an item's other name) and guideConfirm() (a removal's final control). Each helper returns the debug attribute and a callback ref owned by that one mounted use: the ref remembers the element it attached to, and its ref(null) removes exactly the entry it added, whether or not the element is still in the document, so a conditional spread React drops while it keeps the node takes its registration with it. With the element's own ref the callback is the same every render (keyed on that ref), so a callback ref that sets state on its node hears only real attaches; without one it is fresh per render, and React detaches the old and attaches the new in one commit. Readers also filter on isConnected. The generator refuses two registering spreads on one element (each carries a ref, so only the last would hold) and a registering spread beside an explicit ref: one helper's ref goes in as the other's own argument (uiLocation(id, guideAnchor(name).ref)). The test-side proof unregisteredMarkers() checks every identity kind, and a test that unmounts calls it before the unmount. An element that only carries the attribute strings (an SVG artifact, a markdown reply, a file preview) is never registered and so never counted, outlined or treated as an owner, whether or not the data-guide-untrusted container mark and the sanitizer's marker strip also reach it; those two stay as defence in depth.

Pointing at a control by its name

ui.find {route?, label, role?, container?, location_id?, opener?, caution?} points at a control the index has no plan for, by the name the page gives it. The gateway (guide_catalog._validate_ui_find) accepts a route only when the committed index or its auto tier places a control there (as written, or that route's bare pathname; ui_find_routes), never a trust-root page (TRUST_ROOT_ROUTES: Security, Computer Use, Secrets; sensitive_page); no route means the page the person is on. label and container are agent text under the same rules as a note (plain text, 80 characters); a label CEILING_LABEL_RE matches (approve, grant, trust, allow, autopilot, yolo) is sensitive_label, and one REMOVAL_LABEL_RE matches always carries caution. role is one of FIND_ROLES. location_id is accepted only when ui_find_location_ids lists it: a control of the committed index (curated or generated, not the auto tier) that is not a page, list, setting, denied location or part of the trust-root tabs (unknown_location otherwise). opener is never the caller's choice: it is the target's indexed opener (ui_find_opener), set from location_id whether or not the caller passed one, and a caller value that is not exactly that id (another control, one that removes something, a trust-root control, or any opener without a location_id) is unknown_location. A container that is a number (#2, 2) is invalid_params: a number names a match only in the list the person saw, so several matches are picked in the panel. The action has two fixed ui steps, open and show.

Before guide_start sends a ui.find, mcp_guide sets its label from the index (ui_index.authoritative_find): with a location_id, a label that is not one of that location's own (label, alias or state keys, in any shipped language) becomes its label in the dashboard's language; without one, a label no indexed control carries is looked up with find_ui, and the best result's find_ref replaces the params (the agent's container kept) only when it is on the route the agent named, or the agent named none (a match drawn on every page keeps the agent's route); a match on another page leaves the agent's params as they were, for the catalog to judge. Any agent opener is replaced by the indexed one, or dropped. The tool result's next then tells the agent to name the control exactly as the guide does, so the reply quotes "Add Job" and never a name of its own such as "New schedule".

In the tab (guide/findByName.ts), searchByName looks over the visible interactive elements outside the guide's own layer (never a box under 2px, the visually-hidden pattern of a file input), filtered by role (a switch matches a checkbox, any menu item kind a menu item; a role that matches nothing is dropped, since the page does not always draw a control as the kind the index knows it by: a Settings sub-page is a list option, a side-panel tab a plain button, a panel toggle a pressed button): an exact accessible name, then one equal once case, spacing and punctuation are folded. A name that only contains the label is never the control ("Remove" is not "Report a problem — secrets removed"), and with location_id a control carrying another registered id is never a name match. Of several matches, a section title (a heading, or a control drawn in one) gives way to one that is not, and for a tab role or a settings.* location the one inside the page's navigation (nav, navigation, tablist, listbox) wins over a field or control of the same name in the section it opens. Without location_id, a single match in the main navigation wins over same-named controls outside every navigation region (the Mates rail row over the Mates page's switcher chip, which is also named "Mates"), so a tour of the rail never asks the person to pick; a rail entry and another navigation entry of the same name (a Customize tab) stay ambiguous. With location_id, a visible control carrying that id is the match before any name is compared, whatever its label reads in the page's current state (the top bar's Search reads "Open command bar" while an app owns the slot): data-ui-location on the control, or on a wrapper holding exactly one, or data-guide-target (guide/trustRoot.ts) for a row a shared primitive builds from its props, such as a Settings sub-page row (SettingsSubNav guideTargetPrefix, settings.sub.<tab>.<key>), whose name also carries its status line. With no such control on the page the name search runs as without it. container narrows several matches to those whose surroundings carry that name; a number (#2) never narrows. One match is found, several ambiguous, none none.

What the match is, is decided on the matched element, never on the agent's words (guide/findTargetPolicy.ts). isTrustRootTarget makes the search sensitive when the page is a trust-root route (whether or not the action named a route), when the element sits in a region marked data-guide-trust-root (the Security, Computer Use and Secrets panels wherever Settings renders, a chat approval card and its trust menu, the approval-mode picker, a Modal opened with guideTrustRoot such as the app and project trust dialogs and the Security panel's confirms), when its registered location or auto site belongs to those tabs, when it is a settings row isSensitiveSetting refuses, or when its English name or any catalog key it renders from names a ceiling word (approve, grant, trust, allow, autopilot, yolo). The marker crosses portals: a trust-root region provides GuideTrustRootProvider (guide/trustRoot.ts; GuideTrustRootRegion is the marker and provider in one), and every shared primitive that portals its content (DropdownMenu, Popover, Dialog, Select and ContextMenu content, Modal, InfoTip, InstantTip) re-emits data-guide-trust-root on that content while inside one, so a trust menu rendered at the body is as refused as the card that opened it. A name rendered from a catalog value with {{...}} parts resolves to that value's key when it carries all of the value's static text in order from start to end (markup and spacing ignored, at least two static characters), so a Chinese 信任“npm test” names components.trustDropdown.trust_this_command. A sensitive match is never pointed at, resolved or reported as found: the gateway hears none and detail not_found, and the panel says it is a security control. isCautionTarget adds the caution line (and the confirm-aware finish) to a found control marked data-guide-caution (guideCaution, for a destructive control whose name is built at run time, such as "Delete {{name}}"), whose location the index marks caution (GUIDE_CAUTION_LOCATIONS in guidePlans.gen.ts), or whose catalog key, from its location, its auto site id or the active catalog's entry for its name, names a removal; keys are the same in every language, so a control labelled 删除 carries it as Delete does. The gateway's REMOVAL_LABEL_RE caution on the label still applies on top.

The open step passes at once when the control is visible. Otherwise, with an opener that is on screen, and whose element is neither a trust-root control nor one that removes something (isSafeOpenerTarget, judged again on the element each time the step resolves; the tab also refuses such an opener id outright), it points at that control with "Open the highlighted control: … is inside" and passes once the person opened it and the control shows; nothing is probed or opened for them. Without one it points at the container the probe found the control in; the show step points at the control and its panel quotes the control's own accessible name. When the step starts and the control is neither visible, ambiguous nor sensitive, useFindProbe runs probeForName once. It opens only containers a shared primitive registered in guide/probeRegistry.ts, each with a paired open / restore driving the primitive's own state; no click, key or other event is dispatched. DropdownMenu and Popover register an instance that is uncontrolled with no onOpenChange, or whose caller passes guideProbe (guideProbe={false} keeps any out); Tabs registers only a rail declared guideProbe="local", so a tab whose selection lives in the address is never selected. Hand-rolled menus, disclosure buttons, <details>, destructive confirm toggles and the composer's Sketch entry are not registered and are never opened: when nothing registered holds the control, the panel asks the person to open the menu or section it is in, and the step resumes once it is on screen. Each registered container is opened, searched, and its own newly registered containers searched one level further, then restored, with scroll positions put back; never one inside the guide's layer or a trust-root region, and never on a trust-root page. Focus is never moved: while the probe holds a DropdownMenu or Popover open (useProbeHold), its content skips the open and close autofocus and is dismissed by no focus or press outside it, a probed menu is non-modal, and restoring focuses nothing, so no field blurs (a blur can save a setting) and no other open layer closes. The person's next press, key or wheel outside the guide's layer ends that hold before the primitive hears the input. It stops at the first hit, after 12 containers, at depth 2, after 1.5 seconds, when the address changed, or when its AbortSignal aborts (the step changed, the page moved, the guide ended), restoring what it opened. Pressing Cancel calls abortProbes at once, before the gateway answers, and the probe stays off while the cancel is in flight (cancelling, busy); Next and Done abort it the same way. The press also locks the guide synchronously until the cancel settles: report sends nothing (no progress, recovery or selection), the step tracker is off, and no heartbeat or re-plan goes out. A report already in flight lands first, then the cancel is sent at the revision it left; a 409 re-reads the guide and retries the cancel at the new revision (GUIDE_CLOSE_ATTEMPTS), never resuming the guide in between. A real pointer-down, key or wheel outside the guide's panel stops it and nothing is restored, so the probe never overrides what the person just did; such input is heard from the moment the step starts, so input during the settle wait means no probe at all, and none starts while the person's focus is in a field they type into. Both leave the verdict none, and the panel asks the person to open the container. While it runs, no find target resolves. The verdict (findState) is the container path to point at, with a count when the container holds several matches, or ambiguous / none, which the step tracker reports as target_missing with detail ambiguous / not_found after the short settle. Several matches, visible or inside a container the person has just opened, are numbered in the panel by what surrounds each; the person picks one there (setFindPick) or tells the agent its number, and the person picks it in the panel; the agent never offers a number as a container. The candidates are kept in the tab for when they leave the screen. A pick is bound to the control the person chose and to the whole set of matches as they were (each match's name, role, surroundings, the section title above it and its registered id, in order), never to its number or position: when the set changes or the picked element is gone (a remount draws new elements, never assumed to be the same entity), the pick is stale and the person is asked again (findNeedsPick), even when a single match remains.

find_ui hands out a find_ref for a page too: a page the navigation rail opens is named by its rail entry with no route, so the guide points at the rail from wherever the person is; any other page carries its route.

Every progress report on a ui.find step carries find (guide_catalog.clean_find_report: result, count, and for a found match its role and, for a registered control, its location_id and label_key). Page text never leaves the tab: the panel shows the found name, the containers and the numbered alternatives (distinguishingContexts: each one's labelled surroundings, else the section heading above it; two that read the same are named by the heading above each, never by a bare number) to the person, and the gateway hears none of them. The guide record keeps the latest find; guide_status returns it, with reason not_found or ambiguous_target when the step is missing. The order the results' next gives is: a guide_ref, else a find_ref, else ui.find with a page and label from find_ui or search_docs; only after not_found does it give the path in words, saying it was not on the screen.

Adding a UI location

An unregistered control with one static label needs nothing: the build-time auto tier picks it up (under each page that draws its file), and adding it never stales the committed index. Register a control (below) when it needs more than a hedged "on page X there should be a Y": an exact place, prerequisites, newcomer search terms, a one-word label, or one instance of a file a page draws several times.

Two steps, and the generator fails on either one alone; then regenerate:

  1. At the element the person sees, spread {...uiLocation('<area>.<name>')} (src/uiLocations/uiLocation.ts); a render module that has none yet also needs that import. One id names one render site. The spread carries the attribute AND a callback ref that registers the element in the trusted target registry (below), so an element that has a ref of its own passes it as the second argument, uiLocation('<id>', ownRef); the generator refuses a ref attribute beside the spread and a bare data-ui-location attribute. A custom component that receives the spread must forward it, ref included, to the DOM node a person clicks (a forwarding component re-emits it with forwardUiLocation(id, ...ownRefs)), proven by a rendered test: uiIndex.test.ts scans every production marker and accepts an intrinsic element, or a component in its FORWARDING_PROVEN list (Btn, SendBtn, DropdownMenuItem, Glass, IconButton, Clickable, Link, NavItem, Row, AddMenuItem, SimpleSelect, SegmentedControl, CrewEditorNextRail, Tablist, Table, DropdownMenuSubTrigger, Item today), each with its own rendered forwarding test, whose afterEach fails on any data-ui-location in the document not registered under that same id (unregisteredMarkers, src/test/guideTargets.ts). NavItem (shell/nav/navRow.tsx) takes a fixed prop list and forwards only its typed data-ui-location prop (the one uiLocation() produces) to the row, pinned by src/test/App.navItemUiLocation.test.tsx; SimpleSelect likewise forwards only that prop, to its Radix trigger or (on touch) its native <select>. A component that draws one control per entry of a data array is the one place a marker goes inside an object instead: a SegmentedControl segment (or a CrewEditorNextRail / Tablist tab, through their segments prop) is marked by spreading the marker into that entry, { key, label, ...uiLocation('<id>') }, directly inside the array passed as segments (the generator's SEGMENT_HOSTS; anywhere else the spread is refused). The entry's label is the location's label, so label must be text (the default), and the component puts the attribute on that segment's radio. A site that renders such rows through a shared .map (the side panel's "+" menu) gives the one row it registers its own JSX branch, since a marker on the shared row would mark every row under a label read from data.
  2. Add one entry to your area's file, src/uiLocations/areas/<area>.ts (its LOCATIONS table; apps, artifacts, capabilities, chat, composer, members, notifications, schedule, sessions, settings, shell today): kind, placements (surface, the parent location id, entry, optional route, parentPlacement and requires), optional aliasKeys, optional terms (newcomer words per shipped locale), optional opt-in guide, and label only when the label is not the element's own text ({ from: 'attr', attr: 'aria-label' }, a forwarded label prop), the site can render several keys (key picks one), or the label is runtime data (below). Types are in src/uiLocations/types.ts.

A control whose visible label is runtime data (the composer's model chip shows the session's model name; the memory chip's text changes with the mode) uses label: { from: 'description', key: 'uiLocations.description.<name>', attr? }. The generator accepts it only where the site's text (or attr) really is dynamic, refuses it where a static label exists, and requires the key in every shipped locale (npm run i18n:pseudo regenerates en-XA; add a translator note in en.context.json). The uiLocations.description. namespace belongs to find_ui alone: no on-screen label or alias may use it, and nothing is ever rendered from it. The index marks the location label_kind: "description", and find_ui returns description instead of label, so the agent describes the control rather than quoting it. A description location is a leaf: it cannot be a parent or a shown_by step, because those must be quotable.

Only if the location needs a condition or reveal state that conditions.ts lacks, add that one entry there too (it is the single prerequisite vocabulary). A new area is a new file in areas/ plus one line in UI_LOCATION_AREAS (descriptors.ts). The generator refuses an id two areas declare, an area file the aggregator does not list and a listed area with no file, so areas can be filled in parallel without touching a shared table. A redirecting extra page is one LEGACY_PAGE_CANONICAL entry.

entry says how the person reaches the control from its parent: rail, tab, sidebar, menu, toolbar, header, content (the page body itself, such as an empty state) or direct-link. A control drawn in several states of one page is one id per site, each qualified by the condition that draws it (Schedule's schedule.create-first with no_schedules, schedule.add-job with has_schedules). App-shell chrome drawn over every page (the top bar, the phone menu) uses surface: 'shell' with no route; the index emits surface_id: "shell" and route: "", and find_ui returns on_every_page: true instead of a route and keeps it under any surface filter. A shell placement may name a parent only when that parent is itself a registered shell location (the phone menu's Search row, shell.menu-search, under the menu button shell.mobile-menu); it inherits that placement's path and requirements exactly as a page child does, and parentPlacement picks among several. A page location never hangs under shell chrome, nor shell chrome under a page.

Pages, tabs and settings get search terms from SEARCH_TERMS in descriptors.ts, keyed by the generated id (page.schedule, settings.tab.secrets, setting:display.mode). Add a term when a newcomer's wording shares no phrase with the label, and a locale only where its wording differs from English. The generator refuses an unknown id, a registered id in SEARCH_TERMS (its terms belong in the descriptor), an unknown locale, an empty list, a blank, repeated or over-60-character term, more than 16 terms per locale, and a term that only repeats a label already searched in that locale.

Then run npm run gen:ui and commit the regenerated index. The label is read from the site, never written in the descriptor: visible text minus nested controls (a button or role="button" inside is skipped), or the named attribute; a translate call, a resolvable const/as const map (the scripts/lib/i18n-key-resolve.mjs resolver the key gate uses), or a literal. A translate call is proven by the callee's own lexical binding, not its name: i18nT (or an alias) imported from i18n/t, t (or an alias) imported from i18next or destructured from useTranslation(), or i18next.t/i18n.t on an imported object. A parameter or local that shadows the name (.map(t => t(...))) and an unbound name are refused as dynamic. The key gate keeps its own, file-level check. The generator refuses, naming file and line: an id with no descriptor, a descriptor with no site, an id marked twice, a non-literal id, a marker not spread onto an element, a dynamic or interpolated label, several labels without label.key, an unknown parent, surface, requirement, condition or reveal state, a parent cycle, a parent with several different compatible placements and no parentPlacement, an empty route or one not in the route table (or only a redirect), a guide binding the guide registry refuses, a reserved prefix (page., tab., settings., setting:), and a preview flag without an enabler. Pick the next targets from the --report candidates.

Several area batches can work at once. Each batch edits only its own render-site markers and its own areas/<area>.ts. conditions.ts has a single owner: the conditions and reveal states the batches need are declared there before they start, so no batch edits it. A batch validates its work without touching the committed index:

npm run gen:ui -- --out "$KIROCREW_SCRATCH/ui-index.<area>.json"
UI_INDEX_FILE="$KIROCREW_SCRATCH/ui-index.<area>.json" npx vitest run src/uiLocations/uiIndex.test.ts
KIROCREW_UI_INDEX="$KIROCREW_SCRATCH/ui-index.<area>.json" pytest test/test_find_ui.py

--out runs every check and writes the index only to the named file; it refuses the committed path and --check. The two variables are test seams that point the goldens at that file; the find_ui tool itself never reads a path from anywhere. A batch's own goldens go in new files, src/uiLocations/<area>.locations.test.ts and test/test_find_ui_<area>.py (never in areas/, where every .ts file is an area). They read the committed index only, so every area's goldens are checked against the one index that ships: the committed index is regenerated once, after the last batch lands, followed by npm run gen:ui -- --check and every area's goldens together.

What belongs in kirocrew-core, and what does not

kirocrew-core is the surface EVERY session carries. kiro-cli reads tools/list once per session, so a tool listed there spends context in every request of every session for as long as the session lives — whether or not that session will ever use it. With agent.tool_search on (the default), kiro defers MCP specs once they cross agent.tool_search_min_pct or agent.tool_search_min_tokens, and Crew's own servers defer like any other when the spawn runs the pinned kiro-cli install or its kiro-cli-chat, and both are >= 2.27.0. Both the spawned path and the pin are first passed through the edition's agent_executable resolver, the one the OS sandbox applies to argv[0], so a managed launcher is judged by the install it runs. For any other executable (a pod bundle, a kiro-cli found on PATH), below that floor, or when the version is unknown, Crew keeps its servers resident to avoid the thinking-signature "tools list differs" rejection that bricks a session. KAS ignores the toggle and the thresholds and defers every MCP tool not on its toolSearch.neverDefer list, so for an agent whose tools grants no tool_search Crew sends that list with each of the agent's MCP tools as <server>::<tool>, expanding @server grants from the tool names it already holds; a server it holds none for stays deferred. A deferred tool costs a name plus a description rather than a full JSON schema; it is smaller, not zero, and it scales with the tool count. An operator's ASBX_KIRO_MANDATORY_MCPS value (comma-separated server names) in the gateway's environment always wins, including an explicit empty value; per-session overlays cannot change it.

That makes the placement question a real one rather than a matter of taste:

  • Core is for capabilities a session may need without being asked — subagents, messaging, memory, artifacts, session-bound directives.
  • Its own server is for a capability an agent is granted on purpose. Give it the kirocrew-dashboard shape: an assignable set, marked opt_in in _MANAGED_MCP_SERVERS so neither spec writer adds it to the default agent. kiro-cli loads a server only when tools names it, so an unassigned set costs a session literally zero — which an always-refusing tool in core cannot achieve, since it still ships its description every turn.

Assignment is the mechanism; a config bool is not. Which agents get a set is decided by their own specs: the entry in mcpServers plus the matching @<server> ref in tools. Only kirocrew.json is rewritten on install, and a refresh keeps an existing grant's command current without ever introducing one, so a hand-granted set survives upgrades and an ungranted one does not come back behind the user's back. Adding a second boolean in config.json on top of that gates nothing an unreferenced server was not already denying.

Granularity: the set, not the tool. A spec that references a server gets every tool in it. So a capability that must be grantable separately belongs in a server of its own, not alongside a set someone might want for other reasons.

A grant is not authority over everything the tools can name. Assignment says which agent may call a set; it does not say what that agent may reach. The dashboard set resolves the calling session strictly — only a gateway-injected per-call caller context, an injected session key, or an HMAC-verified host pid counts, never a /proc ancestor walk, which would resolve a subagent to its parent slot — and then bounds itself by what that caller owns:

Caller Sees May file May reshape the tree
the person's own agent every session any session yes
an app agent only its own app's sessions only its own app's sessions no
a delegated caller whose slot cannot be located nothing nothing no
a dashboard: caller whose named slot is absent nothing nothing no
unverifiable nothing nothing no

A delegated caller gets its own row because absence of a slot means different things for different callers. A Slack thread or a channel session has no dashboard slot and never had an app to be confined to, so it is unscoped. A subagent or a scheduled job also matches no slot, but it runs on behalf of whatever created it — and a cron can be created by an app — so reading absence as "no app" would let an app that may not touch a foreign session gain that reach by spawning a helper or scheduling a job. Delegated callers inherit authority; they never mint it.

A dashboard: caller is refused for a different reason, and it is deliberately not on that delegated list. It is not delegated work — it names a slot. So absence is never the "never had a slot to be confined to" case that makes a Slack thread unscoped; it means the named slot is not there, which happens when the tab was closed while the call was still in flight (slot removal is synchronous and does not drain in-flight MCP calls) or when the key is wrong. An app-owned session going through that race would otherwise hand its agent authority the app itself does not have.

Note this refusal is strictly narrower than inverting the default for every caller: Slack threads, channel sessions and crons do not carry the dashboard: prefix, so it costs them nothing.

The delegated list is knowingly incomplete. It enumerates the delegated key forms that exist today, so a key form added later reads as unscoped until it is added to it. The sound shape is the inverse — grant authority only on positive confirmation that the caller is the person, refusing everything unplaceable — but that also removes these tools from callers who legitimately have no slot and no app, including the person's own crons. Until that inversion is taken, the gap is documented here rather than hidden.

The asymmetry in the last column is not an oversight. Sessions carry an owning app, so "yours" is a decidable question and an app is confined to its own. Folders answer the same question: a folder created by an app carries it in owner_app, and an absent key reads as the person's, so a folder with no such key needs no migration. An app may create at the top level or inside a folder it owns, and may rename, reparent or delete only what it owns; the top level is not a folder row and so has no owner to violate, which is where an app's own tree starts. A reparent is refused when the folder's SUBTREE holds one the caller does not own, because a move takes the subtree with it and would relocate the person's folder under cover of moving the app's. A rename, colour or collapse is not gated that way -- it relocates nothing. The person is never confined by any of this, and an app keeps what it always had: reading the whole tree, and filing its OWN sessions into any folder that exists.

An app cannot delete a folder at all. Not even an empty one it owns. A delete relocates everything the folder contains, and those contents live in a DIFFERENT store from the folder -- sessions are in the slot table and the session archive, neither sharing a lock with it -- so "is this folder empty?" cannot be established atomically with the removal. Successively narrower rules each leaked through another seam: a session filed while the archive scan awaited, a child created while the lock was acquired, a session closing after the scan and writing its folder_id on the way out. Each was closable alone; the class was not, so the verb is withheld from apps. An app organizes its work by creating, renaming and reparenting its own folders and filing its own sessions. The person deletes a full folder exactly as before.

The person's own sessions can delete an EMPTY folder through chat_folder_delete, and only one the calling session created that the person has not touched since. An agent create stamps the creating session's key on the row as created_by_session; a browser write that renames, moves, restyles or hides the folder, files a session into it, opens a chat in it, or nests a folder under it removes the field for good. A person's folder, a reused same-name folder and every older row carry none, so an agent's cleanup can never remove a folder the person relies on. The field lives on the folder row in folders.json, so it survives a restart with the folder. The delete sends ?if_empty=true, which never unfiles a session or lifts a subfolder: the endpoint reads the mark, counts archived sessions, then re-checks the mark, subfolders and live slots in the same locked folder-store step that removes the row. A slot PATCH and a child create both re-check the folder under that lock, so neither can slip between the check and the removal. One seam stays open: a session filed and then closed while the archive scan runs is in neither store at the locked check, so the delete proceeds and that archived transcript keeps the gone folder's id. Every reader already renders such a session as unfiled, which is the same state the person's full delete leaves on every archived session it does not touch, and nothing in the transcript is lost. Closing that seam means registering every in-flight close across all of the slot-removal paths, which this verb does not justify.

The policy lives in the endpoints, not in the MCP server. Only the endpoint holds the store lock and sees the authoritative tree, so a second copy of the rule in the tool layer could only drift or race. What the tool layer still decides is the one question the endpoint cannot: whether the caller can be placed at all, since an unverifiable or delegated caller has no scope to bound a write to.

Position is the one folder write the tool layer has to compose. A folder's place among its siblings is an order int the endpoint stores verbatim and never renumbers, so there is no single value a caller could compute — which is why chat_folder_move takes before/after naming a SIBLING rather than a number. Most placements are still ONE write: when the store already has a free integer slot at that position — ahead of the first sibling, past the last, or in a gap a delete left behind — only the moved row is written, so the reposition cannot land half-applied. Only two neighbours holding adjacent integers, which is what a sidebar drag leaves behind, force the siblings to be renumbered; that renumber is contiguous from 0, the same values computeReorderedFolders writes, so the two paths leave one convention in the store instead of two.

An anchor may stand in for new_parent because an omitted new_parent means the top level: without that, ordering a folder inside a folder would be inexpressible, since every call would drag it out to the root as the price of positioning it.

Composing writes is where an app's confinement needs a rule the endpoint cannot state. The endpoint judges each PATCH on its own, so an app whose placement needs a renumber would have its first write accepted and a later one refused, leaving the person's sidebar in an order nobody chose and nothing to roll it back with. So the tool layer checks the WHOLE renumber against the caller's ownership before the first write and refuses the call intact — the only folder rule this layer decides, and it decides it because atomicity across several endpoint calls is a property only the caller can hold. A one-write placement is not gated: it touches the app's own row only, and the endpoint judges that write as it judges any other.

The renumber path keeps one accepted residue. Several single-row writes cannot be made atomic from here, so a transport failure partway through leaves the destination's siblings carrying a mix of old and new numbers until the call is re-run — a display sequence, reported to the caller, over a field whose duplicates and gaps are already legal and already tie-broken by name. The sidebar's own drag has the same shape today, firing one updateChatFolder per changed folder with no transaction. Closing it for both paths needs a bulk order write that applies under the folder-store lock, which is a change to the store's API rather than to this layer.

A second accepted residue sits on the read side. GET /api/chat/folders returns stored rows verbatim — the store's loader validates id and nothing else — so both readers of that response separately coerce order to a clamped integer and name to a string before comparing. That value-cleaning is duplicated in two languages because it happens in two consumers rather than once in the producer, and normalizing on the way out would delete it from both. Deferred rather than done here: this endpoint is shared by more consumers than the two that sort with it, and the change belongs with the store's API alongside the bulk write above. What such a normalization would NOT remove is the comparison itself — Python orders strings by code point where JavaScript orders by UTF-16 code unit, so the tool encodes utf-16-be to compare as the sidebar does, and no shape of producer output makes one language's comparison operator equal the other's.

Neither side folds case. str.lower() reads the interpreter's Unicode tables and String.prototype.toLowerCase reads the browser's, so a character whose case mapping differs between those two versions folds differently on each side, and neither side owns both tables — the skew is unclosable in this layer rather than merely unlikely.

A-Z folds anyway, through a literal 26-entry table in the tool and +32 arithmetic on the code unit in the sidebar. That range's mapping is fixed in every Unicode version published, so folding it adds no version dependency, and it is worth folding because the name is not always merely a tie-break: a store written before order existed carries no order on any row, so every sibling ties at 0 and the name decides that whole sidebar. Raw code-unit order would render those uppercase-first until the first drag renumbered them.

chat_folder_tree lists folders in that same stored order rather than by path, because it is what an anchor is picked from — an alphabetical listing would show a sequence the person never sees and make every before/after a guess. The comparator is order then name, and both sides read a missing order as 0: folderTree.bySidebarOrder for every surface that draws siblings, and _chat_folder_order for the tool. A folder written before the field existed carries no order at all, so a comparator without that coercion would compare NaN, fall through to its tie-break, and show the agent a different sequence than the person sees.

That stored order is one of three the sidebar can draw. dashboard.folder_sort (config.json, written through the config PATCH allowlist from the sidebar's sort-and-filter menu; read back by the sidebar through its GET /api/config/kirocrew query and by the tool from the same file through the loader — that route is cookie-only, in neither internal-secret allowlist, and admitting it would open the whole config surface to secret-bearing callers to read one enum) selects custom — the stored order above, the default, so nothing changes for a person who never picks a mode — name, an ASCII-case-insensitive natural order in which 01. < 02. < 10. (only A-Z fold), or created, newest first on the created_at epoch stamp every folder creator writes (a row from before the stamp sorts as older than every stamped one). The two view modes are layered on the custom key — a pair they cannot separate keeps its stored order — and choosing a mode rewrites no order, so switching back to custom restores the manual arrangement exactly. folderTree.folderComparator(mode) is the sidebar's comparator and _chat_folder_sort_key(mode) the tool's; the shared fixture test/fixtures/chat_folder_sibling_order.json carries a mode per case so the two are checked against one artifact. Digits are ASCII 0-9 on both sides (never str.isdigit, which reads the interpreter's tables) and a digit run compares by value without ever becoming a number, for the same reason the name compare never folds outside A-Z.

The tool's header line names the active mode (folder order: name). A POSITION is still a stored-order concept: the placement helpers compute a before/after gap in the custom order whatever the mode, so when the mode is not custom the listing says so on its second line and states that an anchor sets the stored position without changing the order shown — otherwise an agent would move A after B, re-read the tree, and see nothing move. When the config read itself fails the tree is still listed, in the stored order, with the header saying the order is assumed rather than known.

Moving the decision to the endpoint makes the write's IDENTITY load-bearing, so the gate returns the key it verified and every folder write sends that key unchanged. The write helpers default to _resolve_session_key, whose /proc ancestor walk can resolve to a different slot than _resolve_session_key_strict did; letting them re-resolve would check one identity and write under another, and for an app-owned session the walk landing on an ancestor makes the write arrive looking like the unconfined person -- which would let an app reach the folders the ownership rule exists to protect. chat_folder_move_session, create and move all send the verified key, including for each intermediate folder a mkdir -p parent path creates.

The same reasoning covers the OTHER way an app's write can arrive unattributable. An empty scope reads as the person, which is correct for a caller that never had a slot -- a Slack thread, a channel session, the person's own cron -- but not for a dashboard: key, which NAMES a slot: absence there means the app it would have been confined to is exactly what got popped, which is what a tab closing mid-call produces. The folder mutations therefore refuse a caller matching caller_names_a_missing_slot, the predicate that exists so a route outside the MCP tool set can apply the rule _caller_app_scope already applies inside it. It stays per-route rather than in the middleware on purpose: a popped slot no longer says whose tab it was, so refusing centrally would also refuse the person's own in-flight calls on every internal route at once.

Tags ride the same server, with the same shape. chat_tag_list reads the vocabulary (GET /api/chat/tags), chat_tag_create adds to it (POST /api/chat/tags, which dedups on the lowered name so a repeat call is a no-op), chat_tag_update renames, recolors or flips the status flag of one (PATCH /api/chat/tags/<id>, metadata only — every session keeps the tag), and chat_tag_assign labels a live session (PUT /api/chat/slots/<slot>/tags). No delete: removing a tag from the vocabulary strips it from every session and column at once, which is the one operation in the set with real blast radius. Two differences from the folder verbs follow from tags having no owner. First, POST and PATCH /api/chat/tags refuse an app-scoped caller outright (403 app_forbidden, which the tools surface): a folder an app makes is the app's own, but a tag lands in the person's one shared list with nothing to tell it apart, so there is no boundary to bound that write to. The rule sits in the endpoint, on the middleware's validated claim, for the same reason the folder policy does — a tool-layer copy could only drift. POST /api/chat/tags also draws on the same per-caller create budget as api_chat_folder_create (create_rate_limit, TAG_CREATE), keyed by the validated X-Internal-Caller component, so a granted agent loop cannot grow tags.json without bound; the browser is exempt. Second, chat_tag_assign takes add / remove DELTAS rather than a list to replace, and sends the slot's tags_revision as base_tags_revision so the endpoint applies the write compare-and-set: a tag the person toggles between the tool's read and its PUT is not silently dropped by a wholesale replace — the call fails 409 stale_base and re-reads. The session is resolved through the same scoped _visible_chat_slots as chat_folder_move_session, and the PUT route applies the same App Kit ownership check api_chat_slot_folder does, so an app agent cannot reach a foreign session's tags from either side. The route also applies the agent tag-grants policy for every non-person caller — the same protected-store authority the chat_tag set_state directive enforces, so chat_tag_assign cannot be a bypass of it: a tag the person reserved (a protected grant row) is refused tag_policy_denied, a workflow-status tag with no protected row is refused status_identity_unprotected on add as well as strip, a replace that would leave two status tags is refused status_tag_requires_set_state, and a degraded store fails closed with tag_grants_unavailable. A rowless ordinary label is not a reservation and is left assignable. The person (browser) is never gated — the whole store constrains agents, not the owner.

Pins follow the same shape. chat_session_pin sets one live session's pinned flag (PATCH /api/chat/slots/<slot>/pin). It resolves the session through the same scoped _visible_chat_slots, verifies the caller strictly, and writes nothing when the session already has the requested state. The endpoint applies the unattributable-caller refusal, the crew-member member_owns_slot fence and the App Kit ownership check that api_chat_slot_folder applies, and the member chat-route gate admits PATCH on that path for the same reason it admits the folder and tag writes.

Board columns follow the tag rules. chat_tag_column_list reads the board (GET /api/chat/tag-columns), chat_tag_column_create appends a column that filters on one existing tag (POST /api/chat/tag-columns with ensure: true, which makes the endpoint return an existing column with the same name, tag and mode under its write lock instead of appending a twin), and chat_tag_column_move places one column before or after another (PUT /api/chat/tag-columns/order with the full id list plus base_ids, the order the tool read; the endpoint refuses 409 stale_base when the board changed in between, so a person's reorder is never overwritten). The board UI sends neither field and keeps its append and last-write-wins behaviour. The board is the person's own layout with no owner, like the vocabulary, so all four column write endpoints apply _refuse_vocabulary_write (apps and crew members get 403 app_forbidden), the create endpoint draws on its own TAG_COLUMN_CREATE budget, and the member chat-route gate admits only GET on the list. There is no delete or retag tool: either would remove a view the person built. The two writes are blocked for channel agents, at the permission prompt and again at dispatch.

Moving a card is a tag write, not a board write. session_move_to_column resolves the session through the scoped _visible_chat_slots, verifies the caller strictly, resolves column with _resolve_chat_tag_column, and posts {column_id, expected_created, base_tags_revision} to POST /api/chat/slots/<slot>/drop, the route the board's drag calls. Because it changes a session's tags and not the layout, it follows the tag-assignment rules rather than the column rules: the route applies the unattributable-caller refusal, the crew-member member_owns_slot fence and the App Kit slot and transcript ownership checks PUT /tags applies, re-checks expected_created and base_tags_revision (409 stale_base, the compare-and-set chat_tag_assign gets) under the tags write lock, and holds every non-person caller (decided by slot_tag_write_principal, the enumeration PUT /tags uses) to agent_slot_tags_refusal over the same prior-to-new diff, so a drop can never be a bypass of PUT /tags. It is then held to the chat_tag set_state rule on the target as well: the column's status must be a row-backed workflow state with add-remove policy (not_a_status_tag, tag_policy_denied otherwise). PUT /tags admits an add-only state, which a drop would turn into a card no agent can move out again. The person's drag is never gated. The route's rejections carry a code: not_status_lane and state_lane read as "Not moved" (calling again changes nothing), while session_gone comes back as an error telling the caller to re-resolve the session. The member chat-route gate admits POST on the path; the tool is withheld from unattended conductors and blocked for channel agents at the prompt and at dispatch.

Assignment is still not authorization. Being unreferenced by default keeps a capability cheap and deliberate; it does not prove the user consented to reach the agent does not otherwise have. For that, config.json is the WRONG home — security.py spells out why, and the keystone leaves (computer_use.json, browser-mode-enabled, the Ops Mission Control mode) exist because each grants something outside Kiro Crew (desktop input synthesis, the operator's logged-in browser, writes against production incident tooling) or is the security floor itself.

The test is blast radius, not wording: ask what the agent gains that it did not already have. Folder tools grant no new read (list_sessions already returns every session's title and key) and cannot delete, so assignment alone is the right ceiling for them. Driving or stopping another session is not, and would need a keystone leaf on top of its own server. Ratchet each set so the next capability cannot arrive inside one whose grant was never meant to cover it.

Per-agent scoping composes on top and needs no new mechanism: an agent spec's own mcpServers map decides which agents see a server at all (agent_discovery_parts/agent_roster.py), so a server can be handed to an orchestrator-class agent without every agent inheriting it.

Adding a managed server is a parity tax — the name must appear in agent._MANAGED_MCP_SERVERS, mcp_discovery._MANAGED_SERVER_SUBCOMMANDS and _MANAGED_SERVER_TOOL_MODULES, mcp_cleanup.KIROCREW_BIN_MCP_SERVERS, onboarding_sources._CORE_MANAGED_MCP_NAMES, and the hidden cli.py subcommand. test_computer_use_registration.py asserts set equality where it can: agent._MANAGED_MCP_SERVERS, mcp_discovery._MANAGED_SERVER_SUBCOMMANDS and mcp_cleanup.KIROCREW_BIN_MCP_SERVERS must be the same set. The other registries are checked per name, so the next server is caught there only once a test names it. The onboarding import's managed names are an intentional superset: they include the predecessor brand's openclaw-* names, so an imported config's foreign copy is not kept as a user-installed server.

The one deliberate exception

kirocrew computer call <tool> has no MCP twin, on purpose. It is not a capability; it is a human debug and repro harness that runs the eleven existing computer_* tools through the same gated chokepoint (optionally a JSON array of them in one process, so element_index values stay resolvable across calls). The MCP-first rule exists so the model gets a structured tool instead of shelling out, and the model already has all eleven. A tool that runs other tools would let a model launder one per-call gate decision into many, so do NOT add computer_call.

MCP tools MUST be stateless

The direct kirocrew-cron server sends member jobs through POST /api/crons/tools using ordinary internal transport and strict session identity. The gateway captures the canonical execution record and applies the same argument validation, cron ownership, governance and deterministic-job checks as its regular dispatcher. A request-local CallerContext is restored even on failure. Transport failure never triggers a local file-write fallback or blind mutation retry; callers inspect cron_list after an uncertain response. The ONE exception is not a transport failure: a dial that was refused (_post returns refused=True — no gateway is listening, so nothing was executed and nothing can be replayed) from a process with NO gateway-injected caller whose resolved session key is POSITIVELY the attended CLI's own (validation.infer_use_case(key) == "cli", the cli_chat key kirocrew chat presents everywhere it is identified) dispatches to the direct host store, which is the behaviour that runtime always had before the transport was required. The absence of an injected caller alone is not enough: the non-pooled stdio gateway topology also has none, and a gateway-minted key (dashboard:, a channel, a cron, a subagent) with a refused dial is the validating gateway being down — an outage to report, never a licence to write around it. A gateway-injected caller likewise proves a gateway exists, so its refused dial is reported as an outage. Global V1 direct runtimes retain their existing local cron dispatch.

A new kirocrew-core or kirocrew-cron tool MUST NOT keep per-caller or per-session state in the MCP-server process. Resolve the caller's identity on every call and keep authoritative state in the gateway.

Why: the shared-backend invariant

The managed servers are long-lived stdio subprocesses, and one server process serves many sessions. In the pooled topology a single warm backend is reused across sessions, and a sub-agent spawned via spawn_run runs inside the parent slot's process tree and talks to the same MCP server. Anything the process remembers is therefore shared by every session and sub-agent that touches it. Three failure modes follow.

1. Identity is not the process, it is the call. KIROCREW_SESSION_KEY and os.getppid() identify the process, which is wrong by construction in a shared backend: the warm pool spawns with an empty key, and a sub-agent inherits its parent's tree. mcp_core.py offers two resolvers (both defined in mcp_core_parts/identity.py):

  • _resolve_session_key_strict for anything that mutates or targets a specific session (post to a slot, change its state, deliver a callback) — reached ONLY through require_strict_session_key(), the shared fail-closed gate every reflexive tool module routes through (REFLEXIVE_TOOL_MODULES enumerates them; a ratchet test rejects direct calls outside mcp_core_parts/identity.py). It accepts only the gateway-injected caller context (mcp_caller.current_caller(), which gatewayd stamps on every forwarded frame after stripping any client-forged kirocrew.caller block), the signed per-session token (session_token_sig.session_key_from_env_token), the injected KIROCREW_SESSION_KEY (accepted EXCEPT on a host pid the signed session-pid mapping records as hosting several sessions, where both _resolve_session_key_strict and the client ladder resolve_own_identity drop it through the same host_pid_is_shared read, an unsigned denies-only read: the var is stamped once per runtime and inherited by every MCP child, so on a multi-session runtime it names one tenant and cannot say which is calling), or a KIROCREW_HOST_PID lookup whose HMAC sidecar verifies against the keystone-protected sel_hmac.key. It deliberately drops the /proc ancestor walk and the bare session_pid_<pid>.txt fallback: the .txt file is agent-writable and therefore forgeable, and a sub-agent walking ancestors from its own MCP child resolves to its parent slot, which would let it mutate the wrong conversation.
  • _resolve_session_key() (lenient, still walks ancestors) is only for read-only and telemetry callers where misattribution is harmless. skill_search is read-only but NOT harmless to misattribute: its gateway route returns the session project's confined skill bodies, so it resolves through the strict gate and degrades to the global-only search when no signed identity exists.

What names a session on the stub path: the stub session token. The injected caller context above is the only identity channel a pooled backend has, and every input gatewayd had for building it answered per RUNTIME, not per session: the stub's own self-report (its KIROCREW_SESSION_KEY or session_pid_<pid>.txt walk), gatewayd's own SO_PEERCRED /proc walk, and claim-push, which re-targeted every connection indexed under a runtime PID. One kiro-cli process hosts N ACP sessions, so all three answered with the parent slot for a spawn_run subagent's stub, and a parent re-claim overwrote whatever a subagent had. So Kiro Crew mints one unguessable token per ACP session (claim.mint_stub_session_token), puts it in the env of that session's injected stub entries (session_servers.attach_stub_session_token), and remembers it on the session handle. The stub returns it on its register frame as a sibling field — never a PoolKey dimension, which would make every session's backend private and turn pooling into a no-op — and claim frames carry it too. gatewayd then keys claims by (pid, token): a claim re-targets the connections carrying its token. Tokenless connections are re-targeted only on a non-shared runtime; on a shared runtime their identity is cleared and subscriptions evicted instead. A claim with NO token re-targets every connection under the PID, which is what a stub launched from a hand-written config or an older overlay still needs.

The token narrows within a runtime; the runtime bounds who may present the token. A claim binds the token together with the PID it named, and a register is answered from that binding only when the same PID is in the chain gatewayd walks from the SO_PEERCRED peer pid — never the stub's self-reported ancestor_pids. That distinction is the whole value of the second factor: the register frame is peer-supplied in full, so an actor who has read another session's token out of /proc/<pid>/environ (readable at the operator's own uid) can equally name that session's runtime in its own chain, and one actor would then satisfy both halves. The peer pid comes from the kernel and the walk is gatewayd's own, so the registrant cannot author it. The self-reported pids stay in the claim INDEX, where they are harmless: a claim only ever narrows to connections carrying its own token or none. A connection whose ancestry the kernel did not attest loses the register-time shortcut, not its identity — claim-push still reaches it through the index. (What a same-uid process can assert on the register frame itself is a separate question — a tokenless register's self-reported session_key is believed.)

Two details keep that binding sound (mcp_gateway/daemon/identity.py). The register path asks for the token's binding exactly once, after its last await and immediately before it indexes the connection, so a claim cannot bind between the answer and the index that lets the claim land. And a binding records the start token of the runtime PID its claim named; register snapshots the start token of every PID it indexes, and resolves the binding only when the two do not definitely differ. A mismatch means the OS recycled the PID for another process. A missing start token never denies.

A token nothing has claimed is refused, not resolved. A binding outranks both process-tree sources at register time, and where no claim has named the token yet the connection stays identity-less — the stub's own self-report and the peer walk are not consulted, and neither is the stub-initiated recaller frame, whose key comes from the same walk. The refusal cannot be made conditional on some sibling session happening to be named: an empty binding table is the state a fresh daemon, a respawn and an evicted binding all share, and in each of those the tree answer would hand a subagent its parent's session. What repairs a deferred identity is the owning session's own claim — pushed before session/new where the owner is known, at rekey() on a pooled claim, and after new_conversation re-launches a worker's stubs.

And re-pushed at the start of every turn, which is what re-binds a token whose daemon restarted under it and bounds that outage to the turn it happened in. Two places do it, because no single one sees every session: the shared identity publisher (messaging/identity.py, the same boundary that rewrites session_pid_<pid>.txt) covers each surface that drives a user turn, and AcpSessionProvider.stream covers the sessions no surface publishes for — which is where a subagent's turns live, the session type the token exists to protect.

A claim carries a session key or gatewayd discards it, so every provider is told which session it serves when it is CONSTRUCTED rather than only at rekey(): that is a warm-pool event, and a cold start (pool miss, pooling off, a subagent's own session) reaches it never. A provider that learned its key there would re-claim with an empty one, which is rejected as malformed before the binding is recorded — so the token could never be re-bound and the session would stay identity-less for the rest of its life rather than for one turn.

The token is a bearer name for a session's identity, so it is never logged, never in stats(), and stripped from the register payload before the prewarm recorder can persist it.

The one place the token is forwarded: Kiro Crew's own pooled control planes. gatewayd spawns a pooled backend from its OWN environment, so the per-session token the stub carries never reaches the backend's os.environ. That is right for a third-party server, which has no business proving a session to anyone. kirocrew-core, kirocrew-cron, kirocrew-guide and the opt-in Crew servers (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-debug, kirocrew-panel) are different: they post back to the gateway over loopback (/api/crons/tools, the memory routes, the session and folder routes) on behalf of the session they act for, and every one of them reads the session's tool policy through mcp_shared, a read the gateway answers only behind the attestation; the gateway requires X-Session-Token on that transport when no kernel peer attestation is present — which a gatewayd child never has. So for exactly gatewayd.CONTROL_PLANE_BACKENDS -- every managed Crew server, read from mcp_cleanup.KIROCREW_BIN_MCP_SERVERS -- the connection handler copies conn.stub_session_token onto the injected CallerContext (session_token), build_caller_meta emits it as sessionToken only when set, and mcp_core._session_token_header reads the gateway-injected caller's token before falling back to KIROCREW_STUB_SESSION_TOKEN. The name alone does not earn the token: the server name arrives in the stub's register frame while the spawn target resolves separately from the spec-derived KIROCREW_MCP_TARGET_<NAME> mapping. That mapping is not the spec's word for a reserved name, though. The rewriter re-derives every stubbed kirocrew-* entry, whether an agent spec declares it or settings/mcp.json injects it, from agent.managed_mcp_spec_entry before it resolves, hashes or bakes anything (rewriter._repair_control_plane_entry), and holds the entry's declared env to the managed-entry ownership rule the disk writer (agent._enforce_managed_mcp_ownership) and the ACP element (session_mcp._managed_element_env) apply -- reserved KIROCREW_* keys, loader channels, home-deriving and launcher-exec keys dropped. Of the spec's other keys the repaired entry keeps only type, timeout, disabled and disabledTools (rewriter._RESERVED_ENTRY_SPEC_KEYS), which can only narrow the grant. autoApprove is dropped, because kiro-cli would honour it ahead of the PreToolUse gate, and so is every other declared key; each drop is named in a gateway WARNING. So a spec that spells the launcher the only way a hand can ("command": "kirocrew", which resolves to the shared Toolbox dispatcher, not the versioned binary) or pins a path an upgrade has since reaped still runs our binary, and a third-party command declared under a reserved name runs our binary too, never its own. The gate below is unchanged; the repair is what makes an honest spec pass it. At spawn, gatewayd._spawns_own_control_plane compares the command actually exec'd (by real path) and its args against the invocation agent.managed_mcp_spec_entry emits for that name and records the verdict as Backend.control_plane; the handler forwards the token on that flag only. The invocation being ours is still not proof of what runs: the managed spec falls back to <python> -m kiro_crew <sub> when no launcher resolves, and the child's CWD could carry foreign code under our name. Python's PYTHON* environment namespace is an extensible interpreter control surface: entries can add roots, execute hooks, select an executable, or move user-site without changing the command, and the dynamic-loader LD_* / DYLD_* namespaces replace code in every binary of the spawn chain. For a control-plane backend, the gateway's pooled-backend resolver removes all three namespaces (env._SPEC_ENV_DENIED_PREFIXES) from the operator environment. Any non-empty entry in them present at the verdict therefore came from a hand-declared overlay or another resolver and denies the token without value inspection. The prefix rule fails closed when Python adds a variable; it cannot drift into a false grant through an incomplete list. Third-party pooled backends never receive the token and keep operator Python settings outside the four keys in sandbox._PYTHON_ENV_PREFIXES; PYTHONUNBUFFERED is one such setting. With those environment controls excluded from a control plane, two roots remain. The first is the fixed local root: the CWD for module form or the launcher's directory for script form. The second is per-user site-packages, which needs no variable to take effect — the interpreter adds it from a default location ahead of the install's own site-packages, so removing PYTHONUSERBASE relocates it rather than disabling it, and PYTHONSAFEPATH does not cover it. It is read from the gateway's own process, which is sound because the spawn is already pinned by realpath to the managed spec's launcher, so the child runs this install's interpreter. Inspecting that directory cannot cover everything it does: its .pth entries execute code at interpreter startup under any filename. So when nothing there is load-bearing -- user-site does not hold the package this process is running -- an accepted control plane is launched with PYTHONNOUSERSITE=1, removing the surface rather than inspecting it. A --user install is the case that keeps user-site enabled, because its own package lives there; an unresolvable user-site is treated the same way, leaving the child's import behaviour unchanged rather than guessing. The verdict is false when either root holds an importable kiro_crew other than this process's package. A --user install therefore keeps its token: its user-site holds the very package this process is running, which matches. Disabling user-site instead would break that install shape outright. A namespace directory without __init__.py does not count, and a dev gateway whose project CWD is its own src/ remains valid. Interpreter flags such as -P, -E, and -I never relax this bearer-token fence: an inert root may cause a safe false-deny, but a Python version change cannot create a false-grant.

The verdict is taken BEFORE spawn_backend forks, under asyncio.to_thread (it imports kiro_crew.agent, reads config and stats those roots), so foreign code cannot erase its shadow before a post-spawn check. An accepted backend is still launched with PYTHONSAFEPATH=1 as defense in depth. After the verdict, and for every pooled backend, the spawn site re-applies Kiro Crew's own UTF-8 pinning (platform_compat._UTF8_PROCESS_ENV: PYTHONUTF8 and PYTHONIOENCODING) to the child environment, so a pooled interpreter builds its stdio from UTF-8 rather than a Windows ANSI codepage. The order is the guarantee: the classifier sees an environment free of every denied namespace, and the pinning lands on a child whose verdict is already fixed -- the same pair present before the verdict would deny every control plane its own token. Backend.control_plane is set from that pre-spawn verdict and never recomputed. The token joins a caller in one place, daemon/control_plane.py::_caller_for_backend, which reads the flag off the backend that receives THAT frame and returns a token-bearing copy; the connection's base CallerContext stays tokenless for its whole life. A transparent respawn is therefore judged on its own: the handler hands the tokenless base to _respawn_backend_for_stub, whose tool-surface probe and subscription replay decide against the replacement, and the frames the session forwards afterwards decide against whatever backend now serves it — so a control plane that died is not a warrant for the fresh process spawned under its name. A denial for a reserved name is logged at spawn (_deny_control_plane) naming the backend and the condition that failed — no spec entry, a different binary, different args, a non-empty PYTHON* / LD_* / DYLD_* variable, or a root that shadows kiro_crew (named in the message, so per-user site-packages is distinguishable from the local one) — so an install that trips the check has more to read than every cron tool answering 403. The same reason rides to the denied backend itself: the spawn site records it as Backend.control_plane_denial, _caller_for_backend copies it onto the frames it forwards to that backend as CallerContext.identity_denial (identityDenial in the caller block, emitted only when set), and the backend's identity_unattested refusal quotes it. Without that channel the only record was logs/mcp-gatewayd.stdout, which no session surfaces, and the refusal's generic text pointed at the token and the spec when the cause was neither.

CONTROL_PLANE_BACKENDS is named in the daemon itself, in mcp_gateway/daemon/control_plane.py (importing acp.session_mcp would put kiro_crew.agent on the daemon's boot path; the set is read from the mcp_cleanup leaf instead). It is a superset of acp.session_mcp.CONTROL_PLANE_SERVERS, not a mirror, because the two answer different questions: CONTROL_PLANE_SERVERS decides which servers every session mounts and which survive a disabledTools entry; CONTROL_PLANE_BACKENDS decides who is handed the token. Containment holds in one direction: a server mounted in every session posts back for that session, so it needs the token. The opt-in Crew servers are the reverse case -- kirocrew-dashboard posts back for the CALLING session (session_create, session_send, the folder and tag tools), so it needs the token, but it is opt_in, so naming it in CONTROL_PLANE_SERVERS would mount it in every session and make an operator's decision to switch its tools off unenforceable. A ratchet test pins that relationship rather than equality with CONTROL_PLANE_SERVERS: it asserts CONTROL_PLANE_SERVERS is contained in CONTROL_PLANE_BACKENDS, pins the token-only extras to exactly mcp_cleanup.OPT_IN_BIN_MCP_SERVERS plus the spec-gated kirocrew-computer and kirocrew-guide (always emitted, but still a spec's to withhold, so not mounted regardless of the spec the way the control plane is), requires every other extra to be a managed server that is not unconditionally mounted (opt_in, or behind a spec_gate), and pins the whole set equal to acp.session_mcp.IDENTITY_BOUND_SERVERS -- the kiro-backend element list that carries the same token per element -- so the two identity paths grant the same servers and a new recipient has to update both in the same commit. Because the opt-in servers are opt_in, _spawns_own_control_plane asks agent.managed_mcp_spec_entry for the invocation with include_opt_in=True, which skips only the opt_in emission disqualifier; a closed spec_gate still yields no invocation, and therefore no token. The stub-strip in backend._strip_caller_meta removes the whole caller block, so a stub cannot forge a sessionToken either. A gateway-injected caller also marks the backend as gateway-hosted: when its dial to the gateway is refused it reports the outage, whereas the attended CLI's own identity (kirocrew chat with no gateway — no injected caller AND a session key infer_use_case classes as cli — whose _post returns refused=True meaning nothing was executed) falls back to the direct host store the cron tools always had before the transport was required; a gateway-minted key with no injected caller is the non-pooled topology and reports the outage instead.

The kiro-backend element list carries one population CONTROL_PLANE_BACKENDS does not: the builtin app servers that run Kiro Crew's own code (session_mcp.builtin_app_identity_launches). A shipped, builtin-owned manifest that declares command: "kirocrew" (Mochi's mochi:mochi) is pinned by bridges._pin_host_cli_command to the gateway's interpreter and serves through mcp_shared, so it reads the same attested tool policy. kiro-cli mounts it straight from the spec, and without its own element every call refuses as identity_unattested for session mcp. kiro_control_plane_servers therefore re-declares a granted one after the managed servers, with the launch re-derived from the manifest by apps.execution.builtin_app_host_cli_mcp_launches and pinned exactly as registration pins it, never read from the spec, and with PYTHONPATH and KIROCREW_HOME set from that pin over anything the spec declares. A user app, a shadowed builtin, or a builtin app that ships its own binary is not Kiro Crew's code and gets no element. gatewayd's set stays the managed servers: a pooled app server is not handed the token. KAS never reaches kiro_control_plane_servers; its hoist tokens the same app servers from the same manifest launch (acp/kas_app_identity.py, see acp-client).

A server that is NOT Kiro Crew's code can opt into a much smaller grant: a session LABEL, never the token (acp/session_label.py). Its mcpServers entry carries "x-kirocrew-session-label": true (an app manifest's entry reaches the spec verbatim, so an app declares it there), and the server receives KIROCREW_SESSION_LABEL set to the session key, which the dashboard already shows in its URL. The name is deliberately not KIROCREW_SESSION_KEY, a rung of mcp_caller.resolve_own_identity, so the label is readable as a name and as nothing else. On kiro the label rides a per-session element built by kiro_session_label_elements and appended by AcpRuntime._session_label_elements AFTER _own_stub_session, because that method stamps the token onto every element it is handed; the element re-declares the entry's own command, args and env, and a declaration it cannot reproduce (anything native_mount_withholding names, an autoApprove, an env value holding ${NAME} or secret://) stays native and unlabelled. On KAS _project_mcp_servers adds the one value to the projected entry after the credential strip and drops the marker from the wire. A session with no key yet (a warm-pool session) and a broker-pooled server get no label: a value baked into a process at start cannot follow a rekey, so absent is the only answer that is never wrong. Publishing the pid mapping earlier would not do it either: on the shared runtime one pid hosts several sessions, and the resolver refuses a mapping with more than one tenant.

register_hook resolves through require_strict_session_key. Member hooks capture their originating execution record before provider allocation; Global hooks retain their existing no-conversation behavior. Hook context and display labels do not retarget that record. Direct and pooled member MCP use the same ordinary transport contract.

Gatewayd validates the accepted stub's ordinary peer ownership and session claim, strips client-supplied caller metadata, and injects the admitted caller for each invocation. Shared backends use a request-local CallerContext, including concurrent tool calls and listings; they never keep a mutable current member on the process or connection. The gateway resolves that session's canonical execution record once for each memory request and forwards the frozen binding to background work.

Member memory requires no additional PID-ancestry proof, HMAC capability or X-Member-Session-Proof header. Direct and pooled MCP follow the same routing contract. Ordinary transport authentication, broker claim validation and signed PID-sidecar identity remain intact. An execution record that declares a member but cannot be resolved fails explicitly instead of becoming a Global V1 call.

An unresolved key is not automatically a refusal. mcp_computer.py forwards a namespace-only key (unresolved:<shim pid>, plus the gateway's per-connection nonce when there is one) and lets the call proceed, because neither strict source exists for a GUI-launched kiro-cli on macOS, so gating on identity would make the feature unusable on its only supported platform. What is lost there is audit attribution, not a control: the trail records a key the prefix marks as unresolved, which is honest, where the lenient walk would have recorded a forgeable one.

2. State belongs in the gateway. The tool should be a thin forwarder: resolve the session, then POST to a gateway HTTP endpoint that owns the state (usually in DashboardState), addressed by session key plus a per-request id, blocking on that round-trip if it needs a result.

3. One stray line costs that line, never the reader. A shared process makes its stdio readers shared too, so a line that is not valid UTF-8, not JSON, not a JSON object, or nested past the decoder's ceiling is dropped and the next line is read. The line-oriented JSON-RPC readers on either side of a stdio MCP server (the stdio loop, the auto-improvement app's server, the gateway's stdout pump and pre-init reader, the stub's and gatewayd's frame readers, the app-call round trip, a script cron's McpToolClient) parse through kiro_crew.json_line.parse_json_object_line, which catches ValueError (that covers an integer literal past the int-string digit limit too) and RecursionError, the case a JSONDecodeError arm misses, and returns None for anything that is not an object. None there never means end of stream. The discovery probe's stdio reader is the one deliberate difference: it counts only lines that are not JSON toward its banner cap, so a server printing a JSON progress counter before it answers is bounded by the probe's timeout like a notification, not mistaken for a flood. The stub's admission wait skips a frame that is JSON but not an object; text that is not JSON, or null, still ends it as closed (the daemon is not speaking the protocol), and the handshake falls back on either.

A dropped line may still be a request someone waits on. Every reader that serves requests (the stdio loop, the auto-improvement app's server, gatewayd's connection reader) answers a dropped REQUEST, one whose head shows a top-level method, that carries a recoverable top-level id with a -32700 parse error under that id, instead of leaving its caller to its own timeout while pings keep the connection looking healthy. A dropped response is never answered: gatewayd's reader also carries kiro-cli's answers to a backend's own requests, under the backend's ids, and an error sent under one would answer whichever kiro-cli request shares the number. The id comes from json_line.recover_line_id(line, requests_only=True), which reads only the first and last 512 bytes (ID_PROBE_BYTES) for the TOP-LEVEL object's id, never one nested in params or result: a writer puts the id first or (the MCP TypeScript SDK) last, and a bounded probe costs the same on a multi-MiB line as on a short one. A number the probe's edge cuts in half is not read as an id, and a line that fits in the probe is read by the head scan alone. An id in the middle of a long line, or a method past the head, is not found, and that line is just dropped.

On the server side mcp_shared._read_message returns SKIP for each dropped frame, which is distinct from None (EOF), so a null line cannot end the server, and returned per frame, so a busy loop goes back to delivering a finished tool's result instead of blocking on the next line. Before the busy loop polls stdin it reads any complete line the buffered reader already holds: select sees only the descriptor, so a ping or a cancel that arrived in the same read as the line before it would otherwise wait for the client's next write. On a stream already read as bare JSON a Content-Length: line is skipped as noise. A declared body over MAX_CONTENT_LENGTH_BYTES (the gateway's default read limit) is drained in bounded reads and answered -32600 under the id its top-level request object carries, found at either end. A header whose length cannot be read (a word, a negative number) ends the stream, logged at ERROR: a client that writes a header writes its body after it, and with no length that body cannot be delimited, so every later frame would be read joined to it and answered as unparseable. A declared length past any drainable size ends the stream the same way, because draining to it would swallow every later request.

Every message is validated once, before the busy/idle split, so it is served or refused the same way under load as at rest. validate_jsonrpc_request reports params that are present and not an object (absent or null read as {}) as a JsonRpcEnvelopeError carrying the request's id: such a request is answered -32602, and a malformed envelope (a non-string method, a jsonrpc other than 2.0) -32600; a notification is never answered. A tools/call without an object params and a non-empty string name is answered -32602 and audited as a refused call (SEL tool_call.invalid_params, outcome rejected, recording the type it got in place of a name), never dispatched and never audited as an invocation of a tool. Any other exception while dispatching one message is logged, an id-bearing request is answered -32603, and the loop goes on; a worker thread that cannot start (the scope's task ceiling) costs that call the same way and leaves nothing behind for the next pass to join.

On the gateway side the start path is the stdout pump: Backend.run_stdout_pump isolates each line's handling, so a raise anywhere in it (budgeting an image, spilling, routing, failing a request) costs that line, logged at WARNING; a raise that ended the pump would fail every co-pooled session with backend-gone in its finally. A line that does not parse is dropped at DEBUG, unless it opens like an object and json_line.recover_line_id finds the id of a pending request at either end of it, which is then failed (WARNING) rather than left to hang. The probe is the bounded one above and runs inline: bounded, it cannot hold the shared pump, and through the GIL the whole event loop, on a multi-MiB line. Only the top-level id counts, so a server logging the call it serves cannot fail that call; an oversize line keeps its first and last 512 bytes for the same probe. A non-string method is dropped. When routing a response raises after it took its pending request, that request still gets an error. Every failed request is settled by Backend._settle, the same code a real response runs, with a synthetic error: queued initialize waiters are answered through _fail_init, an MCP Apps fetch is resolved at once, lease riders and release waiters are answered and the lease bookkeeping cleared, and the forwarding stub gets the error. That error is the gateway's, not the server's verdict, so a resources/subscribe settled this way is an unknown verdict, as a malformed reply is: with nobody routed, the lease is released upstream (as the caller that took it on an identity-capable server) instead of being read as a refusal and left live. A capabilities that is present but not an object is cosmetic, so the handshake reads it as {} (logged) instead of failing the shared backend over it, on both the lazy path and send_initialize. prime_initialize refuses a backend that is no longer alive even when its handshake state reads ready.

Reference implementations

Two shapes are both correct; pick by whether the tool needs a value back inside the same turn.

POST to gateway endpoints that hold the pending future. The blocking ask_question tool (mcp_tools/control.py) with its /api/agent-ask/* routes (dashboard/handlers/ask_question.py) is the model: the pending question lives in DashboardState._agent_asks / _question_futures, keyed by a client-chosen ask_id, and is addressed to the slot of the ATTESTED session making the call — the strict internal transport vouches for the X-Session-Key, never a body field. The open refuses a session with no dashboard tab (404) or no attached client (clients: 0) rather than blocking for the full window on a card nobody will render; the tool then waits in fixed 5s slices (ASK_WAIT_SLICE_SECS) with a keepalive between them and the answer is routed back by ask_id from POST /api/ask-question/{ask_id}/answer. A stateful version, parking the pending question in a module global and trusting env-var identity, would hand the answer to whichever session the shared process last saw and let a sub-agent's card land in its parent's slot.

Return a session directive and let the session-aware consumer apply it. This is what nothing_to_do, monitor_start, monitor_watch, monitor_update, monitor_stop, autonudge_stop, set_project, suggest_followup, reset_conversation and chat_tag do (session_directive.DIRECTIVE_TOOLS). The tool validates its arguments and returns a human-readable confirmation plus a marker line carrying the validated payload and no session key. _on_tool_result (dashboard/chat_turn/tool_results.py) decodes the marker, applies the effect against its own slot.key, then strips the marker from the stored transcript. Sub-agent isolation is therefore structural rather than cryptographic: a sub-agent's tool result flows through the sub-agent's own runner, so it can only bind to the sub-agent's session. There is no walk to get wrong.

A second, provider-neutral channel covers a backend that emits no _meta.kiro identity. After encoding, the tool reports the CALL (tool name and raw arguments, never the payload) to POST /api/session-directive; the gateway re-runs the tool on those arguments (mcp_core.derive_directive) and parks the record in dashboard/directive_queue.py, keyed by the digest of the raw call input. The runner applies it only when directive_queue.claim finds a record whose digest equals the one the turn's own tool_call frame carried, parked during that turn; on such a backend the marker in the result text is display only. Records are in memory, expire after MAX_AGE_SECS (300 s), and are capped per session (MAX_PER_SESSION) and in total (MAX_SESSIONS). The messaging TurnDriver applies directives from the verified marker alone.

Terminal directives carry a structured turn-end signal. One directive is the turn's intended LAST act — a recorded nothing_to_do quiet end (session_directive_apply.TERMINAL_DIRECTIVES); ask_question is not a directive, because it blocks and returns the answers as its own result. The applier returns a DirectiveOutcome(text, ends_turn=True) through apply_session_directive_outcome, and only on the path where the effect landed (a quiet step recorded): a refusal or an error text leaves ends_turn False. Both consumers read that flag — the dashboard runner skips its empty-response ladder, the channel driver owes no empty-turn notice — and neither derives it from the outcome prose (the prose match the first fix used was the thing #9324 asked to replace). The string-returning apply_session_directive remains for callers that need the text alone. nothing_to_do exists for the turn-end contract the base prompt states: after its tool calls a turn ends with a closing text or with nothing_to_do, never by stopping bare after an ordinary tool — a bare stop keeps the recovery ladder, which is what makes the directive the only sanctioned silent exit. Its ONE gate is who opened the turn: it applies on a monitor wake (producer_is_self_wake) or a headless producer (cron, crew runtime, app or task-runner injection), and is REFUSED (QUIET_END_REFUSED_USER_TURN, ends_turn False) on a turn a person opened — a user-facing dashboard turn or any channel turn, since the channel driver cannot yet tell a human's message from a loop's wake. The refusal is what keeps a model misfire a visible failure: the ladder, the Resume control and the channel notice run exactly as before. No slot or surface gate otherwise (it mutates nothing a wrong identity could misdirect); isolation from a sub-agent is the same structural isolation every directive has. The runner stamps meta.ends_turn = True on the applied directive's tool row (persisted, and patched live over chat_message_update), which is the structured fact the interrupted-turn scan reads.

The directive marker is model-visible, since it comes back as tool-result text, so the consumer defends against forgery by honoring a directive only when the tool call it arrived under was recorded, from kiro-cli's out-of-band _meta channel, as an MCP-served call whose canonical name (_meta.kiro.toolName, with _meta.kiro.mcpServerName equal to kirocrew-core) is in DIRECTIVE_TOOLS. The LLM-authored title is explicitly not accepted, because a shell command titled monitor_start whose stdout forges the marker must not be honored. The gate fails closed when _meta identity is absent, and refuses native-sub-agent tool calls, which surface as flat events in the parent's loop but have no independently bindable slot. The marker is ASCII-only: an earlier invisible-separator prefix was destroyed by validation.build_tool_response, which strips Unicode category Cf from every tool response, so every directive silently failed. A machine-facing framing token must not depend on characters that sanitizers and normalizers legitimately rewrite. encode() refuses above MAX_DIRECTIVE_CHARS (3800), under the ACP tool-result truncation bound, so an oversized payload fails loudly instead of losing its trailing marker. The bound covers the whole result: the confirmation text, the marker and the JSON payload, where a non-ASCII character is escaped to six characters or more. So the refusal names the largest argument (a field inside the request when the tool wraps it, as monitor_update wraps its fields in patch) and the least number of characters to cut from the end of it, counted at each character's encoded size. A monitor_start cut that changes the subject the loop infers from its message also changes the confirmation, so it can need a few more. monitor_start and monitor_update advertise a message budget of about 1,500 characters (_MONITOR_MESSAGE_BUDGET_CHARS in mcp_tools/control_parts/schemas.py) rather than their 8000-character entry bound. test/test_directive_tool_size_limits.py fails when a message of the advertised size stops fitting.

A tail-anchored marker must survive delivery, and a rejection must not be able to carry one. validate_tool_args reports an unknown field by echoing the argument NAME, which the model chooses, so that name is the injection point for both problems. A name carrying the sentinel plus a JSON payload plus a newline would make the REJECTION string decode as a genuine directive under the real tool's authenticated identity, applying the arguments validation had just refused; the vouch gate below is what stops that. A very long name would make the transport cut remove the result's refusal tag, so the decline would read as a lost marker: tag_refusal elides the middle of an over-long text against MAX_TOOL_RESULT_CHARS, the single constant acp/_dispatch_parts/tool_result_events.py slices on. That bound alone is necessary but not sufficient, because the cut runs AFTER redaction and redaction GROWS text (a credential becomes a longer placeholder, measured 7,999 chars in and 8,755 out), so preserve_tail_marker re-attaches a marker the cut removed — the same re-injection the MCP App render marker already gets at that seam, for the same reason: a control token that decides how a frame is interpreted must not be a casualty of a length cut applied to the frame's prose.

A marker is honoured at that gate ONLY if the emitter vouched for it on the same dispatch: _emit_directive is the one producer of a real marker, so it records a digest of what it built, _call_tool clears that record before every dispatch, and refuse_if_markerless defangs any marker nobody vouched for. "Does this look like a directive?" is not a safe question — a rejection echoing a model-chosen argument name can imitate one, and a rejected call would then apply the very arguments validation had refused. Every place mcp_shared builds an "Error: …" result also passes the interpolated text through session_directive.neutralize_markers, kept as defense in depth because those strings reach the audit row and the four other servers' outputs, where no vouch gate runs. That defanging is applied only where the caller KNOWS the string is not a directive: doing it centrally over every tool result would defang the real marker too.

_emit_directive classifies its OWN output the same way — by the marker's presence, not by content. Testing is_refusal(out) there would match any payload that merely CONTAINED the refusal token, so a stop whose reason quoted that token would be filed as a refusal, skip both the publish and the vouch, and have its genuine marker defanged downstream: the stop would be lost. A gate against imitable content cannot itself be built on imitable content.

An Error: prose result can also be framed as an MCP error

build_tool_response is the single exit point for every tool result. The "Error: …" prefix is what mcp_shared derives the SEL audit outcome from (failed when the text starts with the prefix, completed otherwise), but a prefix alone says nothing in the wire frame, and a client would have to pattern-match prose to tell a refusal from an answer. cron_script.McpToolClient.call_tool raises RuntimeError on result["isError"], so a refused cron write must carry the flag or it reads back as a completed one.

build_tool_response takes a keyword-only is_error, which adds MCP's "isError": True to the frame. The prose is untouched: the flag is computed from the RAW result text before sanitization, so a refusal is byte-identical whether it is flagged or not, and the audit outcome derivation does not move.

The flag is per-server opt-in, not a global. run_mcp_stdio_loop takes error_prefix_is_error, default off, and every tools/call result on that loop — the POSIX worker path, the Windows synchronous path, and the two tool-policy refusals (unresolved policy, excluded tool) — goes through one nested _tool_response helper so a server cannot be half-converted. kirocrew-cron is the only server that sets it. The other servers keep their frames unflagged deliberately: each has in-tree callers and model-facing prompts that read "Error: …" prose on purpose, so flipping them together would change what those callers see.

A server that opts in owes its failure answers the prefix, and the audit half already held it to that: an answer without the prefix is filed completed. The sharp edge is a REFUSED durable write, because its answer sits one line below the committed one: a cron mutation whose store call comes back falsey — the row the ownership gate just saw is gone, a concurrent delete between check and write — frames beside "Removed job: <id>", so an unprefixed answer there reads as a completed delete. All four such returns (cron_update, cron_remove, cron_pause, cron_resume) are "Error: job not found: <id>", which is what AUTOSDE.yaml's a-refusal-is-not-a-commit requires. Naming the row there leaks nothing: the gate has already proved this caller owns it, which is why _not_found's anti-enumeration wording is deliberately NOT reused post-gate.

Cron's "Unknown tool: …" fall-through is the apparent second exception and is not one — _call_tool rejects an unknown name at its argument validation, ahead of that return, with prose that does carry the prefix, so the unreachable string needs no marker.

A directive tool's result either carries the marker, or it is a tagged refusal — nothing in between. The consumer cannot otherwise tell a decline from a marker destroyed in transport: both decode to "no directive", but only the second is a bug, and the diagnostic for the second is a WARNING (session-directive decode FAILED … effect dropped) whose whole purpose is to catch a rawOutput-envelope escaping regression. So every marker-less return is stamped with _REFUSAL_SENTINEL and reported at INFO as session-directive REFUSED: encode() stamps its own oversized-payload refusal, and mcp_core._call_tool stamps the rest via refuse_if_markerless(). That second producer sits at the OUTERMOST return because argument validation runs in the dispatch wrapper ahead of the handler, so a schema rejection never reaches code inside the tool that could tag itself. Tagging is diagnostic only and keys on the tool name alone: the token carries no payload and grants no effect, so it can change how a line is logged and never what is applied. Two consequences for a tool author — a directive tool must RETURN its declines rather than raise them (an exception escapes this return path and reads as a lost marker), and a caller that sees decode FAILED is looking at a transport bug or at a handler that crashed -- the line names both, because a crash also drops the effect and asserting only the transport cause sends an operator hunting a regression that is not there. That first rule is enforced rather than left to convention: a parametrized test drives every name in DIRECTIVE_TOOLS with a hostile call and asserts the result is a marker or a tagged refusal, and its companion asserts the table covers the frozenset, so a new directive tool fails until it is added. The one raising dependency these handlers share, monitoring.targets.normalize_pull_request_target, is reached only through one guarded seam (_parsed_pull_request_target) for the same reason: one guard cannot be missed at a second call site.

FieldSpec.clamp_to_max is the other half of that: an over-long argument must not defeat the request it is only describing. autonudge_stop and monitor_stop both take a reason that selects no behaviour — the applier just interpolates it into the outcome text and the persisted stop record — so their reason is TRUNCATED to the cap instead of rejecting the stop, and the truncated value carries a [... truncated, dropped N chars] note so the cut is visible wherever the value travels. N counts what THAT cut dropped, including the note's own cost — deliberately not the caller's original length, which the clamp cannot know because the field is sanitized before the cap is checked, so one number cannot honestly stand for both removals. Opt-in per field, and never for a field the handler acts on: a truncated control input is a wrong control input, and rejecting is the only safe answer there.

Structured monitoring deliberately splits mutation from inspection. monitor_watch, monitor_update, and monitor_stop are directives: the consumer applies them to its authoritative session, so their payloads contain neither a session key nor a loop id. monitor_inspect needs a result in the same turn and therefore calls the session-bound read route only after require_strict_session_key() resolves, passing that exact key to _get. It projects that response into bounded agent-oriented state (check counts and accepted wake count, plus only a small failed/pending/unknown name sample), omitting wake instructions and browser/persistence internals. Inspection reports unavailable when strict identity is absent; it never falls back to the process-ancestor resolver. Every structured-monitor tool refusal caused by a missing or unsupported session binding returns an Error: result and writes an explicit denied SEL event; the shared MCP wrapper therefore records the call as failed rather than completed. The structured tool exposes no caller-declared evidence scope: requests that need comments or advisory findings route directly to the finite legacy tool whose agent turn can inspect them. Structured creation is admitted only from dashboard, Slack, and Discord sessions, the surfaces with typed wake dispatch and completion correlation. Webex retains finite legacy prompt loops but refuses monitor_watch at both the stateless tool and authoritative consumer boundaries. The legacy monitor_start descriptor routes supported pull-request readiness through monitor_watch, and which of the two it names as the DEFAULT is the installation's choice: with monitoring.prefer_structured_arming off (the shipped position) the structured path is offered only when typed provider facts fully determine the objective, and with it on the structured path is the default and the legacy loop is the exception. Neither position refuses either tool. Objectives that require interpreting comments or advisory review evidence keep a finite legacy loop in both positions instead of claiming the structured probe observes those facts.

monitor_watch.kind is the closed set github_pull_request, gitlab_merge_request, azure_devops_pull_request, and bitbucket_pull_request, all with the review_ready objective. Its target is a canonical provider URL and is parsed against that kind before a directive is emitted. A later target-only update is revalidated against the retained kind by the authoritative session consumer.

The one allowed exception: caller-agnostic process caches

A module-level cache is fine when it is keyed on an external signature and is identical for every caller. mcp_core._KNOWLEDGE_CACHE is keyed on the knowledge-DB and config file signature and is shared safely across calls. Never key a cache, or any retained object, on caller identity, session, or "the last request I saw".

A tool that only waits returns a DeferredTool

The stdio dispatch loop (mcp_shared.run_mcp_stdio_loop) runs one worker thread per server: the part of a call that computes runs there, one call at a time, while the loop keeps reading stdin to answer ping, honour notifications/cancelled and queue the next tools/call. A handler that spent its whole duration waiting on that worker -- wait sleeping up to 1800s, spawn_sub_agents polling for up to 7200s, ask_question long-polling until a person answers -- parked the worker and every other caller's call behind it. On the pooled kirocrew-core backend that is every dashboard session at once: one session's wait stalled everyone's memory_recall for minutes, and because the loop still answered pings the gateway's wedge detector saw a healthy backend and never recycled it (the 3-hour hard ceiling was the only exit). A worker pool would only move the threshold, from one parked call to N.

So a handler that only has to wait does not hold the worker. It does its setup on the worker (validate, resolve identity or open the card) and returns a mcp_shared.DeferredTool instead of a string. spawn_sub_agents and spawn_run step submission too: each step posts one /api/spawn member with the request timeout; spawn_run returns its usual receipt after the last member is handled, and the children's blocking wait budget for spawn_sub_agents starts after submission finishes. A parked batch holds at most validation.SPAWN_BATCH_MEMBERS_MAX members (one name for spawn_run.tasks, spawn_run.agents and spawn_sub_agents.agents), refused by the schema before any deferred state is built, because the step retains the member list until submission finishes; each step is one bounded POST, _SubAgentsStep drops its member list once every member is submitted, and a spawn_run that is cancelled or abandoned mid-submission reports each unsubmitted task lost to its wave (_close_unsubmitted, one bounded attempt from the loop's thread) so the wave digest closes without the stuck-wave sweep. The loop registers it and, from its own 100 ms tick, runs the deferred's short step() whenever its due_at() has passed; the call is answered by the step that returns text. A step is one loopback round-trip (a keepalive POST, one poll pass, one wait slice), never a sleep, and runs with the call's caller identity installed as the worker had it. An ask step's wait slice is the server's fixed validation.ASK_WAIT_SLICE_SECS (5s; the wait route reads no body, so a caller cannot choose it): a step holds a pool thread for one slice, so the admitted-card queue budget ceil(DEFERRED_PARKED_MAX / DEFERRED_STEP_WORKERS) * 5 = 40s stays below the dashboard's 120s answer-retention grace, while an idle card costs one request every 5s rather than every 2s. Steps run on a small shared pool (DEFERRED_STEP_WORKERS), not the dispatch thread, so a step blocked on a stalled gateway delays other steps and nothing else. notifications/cancelled for a parked call drops it with no response and runs its cancel() hook (the countdown card is retired, the question card withdrawn); a cancel that lands mid-step discards that step's result. Cancel hooks run with the call's caller identity and tenant nonce installed, and the parked table is bounded by DEFERRED_PARKED_MAX; overflow is cancelled, SEL-audited as failed, and answered with a retryable -32000 busy error. The SEL completed/failed row call_tool_with_logging writes for a blocking tool at return is written for a deferred one by the DRIVER, through DeferredTool.on_settled, after the dispatch thread has ruled out a cancel -- never inside the settling step(), which runs on a pool thread and could otherwise write completed beside the cancelled row a concurrent cancel produces. Settlement installs the call's caller identity and tenant nonce. Once the answer is written the driver runs DeferredTool.on_answered(written), with the same identity installed: written is True only when respond() reports the whole frame written to the client's own pipe, and never for a pooled backend, whose frame lands in the broker. spawn_sub_agents marks the children its reply carries collected only there, on True -- never in its collect step, in on_settled, or for an abandonment reply. For every parent that is not dashboard-born that mark is held only under the attempt that spawned the child, the token (key, task, epoch) opened at the parent tool's spawn, done read or landing note and ended by settle_turn or release, and only an attempt that landed confirms it (kiro_crew.parent_turns). The spawn names the attempt that held the parent's session, with its prompt in flight, when its request arrived, and every member of one call names its first member's attempt (call_id). A done read under any other attempt, or after the spawning attempt ended, holds nothing, so the completion takes normal delivery: a duplicate at worst, and a loss only in the two windows the sub-agent spec's Residual names. A directive tool's refuse_if_markerless tag is applied to the settling text the same way, so neither path can tell the two shapes apart. The pool is mcp_shared._StepPool, not ThreadPoolExecutor: its threads are created up front, so submit only enqueues and cannot fail after queueing (ThreadPoolExecutor starts threads lazily inside submit, after the item is queued, and a start that fails there leaves an orphan an idle worker runs later -- for a deferred step, a call just answered with an error consuming an answer or a collect). The one place a thread start can fail is the pool's construction, where nothing is queued yet: that fails only the call that needed it, as a worker that cannot start does, and the pool is tried again on the next tick. A step queued for a thread longer than DEFERRED_STEP_STUCK_SECS is left out of the report like a step holding one that long: every worker is stuck, so the gateway must be allowed to see it. On a pruned-install exit, a step in flight is let finish (bounded by DEFERRED_STEP_STUCK_SECS) and its outcome delivered before the remaining parked calls get the retryable error (one the client already cancelled gets no response, only its cancel() hook and a cancelled row), because a step can consume a card's answer or build child results the accepted-result commit then marks collected; a step still queued at that point (every worker stuck) has its future cancelled first, so no worker runs it for a caller already told to retry; a cancel that LOSES to a worker claiming the step means the step is running, and it is then waited for and delivered like the others. A parked call whose unrepeatable work happened BEFORE it parked says so through DeferredTool.abandon(), which the loop consults at every moment it answers a call it will never step again -- the parked table is full (DEFERRED_PARKED_MAX), the step pool cannot start, or the pruned exit: spawn_sub_agents and spawn_run return final text naming the children it already spawned (still running, not to be spawned again), plus the count of members not submitted yet (only those may be resubmitted), instead of the retry error or failure, settled through on_settled like any other answer; with no child accepted yet and no transport error indicating unknown acceptance it returns None, since the whole call may be retried. spawn_run preserves its unknown-acceptance warning even without confirmed IDs and reports only the unsubmitted members as safe to resubmit. A hook that returns None (the default) or raises keeps that moment's own refusal. However the loop ends -- EOF, the pruned exit, an exception that escaped -- its finally cancels every still-queued future before the pool's shutdown sentinels queue behind them. Servicing one parked call and sending the report are each guarded like one message on the read loop: a failure answers that call (or costs one report) and the loop keeps serving. _call_tool (what a test, the CLI or a non-loop caller invokes) drives a deferred to completion inline with drive_deferred: from outside the loop a deferred tool is a blocking one. The loop itself is the same on every platform. Windows select.select cannot poll stdin, so there _start_stdin_pump reads frames on a daemon thread into a queue the loop waits on with the same short timeout; the worker, the parked-call timer, cancels and ping answers do not depend on how a frame was read.

The in-flight report. A backend whose long calls are all deferred can prove they are healthy. When the client's initialize declared mcp_caller.INFLIGHT_CAPABILITY_KEY under capabilities.experimental, the loop sends mcp_caller.INFLIGHT_NOTIFICATION every INFLIGHT_REPORT_SECS (30s) while any call is parked or queued, naming the parked request ids that are not stuck inside a step (DEFERRED_STEP_STUCK_SECS) and the ids still waiting in the loop's FIFO behind the worker: time spent queued is the queue's, so five slow synchronous calls back to back do not age the last one past the ceiling. The call RUNNING on the worker is never named, so its stamp freezes at about its start and the ceiling bounds how long one call runs. The report is opt-in per server (run_mcp_stdio_loop(..., reports_inflight=True)), and only kirocrew-core opts in: it is the one server that parks DeferredTool calls, while a server whose every tool is synchronous gains nothing from the report and would only have its recycle ceiling lowered under its running call. A server that did not opt in neither advertises the key nor sends the frame, even to a client that declared it. An opted-in loop advertises the key in its initialize result on every platform. The gateway asks for the report on every initialize it forwards (_inject_inflight_capability, beside the MCP Apps extension injection) and in its own prewarm send_initialize; Backend._apply_inflight_report consumes the frame off the backend's stdout (it names gateway forward ids, so it is never routed to a stub and never recorded as an unattributable notification) and stamps _PendingRequest.t_progress_ms. The wedge detector in Backend._heartbeat_once then ages each request from its last report rather than its start, so a parked wait is old but never slow, and a backend that advertised the report is held to PROGRESS_WEDGE_CEILING_SECS (900s) instead of HARD_WEDGE_CEILING_SECS (SUBAGENT_TIMEOUT_SECS + 300, about 3 hours): an age that old on a reporting backend is a worker call that stopped progressing, and no shipped synchronous tool runs that long on purpose (the longest, pod_up, bounds itself at 210s). A backend that never advertised -- an older install, the Windows loop -- keeps the long ceiling, because it cannot tell a parked call from a hung one, and so does every server other than kirocrew-core. A forwarded notifications/cancelled marks the pending entry cancelled (_PendingRequest.cancelled). The backend answers a cancelled call with no response, so the entry ages forever: the hard ceiling skips it, while the two-condition rule still counts it, so a backend whose pings have also stopped is recycled as on main. Notification attribution and the last-stub recycle (has_recyclable_in_flight) still see the entry, so a late progress frame or log for it routes or drops exactly as for any pending request, and the last stub leaving after a cancel still recycles a backend whose synchronous tool kept running. A subscribe or unsubscribe is not marked, because its verdict settles the shared lease tables: its cancel is not forwarded at all, so the server answers it and the verdict settles the lease under the stub that sent it, as on main when a server answers a request it was asked to cancel. The client side is gated on the declaration because a direct kiro-cli or an older gateway never asked, and would at best drop the frame as unattributable.

On an identity-capable server, the upstream release of a caller's subscription to a URI is held while another stub of that caller is routed for the URI, or while a same-caller subscribe for it is in flight (Backend._hold_identity_release), whether or not anything was cancelled. The unsubscribing stub is answered locally, and with no such stub routed the first same-caller subscribe in flight inherits the release (_PendingRequest.release_owed). A grant that routes a stub discharges it, because the caller's one upstream subscription now serves that stub, whose own departure releases it. A refusal, an unknown verdict or a grant that routes no stub has the gateway send it as that caller, unless the rule still holds. When the unsubscribing stub was the last one routed for the URI, the URI is orphan-marked while the release waits, as detach does, so an update the server sends for the still-live subscription is dropped without a hazard.

Checklist for a new tool

  • No module global holds per-call or per-session data.
  • Identity never comes from a bare env read. Anything mutating or targeting a session resolves it through mcp_core.require_strict_session_key(), and the module is listed in mcp_core.REFLEXIVE_TOOL_MODULES (test_identity_topology.py enforces both). Read-only paths may use the lenient _resolve_session_key().
  • A tool on kirocrew-core, kirocrew-cron or kirocrew-dashboard declares its display title in src/kiro_crew/data/mcp_tool_titles.json. The server serves it as the MCP Tool.title, and the dashboard and channel task labels read the same file for the tool-call row's title. test_mcp_tool_titles.py fails when a listed tool and the table disagree.
  • Durable state lives behind a gateway endpoint keyed by session.
  • The tool behaves identically whether it is the only caller or one of many sharing the backend.
  • A tool that waits -- for a clock, for another process, for a person -- returns a mcp_shared.DeferredTool from its handler and does the waiting in short step()s. A synchronous handler bounds every call it makes well under PROGRESS_WEDGE_CEILING_SECS, or the pooled backend is recycled under it.
  • A clear never depends on an empty list or object arriving. Kiro CLI rebuilds a call's arguments and drops every container that holds no scalar, plus a top-level null, so tags: [] reaches the server as an omitted tags. Give each clear a spelling that arrives unchanged, a boolean or a list of at least one name, keep the empty spelling working beside it, and say which to use in the description: cron_update clear_skip_dates: true, cron_secret_request withdraw: true, monitor_update judge: {"wake_when": "", "quiet_when": ""}, propose_change clear: true (folder.steering) and clear: [<field>] (template.update), artifact_update clear_tags: true, issue_radar_crew_record clear: ["labels_applied"].

Troubleshooting

MCP tools not working. Check that ~/.kiro/agents/kirocrew.json contains kirocrew-core and kirocrew-cron, that includeMcpJson is false, then run kirocrew doctor (which checks probe status) and read the live probe results in the dashboard MCP panel.

Status stays "Unknown". The handler auto-triggers a probe for a server it has no cache entry for, but the result only appears on the next refresh. If it stays Unknown, the server is failing its handshake: read the dashboard error text or the gateway log.

Tools present in Kiro Crew but absent in interactive kiro-cli. That is correct. kirocrew-core / kirocrew-cron / kirocrew-computer are agent-scoped and must not appear in interactive kiro-cli or Kiro IDE sessions. If they do, something wrote them into a provider global.

A newly added server does not appear in sessions. On kiro-cli 2.21.0+ the running sessions reconcile the agent file themselves and the dashboard skips its reset (see "Live reconcile" above); a server that stays absent there means the entry never reached ~/.kiro/agents/kirocrew.json — check kirocrew doctor — or the watcher failed at runtime, which the skip cannot see: POST /api/sessions/restart is the recovery. On an older kiro-cli, or another harness, the warm pool holds pre-spawned processes carrying the old config. Use Apply & Restart or POST /api/sessions/restart. kirocrew config set restarts nothing: a config write only changes the defaults new sessions adopt, and MCP servers are not config.json keys.

-32602 Invalid request parameters with empty data, only under the gateway. That frame is the Python MCP SDK refusing a request on a session that never got initialize + notifications/initialized; the arguments were not lost. It happens when a pooling multiplexer behind the pipe (the configured command is its thin client) respawns the real server cold while its own connection stays up: the gateway sent initialize once for that backend and answers every later stub from its cache, so nothing re-handshakes the new process. A standalone kiro-cli run works because it is a fresh connection with a fresh handshake. The backend recovers by itself (Backend._retry_after_rehandshake): on that exact frame, for a method in _REHANDSHAKE_RETRY_METHODS, it re-sends the cached initialize and initialized and the request, in one write, once. The gateway log line refused ... as not initialized; its MCP session was lost behind the pipe marks each recovery.

Finding a failing tool call. Every failed tools/call through the gateway logs one WARNING to the gateway log, mcp tool call failed: server=<s> tool=<t> session=<k> error=<text>. Both failure shapes count: a JSON-RPC error reply and a result carrying isError: true, where the tool ran and reported its own failure. The same call scores ok: false in the call metrics (MCP_GATEWAY_CALL_METRICS_PATH).

Workflow execution identity

Workflow writes resolve the current strict MCP session and pass that same key to HTTP. This includes authoring, saved-definition runs, ad-hoc source and intent runs, cancellation and subtree reruns. Missing strict identity refuses the write before HTTP; a lenient ancestor-session fallback cannot authorize it. Ordinary transport authentication identifies the caller; the captured execution record selects its member and retention mode. Workflow IDs and template names do not retarget memory. Run/detail/list/cancel/rerun preserve the original run's member while applying ordinary execution permissions. Direct and pooled MCP use the same rule. The deterministic workflow E2E model executes these real MCP transports through sandboxed_spawn_argv and popen_limited, which applies resource limits after exec rather than running Python in a fork child. Temporary launcher profiles are cleaned up even when spawning fails; synthetic tool events are not memory-access evidence.

Compact skill discovery descriptions

Crew-owned skill_search, skill_discover and skill_fetch descriptions keep local versus public-registry scope, read-only semantics, result limits, explicit load instructions and the untrusted-content/sibling-file caveat. Full procedures stay in the skill files rather than in repeated discovery prose. This affects only the descriptors Crew owns; external MCP descriptions, Tool Search thresholds and native serialization are unchanged and outside the measured assembly boundary.

Session-bound skill_search uses the already-admitted route /api/skills/-/discover, delegating to /api/skills' local search branch. Search and list are a GET /api/skills/-/discover?scope=installed&q=...; the exact-key read POSTs a JSON body (scope, q, action, key, capacity, plus offset and limit when the caller pages) to the same path, so a long or escaped key never hits the HTTP request-line limit. No authentication paths or policy controls are expanded. The server resolves only that session's project, applies the catalog's repo-scope filter and identical-content deduplication, and loads confined project bodies through SkillsLoader.load_skill with a shared 24,750-byte read allowance. Those results contain safe names and content, not live project paths. Sessionless CLI search remains global-only. Mixed CJK/English keywords use memory's existing CJK-pair tokenizer. Native tool schemas and Tool Search thresholds are unchanged.

skill_search supports scoped search, paginated list and exact-key read. The gateway resolves scope from the signed session, never a model-supplied agent name. Without signed identity it uses the global installed catalog. Incremental indexing reports incomplete recall explicitly; list/read remain available during refresh. A read delivers at most one response's worth of body; a larger body is refused with its size and read in whole-line pages through the same offset/limit parameters, each page stateless and sized by the gateway to the capacity the tool derives from its own response framing, and a refused read names which of three reasons stopped it (outside the scope, unreadable, over the capacity). See memory, skills and hooks.

Codex session-control delivery

Eligible Codex sessions receive the dashboard server through their verified per-session projection on create and resume; see providers. The managed launcher is reconstructed before identity is attached, and broker claims retain their per-session ownership checks. A global dashboard entry has no verified session identity and cannot grant access by its name alone.