Skip to content

fix(agent): wire edition-contributed MCP servers into the heartbeat agent - #10158

Closed
maiza172 wants to merge 2 commits into
kirodotdev:mainfrom
maiza172:fix/heartbeat-agent-extra-mcp-servers
Closed

maiza172 wants to merge 2 commits into
kirodotdev:mainfrom
maiza172:fix/heartbeat-agent-extra-mcp-servers

Conversation

@maiza172

@maiza172 maiza172 commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let a companion edition's MCP servers reach the unattended heartbeat agent, closing the one agent-config builder that never wired in edition-contributed servers.

_install_heartbeat_agent() builds the heartbeat agent's mcpServers from a hardcoded single-item tuple and never reaches any edition-contributed server. _install_research_agent() and the main agent config (build_agent_config()) both correctly merge edition-contributed servers via the platform seam; the heartbeat path was the one builder that never called through, so a companion contributing a heartbeat-relevant MCP server had no way to reach the unattended heartbeat agent at all.

Why it matters

Any companion/edition that wants its own MCP servers available to the unattended heartbeat cycle currently cannot get there — the seam other agent builders use simply isn't wired for this one. The gap is silent: nothing errors, the heartbeat agent just installs with a narrower server set than intended, so the failure mode is a companion server that quietly never runs rather than a visible break.

Not a goal

  • A CONTRACT_VERSION bump for the new extra_heartbeat_mcp_servers() seam — an older companion built without it degrades to {} via the existing fail-closed/degrade split rather than being required to update.
  • Deciding whether a live heartbeat-cycle run is required before merge — flagged in review as a maintainer call, not resolved by this PR.

What changed (motivation → approach → change)

Heartbeat is the one agent with no approver, ever. Letting an edition add servers to it also means every tool call from those servers must be judged on a trusted identity, never on text the model wrote. So the PR adds the seam and closes the approval paths the seam would otherwise open.

Part What it does now
platform/interfaces.py, platform/defaults.py New extra_heartbeat_mcp_servers() on McpToolingProvider. Default {}.
agent.py _install_heartbeat_agent() merges those servers after kirocrew-core, core wins collisions, and drops autoApprove from every edition entry (audited). The assembled map then goes through strip_ungoverned_auto_approve. PlatformCompositionError is held until every sibling installer has run, then re-raised; other errors degrade to {}.
dashboard/handlers/mcp_custom.py MCP add/update return 500 agent_config_rebuild_failed when the rebuild fails, instead of a silent ok, with a SEL error row.
slack/gateway.py _is_heartbeat_safe_tool() keys on mcp_identity_trusted, tool_name, mcp_server_name, never event.title. Builtins delegate to hooks._is_host_read_only_builtin (fs_read, glob, grep); the title spellings Read, Grep, Glob, WorkspaceSearch leave the allowlist; web_fetch/web_search excluded. Read-only shell allowed via is_read_only_bash, every git invocation excluded. SEL audit records the trusted server/tool.
hooks.py HooksConfig.deny_kind_based_read_only turns off the three kind- and title-based auto-approve branches; heartbeat hooks set it.
security/readonly_bash.py command_invokes_git() splits on the same _SEGMENT_SEPARATOR_RE as _classify_bash, so pwd; git status cannot slip past the git exclusion.
builtin_skills/kirocrew-dev/prepare-pr SKILL.md and references/rationale.md state that heartbeat cannot read a repo.
docs/system-specs/modules heartbeat.md, platform-context.md, slack-gateway.md describe the seam and the approval rules.
.github/black-baseline.txt Two touched files are now black-clean and leave the baseline, as the black gate requires.
test/test_security_gate_liveness.py _PACKAGE_LINE_BUDGET re-pinned to the measured total, reason recorded in the ratchet's log.

Why autoApprove is handled two ways: it lets kiro-cli approve a call locally, before _heartbeat_approval ever sees it. An edition entry loses it on every install, even when the same spec is declared on the main-agent seam, because heartbeat has no approver and the declared-verb exemption would run that server with no gate and no per-call audit. The owner's kirocrew-core entry keeps an owner-written autoApprove under mcp.honour_auto_approve (rfc-owner-written-mcp-auto-approve), as on the main agent.

