idea: per-verb permission allowlist for the peer-bridge — inspired by claude-code-action's prefix-based MCP tool filtering

[github-actions]

Summary

Add an optional per-agent allowlist of which agentmesh_peerbridge verbs an agent is granted, so a peer whose job doesn't need onward-delegation power (e.g. one that only picks up board tasks) doesn't uniformly receive all six verbs including delegate_to_peer/fan_out_to_peers/create_task_for_peer. This narrows the peer-bridge's blast radius the same way #845 already narrows do-mode's WRITE_TOOLS — a distinct axis (bridge verb surface, not write-tool surface).

Landscape basis

claude-code-action's tool-permission model layers two levels: whether an MCP server is included at all, and then which individual tools on that server are allowed, using prefix-based matching on the mcp__server__tool name (e.g. allow mcp__github__get_* but deny mcp__github__create_*).

• Source: claude-code-action security docs
• Source: tool/permission configuration (deepwiki)

Gap vs. existing #845

src/a2a/peer-bridge.js's buildTools() (lines 526-648) registers all six verbs (list_peers, delegate_to_peer, fan_out_to_peers, create_task_for_peer, list_my_tasks, update_my_task) unconditionally for every agent the bridge is wired to — no narrower grant exists. #845 (per-peer writeTools narrowing) is the nearest precedent but is scoped entirely to src/config.js's WRITE_TOOLS constant used by delegate-invocation.js for the worker's own tool surface during do-mode — a completely different MCP server (RESERVED_PREFIX = 'agentmesh_', BRIDGE_SERVER_NAME) and axis than the peer-bridge's onward-delegation verbs. Confirmed by reading both #845's full body and peer-bridge.js directly (2026-07-30) — no overlap.

Concretely: a peer whose whole job is triaging board tasks never needs delegate_to_peer/fan_out_to_peers/create_task_for_peer, but there is no way today to grant it only list_my_tasks/update_my_task.

Proposed design

• Add an optional peerBridgeVerbs array under the agent's own agent.json x-agentmesh block (same established namespace as idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845's writeTools), e.g. "x-agentmesh": { "peerBridgeVerbs": ["list_my_tasks", "update_my_task"] }.
• buildTools() takes an optional allowed-verb set and returns the intersection of the full six and the declared set — narrowing only, never widening (a tampered agent.json cannot grant a verb outside the fixed six).
• handle()'s tools/call dispatch enforces the same intersection at the call boundary (not just at tools/list discovery), mirroring how path-guard.js enforces at the call boundary rather than relying on tool-list omission.
• Omitting the field preserves today's behavior exactly (all six verbs) — fully backward compatible, opt-in hardening, same shape as idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845.

Invariants preserved

• Anti-spoof: the allowlist is read once from the agent's own manifest at bridge-server start, never from delegate_to_peer's tool-call args.
• No widening: intersection-only; a peer can never gain a verb outside the fixed six.
• Existing mode gates (readonly_parent, do-lock, ask-only fan-out) are unaffected — strictly an additional, orthogonal restriction layer.
• Single-writable-root / path-guard unaffected — create_task_for_peer already writes only the framework-owned board, never a peer's folder.

Risks

A peer misconfiguring its own allowlist too narrowly just fails a delegation attempt with a clear tool-not-available signal — no security risk either direction (matches #845's precedent).

Dedup confirmation

Checked full open-issue title/body set (2026-07-30). #845 is the nearest match and is confirmed a different axis (do-mode write-tool narrowing, not peer-bridge verb narrowing). No open or recently-closed issue proposes verb-level gating of the agentmesh_peerbridge server.

Sources

• claude-code-action security docs
• tool/permission configuration (deepwiki)
• agent_mesh source: src/a2a/peer-bridge.js:38-39,464-648
• Prior art in this repo: idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845 (per-peer writeTools narrowing for do-mode)

---

Draft spec location: docs/superpowers/specs/2026-07-30-peer-bridge-verb-allowlist-design.md (Goal/Non-goals/design/invariants/risks above). Spec-push is currently blocked pending #771 (DEV_MESH_PAT not configured — reconfirmed 2026-07-30 via gh api repos/danabaxia/agent_mesh --jq '.permissions', still push: false, active token still the integration/15368 app install token). This issue carries the full draft in the body in the meantime, matching current practice for #818/#824/#831/#849/etc.