Skip to content

fix(agent): mount edition MCP servers on the heartbeat agent and approve on trusted identity - #20047

Merged
bolichen97 merged 1 commit into
mainfrom
takeover/10158-heartbeat-edition-mcp
Oct 14, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
takeover/10158-heartbeat-edition-mcp

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

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, and McpToolingProvider has no way to name another. A companion that pins @its-server/ReadTool in heartbeat_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_tool read event.title, which the model writes. The read-only tier still ran for heartbeat, approving on the agent-declared ACP kind, a read-shaped title, or any read-only shell command (git included) before _heartbeat_approval and 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

  • Letting an edition mount a heartbeat-only server the default spec does not carry: a name must also come from extra_mcp_servers(), so the default spec's governance applies.
  • A new McpToolingProvider method or a CONTRACT_VERSION bump: the mount list is read from the pins an edition already returns; a gate that cannot answer degrades to kirocrew-core alone.
  • Changing what the interactive or cron paths auto-approve; the read-only tier is untouched for every other session.
  • Heartbeat tools on a backend that publishes no _meta identity (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 in SlackEnterpriseGate.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.

Part What it does now
agent_materialization/worker_agent.py, platform/interfaces.py heartbeat_mirrored_servers() = kirocrew-core + the pins' @server/ prefixes (an unmounted name is skipped); an edition entry is copied minus autoApprove; the fingerprint covers it. heartbeat_safe_tools() documents the rule.
agent.py _write_heartbeat_spec logs the mounted edition servers and the withheld autoApprove; the prompt and spec description name _heartbeat_approval.
slack/gateway_runtime/tool_policy.py _is_heartbeat_safe_tool(event) keys on mcp_identity_trusted, tool_name, mcp_server_name: built-ins via hooks._is_host_read_only_builtin (the tier's own table, web_fetch / web_search included); seven kirocrew-core reads only on kirocrew-core (no cron_list: that server is not mounted); host shell: name_grant.program_names must establish the program set with no git in it, then is_read_only_bash; edition @server/tool pins. HEARTBEAT_SAFE_TOOLS is deleted (no reader). _build_heartbeat_hooks sets defer_reads_to_approver.
hooks.py, hook_runtime/gate_tiers.py HooksConfig.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_approval runs the name-grant check on an approved shell and audits the trusted server/tool. A deny with no trusted identity, or a trusted but empty tool_name (the cache-hit-on-empty-names shape a backend with no _meta channel produces), is audited no_trusted_identity and warns that the backend publishes none; other denies stay not_in_heartbeat_safe_tools.
docs/system-specs/modules, prepare-pr rationale.md, comments in session.py / hooks.py / platform/*.py the five module specs describe the rules and both deny reasons; harness-parity.md records 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 spec and _HEARTBEAT_SYSTEM_PROMPT digests re-pinned for the reworded strings (mcpServers and tools unchanged).

Why autoApprove is 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's kirocrew-core entry keeps it (rfc-owner-written-mcp-auto-approve).

Read-only shell is not new to heartbeat: on the base, _tier_read_only auto-approves is_read_only_bash commands for heartbeat before _heartbeat_approval runs (base heartbeat.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/config on every run, and core.fsmonitor / core.hooksPath name a program there that no text classifier can see. The exclusion is heartbeat's alone: _tier_read_only (cron, subagent, app sessions) and chat_runner.py trust-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 are test_heartbeat_safe_tools.py and test_slack_gateway_more_coverage.py, rewritten here; test_slack_gateway_composition_contract.py pins the signature. HEARTBEAT_SAFE_TOOLS had no reader outside tool_policy.py, the gateway.py re-export and those tests. A standalone heartbeat spec mounts the same servers and tools; only its description changes.

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 heartbeat git command; a heartbeat MCP call the gate approved on kind="read" or a read-shaped title; heartbeat tool use on a backend with no _meta identity.

Reader: slack/gateway.py:_heartbeat_approval -- heartbeat -- reads the event, not the title; TestHeartbeatApproval, TestHeartbeatShellNameGrant
Reader: llm_helpers.py:_resolve_permission -- heartbeat -- HOOK_BASED path unchanged; a deferred read falls to on_tool_approval; test_the_read_only_tier_gives_no_verdict
Reader: 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.py
Reader: agent_materialization/worker_agent.py:_require_fresh_heartbeat_spec -- heartbeat -- derives through heartbeat_mirrored_servers(); test_an_edition_change_to_a_mirrored_server_is_caught_at_spawn
Reader: agent.py:_HEARTBEAT_SYSTEM_PROMPT and the spec description -- heartbeat -- name _heartbeat_approval as the gate; test_heartbeat_cycle_recycle.py
Reader: heartbeat.md, slack-gateway.md, platform-context.md, harness-parity.md -- release -- rewritten here

Tests

test_heartbeat_safe_tools.py (rewritten): a trusted built-in approves, read alias included; untrusted identity, empty trusted identity and a forged title deny; a built-in name with a server attached denies; trusted web_fetch / web_search approve; core reads approve only on kirocrew-core and cron_list on any server denies; read-only shell approves, mutating or unrecoverable denies, every git form denies; an MCP tool declaring execute is judged on its pin; edition pins need the trusted pair; the audit row carries server/tool; an untrusted deny, and a trusted deny with an empty tool_name, are audited no_trusted_identity with a backend warning, a trusted write deny not_in_heartbeat_safe_tools; TestRecordedWire replays 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 as no_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 minus autoApprove and 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_denies covers ;, &&, |, newline, (git ...), FOO=1 git ..., /usr/bin/git and GIT; test_untokenizable_command_denies covers an unclosed quote. test_cpp_wiring_standalone.py pins the empty default; test_slack_gateway_more_coverage.py pins 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_spec writes a JSON spec) and pure approval functions; the tests run them against a real temp agents directory and a real AcpEvent.

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

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 01:30
@bolichen97
bolichen97 requested a review from mbriones98 October 14, 2026 01:30
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/hook_runtime/gate_tiers.py

  • src/kiro_crew/hooks.py

  • @bolichen97 posted a complete reasoning template for 305bed4.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: bf2d758
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when is_read_only_bash passes AND command_invokes_git is false, then only after name_grant.refusal_for_event is clean. readonly_bash.py itself gains command_invokes_git and one shared _SEGMENT_SEPARATOR_RE; _classify_bash behaviour is unchanged (same regex, now a named constant).
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (66 tests: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /), test/test_readonly_bash_git_exclusion.py, test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on bf2d758).
  • How to undo: revert the single commit bf2d758; no data, config key or on-disk format changes, so nothing migrates back.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 305bed422768493b4bf67797a193d44e2c8cbc21 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 305bed4

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 305bed422768493b4bf67797a193d44e2c8cbc21: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 305bed422768493b4bf67797a193d44e2c8cbc21 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from bf2d758 to c0430e5 Compare October 14, 2026 01:50
@bolichen97

Copy link
Copy Markdown
Contributor Author

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).

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: c0430e5
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when is_read_only_bash passes AND command_invokes_git is false, then only after name_grant.refusal_for_event is clean. readonly_bash.py itself gains command_invokes_git and one shared _SEGMENT_SEPARATOR_RE; _classify_bash behaviour is unchanged (same regex, now a named constant).
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (66 tests: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /), test/test_readonly_bash_git_exclusion.py, test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on c0430e5 (re-run after rebase onto ab333e6)).
  • How to undo: revert the single commit c0430e5; no data, config key or on-disk format changes, so nothing migrates back.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ human override accepted

@bolichen97 overrode this lane for 305bed422768493b4bf67797a193d44e2c8cbc21 via /ai-review override (this commit only).

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ human override accepted

@bolichen97 overrode this lane for 305bed422768493b4bf67797a193d44e2c8cbc21 via /ai-review override (this commit only).

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 305bed422768493b4bf67797a193d44e2c8cbc21 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 305bed4

Verdict parsed from the review's SHA-scoped output markers for commit 305bed422768493b4bf67797a193d44e2c8cbc21.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 305bed422768493b4bf67797a193d44e2c8cbc21: <one-sentence reason>

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 4 — heartbeat tool approval on backends with no _meta identity span=9d15cc1cdc36

rebutted: the premise is confirmed in code, not asserted. AcpEvent.mcp_identity_trusted is set only from a tool_call-frame cache hit (acp/_dispatch.py:2435), and the caches are filled from classify_tool_call / _meta_identity_full, whose channel table _MCP_IDENTITY_META_CHANNELS (_dispatch.py:3293-3330) has three rows: _meta.kiro (KAS spelling), _meta.kiro (kiro-cli spelling) and _meta.goose.toolCall; codex-acp is read through its _meta.is_mcp_tool_call marker in classify_tool_call.
claude-agent-acp and opencode have no row and no marker: classify_tool_call's own contract (_dispatch.py:1411-1412) records that they send kind="other" with no identity, and harness_tool_name reads opencode's first-frame title only into harness_tool_id, never into the MCP identity pair. So on those two backends every heartbeat event arrives with mcp_identity_trusted=False.
The take-away is deliberate and recorded: ## Backwards compatibility lists it under "What stops working", ## Not a goal names it, and docs/system-specs/modules/heartbeat.md states heartbeat runs text-only there. On base those backends approved Read/Grep on the model-written title alone, which is the defect this PR fixes; keeping a title fallback for them would keep the defect for exactly the backends that cannot prove a tool's identity.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 14, 2026
@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from c0430e5 to ca53368 Compare October 14, 2026 02:32
@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 Oct 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: a derived HEARTBEAT_SAFE_TOOLS frozenset kept as a read-only view after the decision moved into _is_heartbeat_safe_tool

  • Item 10 — HEARTBEAT_SAFE_TOOLS rebuilt as a derived constant nothing reads span=6d384a0164dc

fixed in ca53368: the constant, its tool_policy.py module-level _HOST_READ_ONLY_BUILTIN_TOOLS import and the slack/gateway.py re-export are deleted (subtraction, as the lane proposed). Every remaining mention in prompts, docstrings, log strings and docs names _heartbeat_approval's allowlist instead; grep -rn HEARTBEAT_SAFE_TOOLS src test docs website .github is empty on that head.
Tests: TestHeartbeatSafeTools is rewritten over the two sets that remain (_HEARTBEAT_SAFE_CORE_MCP_TOOLS with each read's owning server; _HEARTBEAT_EXCLUDED_BUILTIN_TOOLS == {"web_fetch","web_search"} and a subset of hooks._HOST_READ_ONLY_BUILTIN_TOOLS); test_heartbeat_cycle_recycle.py asserts the spec description names _heartbeat_approval; the composition-contract rows for the constant are removed.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A non-Kiro backend's heartbeat warns that all its tool calls will be denied, not only in SEL rows

fixed in ca53368: _heartbeat_approval's deny path now tells the two cases apart per call. An event with no trusted identity (event.mcp_identity_trusted is False, which is every call on claude-agent-acp / opencode) is audited reason=no_trusted_identity and logs Heartbeat blocked tool call: <label> (this backend published no trusted tool identity, so every heartbeat tool call is denied on it; heartbeat runs text-only here); a trusted call outside the allowlist keeps reason=not_in_heartbeat_safe_tools and the allowlist warning.
Per call rather than once per session: the deny path holds no state, and a heartbeat on such a backend attempts few tool calls per cycle (the prompt tells it a denied tool is a wasted turn), so the warning stays legible; the operator reading SEL sees the reason on every row. test_untrusted_deny_warning_names_the_backend_condition and test_rejects_trusted_write_tool pin both branches; heartbeat.md and slack-gateway.md list both reasons.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_slack_gateway_coverage.py since this head went green (ab333e6 -> 328f749); CI re-running. This head also carries the round-1 fixes (HEARTBEAT_SAFE_TOOLS removed; distinct no_trusted_identity deny reason).

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: ca53368
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when is_read_only_bash passes AND command_invokes_git is false, then only after name_grant.refusal_for_event is clean. readonly_bash.py itself gains command_invokes_git and one shared _SEGMENT_SEPARATOR_RE; _classify_bash behaviour is unchanged (same regex, now a named constant). The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (66 tests: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /), test/test_readonly_bash_git_exclusion.py, test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on ca53368 (re-run after rebase onto 328f749; 1506 related tests green)).
  • How to undo: revert the single commit ca53368; no data, config key or on-disk format changes, so nothing migrates back.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 14, 2026
@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from ca53368 to 669e6e4 Compare October 14, 2026 02:44
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_security_gate_liveness.py (_PACKAGE_LINE_BUDGET re-summed: 29,165 + 27 = 29,192) and docs/system-specs/modules/platform-context.md since this head went green (328f749 -> 2f5c7d5); CI re-running.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 669e6e4
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when is_read_only_bash passes AND command_invokes_git is false, then only after name_grant.refusal_for_event is clean. readonly_bash.py itself gains command_invokes_git and one shared _SEGMENT_SEPARATOR_RE; _classify_bash behaviour is unchanged (same regex, now a named constant). The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (66 tests: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /), test/test_readonly_bash_git_exclusion.py, test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on 669e6e4 (re-run after rebase onto 2f5c7d5; 755 related tests green after the re-sum)).
  • How to undo: revert the single commit 669e6e4; no data, config key or on-disk format changes, so nothing migrates back.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 14, 2026
@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from 669e6e4 to c9cf7f2 Compare October 14, 2026 03:08
@bolichen97

Copy link
Copy Markdown
Contributor Author

New head d21b4b4 (base ae9e29e, +7 since c46a1dc, no file this PR touches): round-5 from the Opus finding on eccad68 -- _heartbeat_approval classifies a deny as no_trusted_identity when the trusted flag is set but the tool name is empty (the shape a backend with no _meta channel produces), and TestRecordedWire replays the recorded kiro / claude / opencode permission frames through the gate. Docs state the condition; the description adds the web_fetch / web_search rationale and the read-only-shell provenance. 630 related tests green incl. both digest suites and test_acp_frame_replay.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: d21b4b4
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when name_grant.program_names establishes its program set with no program whose basename is git (any position, any case) AND is_read_only_bash passes, then only after name_grant.refusal_for_event is clean. security/readonly_bash.py is byte-identical to origin/main. The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity or a trusted but empty tool_name, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it. Core MCP reads are matched only on kirocrew-core (cron_list, served by a server heartbeat does not mount, is not listed), and the servers heartbeat mounts are the @server/ prefixes of the edition's heartbeat_safe_tools() pins -- no new McpToolingProvider method.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (67 passed: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /, an unclosed quote denied), test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on d21b4b4 (re-run on base ae9e29e after round 5; 630 related tests green incl. TestRecordedWire replays and test_acp_frame_replay incl. test_security_gate_liveness at main's budget and test_name_grant)).
  • How to undo: revert the single commit d21b4b4; no data, config key or on-disk format changes, so nothing migrates back.

@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from d21b4b4 to cb63378 Compare October 14, 2026 06:34
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — text-only heartbeat on claude-agent-acp / opencode "comes from a table choice" span=6c90e05344ae

rebutted. The table choice is the platform's rule, not this PR's: ACP_BACKENDS_META_IDENTITY / _MCP_IDENTITY_META_CHANNELS admit a harness only on a recorded corpus per tool class (agent_sdk/backends.py: "a row and its membership cannot drift apart ... the pin then checks it against its own recordings"), and #19059 deliberately did not add a claude row: it reads _meta.claudeCode.toolName only on a Side Chat session the harness itself launched read-only (claude-code-provider.md, "A Side Chat session"), where the harness config, not the stamp, carries the read-only promise. Heartbeat has no such launch profile on claude, so trusting the stamp there would be the identity-table addition that spec forbids without a corpus. This PR records exactly that, and the way back, in harness-parity.md.
The maintainer decision is recorded in that spec and was taken by @bolichen97 when commissioning this takeover (full redo including the approval path; text-only heartbeat on those two backends named as the consequence). What base approved there was a model-declared kind="read" through the read-only tier on a session with no approver -- the defect this PR closes, so "base had heartbeat tool approvals on those backends" is the bug, not a capability to preserve. If the lane's own Clears when wording is wanted verbatim, it is one /ai-review override first-principles <head>: ... for the maintainer; the agent does not author product-shape overrides.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: cb63378 is d21b4b4 replayed onto main 370b190 (+1 commit, #17540, which touches platform/defaults.py far from the one comment line this PR changes there). Patch identical; 593 related tests incl. both digest suites green. Design PASS on d21b4b4; First Principles item 7 answered by disposition.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: cb63378
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when name_grant.program_names establishes its program set with no program whose basename is git (any position, any case) AND is_read_only_bash passes, then only after name_grant.refusal_for_event is clean. security/readonly_bash.py is byte-identical to origin/main. The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity or a trusted but empty tool_name, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it. Core MCP reads are matched only on kirocrew-core (cron_list, served by a server heartbeat does not mount, is not listed), and the servers heartbeat mounts are the @server/ prefixes of the edition's heartbeat_safe_tools() pins -- no new McpToolingProvider method.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep approve only as trusted built-ins with no server; core reads approve only from their owning server; web_fetch/web_search and every git invocation are denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (67 passed: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /, an unclosed quote denied), test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on cb63378 (re-run on base 370b190 after the rebase; 630 related tests green incl. TestRecordedWire replays and test_acp_frame_replay incl. test_security_gate_liveness at main's budget and test_name_grant)).
  • How to undo: revert the single commit cb63378; no data, config key or on-disk format changes, so nothing migrates back.

@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from cb63378 to df847c2 Compare October 14, 2026 06:46
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 4 — web_fetch / web_search exclusion goes beyond the Goal and contradicts the charter span=911bf4b4e607

fixed in df847c2, as the subtraction asked: _HEARTBEAT_EXCLUDED_BUILTIN_TOOLS is deleted, the host built-in branch is hooks._is_host_read_only_builtin on the trusted name alone, and the five _HOST_READ_ONLY_BUILTIN_TOOLS spellings approve on heartbeat as the read-only tier approved them on the base (test_trusted_web_builtins_approve). The charter line "an external page state" stands unchanged. heartbeat.md (allowlist sentence + constants row) and slack-gateway.md (both rows) drop the set; the description's egress paragraph is gone and its "What stops working" list no longer names the two tools.

@bolichen97

Copy link
Copy Markdown
Contributor Author

accepted-and-deferred, standing since round 3: #20105 (deferred-finding, @bolichen97, Due: 2026-11-14) owns the classifier-level question for _tier_read_only and the two chat_runner.py trust-read sites. The heartbeat clause stays: it is the one approval path with no human behind it that polls repositories it did not choose, and git's core.fsmonitor / core.hooksPath run a program from .git/config on the first git status. Dropping the clause here would re-open that on the approver-less session until #20105 lands; the one-line program check costs nothing to keep and is covered by test_every_git_invocation_denies on every spelling the corpus has. The description names the exclusion as heartbeat-only and names both sibling sites.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Silent capability loss on claude-agent-acp / opencode; warn once at start or record why per-call is enough span=4487168f6d87

fixed in df847c2 via the second clause: docs/system-specs/modules/harness-parity.md ("Heartbeat tools on a harness with no adapter-authored tool identity") records why the signal is per call -- each no_trusted_identity row and warning is derived from the event the gate decided, so it cannot drift; and the positive set a start-time warning would key on, ACP_BACKENDS_META_IDENTITY, deliberately omits kiro-cli (membership requires a recorded corpus per tool class, agent_sdk/backends.py), so a start-time warning keyed on it would fire on the default harness. The maintainer decision itself is recorded in the same section and was taken by @bolichen97 when commissioning this takeover.

@bolichen97

Copy link
Copy Markdown
Contributor Author

New head df847c2 (same base 370b190): round-6 subtraction from the First Principles verdict on cb63378 -- _HEARTBEAT_EXCLUDED_BUILTIN_TOOLS is deleted, so trusted web_fetch / web_search approve on heartbeat as the read-only tier approved them on the base, matching the charter line "an external page state". harness-parity.md records why the no-identity signal is per call. 461 related tests green. Opus/GPT lanes on cb63378 are superseded.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: df847c2
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when name_grant.program_names establishes its program set with no program whose basename is git (any position, any case) AND is_read_only_bash passes, then only after name_grant.refusal_for_event is clean. security/readonly_bash.py is byte-identical to origin/main. The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity or a trusted but empty tool_name, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it. Core MCP reads are matched only on kirocrew-core (cron_list, served by a server heartbeat does not mount, is not listed), and the servers heartbeat mounts are the @server/ prefixes of the edition's heartbeat_safe_tools() pins -- no new McpToolingProvider method.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep/web_fetch/web_search approve only as trusted built-ins with no server; core reads approve only from their owning server; every git invocation is denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (67 passed: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /, an unclosed quote denied), test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on df847c2 (re-run after the round-6 subtraction; 461 related tests green; 630 related tests green incl. TestRecordedWire replays and test_acp_frame_replay incl. test_security_gate_liveness at main's budget and test_name_grant)).
  • How to undo: revert the single commit df847c2; no data, config key or on-disk format changes, so nothing migrates back.

…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>
@bolichen97
bolichen97 force-pushed the takeover/10158-heartbeat-edition-mcp branch from df847c2 to 305bed4 Compare October 14, 2026 07:12
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: 305bed4 is df847c2 replayed onto main beb3c40 (+4 test-only commits; the one overlap is test/test_mcp_apply.py, which imports a module this PR touches and passes on the new base). Patch identical; 656 related tests green. The review lanes on df847c2 all failed at 06:49Z on the GitHub installation rate limit ("API rate limit exceeded for installation"), so this push is also their re-run.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 305bed4
  • What rule changed: three heartbeat-only approval rules. (1) _is_heartbeat_safe_tool decides on the event's trusted _meta.kiro identity (mcp_identity_trusted, tool_name, mcp_server_name), never on the model-authored title. (2) The heartbeat-scoped HookManager sets HooksConfig.defer_reads_to_approver, so _tier_read_only gives no verdict for that one session and the call falls to _heartbeat_approval. (3) A heartbeat shell command is approved only when name_grant.program_names establishes its program set with no program whose basename is git (any position, any case) AND is_read_only_bash passes, then only after name_grant.refusal_for_event is clean. security/readonly_bash.py is byte-identical to origin/main. The deny path audits no_trusted_identity (and warns that the backend publishes no identity) when the event carries no trusted identity or a trusted but empty tool_name, else not_in_heartbeat_safe_tools; the dead HEARTBEAT_SAFE_TOOLS constant is deleted, so no approval reads it. Core MCP reads are matched only on kirocrew-core (cron_list, served by a server heartbeat does not mount, is not listed), and the servers heartbeat mounts are the @server/ prefixes of the edition's heartbeat_safe_tools() pins -- no new McpToolingProvider method.
  • Before -> after (what was allowed/blocked, now): Before: heartbeat approved any title spelled Read/Grep/Glob/WorkspaceSearch or @server/<allowlisted-name> with no identity check; the gate's read-only tier auto-approved heartbeat MCP calls on kind="read", read-shaped titles, and every read-only shell command (git included) before _heartbeat_approval ran. After: a heartbeat call with no trusted identity is denied; fs_read/glob/grep/web_fetch/web_search approve only as trusted built-ins with no server; core reads approve only from their owning server; every git invocation is denied; an edition @server/tool pin approves only on the trusted pair. Every other session's gate (interactive, cron, subagent, app) is untouched: defer_reads_to_approver defaults to False and is never read from config.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): too narrow -> a heartbeat task is denied a read it used to get (visible as SEL denied rows + Heartbeat blocked tool call warnings; heartbeat only reports, nothing else is locked out). Too wide -> an edition tool could run unattended; guarded by deny-by-default on every branch, the owning-server match, the autoApprove strip on edition entries, and the spawn gate verifying the heartbeat spec against the default spec.
  • Evidence checked (which sandbox result proves it): test/test_heartbeat_safe_tools.py (67 passed: untrusted/empty identity denied, forged title denied, builtin-with-server denied, wrong-server core read denied, every git form denied, name-grant refusal denied, deferred read-only tier still denies rm -rf /, an unclosed quote denied), test/test_heartbeat_spec_freshness.py (edition entry copied minus autoApprove; spawn gate re-derives on edition change), test/test_gate_tiers.py + test/test_hooks.py (interactive read-only tier unchanged). Local lanes gpt-6.1-sol and claude-opus-5.5: no findings on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): scripts/local-gate.py backend related set: 30043 passed; the 19 failures (test_acp_spawn_offload, test_auto_improvement_members, test_browser_launcher) reproduce identically on a clean origin/main worktree (host env, not this diff). black / isort / flake8 / mypy (2309 files) / semgrep diff scan / flake-pattern ratchet: clean.
    • Backward compatible (old config / old data / old callers still work, how checked): standalone heartbeat spec is byte-identical (test_a_standalone_install_mirrors_core_only); an older companion without heartbeat_mcp_server_names degrades to core only (test_an_older_companion_without_the_seam_degrades_to_core); HooksConfig.from_dict never sets the new flag; _is_heartbeat_safe_tool has one production caller, changed here (writer sweep in the PR body).
    • Existing tests (which suites passed on this head): test_hooks, test_gate_tiers, test_hooks_composition_contract, test_slack_gateway_composition_contract, test_worker_agent, test_security_gate_liveness, test_security_posture, test_agent, test_heartbeat_, test_mcp_custom_api, test_prepare_pr_ (all green locally on 305bed4 (re-run on base beb3c40 after the rebase; 656 related tests green; 630 related tests green incl. TestRecordedWire replays and test_acp_frame_replay incl. test_security_gate_liveness at main's budget and test_name_grant)).
  • How to undo: revert the single commit 305bed4; no data, config key or on-disk format changes, so nothing migrates back.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/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 no_trusted_identity audit + warning) and the way back are recorded in docs/system-specs/modules/harness-parity.md, "Heartbeat tools on a harness with no adapter-authored tool identity".

@bolichen97

Copy link
Copy Markdown
Contributor Author

/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 no_trusted_identity audit row and warning are the intended signal (a start-time warning would key on ACP_BACKENDS_META_IDENTITY, which deliberately omits kiro-cli), as recorded in docs/system-specs/modules/harness-parity.md.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 305bed422768493b4bf67797a193d44e2c8cbc21.

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 no_trusted_identity audit + warning) and the way back are recorded in docs/system-specs/modules/harness-parity.md, "Heartbeat tools on a harness with no adapter-authored tool identity".

This decision applies only to this commit. A new push requires a new judgment.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the design AI finding as false positive, not applicable, or explicitly accepted for 305bed422768493b4bf67797a193d44e2c8cbc21.

agent: on @bolichen97's explicit authorization -- text-only heartbeat on claude-agent-acp / opencode is accepted by the maintainer; the per-call no_trusted_identity audit row and warning are the intended signal (a start-time warning would key on ACP_BACKENDS_META_IDENTITY, which deliberately omits kiro-cli), as recorded in docs/system-specs/modules/harness-parity.md.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 14, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 14, 2026 07:42
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 305bed4: reserved for human review.

This PR changes how the unattended heartbeat agent approves tools. _is_heartbeat_safe_tool now decides on the adapter-stamped identity (tool_policy.py#L184-L271). The read-only tier is turned off for heartbeat through a new HooksConfig.defer_reads_to_approver (gate_tiers.py#L1102, hooks.py#L712). Edition MCP servers are now mounted on the heartbeat spec. Approval, identity and hook-gate changes need a human reviewer, however sound the code looks. I found no concrete regression: every branch denies by default, a forged title no longer approves, and autoApprove is stripped from edition entries.

To clear: a maintainer reviews the sensitive files above, and the author answers the current-head Security Scope CONCERNS with a target=scope disposition. That disposition should confirm that dropping cron_list and every git command from heartbeat is intended, and that the recorded-wire tests cover each backend's real _meta.kiro spelling. The Windows git.exe bypass the lane raises does not hold by my reading, because is_read_only_bash normalizes the verb the same way and does not treat git.exe as read-only. It still needs a reply on the PR. CI is green on this head. No tests were run locally.

— crew-pr-reviewer (r100)

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

Checks green and PR Readiness passed at 305bed4; non-feature change.

@bolichen97
bolichen97 merged commit 824c6c7 into main Oct 14, 2026
107 of 110 checks passed
@bolichen97
bolichen97 deleted the takeover/10158-heartbeat-edition-mcp branch October 14, 2026 17:02
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Heartbeat agent never mounts edition MCP servers; approval keys on the model-authored title

3 participants