Why git is excluded even for git status: git reads .git/config on every invocation. core.fsmonitor and core.hooksPath name a program from that file, not from the command line, so no text classifier can see it.

Backwards compatibility

Compatible: for a standalone install the heartbeat agent config is byte-identical, including an owner-written autoApprove on kirocrew-core, which still follows mcp.honour_auto_approve. An older companion without the new method still installs heartbeat with kirocrew-core alone.

Two approval-path changes affect existing installs. A heartbeat tool call is approved only on a trusted _meta identity, so on a backend that publishes none (claude-agent-acp, opencode per acp/_dispatch.py) heartbeat approves no tool and runs text-only; heartbeat.md records this as intended. The old title spellings (Read, Grep, Glob, WorkspaceSearch) no longer match; WorkspaceSearch has no entry in hooks._HOST_READ_ONLY_BUILTIN_TOOLS and is not mapped.

Tests

New and updated tests across test_cpp_wiring_enterprise.py, test_cpp_wiring_standalone.py, test_heartbeat_cycle_recycle.py, test_app_mcp_scoping.py, test_agent.py, test_heartbeat_safe_tools.py, test_slack_gateway_more_coverage.py, test_hooks.py, test_mcp_custom_api.py, test_trust_reads.py lock in:

  • the seam: fail-closed on PlatformCompositionError, degrade to {} on other errors, forward-compat with an older companion, verbatim merge of edition filters, core wins a name collision
  • autoApprove: an edition entry's is dropped and audited even when the same spec is declared via extra_mcp_servers() (the case the governed helper alone would keep); the owner's kirocrew-core entry keeps it while mcp.honour_auto_approve is on and loses it when off; a governance ceiling withholds it
  • _is_heartbeat_safe_tool(): untrusted identity denied even with an allowlisted name; bare or wrong-server core tool names denied; builtins with a server attached denied; web_fetch/web_search denied; read-only shell approved, mutating or unrecoverable command denied; every git form denied
  • deny_kind_based_read_only on all three branches, default HookManager unchanged, deny never widened
  • command_invokes_git: every separator, pipe targets, case, empty input, gitk/digit do not match
  • dashboard add/update report agent_config_rebuild_failed and audit it as outcome=error; the rebuild still runs every sibling installer before the composition error is re-raised
  • _heartbeat_approval SEL label uses the trusted identity on trusted events and the redacted title on denied ones

Manual verification

N/A — unit coverage sufficient. This is a backend config-generation path (_install_heartbeat_agent() writes a JSON agent spec to disk) plus pure-function gates (_is_heartbeat_safe_tool(), HookManager.on_tool_call); the tests exercise them end-to-end against a real temp directory and assert on the written file's contents or the returned action.

Screenshots / video

Why no screenshot: backend-only change, no rendered surface is touched.

Related Issues

None filed; found while investigating heartbeat MCP access during unrelated work.

no linked issue: this PR was opened from a review finding during unrelated work, not from a tracked issue.

Pattern harvest

Rule candidate: semgrep
Pattern: one of several sibling "install agent config" functions omits a call
to the shared edition-extension helper that its siblings all call
(_install_research_agent() and build_agent_config() both call
_extra_mcp_servers(); _install_heartbeat_agent() did not). A structural
check comparing sibling functions with a shared naming/role convention
(_install_*_agent) against a required call to a named helper would have
caught this at review time rather than needing a live bug report.

Second rule candidate, from this PR's own review cycle: a multi-branch
matching function (bare-name vs. qualified-name cases) that closes a
collision class in one branch should be checked for the identical collision
shape in every sibling branch before merging, not branch-by-branch across
separate review rounds — three of this PR's review rounds each found the
same unguarded-branch shape in a different branch of _is_heartbeat_safe_tool().

Checklist

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

@maiza172
maiza172 requested review from a team and patrigao September 11, 2026 17:52
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 11, 2026
@github-actions

github-actions Bot commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

Backends publishing no _meta identity lose all heartbeat tool approval on existing installs — a posture regression riding a seam-wiring PR.

