idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules

[github-actions]

Research brief

Source: Analyst landscape survey 2026-07-24 — agent_mesh roadmap vs. comparable OSS agent frameworks (OpenHands, SWE-agent, Aider, MetaGPT/ChatDev, Renovate, claude-code-action).

Claude Code's own June 2026 release added Tool(param:value) permission-rule syntax so a rule can match a tool's input parameters with * wildcards — e.g. Agent(model:opus) to block Opus subagents (v2.1.178, 2026-06-15) — a first-party move toward finer-grained, parameterized restriction of what a spawned subagent may do, beyond a flat allow/deny per tool name. [Source: Claude Code changelog]

SWE-agent's Agent-Computer Interface (ACI) design principles argue a tool surface should be no larger than the task needs — the ACI should "help the agent recover from mistakes" and "remove unnecessary context from prior observations," i.e. a smaller, task-appropriate tool surface reduces mistake surface. [Source: arXiv:2405.15793, docs/background/aci.md]

The gap, confirmed against this repo (not just landscape-inspired)

src/config.js:49 defines WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'] as a single global constant. src/delegate-invocation.js:191 applies it uniformly to every do-mode spawn:

const tools = mode === 'ask' ? [...READ_TOOLS] : [...READ_TOOLS, ...WRITE_TOOLS];

There is no way for an individual peer to receive a narrower write-tool set than the full four. Contrast with WEB_TOOLS: agentWantsWebTools (delegate-invocation.js:159-188) already threads a per-agent additive grant from the operator-owned mesh.json manifest (webTools: true, ask-only, "operator-owned... so a tampered third-folder card cannot expand egress"). There is no analogous subtractive per-peer scoping for do-mode's write tools.

Concretely: a peer whose entire job is prose/doc editing gets the identical NotebookEdit/MultiEdit/Write grant as a peer that legitimately creates new files — needless blast radius. Every ACI mistake-surface argument applies to the unused tools just as much as the used ones.

Proposed direction

Add an optional writeTools array under a peer's own agent.json x-agentmesh block (the same established namespace already used for modes/meshVersion — see test/structure-conformance.test.js), e.g. "x-agentmesh": { "writeTools": ["Edit"] }. At spawn time, the tool-list builder intersects the declared list with the global WRITE_TOOLS constant — a peer can only ever narrow its own write surface, never widen it (a tampered/compromised agent.json cannot grant itself Bash or anything outside the fixed global set). Omitting the field preserves today's behavior exactly (full WRITE_TOOLS) — fully backward compatible, opt-in hardening.

This is a distinct axis from two already-open ideas, so it doesn't overlap:

• idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509 (post-do validation gate) is detective — declared validators run after the task to catch bad outcomes.
• idea: read-confinement guard — extend path-guard's single-writable-root enforcement to Read/Glob/Grep/LS #818 (read-confinement guard) restricts where reads may happen (path confinement), not which tools are grantable.
• This proposal is preventive and restricts which write tools a peer may ever invoke, independent of path.

Non-goals

• No change to ask mode (already read-tool-only).
• No per-task-call scoping via delegate_task tool args — that would violate the anti-spoof invariant (model-facing surface stays exactly { mode, task }). Scoping is declared once, out-of-band, in the peer's own agent.json — same trust boundary as idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509's proposed validators.
• No dynamic/runtime tool negotiation — the allowlist is static per peer, read once (like description.js reads AGENT.md once at server start).

Invariants preserved

• Single writable root / path-guard unaffected — this narrows which write tools exist, not where they may write.
• No Bash in do: the intersection is always a subset of WRITE_TOOLS, so Bash can never enter regardless of what a peer declares.
• Anti-spoof: no new field is read from tool-call args, only from the peer's own manifest at spawn setup.

Considered and rejected

MetaGPT's global publish-subscribe message pool (agents broadcast to a shared bus; others subscribe by role) was also surveyed as a landscape idea for cross-peer coordination, but it directly conflicts with this project's governing "no central registry, broker, or dispatcher by design" principle (PROJECT.md) and was not carried forward as a proposal.

Sources

