Repository navigation
fix(agent): mount edition MCP servers on the heartbeat agent and approve on trusted identity - #20047
Conversation
Sensitive Change ReviewSensitive files changed:
|
Sensitive change review
|
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
bf2d758 to
c0430e5
Compare
|
Rebased: main moved in src/kiro_crew/llm_helpers.py, src/kiro_crew/session.py, src/kiro_crew/sel.py, docs/system-specs/modules/*.md since this head went green (f5adcd7 -> ab333e6); CI re-running. Also: black --target-version py310 on test/test_readonly_bash_git_exclusion.py (Backend Lint red on bf2d758). |
Sensitive change review
|
Design Review (Opus 5.5) — ✅ human override accepted@bolichen97 overrode this lane for |
First Principles Review (Opus 5.5) — ✅ human override accepted@bolichen97 overrode this lane for |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
c0430e5 to
ca53368
Compare
|
self-added: yes
|
|
Sensitive change review
|
ca53368 to
669e6e4
Compare
Sensitive change review
|
669e6e4 to
c9cf7f2
Compare
|
New head d21b4b4 (base ae9e29e, +7 since c46a1dc, no file this PR touches): round-5 from the Opus finding on eccad68 -- |
Sensitive change review
|
d21b4b4 to
cb63378
Compare
|
|
Rebased: cb63378 is d21b4b4 replayed onto main 370b190 (+1 commit, #17540, which touches |
Sensitive change review
|
cb63378 to
df847c2
Compare
|
|
|
|
New head df847c2 (same base 370b190): round-6 subtraction from the First Principles verdict on cb63378 -- |
Sensitive change review
|
…ove on trusted identity An edition names the default-spec servers the unattended heartbeat agent also mounts through McpToolingProvider.heartbeat_mcp_server_names(); the heartbeat derivation and the spawn-path freshness gate read the same list, and each edition entry is copied verbatim minus autoApprove. _is_heartbeat_safe_tool decides on the event's trusted _meta identity instead of the model-authored title: host built-ins via the hooks allowlist (network egress excluded), core reads qualified to their owning server, read-only shell with every git invocation excluded, and the edition's pinned @server/tool entries. The heartbeat-scoped hooks defer the gate's read-only tier to _heartbeat_approval, which runs the name-grant check on shell and audits the trusted identity. Co-authored-by: Adam Albertson <maiza172@gmail.com>
df847c2 to
305bed4
Compare
|
Rebased: 305bed4 is df847c2 replayed onto main beb3c40 (+4 test-only commits; the one overlap is |
Sensitive change review
|
|
/ai-review override first-principles 305bed4: agent: on @bolichen97's explicit authorization -- heartbeat running text-only on a harness whose adapter publishes no trusted tool identity (claude-agent-acp, opencode) is the accepted shape; the decision, the observable signal (per-call |
|
/ai-review override design 305bed4: agent: on @bolichen97's explicit authorization -- text-only heartbeat on claude-agent-acp / opencode is accepted by the maintainer; the per-call |
Human judgment recorded@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
Human judgment recorded@bolichen97 marked the design AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
HOLD at 305bed4: reserved for human review. This PR changes how the unattended heartbeat agent approves tools. To clear: a maintainer reviews the sensitive files above, and the author answers the current-head Security Scope CONCERNS with a — crew-pr-reviewer (r100) |
mbriones98
left a comment
There was a problem hiding this comment.
Checks green and PR Readiness passed at 305bed4; non-feature change.
Problem / Motivation
Goal: Let an edition's MCP servers reach the unattended heartbeat agent, and make heartbeat approve a tool only on the identity the adapter stamped, never on a name the model wrote.
The heartbeat spec copies one server from the default agent spec:
kirocrew-core, andMcpToolingProviderhas no way to name another. A companion that pins@its-server/ReadToolinheartbeat_safe_tools()allowlists a tool heartbeat cannot call: nothing errors, the server is not mounted, and every heartbeat task that needs it fails quietly. Supersedes fork PR #10158 (unmergeable as a fork: Sensitive Change Review, 1885 commits behind).Two approval paths were weak on the one agent with no human behind it.
_is_heartbeat_safe_toolreadevent.title, which the model writes. The read-only tier still ran for heartbeat, approving on the agent-declared ACPkind, a read-shaped title, or any read-only shell command (gitincluded) before_heartbeat_approvaland its SEL audit saw the call.Why it matters
Heartbeat polls untrusted content (CR comments, ticket bodies) on a timer with nobody watching. An edition that cannot mount its servers there gets no value from heartbeat; one that can must not get a path around the allowlist, where a forged title or
kind="read"on a mutating tool runs unaudited.Not a goal
extra_mcp_servers(), so the default spec's governance applies.McpToolingProvidermethod or aCONTRACT_VERSIONbump: the mount list is read from the pins an edition already returns; a gate that cannot answer degrades tokirocrew-corealone._metaidentity (claude-agent-acp, opencode): those run text-only.What changed (motivation → approach → change)
The heartbeat spec is a pure derivation of the default spec that the spawn gate re-checks on every start, so no new seam: heartbeat mounts the
@server/prefixes of the tools the edition already pins inSlackEnterpriseGate.heartbeat_safe_tools(), read from the default spec; that one list feeds the copy, the fingerprint and the freshness check. A companion with pins needs no change.agent_materialization/worker_agent.py,platform/interfaces.pyheartbeat_mirrored_servers()=kirocrew-core+ the pins'@server/prefixes (an unmounted name is skipped); an edition entry is copied minusautoApprove; the fingerprint covers it.heartbeat_safe_tools()documents the rule.agent.py_write_heartbeat_speclogs the mounted edition servers and the withheldautoApprove; the prompt and specdescriptionname_heartbeat_approval.slack/gateway_runtime/tool_policy.py_is_heartbeat_safe_tool(event)keys onmcp_identity_trusted,tool_name,mcp_server_name: built-ins viahooks._is_host_read_only_builtin(the tier's own table,web_fetch/web_searchincluded); sevenkirocrew-corereads only onkirocrew-core(nocron_list: that server is not mounted); host shell:name_grant.program_namesmust establish the program set with nogitin it, thenis_read_only_bash; edition@server/toolpins.HEARTBEAT_SAFE_TOOLSis deleted (no reader)._build_heartbeat_hookssetsdefer_reads_to_approver.hooks.py,hook_runtime/gate_tiers.pyHooksConfig.defer_reads_to_approver: the read-only tier gives no verdict, so the call reaches the session's approver. Never read from config.slack/gateway.py_heartbeat_approvalruns the name-grant check on an approved shell and audits the trustedserver/tool. A deny with no trusted identity, or a trusted but emptytool_name(the cache-hit-on-empty-names shape a backend with no_metachannel produces), is auditedno_trusted_identityand warns that the backend publishes none; other denies staynot_in_heartbeat_safe_tools.docs/system-specs/modules, prepare-prrationale.md, comments insession.py/hooks.py/platform/*.pyharness-parity.mdrecords that a harness with no adapter-authored tool identity runs heartbeat text-only.test/test_agent_refactor_spec_bytes.py,test/test_agent_refactor_contracts.py_HEARTBEAT_SYSTEM_PROMPTdigests re-pinned for the reworded strings (mcpServersandtoolsunchanged).Why
autoApproveis dropped from an edition entry only: it lets kiro-cli approve a call locally, before_heartbeat_approval, on the one agent with no approver. The owner'skirocrew-coreentry keeps it (rfc-owner-written-mcp-auto-approve).Read-only shell is not new to heartbeat: on the base,
_tier_read_onlyauto-approvesis_read_only_bashcommands for heartbeat before_heartbeat_approvalruns (baseheartbeat.md: "the read-only tier survives the heartbeat scoping"). This PR turns that tier off for heartbeat and moves the decision into_heartbeat_approval, narrowed: trusted identity, no git, name-grant.Why git is excluded even for
git status: git reads.git/configon every run, andcore.fsmonitor/core.hooksPathname a program there that no text classifier can see. The exclusion is heartbeat's alone:_tier_read_only(cron, subagent, app sessions) andchat_runner.pytrust-reads still approve read-only git; #20105 tracks them.Backwards compatibility
Breaking: heartbeat approves fewer calls. Writer sweep on origin/main @ beb3c40:
_is_heartbeat_safe_tool(has one caller,slack/gateway.py::_heartbeat_approval, changed here; its other writers aretest_heartbeat_safe_tools.pyandtest_slack_gateway_more_coverage.py, rewritten here;test_slack_gateway_composition_contract.pypins the signature.HEARTBEAT_SAFE_TOOLShad no reader outsidetool_policy.py, thegateway.pyre-export and those tests. A standalone heartbeat spec mounts the same servers and tools; only itsdescriptionchanges.What stops working:
from kiro_crew.slack.gateway import HEARTBEAT_SAFE_TOOLS; a heartbeat call approved on its title alone (Read,Grep,Glob,WorkspaceSearch,Running: @server/tool); any heartbeatgitcommand; a heartbeat MCP call the gate approved onkind="read"or a read-shaped title; heartbeat tool use on a backend with no_metaidentity.Reader:
slack/gateway.py:_heartbeat_approval-- heartbeat -- reads the event, not the title;TestHeartbeatApproval,TestHeartbeatShellNameGrantReader:
llm_helpers.py:_resolve_permission-- heartbeat -- HOOK_BASED path unchanged; a deferred read falls toon_tool_approval;test_the_read_only_tier_gives_no_verdictReader:
hook_runtime/gate_tiers.py:_tier_read_only-- chat|cron|subagent|app -- the flag is False on every other HookManager;test_deferring_reads_never_widens_a_deny,test_gate_tiers.pyReader:
agent_materialization/worker_agent.py:_require_fresh_heartbeat_spec-- heartbeat -- derives throughheartbeat_mirrored_servers();test_an_edition_change_to_a_mirrored_server_is_caught_at_spawnReader:
agent.py:_HEARTBEAT_SYSTEM_PROMPTand the specdescription-- heartbeat -- name_heartbeat_approvalas the gate;test_heartbeat_cycle_recycle.pyReader:
heartbeat.md,slack-gateway.md,platform-context.md,harness-parity.md-- release -- rewritten hereTests
test_heartbeat_safe_tools.py(rewritten): a trusted built-in approves,readalias included; untrusted identity, empty trusted identity and a forged title deny; a built-in name with a server attached denies; trustedweb_fetch/web_searchapprove; core reads approve only onkirocrew-coreandcron_liston any server denies; read-only shell approves, mutating or unrecoverable denies, every git form denies; an MCP tool declaringexecuteis judged on its pin; edition pins need the trusted pair; the audit row carriesserver/tool; an untrusted deny, and a trusted deny with an emptytool_name, are auditedno_trusted_identitywith a backend warning, a trusted write denynot_in_heartbeat_safe_tools;TestRecordedWirereplays the recorded permission frames through_heartbeat_approval: kiro-cli's shell call (fixtures/acp_frames/kiro/session.jsonl,_meta.kiro.toolName) approves, the claude-agent-acp and opencode frames (trusted flag set, empty name) deny asno_trusted_identity; the one remaining allowlist set holds the seven core reads; the name-grant refusal denies and is not consulted for a denied shell; the heartbeat hooks defer kind, title and shell reads while a deny still denies.test_heartbeat_spec_freshness.py: standalone mirrors core only; a pinned server's entry is copied verbatim minusautoApproveand the spawn gate accepts it; a pin on a server the default spec does not mount is skipped; a bare pin or a malformed@pin mounts nothing; a default-spec edit to a pinned server, or an edition dropping its pins, re-derives before the start; a gate that cannot answer degrades to core; a composition failure re-raises.TestShell::test_every_git_invocation_deniescovers;,&&,|, newline,(git ...),FOO=1 git ...,/usr/bin/gitandGIT;test_untokenizable_command_deniescovers an unclosed quote.test_cpp_wiring_standalone.pypins the empty default;test_slack_gateway_more_coverage.pypins that a title alone is refused.Determinism: the five test files above ran 3 times in a row serially (
-n0), once in reversed file order, and once split across 6 xdist workers: 212 passed every time.Manual verification
N/A — unit coverage sufficient. The change is a config-derivation path (
_write_heartbeat_specwrites a JSON spec) and pure approval functions; the tests run them against a real temp agents directory and a realAcpEvent.Screenshots / video
N/A — backend only, no rendered surface is touched.
Related Issues
Closes #20042
Pattern harvest
Rule candidate: review-prompt
Pattern: a security gate on an unattended surface decides on
event.title(model-authored) where a trusted identity field (tool_name/mcp_server_name/mcp_identity_trusted) exists on the same event.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)