Watch

  • The title→trusted-identity rewrite makes claude-agent-acp/opencode heartbeat sessions text-only ("gets no heartbeat tool approval at all") — a user-visible degradation on installs that never touch editions, decided inside a PR titled as seam wiring. The rationale is sound (forged titles, zero-approver surface), but the posture choice belongs to a maintainer, not the diff.
    Clears when: a maintainer explicitly acks the text-only posture for identity-less backends (comment or decisions entry), or it ships behind its own PR.
  • The whole approval path now rests on kiro-cli stamping _meta.kiro.toolName (fs_read/glob/grep) through the cache-hit path; if a real cycle misses it, heartbeat silently degrades to all-denied with only SEL rows to show it. The PR itself defers this ("a maintainer call, not resolved by this PR").
    Clears when: one live heartbeat cycle on kiro-cli shows a trusted fs_read auto-approve in SEL.

[DESIGN-REVIEWED] c6cfc67

Description read

[DESCRIPTION-READ] 99a2cbcf44088bfe03c1282eaf9e393c7f079ec10346a8b4191fa090a04b5b45

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

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

First-Principles-Verdict: PASS

Verify one live heartbeat cycle on kiro-cli: every approval now rests on _meta.kiro identity reaching the permission event, and the tests only hand-build such events.

Not justified as shipped

  • Item 10 — undeclared: prepare-pr SKILL.md gains "The retired pr_watch babysit cron is not for new work," a sentence the description never mentions; harm-free rider, nothing more.

What this change ships

Inventory (10 items) — 9 justified

Intent: FIX — make the base's existing edition heartbeat-tool allowlist seam (SlackEnterpriseGate.heartbeat_safe_tools(), dead without server wiring) reachable, closing the approval bypasses that reachability would open.

  1. Editions can contribute MCP servers to the heartbeat agent (extra_heartbeat_mcp_servers(), default {}, core wins collisions) — justified
  2. Edition entries always lose autoApprove, audited; owner's core entry still follows the accepted rfc-owner-written-mcp-auto-approve — justified
  3. Heartbeat approval keys on trusted _meta identity; the Read/Grep/Glob/WorkspaceSearch title spellings leave the allowlist — justified
  4. Backends with no trusted identity (claude-agent-acp, opencode — confirmed at base acp/_dispatch.py:1058) get no heartbeat tool approvals; text-only — justified
  5. web_fetch/web_search excluded from heartbeat's builtin trust — justified
  6. Read-only shell moves from the forgeable kind-based hook tier to the identity-gated allowlist; every git invocation denied — justified
  7. Three kind/title auto-approve branches suppressed for heartbeat hooks (deny_kind_based_read_only) — justified
  8. Dashboard MCP add/update return 500 agent_config_rebuild_failed on composition failure instead of silent ok — justified
  9. "No shell" pin in rationale.md rewritten — justified (base heartbeat.md itself contradicted it: the read-only tier survived heartbeat scoping)
  10. Ratchet re-pin, black-baseline exits, plus one undeclared doc sentence — undeclared (the sentence; the gate bookkeeping is mandated)

[FIRST-PRINCIPLES-REVIEWED] c6cfc67

Description read

[DESCRIPTION-READ] a672ef6051fe1b2bb0f7e4855985836f5a6b4841a82c1060b671005170a4ffdf

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

@github-actions

github-actions Bot commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 437d238

@github-actions

github-actions Bot commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

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

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/agent.py:3521 -- Composition failure skips governance refresh for forked agents

raise heartbeat_composition_error
Tightened ceiling + heartbeat composition failure -> rebuild exits before refresh_after_rebuild() -> forked agents can start with stale auto-approvals.
Anchor: backend-security-controls
Fix: Re-raise only after fork refresh and remaining security post-processing run.
[BLOCK-MERGE] c6cfc67
[GPT-REVIEWED] c6cfc67

Adjudication (Opus 5) — is blocking on each finding proportionate?

