Repository navigation
✨ feat(adminmcp): read and act on the Activity monitor; writes run as the verified caller - #16884
Conversation
… the verified caller
stage_tracker_read returns the board the Activity monitor draws
(GET /api/stage-tracker) with its filters and search box, and
delegated_decision_status reads a "Let hive decide" job. The monitor's
row actions are write operations under the preview/confirm contract:
repository.rescan and repository.item_{accept_triage,needs_human,
blocker_recheck,blocker_handoff,blocker_close_partial,decision,delegate}.
The merge answers (merge-now, queue-merge) are refused like
queue-automerge (hivecommons#8697), and repository.item_delegate sends the new
no_merge flag so a merger's delegated approval never queues an
auto-merge.
On the HTTP endpoint a confirmed write now runs as the identity
authenticate verified on the /api/admin/mcp request instead of
re-authenticating with the dashboard token alone, so hub-proxied and
session callers can write and are attributed. A pending confirmation is
bound to the actor that previewed it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
…hosted hives The guide only described the dashboard token, which a hub-hosted hive does not hand to its users and which acts as the owner. Add an Authentication section: hub-hosted hives take Authorization: Bearer <GitHub token> (checked against GitHub /user, then the caller's role on the hive), self-hosted hives the dashboard token, allowlist spokes a session cookie. Client configs for Claude Code (headersHelper) and omp (!command, run through /bin/sh -c) read a fine-grained, no-permission token from a file at connect time. Adds a 401/403 troubleshooting entry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
There was a problem hiding this comment.
Correctness review (head 6d5ed25). The write-identity change checks out: adminMCPWriteRequest (src/pkg/dashboard/admin_mcp.go:315-329) only re-emits the identity authenticate already set on the outer request (server.go:2186-2188 strips inbound copies first), roleEnforcement still gates read-only roles on the inner POST (server.go:2844-2866), and TestAdminMCPWritesRunAsVerifiedCaller exercises hub-proxied, bearer and internal paths end to end. no_merge is a pure narrowing (api_repo_item_decide_delegated.go:288) and executeDelegatedDecision takes the /lgtm+/approve branch for mergerRole=false (:1024, :1099). No blocker.
One low-severity gap worth closing:
Board unavailability reads as "not on the board" — handleStageTracker answers 200 {"status":"initializing"} before the first snapshot (stage_tracker_build.go:1048-1051) and 503 while a build is in progress (:1056). StageTrackerReadResult (tools_stage_tracker.go:111-114) accepts the initializing body as a board with zero items and drops the status key, so stage_tracker_read reports matched: 0, total_items: 0 as if the monitor were empty. stageTrackerItem (tools_stage_tracker.go:702-712) swallows any provider error and returns nil, so every item preview then says "This item is not on the Activity monitor now" (boardDetails, :721) when the real cause is that the board could not be read. Suggested fix for the read tool:
body, ok := data.(map[string]any)
if !ok {
return CapResult(data, LimitFromArgs(args)), nil
}
if _, hasItems := body["items"]; !hasItems {
if st := stringField(body, "status"); st != "" {
return refuse("the Activity monitor is " + st + "; retry shortly")
}
}
and in boardDetails, distinguish a failed read (stageTrackerItem returning an error, or a sentinel) from a genuine miss so the preview says the board was unavailable rather than that the item is absent.
— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
Same content, easier to follow: a page index; transports, quick start and authentication first; client configs grouped by client (Claude Code, omp, other HTTP, stdio) and by hive type; the stdio binary split into getting it, keeping it current, skew notice and environment; the tool table split by area with long cells moved to numbered notes; start-record verdicts and write operations as tables; troubleshooting as symptom/fix. Headings other docs link to are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
Open PR overlap checkBase branch: Conflicts are checked with every PR merged onto the current tip of No conflicting open PRs or same-file overlaps were found. |
There was a problem hiding this comment.
Decision needed: @clubanderson should decide whether admin MCP may make a pull request merge-eligible (item_decision approve / item_delegate post /lgtm + /approve, which the merge sweep then merges) given the catalogue's categorical exclusion of queue-automerge as the only merge-causing action.
Routing to a human: this is a merge-policy boundary, not a code defect. The code I read is consistent and tested; the question is whether it should exist.
What I verified in the tree (head 76b2bb7):
- Writes now run as the verified caller instead of re-authenticating with the bearer token.
src/pkg/dashboard/admin_mcp.go:314(adminMCPWriteRequest) skipsauthenticateand setsX-Hive-User/X-Hive-Rolefromprovider.user/role. Those come fromhandleAdminMCP(admin_mcp.go:61) reading headers thatauthenticate(server.go:2186) had already stripped and re-set only from a proof-bearing proxy, a live session, or the token;/api/admin/mcpis registered on the authenticated mux (server.go:1827) andproxyProofRequireddefaults to true (server.go:99). The owner marker is forwarded only when the outer request was verified owner (admin_mcp.go:325), covered byTestAdminMCPWriteCarriesOwnerMarkerOnlyWhenVerified. This is sound. - Confirmations are bound to the previewing actor.
adminmcp.go:545refuses a confirm from a different actor and puts the pending record back. Note thatTakethenPutis not atomic: a mismatched confirm racing the real one can turn the real one intoErrConfirmationMissing. Low; the owner just previews again. - The merge exclusion is enforced for
merge-now/queue-merge(tools_stage_tracker.go:521) anditem_delegatealways sendsno_merge(tools_stage_tracker.go:616), whichapi_repo_item_decide_delegated.go:288honours by dropping the merger role.
The question: item_decision approve on a PR posts /lgtm + /approve, and the preview says so plainly — "the hive's merge sweep merges it once CI is green and the head has soaked" (tools_stage_tracker.go:548). The new exclusion entry (adminmcp.go:111) argues this is different from queueing a merge. Today no admin MCP operation can make a PR merge-eligible (lgtm appears only in the new file); after this PR an MCP client can, and the result is a merge without a further human action. Whether "merge-eligible, sweep merges" falls inside or outside the "only action that directly causes a merge into real code" exclusion is the maintainers' call. For the record, the author is listed under approvers: in OWNERS, so the role being exercised is one they already hold.
Everything else (stage tracker read, delegated status read, docs) I read only at the wiring level; CI was still running when I looked.
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
Needs a decision, not a merge:
Head: verdict requires_human @878103d, 48/54 checks green, 6 pending, DCO yes, soak 0s of 10m0s. How to release it:
Clear the cause and the hive re-evaluates on its next pass; the stage moves to Updated 2026-11-06 15:46 UTC. |
…fore take Review on hivecommons#16884: - stage_tracker_read treated the endpoint's {"status":"initializing"} answer as a board with no items. It now returns a board_unavailable refusal, and an item preview that cannot read the board says so (on_board "unknown") instead of "not on the Activity monitor". - write_confirm took a mismatched actor's confirmation and put it back, which could race the owner's confirm. It now checks the actor first and never takes another caller's confirmation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
|
Thanks. Both findings are fixed in c5b17dc.
The approve question routed to @clubanderson is a policy decision, so I'm leaving it to the people named in it. |
|
@Danathar this PR is back in your court ( Review asks:
Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path. Queued in your relay fix queue (10 waiting): fixes are handed out before new work as soon as you have capacity. |
There was a problem hiding this comment.
Intent alignment (read at head c5b17dc)
The diff does what the title and body claim, and I found no gap between them:
- Writes run as the hive-verified caller:
pkg/dashboard/admin_mcp.go:315-328(adminMCPWriteRequest) re-setsX-Hive-User/X-Hive-Rolefrom the provider, whose values come from headersauthenticatealready stripped and re-derived (pkg/dashboard/server.go:2186-2188, then 2197-2432). The owner marker is forwarded only whenownerVerified && isOwnerRole(admin_mcp.go:325-327). - Merge answers are refused before any request (
pkg/adminmcp/tools_stage_tracker.go:66,549-551);item_delegatealways sendsno_merge(tools_stage_tracker.go:647), and the endpoint narrowsmergerRolewith it (api_repo_item_decide_delegated.go:288). - The deleted
TestAdminMCPWritePreviewFailsFastWithoutDashboardBeareris replaced byadmin_mcp_activity_test.go:71-160.
One scope note (non-blocking): commit 76b2bb7 "reorganise the guide for people reading it" rewrites 499/347 lines of src/docs/admin-mcp.md with no behavioural tie to the Activity monitor feature. It is disclosed in the body and isolated in its own commit, but under a squash merge that isolation is lost and the feature's doc changes become hard to review against the reorg. Consider landing the reorg as its own docs PR (or first), then rebasing this one onto it.
— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor. Review findings from docs-currency review (head c5b17dc) The guide, design record and changelog match the code I read: tool/op names, the One operator-facing text defect:
The design doc's "re-evaluate now | none beyond write access" row is correct ( Review findings from Conclusion: I found no defect in the code; the auth-path change does what the body says and the safeguards it relies on are real. What it changes is policy — who may write through admin MCP — and that is a maintainer call, not mine. Details below so the decision can be made without re-deriving them. What I verified (read at head
The decision Before: a confirmed admin-MCP write re-authenticated with the dashboard token only, so in practice only the token holder (recorded as the configured owner) could write, and direct-route spokes refused writes outright. After: any identity
|
…cker src/docs/admin-mcp.md: kept the reorganized guide and carried over v6's changes to it: ping and notification answers (hivecommons#16893), version_read hash/short (hivecommons#16890), settings_read takes no limit and the triggers section (hivecommons#16892), What a read masks (hivecommons#16889), and write tools always listed with metadata.preview.enabled (hivecommons#16890); the troubleshooting row follows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
…r's repo permission Pins the decision on approve: it stays, constrained to the caller's own rights. Through the full auth chain into the real decision route, a caller with read access on the repository is refused with "write permission required" and nothing is written; a caller with write access approves, and the /lgtm comment names them. The guide's "Who a write runs as" says the same. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
|
Decision on the open question (may the admin MCP make a pull request merge-eligible): yes, as long as it is held to the rights of the person operating the MCP. That is how it works on this branch, and e38fc6b pins it with a test.
|
|
Maintainer approval (@Danathar): I approve this change. It can go forward once CI is green on the current head ( My earlier comment covers the open question about approve: it stays, held to the operator's own permissions, and |
The repository.rescan preview said "the next one is queued", but handleReposRescan never queues: a running scan answers in-progress and one finished under 30 s ago answers debounced with retry_after_s, both no-ops. Use the hive reviewer's wording (adjudicator-3 on c5b17dc) and pin it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <Danathar@users.noreply.github.com>
|
The rescan preview finding from
|
There was a problem hiding this comment.
Decision needed: @clubanderson should decide whether confirmed admin-MCP writes may run on the identity authenticate verified for the outer /api/admin/mcp request (no re-authentication on the inner write), as this PR implements.
Routing to a maintainer rather than confirming: this changes how a confirmed admin-MCP write authenticates, which is a trust decision, not a code-correctness one. The author asks for a security review in the body, and I agree one is needed. What I verified on e38fc6b:
The new write identity is hive-verified, not client-asserted.
src/pkg/dashboard/admin_mcp.go:63-70— the provider'suser/role/ownerVerifiedare read from the outer request after it passedauthenticate.src/pkg/dashboard/server.go:2186-2188—authenticatedeletes inboundX-Hive-User,X-Hive-RoleandX-Hive-Owner-Role-Verifiedunconditionally, and re-sets them only once a hub-proxy proof (secureCompare(proof, s.authToken)) or a server-side session has been checked. So a client cannot smuggle an identity into the provider.src/pkg/dashboard/admin_mcp.go:323-337(adminMCPWriteRequest) — with a verified user+role, the inner write skipsauthenticateand goes straight toroleEnforcement → securityHeaders → muxwith those headers injected. With no verified identity it falls back to exactly the old path (re-enterauthenticatewith the caller'sAuthorization), so dashboard-token and open-spoke behaviour is unchanged.
no_merge can only narrow. src/pkg/dashboard/api_repo_item_decide_delegated.go:288 — mergerRole := !body.NoMerge && RoleAtLeast(..., RoleMerger) && …; the flag removes the merger path and never adds anything.
What a human has to decide, in one sentence: is it acceptable that a hub-proxied or session caller's outer authentication now authorises the inner confirmed write (bypassing authenticate on that hop), given every endpoint's own role check still runs via roleEnforcement and the pending-confirmation is bound to the previewing actor (PendingConfirmation.Actor)?
Two facts for that decision, no opinion attached:
- @Danathar is listed in
OWNERSas an approver, so the approval should come from a different approver. - The removed
TestAdminMCPWritePreviewFailsFastWithoutDashboardBearerencoded the old rule this PR deliberately reverses; its replacementTestAdminMCPWritesRunAsVerifiedCallercovers the new one.
I found no defect in the parts I read (the auth path, the no_merge flag, the provider wiring). I did not read tools_stage_tracker.go (~1k lines of filters/paging) line by line; CI is green on it.
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Decision needed: @clubanderson should decide whether the admin MCP may issue repository.item_decision with decision: approve — which posts /lgtm + /approve as the caller and lets the merge sweep merge the PR — given the PR's stated contract that admin MCP never merges.
I read the identity change and the write surface rather than the whole 684-line tracker file; no defect found in what I read, but this expands the admin MCP's merge-adjacent authority and that is a maintainer call.
What I verified
src/pkg/dashboard/admin_mcp.goadminMCPWriteRequest: a confirmed write now carriesX-Hive-User/X-Hive-Role/ the verified-owner marker copied from the outer request. Those headers are the onesauthenticateitself set — inbound copies are deleted atserver.go:2186-2188before any of the verified paths (:2197-2272) set them — so the inner request cannot run as an identity the client asserted. The pre-existing path (re-enterauthenticatewith the caller'sAuthorization) is kept for requests with no verified identity.src/pkg/adminmcp/adminmcp.go:PendingConfirmation.Actoris recorded at preview and compared beforeTakeand again after, so a confirmation previewed by one caller cannot be burned or executed by another (ErrConfirmationActor).tools_stage_tracker.go:553:merge-now/queue-mergeare refused at preview, anditem_delegatesendsno_merge: true(:647), whichapi_repo_item_decide_delegated.gohonours by clearingmergerRoleso a delegated approval never queues an auto-merge.admin_mcp_approve_permission_test.goshows a read-only caller's approve is refused by the decision route and a writer's approve is attributed to@writer.
The decision
The body's headline is "Never merges", and the MCP itself does not merge. But repository.item_decision with decision: approve is offered (tools_stage_tracker.go:582: "Posts /lgtm and /approve as your decision; the pull request becomes merge-eligible, and the hive's merge sweep merges it once CI is green"). The preview discloses this, and the permission check is the same one the dashboard's Approve button uses, so this is consistent — but it means an MCP client acting for a merger-role user can cause a merge one step removed, which queue-automerge's exclusion (#8697) was written to prevent. Whether that distinction is the intended line, or whether approve should join merge-now/queue-merge in the refusal list, is the one question a maintainer needs to answer before this lands.
I have not read the full stage-tracker read tool or the ~900 lines of docs changes.
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
Executive summary
The admin MCP can now read the Activity monitor and press its buttons.
stage_tracker_readreturns the board the Activity monitor draws (GET /api/stage-tracker): each item's stage, what it waits on, its decision question and options, linked PRs and issues, blocker, hold and needs-human state, plus a count per stage. It has the monitor's filters, including its search box, where a number matches the item or a linked item.delegated_decision_statusreads the outcome of a "Let hive decide".queue-automerge([RFC] [v6] Operator-facing admin MCP: administer a hive by conversation #8697). A delegated decision sent through admin MCP carries a newno_mergeflag, so a merger's delegated approval cannot queue an auto-merge either.What
stage_tracker_readGET /api/stage-trackerdelegated_decision_statusGET …/items/{n}/decide-delegatedrepository.rescanPOST /api/repos/rescanrepository.item_accept_triagePOST …/items/{n}/accept-triagerepository.item_needs_humanPOST /api/review/pipeline/{o}/{r}/{n}/send-to-humanrepository.item_blocker_recheck/_handoff/_close_partialPOST …/items/{n}/blocker/{recheck,handoff,close-partial}repository.item_decisionPOST …/items/{n}/decisionrepository.item_delegatePOST …/items/{n}/decide-delegatedwithno_mergerepository.item_hold(existing)POST …/items/{n}/holdrepository.item_decisiontakesapprove,direction,close-superseded,close-wontfix,close-read,close-issue,adopt,adopt-now,re-authorandreroute.merge-nowandqueue-mergeare refused before any request, and the exclusion catalogue records why.Why
issues_by_band,prs_by_band), not what the monitor shows: how long an item has sat, what it waits on, how issues and PRs link, and the decision options.adminMCPWritesUnavailableReasonrefused every write for such a caller ("admitted another way … a confirmed write would be refused with 401"), so no write tool worked there at all.How
pkg/adminmcp/tools_stage_tracker.go:StageTrackerReadResultfilters, trims (view=summarykeeps the row's fields;fullkeeps all) and pages. Stage counts always cover the whole board.qfilter followstracker-filter.jsstageTrackerMatches.stageTrackerActionRequestintracker-actions.jssends.Writes run as the verified caller (
pkg/dashboard/admin_mcp.go):adminMCPWriteRequestserves the confirmed write throughroleEnforcement → securityHeaders → mux. It carries the user, role and verified-owner marker thatauthenticateset on the outer/api/admin/mcprequest, the same ones the read tools already carry.authenticatestripped inbound copies before the outer request reached the handler. A dashboard-token caller still runs as the configured owner, as before.Confirmation bound to the previewer (
pkg/adminmcp):PendingConfirmation.Actorrecords who previewed. A confirm from anyone else returnsErrConfirmationActorand puts the confirmation back unused.no_merge(api_repo_item_decide_delegated.go): a request withno_mergedecides without the merger role. An approval then takes the/lgtm+/approvepath instead of an Approve review queued for auto-merge. The flag can only narrow what the caller's role allows.Stdio (
cmd/hive-admin-mcp): routes the two new read tools. Its writes still use the dashboard token.Docs:
docs/admin-mcp.mdanddocs/design/admin-mcp.mdnow cover the tools, the write identity, the new exclusion, and the attribution gap, which is narrowed for the HTTP endpoint.Authentication docs (
docs/admin-mcp.md): the guide described only the dashboard token, which a hub-hosted hive does not hand to its users. A new Authentication section covers each deployment:Authorization: Bearer <GitHub token>. The hub checks the token against GitHub/user, then the caller's role on the hive (pkg/hub/saas_auth.go:599-626).It adds Claude Code (
headersHelper) and omp (!command) configs that read a fine-grained token with no repository permissions from a file at connect time, plus a 401/403 troubleshooting entry.Guide reorganized for readers (
docs/admin-mcp.md, separate commit): the content is the same; only the order and layout change.Tests
TestStageTrackerReadFilters(11 rows),…StageCountsDescribeWholeBoard,…SummaryAndFullViews,…PagesAndRecent,…RefusesBadArgumentsTestItemOpsSendTheDashboardRequests,TestItemDecisionRequests,TestItemDelegateNeverMerges,…NestedPRsAndRerunTestItemDecisionRefusals,TestIssueOnlyOpsRefusePullRequests,TestBoardReadFailureNeedsExplicitTypeTestItemDecisionConfirmRecheckNeedsNoBoardConfirmWrite's provider-less re-check still matchesTestConfirmationIsBoundToThePreviewingActor,TestPendingActorPersistsTestAdminMCPWritesRunAsVerifiedCallerauthenticate: hub-proxied alice writes as alice; bob cannot confirm hers; bearer and internal still workTestAdminMCPWriteCarriesOwnerMarkerOnlyWhenVerified,TestAdminMCPWritesUnavailableReasonTestAdminMCPStageTrackerReadTestDelegatedNoMergeNeverQueuesApprovalno_merge→ no native approval,/lgtm+/approveTestAdminMCPApproveIsHeldToTheCallersRepoPermissionreadis refused and nothing is written;writeapproves and is namedgo testadminmcp, cmd/hive-admin-mcp, dashboard, writeback, cmd/hivecheck-docs-citations.py,check-api-reference-citations.sh,check-docs-links.pyTestAdminMCPWritePreviewFailsFastWithoutDashboardBeareris removed. It asserted the old rule that refuses writes to an internal-header caller, andTestAdminMCPWritesRunAsVerifiedCallernow covers that caller succeeding.Notes
authenticateon the outer request, and is never taken from the client. The role checks inside each endpoint still apply. A cross-site POST to the endpoint could mint a preview but cannot read its confirmation id, and the id is bound to the previewing user.POST …/decide-delegated/plan) is a POST, and the read tools only issue GETs. Display, sound and label-filter settings are presentational, which [RFC] [v6] Operator-facing admin MCP: administer a hive by conversation #8697 already excludes.HIVE_ADMIN_MCP_ENABLE_WRITES.🤖 Generated with Claude Code
https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1