• Claude Code changelog — v2.1.178 (2026-06-15): Tool(param:value) permission-rule syntax
• SWE-agent ACI design — arXiv:2405.15793, docs/background/aci.md
• agent_mesh source: src/config.js:49-56, src/delegate-invocation.js:159-198

---

Draft spec location: docs/superpowers/specs/2026-07-24-per-peer-write-tool-allowlist-design.md (Goal/Non-goals/design above; invariants above; risk: a peer misconfiguring its own allowlist too narrowly just fails a do-mode task with a clear tool-not-allowed error, no security risk either direction). Spec-push to the repo is currently blocked pending #771 (DEV_MESH_PAT not configured); this issue carries the full draft in the body in the meantime, matching current practice for #818/#824/#831/etc.

[github-actions]

Spec ready — attempt 1 of 3.

Authored the full design at docs/superpowers/specs/2026-07-24-per-peer-write-tool-allowlist-design.md (optional x-agentmesh.writeTools array on a peer's own agent.json; do-mode spawn tool-list intersects it against the global WRITE_TOOLS constant so a peer can only ever narrow, never widen, its write surface — Bash can never enter regardless of what a peer declares).

Committed on branch spec/issue-845, git push → HTTP 403 (Permission to danabaxia/agent_mesh.git denied to github-actions[bot]) — same known failure mode tracked centrally at #771 (DEV_MESH_PAT secret not yet configured; reconfirmed this run via gh api repos/danabaxia/agent_mesh --jq '.permissions.push' → false).

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-845 branch deleted after the failed push (nothing lost — it never reached origin; spec content is stable and reproducible from this comment). Two attempts remain before this issue's own circuit breaker trips.

[github-actions]

Spec ready — attempt 2 of 3 (push blocked, HTTP 403 — same as #771)

Re-authored the spec (content unchanged from attempt 1 — it was already
complete and stable, formalized as a standalone spec document from the
sections already drafted in this issue's body) at
docs/superpowers/specs/2026-07-24-per-peer-write-tool-allowlist-design.md.

Committed on branch spec/issue-845, git push → HTTP 403 (Permission to danabaxia/agent_mesh.git denied to github-actions[bot]) — reconfirmed this
run via gh api repos/danabaxia/agent_mesh --jq '.permissions.push' → false.
Same known root cause tracked centrally at #771 (DEV_MESH_PAT secret still
not configured with contents:write), which remains open and unresolved as
of this run.

Labels already correctly reflect this (spec:draft + blocked +
needs-human). Local spec/issue-845 branch deleted after the failed push
(nothing lost — it never reached origin; spec content is stable and
reproducible from the previous comment / issue body). One attempt remains
before this issue's own circuit breaker trips.

[github-actions]

Spec ready — attempt 3 of 3 (push blocked, HTTP 403 — same as #771)

Re-authored the spec (content unchanged in substance from attempts 1-2 -
formalized with full implementation touches: stdio-server.js startup read,
buildClaudeInvocationSync intersection filter, PreToolUse hook matcher
scope, and a fail-closed test list) at
docs/superpowers/specs/2026-07-24-per-peer-write-tool-allowlist-design.md.

Committed on branch spec/issue-845, git push -> HTTP 403 (Permission to danabaxia/agent_mesh.git denied to github-actions[bot]) - reconfirmed this
run via gh api repos/danabaxia/agent_mesh --jq '.permissions.push' -> false.
Same known root cause tracked centrally at #771 (DEV_MESH_PAT secret still
not configured with contents:write), which remains open and unresolved as
of this run.

This is attempt 3 of 3 - the spec-push circuit breaker's attempt cap. Local
spec/issue-845 branch deleted after the failed push (nothing lost; spec
content is stable and reproducible from the issue body / prior comments).
Per the circuit breaker protocol, no further re-authoring attempts on this
issue until the underlying #771 infra gap is resolved by a human; the next
run that finds this issue in scope will trip the breaker (add needs-human

• already present - and file a single deduped escalation comment) rather
  than re-attempt a push doomed to the same 403.

[github-actions]

CIRCUIT BREAKER: spec-push has failed 3+ consecutive times. DEV_MESH_PAT may lack write access or the spec directory is conflicted. Human intervention required. See .github/actions/mesh-retry-backoff for 529.