UNBOUNDED — governance-ceiling bypass: a fork's on-disk allowedTools/autoApprove short-circuit inside the harness and never reach the PreToolUse gate (src/kiro_crew/agent.py:3548-3551).
Conditions confirmed: the held re-raise sits before fork_refresh.refresh_after_rebuild (base src/kiro_crew/agent.py:3457, after the worker installer at 3449), and the spawn gate cannot see a refresh that never started — it waits on _fork_refresh_settled, which is set by default (src/kiro_crew/agent_materialization/fork_refresh.py:95), and checks _fork_refresh_failed, which stays empty unless a pass actually ran and failed (fork_refresh.py:103, gate at agent.py:3651,3657). Recovery: none for the fork gate; only the ceiling-reproject caller retries, because its memo does not advance past the raise (agent.py:3148,3183).
Rarity record cannot be completed: the PR's own mcp_custom handlers exist to serve this error class on a live post-boot endpoint, and the ceiling-tightening trigger is precisely when the skipped refresh matters, so the reaching combination is not self-contradicting or writer-unproducible.

[ADJUDICATION] c6cfc673a6cba1ddd3eddfbfd04699fb9b5d68d4 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] c6cfc673a6cba1ddd3eddfbfd04699fb9b5d68d4

[ADJUDICATION-FENCED] c6cfc673a6cba1ddd3eddfbfd04699fb9b5d68d4 fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/agent.py:3521 -- The held re-raise lands before the fork-governance refresh and the spawn gate has no signal for a pass that never ran, so a fork can start on auto-approvals the tightened ceiling forbids with no backstop.
[GPT-ADJUDICATED-FENCED] c6cfc673a6cba1ddd3eddfbfd04699fb9b5d68d4

@maiza172
maiza172 force-pushed the fix/heartbeat-agent-extra-mcp-servers branch 3 times, most recently from c5caf61 to 46000da Compare September 11, 2026 19:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@maiza172
maiza172 force-pushed the fix/heartbeat-agent-extra-mcp-servers branch from 46000da to 132fe36 Compare September 11, 2026 20:01
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@maiza172
maiza172 force-pushed the fix/heartbeat-agent-extra-mcp-servers branch from 132fe36 to e1a7de9 Compare September 11, 2026 21:56
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@maiza172
maiza172 force-pushed the fix/heartbeat-agent-extra-mcp-servers branch from e1a7de9 to 2965ac7 Compare September 11, 2026 22:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 11, 2026
@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: approval keyed on the trusted-identity path is verified only by hand-built AcpEvents; live cycle deferred span=027ac06edf0b

rebutted, maintainer ruling (bolichen97, recorded on this PR): the live heartbeat run is explicitly waived; unit coverage against the documented _meta.kiro contract is the accepted verification. Failure direction is deny-by-default with a SEL denied record, never a silent approve, so a wrong assumption surfaces as an audited denial on the first real cycle after merge rather than as an unwatched tool run.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: capability regressions for installs with no edition (no web_fetch/web_search, no git reads, text-only on identity-less backends) span=c19c439f758b

rebutted, maintainer ruling (bolichen97): the posture heartbeat.md documents is the intended trade for existing installs. The maintainer is driving this PR to green with that section in place and ruled that no live run is needed; heartbeat is the one session with no approver, polling untrusted content, so network egress, git (which reads .git/config on every invocation) and title-keyed approval are exactly the channels it must not have. A legitimate read that is now denied shows up as a SEL denied record and is added by name, the path heartbeat.md already prescribes.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Item 10: HEARTBEAT_SAFE_TOOLS kept with zero non-test code consumers span=f626903470af

rebutted: the constant pre-exists on main; this PR narrows its content and moves the match to the two constants it is the union of, it does not add an alias. It is the operator-facing name of the allowlist: the SEL reason not_in_heartbeat_safe_tools, the gateway log line, the heartbeat agent's description string and system prompt, the heartbeat.md section title and the name operators are told to extend. Tests read it as the documented union. Deleting it renames a public concept across docs, prompts and audit strings for no behaviour change; that is churn, not a subtraction.

@bolichen97

Copy link
Copy Markdown
Contributor
  • agent_config_rebuild_failed 500 returns with no SEL row for a mutation that is on disk (src/kiro_crew/dashboard/handlers/mcp_custom.py:405) span=61a614c8c890

fixed in 087eef0: both the add and the update path now emit sel().log_api_access(operation=mcp_custom_add/mcp_custom_update, outcome="error", resources="custom: saved; agent config rebuild failed") before returning the 500, matching the malformed-config 500's error row in the same handler. Pinned in test_mcp_custom_api.py (both composition-failure tests assert the row); the assertions fail on the prior code.

@bolichen97

Copy link
Copy Markdown
Contributor
  • re-raising PlatformCompositionError skips the five installers below heartbeat (src/kiro_crew/agent.py:3312) span=58ab3ac8329f

fixed in 087eef0: the error is held in a local while conductor, pipeline-conductor, ledger-conductor, security-conductor and worker install, and re-raised after the worker installer, so no sibling spec goes stale for that boot. test_agent.py::test_heartbeat_composition_error_propagates_not_swallowed now also asserts all five siblings ran in order; it fails on the prior code.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: text-only heartbeat on identityless backends and the blanket git exclusion are shipped behaviour changes a human should own span=cbcc780a9cd9

rebutted, maintainer ruling (bolichen97, recorded on this PR on earlier heads and unchanged): the text-only posture on backends without a trusted identity channel and the exclusion of every git invocation are intended ship criteria for this PR. heartbeat.md documents both; the PR body's Backwards compatibility names both. Heartbeat is the one session with no approver, polling untrusted content, so a title-keyed approval or a git process reading .git/config are exactly the channels it must not have; a legitimate read that is now denied surfaces as a SEL denied row and is added by name.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: the positive approve path is exercised only by hand-built AcpEvents; live cycle deferred span=b2e747fedbb8

rebutted, maintainer ruling (bolichen97): the live heartbeat run is waived; unit coverage against the documented _meta.kiro contract is the accepted verification. If the stamping assumption diverged, the outcome is an audited denial on the first real cycle, never an unwatched approval.

@bolichen97

Copy link
Copy Markdown
Contributor
  • _normalize_mcp_server_keys aliases a slashed heartbeat key, so a heartbeat_safe_tools pin spelled with the original key never matches (src/kiro_crew/agent.py:5016) span=53782b78323f

fixed in d8db3b4: the installer now reads the alias map the normaliser returns and logs a WARNING for every renamed key naming the mount and the exact '@/' spelling a heartbeat_safe_tools() entry must use; the extra_heartbeat_mcp_servers() contract states the rule. The slash-key test asserts the warning and its spelling (fails on the prior code). Refusing slashed keys was the larger change: the normaliser is the same pass the main agent runs, and a slashed key already works once the pin matches the mount.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: identity requirement is a behavioural regression on claude-agent-acp/opencode heartbeats span=a2976659c518

rebutted, maintainer ruling (bolichen97, recorded on this PR and unchanged across heads): the text-only posture on backends that publish no trusted identity is an intended ship criterion. heartbeat.md documents it, the PR body's Backwards compatibility names it. Heartbeat has no approver and polls untrusted content; a model-authored title is not an identity it may approve on.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: identity-path evidence is hand-built AcpEvents; live cycle deferred span=ecdf5acfa77f

rebutted, maintainer ruling (bolichen97): the live heartbeat run is waived; unit coverage against the documented _meta.kiro contract is the accepted verification. The earlier title-space spelling mistake this item cites was caught and the builtin set is now sourced from hooks._HOST_READ_ONLY_BUILTIN_TOOLS, the same set the interactive path trusts, so there is no second hand-maintained spelling left to drift.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Suggestion: one-time gateway startup notice when the active backend publishes no _meta identity span=02cda49a7396

rebutted as out of the frozen goal: a startup probe of the backend's identity channel is a new surface this PR does not need, and the gateway cannot know before the first tool call whether an adapter will publish _meta. What exists today is per call and already names the cause: the gateway log line "Heartbeat blocked tool call: (not in HEARTBEAT_SAFE_TOOLS)" and the SEL denied row, plus heartbeat.md's statement of the posture. A follow-up may add the notice once a backend's identity support is a declared capability.

@bolichen97

Copy link
Copy Markdown
Contributor
  • prepare-pr rationale.md:365 and SKILL.md:783 claim heartbeat "cannot even read the repo"; excluding git does not exclude repo reads span=9decb3e54a98

fixed in a02d1d6: both clauses now state the true consequence, that heartbeat has no write tool and no git, so it can read files but never amend or push. Doc-only change; the skill byte ceiling test still passes.

…gent

Adds McpToolingProvider.extra_heartbeat_mcp_servers() so an edition can
name servers that reach only the unattended heartbeat agent. Default {},
merged ADD-only after kirocrew-core, so a standalone install is unchanged.
PlatformCompositionError propagates out of the heartbeat installer's
wrapper instead of being swallowed; the dashboard MCP add/update handlers
report it as 500 agent_config_rebuild_failed.

Heartbeat has no approver, so every tool call an edition server can now
send is judged on trusted identity, never on model-authored text:

- autoApprove is dropped from every edition heartbeat entry on every
  install, audited as mcp_auto_approve_withheld: kiro-cli would approve
  matching calls locally and bypass _heartbeat_approval,
  HEARTBEAT_SAFE_TOOLS and per-call SEL audit, and the declared-verb
  exemption a spec also returned by extra_mcp_servers() earns does not
  extend to an agent with no approver. The assembled map then goes
  through strip_ungoverned_auto_approve, so the owner's kirocrew-core
  entry follows rfc-owner-written-mcp-auto-approve as on the main agent.
- _is_heartbeat_safe_tool keys on mcp_identity_trusted / tool_name /
  mcp_server_name instead of event.title; builtins delegate to
  hooks._is_host_read_only_builtin with web_fetch/web_search excluded;
  a read-only shell command is allowed via is_read_only_bash with every
  git invocation excluded (git reads .git/config on invocation, a
  channel no text classifier can see); the SEL audit label records the
  trusted server/tool identity.
- HooksConfig.deny_kind_based_read_only turns off the three kind- and
  title-based auto-approve branches in HookManager.on_tool_call for the
  heartbeat-scoped manager only.
- security.readonly_bash.command_invokes_git splits on the same
  _SEGMENT_SEPARATOR_RE as _classify_bash so `pwd; git status` cannot
  slip past the exclusion.

Docs (heartbeat.md, platform-context.md, slack-gateway.md, prepare-pr
SKILL.md and rationale.md) describe the seam and the approval rules.
test_security_gate_liveness re-pins the security package line budget to
the measured total with the reason recorded; two touched files leave the
black baseline as the gate requires.
@bolichen97

Copy link
Copy Markdown
Contributor
  • agent.py:4872 docstring says approval stays gateway-side "regardless", contradicting a preserved owner-written autoApprove span=53782b78323f

fixed in 437d238: the sentence now names the one exception, an owner-written autoApprove on kirocrew-core that the RFC lets kiro-cli honour before the gateway gate, and points at the paragraph below that says edition-added entries never keep one.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: every approval branch needs mcp_identity_trusted; premise never verified live span=8616385b5dc1

rebutted, maintainer ruling (bolichen97): the live heartbeat run is waived; unit coverage against the documented _meta.kiro contract is the accepted verification. The interactive path already trusts the same channel, and if the premise fails the outcome is an audited denial, never an unwatched approval.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: claude-agent-acp/opencode installs lose heartbeat tool use span=92b7df779b18

rebutted, maintainer ruling (bolichen97, recorded on this PR and unchanged across heads): the text-only posture on backends that publish no trusted identity is an intended ship criterion. heartbeat.md documents it and the PR body's Backwards compatibility names it.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: removing the title-match path degrades heartbeat tool use on claude-agent-acp/opencode span=81d8cf9d1493

rebutted, maintainer ruling (bolichen97, recorded on this PR and unchanged across heads): the text-only posture on backends that publish no trusted identity is an intended ship criterion. heartbeat.md documents it and the PR body's Backwards compatibility names it. A model-authored title is not an identity heartbeat may approve on.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Watch: live heartbeat cycle deferred; coverage is unit-level against constructed events span=cd4678ff56a9

rebutted, maintainer ruling (bolichen97): the live heartbeat run is waived; unit coverage against the documented _meta.kiro contract is the accepted verification. The builtin spellings come from hooks._HOST_READ_ONLY_BUILTIN_TOOLS, the set the interactive path already trusts on the same channel, so there is no separate hand-kept spelling to drift.

@bolichen97

Copy link
Copy Markdown
Contributor
  • Suggestion: fix the empty-string identity flag at the dispatch layer in a follow-up span=08b4833309ef

rebutted as out of the frozen goal: changing how acp/_dispatch.py sets mcp_identity_trusted touches every consumer of that flag, not the heartbeat seam this PR wires. The heartbeat consumer guards the case explicitly and the trap is named in the code comment beside the check; a follow-up may move it into the dispatcher.

@bolichen97

Copy link
Copy Markdown
Contributor
  • is_shell applies the host name-grant check to allowlisted server-backed execute-kind MCP tools (src/kiro_crew/slack/gateway.py:3192) span=f00224b0077d

rebutted, maintainer ruling (bolichen97, recorded on this PR for head 1d8041a and unchanged): the name-grant check stays as is, unscoped. Heartbeat has no approver, so a shell-kind tool that carries a recoverable command is checked against the host's program lookup before it is auto-approved, whichever server backs it; a refusal denies and is audited as name_grant_refused, never a silent block. An MCP tool without a command param is unaffected (refusal_for_event returns None for it). Adding "and not event.mcp_server_name" would exempt exactly the tools an edition can wire in, which is the gap the check exists to close.

@iamwhatever

Copy link
Copy Markdown
Contributor

Read-only review note, leaving approval to a maintainer because the diff touches security/readonly_bash.py and the heartbeat's auto-approve path. What I verified: only edition-contributed servers from current_context().mcp_tooling.extra_heartbeat_mcp_servers() are wired in, never user-configured custom servers; autoApprove is stripped and audited; no write tools are added; shell approval now requires a trusted identity, a non-empty tool_name with no server behind it, no git in any pipe segment, and a name-grant check, where before is_read_only_bash was auto-approved unconditionally, so the surface narrows. readonly_bash.py only adds a deny helper (first word 'git' per pipe segment; /usr/bin/git slips the helper but is rejected by the allowlist anyway). mcp_custom.py adds no route, both endpoints stay owner-gated. Nits: the _bare_tool_name docstring (gateway.py:1116) still says it unwraps the same forms _is_heartbeat_safe_tool unwraps, which is stale; the add endpoint returns 500 after the server is already written, so a retry hits 'already exists'.

bolichen97
bolichen97 previously approved these changes Oct 1, 2026
# Conflicts:
#	src/kiro_crew/agent.py
#	test/test_security_gate_liveness.py

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merged main to clear conflicts in src/kiro_crew/agent.py (import list) and test/test_security_gate_liveness.py (kept both re-pin notes, budget 27,994). Liveness test and the PR's own test files pass locally (912 passed). Re-approving the same change.

@dwu96

dwu96 commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: dwu96#8c08bee0]: Security scan flagged this PR for manual review.

Findings:

  • test/test_heartbeat_safe_tools.py:334 — destructive-operation rule (rm -rf against /, ~, $HOME, .. or /tmp/kc): event = _trusted_builtin("", is_shell=True, raw_tool_params={"command": "rm -rf /tmp/foo"})
  • test/test_hooks.py:1778 — same rule: result = mgr.on_tool_call("rm -rf /tmp/x", command="rm -rf /tmp/x", is_shell=True)

Both matches are in test files and read as fixtures that assert the security gate rejects such a command rather than as destructive code. I am not treating that reading as sufficient to clear them, because this PR also changes the enforcement path those fixtures exercise — src/kiro_crew/security/readonly_bash.py (+46/-1), src/kiro_crew/hooks.py (+61/-12) and src/kiro_crew/agent.py (+206/-16) — so whether the assertions still pin a deny outcome is exactly the question a human should answer, not an automated triage pass.

Accordingly this PR is not being enqueued for automated fixes, and no automated commits will be pushed to the branch. I have added needs-human-security-review and removed needs-pr-triage. A maintainer will review before any automated action is taken.

For the reviewer's convenience, the rest of the triage read (not acted on): 2222 additions / 296 deletions across 23 files, 2 commits, mergeable: false (dirty — conflicts with main), maintainer_can_modify: true.

Copy link
Copy Markdown
Contributor

Open-PR triage (2026-10-05), checked against origin/main @ a97659dfc3. Head c6cfc673a6, merge base d8fa6a527e (604 commits behind main).

Classification: DISTINCT. No open or merged PR adds extra_heartbeat_mcp_servers(), deny_kind_based_read_only, command_invokes_git or agent_config_rebuild_failed. None of those names are on main. The open PRs whose diffs mention the heartbeat installer or gate (#15546, #16119, #15326, #15718, #14574, #16913, #12551) only show them as context lines, or wrap the same rebuild_agent_config call for a different reason. Nothing supersedes this PR, and nothing duplicates it.

Still blocking at this head (not resolved by any disposition):

  • Security regression: governance refresh is skipped. src/kiro_crew/agent.py:3521 re-raises heartbeat_composition_error before fork_refresh.refresh_after_rebuild(...) (:3527) and repair_agent_configs() (:3530). On main every installer swallows its error, so those two post-passes always run. With this PR, a PlatformCompositionError during a rebuild after the governance ceiling was tightened means forks keep their stale allowedTools/autoApprove, and the spawn gate does not notice. The GPT 5.6 fenced BLOCK on this head already reports it, and the 2026-09-30 dispositions cover only the earlier "five sibling installers" finding. Suggested fix: keep holding the error until after sync_aim_packages(), refresh_after_rebuild() and repair_agent_configs(), then raise it.
  • Behaviour change for existing installs (breaking for some backends). _is_heartbeat_safe_tool (slack/gateway.py:928) now denies any event without mcp_identity_trusted. As the PR body says, heartbeat on claude-agent-acp and opencode becomes text-only, and the Read/Grep/Glob/WorkspaceSearch title spellings stop matching. The design review left this as a Watch that clears only with a maintainer ack or a decisions entry. I found neither (the 2026-10-01 approval is about the merge-conflict fix). Please record the ack explicitly.

Needs a rebase: mergeable_state: dirty. git merge-tree against main conflicts in platform-context.md, slack-gateway.md, slack/gateway.py, test_security_gate_liveness.py and test_slack_gateway_more_coverage.py. It also hits a modify/delete on builtin_skills/kirocrew-dev/prepare-pr/SKILL.md, which main moved to kirocrew-prepare-pr/.

Recommendation: REBASE, fix the re-raise ordering, then get the maintainer ack on the identity-less-backend posture. Do not close this PR.

@bolichen97

Copy link
Copy Markdown
Contributor

Heads-up from the maintainer side: this change is being carried to main as an in-repo redo, #20047 (fix(agent): mount edition MCP servers on the heartbeat agent and approve on trusted identity), rebuilt on current main with you as co-author (Co-authored-by: Adam Albertson <maiza172@gmail.com>). This fork branch is ~1,900 commits behind and touches Sensitive Change Review paths, so it cannot be brought forward as-is; the merge-conflict and cancelled-check notifications here are expected and need no action. #10158 will be closed with a pointer once #20047 merges. Thank you for the report and the first implementation.

@bolichen97

Copy link
Copy Markdown
Contributor

Superseded by #20047, which landed on main as 824c6c7 (squash via auto-merge, approved by @mbriones98).

#20047 is the in-repo takeover of this fork PR: the heartbeat agent now mirrors edition-contributed MCP servers (heartbeat_mirrored_servers() in agent_materialization/worker_agent.py) and the heartbeat approval path is identity-based (_is_heartbeat_safe_tool in slack/gateway_runtime/tool_policy.py). The commit carries Co-authored-by: Adam Albertson <maiza172@gmail.com> -- thank you for the original work, @maiza172.

Closing this PR; follow-up on the one deferred finding is tracked in #20105.

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

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge needs-human-security-review Security scan flagged — needs manual review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants