idea: risk-tiered confirmation flag for do-mode writes — inspired by OpenHands' LLMSecurityAnalyzer risk classification

[github-actions]

Research brief

Landscape survey (2026-07-25), scoped to: "agent_mesh roadmap & comparable OSS
agent frameworks" (OpenHands, SWE-agent, Aider, MetaGPT/ChatDev, Renovate,
claude-code-action).

Landscape signal — OpenHands' graduated risk confirmation. OpenHands' SDK
ships an LLMSecurityAnalyzer that rates every proposed tool call
LOW/MEDIUM/HIGH/UNKNOWN risk; a ConfirmRisky() policy auto-executes
low-risk actions but transitions the run to a WAITING_FOR_CONFIRMATION
state for medium/high-risk ones until a human approves or rejects (a
rejection feeds explanatory context back so the agent retries safely).
Source (fetched, verified): https://docs.openhands.dev/sdk/guides/security

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

do-mode write confinement today is a flat, binary boundary: the
PreToolUse path-guard hook (hooks/path-guard.js) allows any write inside
AGENT_MESH_ROOT and denies anything outside it — see
src/path-guard.js/src/config.js WRITE_TOOLS. There is no graduated
signal between "inside the root, fine" and "outside the root, denied." A
worker deleting/rewriting a large fraction of the tree, touching a
secret-looking path (.env, credentials.json, a lockfile), or performing
an unusually broad multi-file edit is treated identically to a single
one-line doc fix, as long as both stay inside the writable root. Nothing in
src/delegate.js classifies how risky a write looks before letting the
result finalize as status: done.

This is a different axis from every open security-tagged idea already in the
backlog:

• idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845 (per-peer write-tool allowlist narrowing) is static and
  preventive — it narrows which write tools a peer may ever invoke,
  declared once in agent.json, independent of any specific call's content.
• 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.
• idea: optional namespace/bwrap jail as defense-in-depth beneath the path-guard hook #807 (namespace/bwrap jail) adds an OS-enforced layer under the
  path-guard boundary itself.
• idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509 / idea: semantic dual-agent verification pass for do-mode delegations — complements #509's mechanical validators with an intent-fidelity check #825 (mechanical validators / semantic dual-agent review)
  are detective — they assess the result of a completed do-mode task
  after the fact, not the blast-radius of an individual write.

None of these classify the content/blast-radius of an individual write
call at the moment it happens and route only the risky ones for human
review before the Task is considered final. That's the OpenHands gap.

Proposed direction

Because agent_mesh's do-mode spawn is a one-shot, non-interactive
claude -p run (there is no live human-in-the-loop channel mid-spawn, unlike
OpenHands' synchronous agent loop), the adaptation should stay consistent
with this repo's existing async, review-first model rather than blocking
execution:

• An optional per-peer agent.json x-agentmesh.riskyWritePatterns (or a
  small built-in heuristic set: N+ files touched in one task, a path
  matching common secret/lockfile globs, a Write to a previously
  non-existent large binary, etc.) evaluated after the do-mode spawn
  completes, using the same files_changed data src/change-detect.js
  already computes — no new hook, no new spawn-time gate.
• A match does not block or retry anything (same "failure is data, not an
  exception" invariant as timeout/refused/error): it surfaces a new
  structured field (e.g. agentmesh/risk: { level, reasons }) on the Task
  result, and — reusing the existing review-first session/dashboard
  machinery (src/session-provenance.js, the Task Board view) — a
  needs-human-confirm marker so a risky-but-completed write is flagged for
  review before a caller/board treats it as fully accepted, instead of
  silently landing with the same status as a trivial edit.
• Purely additive: omitting the manifest field preserves today's behavior
  exactly (no risk field emitted).

Invariants preserved

• Single writable root: unaffected — the path-guard boundary is
  unchanged; this only classifies writes that already happened inside the
  root.
• Anti-spoof: risk classification reads only files_changed (already
  framework-computed) and the peer's own manifest — never tool-call args.
• Failure is data: a risky write is still status: done with an
  additional advisory field, never auto-blocked/auto-reverted.

Scope hint

src/change-detect.js (reuse files_changed), src/delegate.js (post-spawn
classification hook), src/config.js (heuristic defaults), src/a2a/protocol.js
(new agentmesh/risk metadata field, additive), pure unit tests only.

Sources

• https://docs.openhands.dev/sdk/guides/security (LLMSecurityAnalyzer /
  ConfirmRisky, fetched and verified directly, not from a search snippet)

[github-actions]

Spec ready — attempt 1 of 3.

Authored the full design at docs/superpowers/specs/2026-07-26-idea-risk-tiered-confirmation-flag-for-do-mode-writes-design.md on branch spec/issue-846, commit 6b0503c.

git push origin spec/issue-846 → 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-846 branch deleted after the failed push (nothing lost — it never reached origin; full spec content is reproduced below so a human can publish it manually). Two attempts remain before this issue's own circuit breaker trips.

To publish manually: create branch spec/issue-846, save the content below as docs/superpowers/specs/2026-07-26-idea-risk-tiered-confirmation-flag-for-do-mode-writes-design.md, commit, push, gh pr create --title "spec(#846): risk-tiered confirmation flag for do-mode writes" --base main --head spec/issue-846. Then set label spec:in-review, remove spec:draft + blocked + needs-human.

---

Risk-Tiered Confirmation Flag for Do-Mode Writes — Design

Closes: #846.

1. Goal

Give a do-mode Task result a graduated signal about how risky the write it
just completed looks — not just "inside the root, allowed" — so a caller (a
peer, the orchestrator's board pipeline, a human watching the dashboard) can
tell a routine one-line edit apart from a broad or secret-adjacent write,
without blocking or slowing down execution.

Landscape basis: OpenHands' LLMSecurityAnalyzer rates every tool call
LOW/MEDIUM/HIGH/UNKNOWN and can pause a run pending human confirmation for
medium/high-risk calls
(https://docs.openhands.dev/sdk/guides/security). agent_mesh's do-mode spawn
is a one-shot, non-interactive claude -p run with no live human-in-the-loop
channel mid-spawn, so this spec adapts the classification half of that
pattern (not the synchronous pause-for-confirmation half) to fit the
framework's existing async, review-first model.

2. Non-goals

• No blocking, no retry, no auto-revert. A risky write still completes and
  is still status: done — "failure is data, not an exception" is unaffected
  because this isn't a failure path at all; it's an additional advisory field
  on a successful result. Invariant preserved as-is.
• No new PreToolUse hook, no spawn-time gate. Classification runs entirely
  after the do-mode spawn completes, over data the framework already
  computed (files_changed). The path-guard hook's binary in-root/out-of-root
  boundary is untouched.
• No OS-level sandboxing. Orthogonal to idea: optional namespace/bwrap jail as defense-in-depth beneath the path-guard hook #807 (namespace/bwrap jail), which
  is a defense-in-depth layer beneath the path-guard boundary; this spec
  classifies writes that already legally happened inside the root.
• No mechanical/semantic result validation. idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509 (declarative validators)
  and idea: semantic dual-agent verification pass for do-mode delegations — complements #509's mechanical validators with an intent-fidelity check #825 (semantic dual-agent verification) assess whether the result
  of a task is correct; this spec assesses the blast radius of the write
  itself, independent of correctness. All three can coexist and populate
  distinct metadata fields on the same Task.
• No dashboard UI work. The metadata field is the deliverable; rendering
  it in the Task Board / session views is a separate, later item.

3. Background — current state

• src/path-guard.js + hooks/path-guard.js: binary allow/deny per write
  call, based only on whether the canonicalized path is inside
  AGENT_MESH_ROOT. No notion of how much or what kind of write.
• src/change-detect.js computeFilesChanged(root, before) already computes
  the full files_changed array (porcelain delta ∪ content-digest delta) for
  every do-mode task, git-backed folders only (files_changed: null for
  non-git folders — this spec inherits that same degrade-to-null shape).
• src/delegate.js buildDelegateResult({ spawnResult, changed, logPath, … })
  builds the result object callers get; there is no classification step
  between computeFilesChanged and buildDelegateResult today.
• src/a2a/protocol.js buildTaskFromDelegateResult maps result.* fields
  onto agentmesh/* Task metadata (e.g. agentmesh/files_changed,
  agentmesh/best_effort) — purely additive if (result?.x) metadata['agentmesh/x'] = …
  lines, one per field.

4. Design

4.1 Pure classifier: src/risk-classify.js

export function classifyWriteRisk(filesChanged, { thresholds } = {}) {
  // filesChanged: string[] | null (from changed.files_changed)
  // Returns null when filesChanged is null (non-git folder — no signal available)
  // or when nothing matched (level 'none'); otherwise { level, reasons }.
}

• Pure function, no I/O, no claude awareness — takes the already-computed
  files_changed array (plus optional built-in/manifest thresholds) and
  returns { level: 'low'|'medium'|'high', reasons: string[] } | null.
• Built-in heuristics (always on, no manifest required):
  • file-count: files_changed.length >= N (default N=10) → medium;
    >= 2N → high.
  • secret/lockfile glob: any path matching a small built-in list
    (.env, .env.*, *credentials*, package-lock.json, *.pem, *.key)
    → high, reason secret_or_lockfile_path.
• Optional per-peer override/extension via agent.json
x-agentmesh.riskyWritePatterns: string[] (glob patterns, evaluated with
  the same matcher src/path-guard.js already uses for path normalization) —
  a peer can widen (never narrow) the built-in high set. Absent → built-ins
  only.
• No filesystem stat/content inspection — the classifier reasons only over
  the path list and counts already in files_changed; it never reads file
  contents, so it stays cheap and cannot itself become a new information leak
  vector.

4.2 Wire into delegate.js

In buildDelegateResult, after files_changed is known and only for
mode === 'do' (ask-mode never writes, so never classified):

const risk = mode === 'do' ? classifyWriteRisk(changed.files_changed, { thresholds: manifestThresholds }) : null;
if (risk) base.risk = risk;

manifestThresholds is read once from the peer's agent.json the same way
src/description.js reads AGENT.md once at server start — no per-task
re-read.

4.3 Task metadata: agentmesh/risk

buildTaskFromDelegateResult (protocol.js) gains one additive line, following
the exact pattern already used for agentmesh/best_effort /
agentmesh/preexisting_dirty:

if (result?.risk) metadata['agentmesh/risk'] = result.risk;

Absent when result.risk is null/undefined (ask-mode tasks, non-git
folders, or a low/none-only write) — a caller that doesn't know about this
field sees exactly today's Task shape.

4.4 Surfacing (data only, no new machinery)

agentmesh/risk rides the same metadata channel agentmesh/best_effort
already uses to reach the peer-bridge's mapTask() (src/a2a/peer-bridge.js)
and the run log. This spec stops at making the field exist and populated
correctly; a future item can have the dashboard's Task Board
(src/dashboard/public/tasks-view.js) render a badge for risk.level !== 'none', or have board-notify flag a needs-human-confirm marker — both are
additive consumers of a field this spec already produces, not a hard
dependency of this spec landing.

5. Invariants preserved

• Single writable root: unchanged. The path-guard boundary and every write
  tool's allow/deny decision are untouched; this classifies writes after
  they already legally happened inside the root.
• Anti-spoof: the classifier's only inputs are files_changed (already
  framework-computed from git state, never from tool args) and the peer's own
  agent.json (trusted, operator-authored config) — never anything from the
  worker's tool-call arguments or its final text output.
• Failure is data: a high-risk write is still status: done; nothing
  about this spec introduces a new failure/refusal branch.
• No Bash-in-do: unaffected — classification only reads
  changed.files_changed, never inspects or executes anything.

6. Implementation surface

• New src/risk-classify.js — pure, unit-testable (classifyWriteRisk).
• src/delegate.js — one classification call site in buildDelegateResult,
  gated on mode === 'do'.
• src/config.js — built-in default thresholds
  (DEFAULT_RISK_FILE_COUNT_MEDIUM / _HIGH, default secret/lockfile glob
  list), read via the existing readPositiveInt/config-resolution pattern.
• src/a2a/protocol.js — one additive line in buildTaskFromDelegateResult.
• No changes to src/path-guard.js, hooks/path-guard.js,
  src/context.js, or the peer bridge's mode gating.

7. Testing (hermetic, npm test)

• risk-classify.test.js: pure unit tests —
  • files_changed: null → null (no signal, e.g. non-git folder).
  • Empty array → null (no write happened worth flagging, e.g. an ask task
    that somehow reaches the classifier — should not occur given the
    mode === 'do' gate, but the pure function stays total).
  • < N plain-path files → null/{level:'low', …} per the default band.
  • >= N files, no secret paths → {level:'medium', reasons:['file_count']}.
  • >= 2N files → {level:'high', reasons:['file_count']}.
  • One path matching a built-in secret glob (even with 1 file total) →
    {level:'high', reasons:['secret_or_lockfile_path']}.
  • Peer-supplied riskyWritePatterns widens matches beyond the built-ins.
• delegate.test.js: a do-mode done run with a small edit carries no (or
  low) risk; a do-mode run touching a fixture .env-like path carries
  risk.level === 'high'; an ask-mode run never carries a risk field
  regardless of what it read.
• protocol.test.js: buildTaskFromDelegateResult maps result.risk onto
  agentmesh/risk when present, and the field is absent entirely when
  result.risk is unset (unaffected callers see the exact same Task shape as
  before this spec).

8. Risks & mitigations

• False sense of security — a caller might assume a low/absent risk
  field means "verified safe," when it only means "did not match a cheap
  heuristic." Mitigation: field/tool-facing docs describe it explicitly as an
  advisory, non-exhaustive signal, never a security boundary (the path-guard
  hook remains the only enforcement).
• Heuristic drift / false positives on legitimate large refactors (e.g. a
  repo-wide rename touching 40 files). Mitigation: this is advisory metadata,
  not a block — a caller can freely ignore a medium/high flag it judges to
  be a false positive; no auto-retry or auto-escalation is introduced.
• Glob-matching cost on very large files_changed arrays. Mitigation:
  the classifier is O(files_changed.length × patterns), bounded by the same
  practical task sizes the framework already handles; no new spawn or I/O is
  added.

9. Open decisions

1. Default N (file-count threshold) — proposed 10/20 for
   medium/high; tune from real do-mode task sizes if it proves noisy.
2. Whether the built-in secret/lockfile glob list should be centralized in
   src/config.js alongside WRITE_TOOLS, or live next to the classifier in
   src/risk-classify.js. Proposed: src/config.js, matching how
   WRITE_TOOLS and other security-relevant constants are already grouped.
3. Whether a future needs-human-confirm board/dashboard marker (§4.4) should
   be a separate follow-on spec or folded into the Task Board work already
   tracked elsewhere — deferred, out of scope here.

[github-actions]

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

Re-authored the spec (content unchanged from attempt 1 — no design changes)
at docs/superpowers/specs/2026-07-26-idea-risk-tiered-confirmation-flag-for-do-mode-writes-design.md
on branch spec/issue-846.

git push -u origin spec/issue-846 failed:

remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/danabaxia/agent_mesh.git/': The requested URL returned error: 403

Reconfirmed this run: gh api repos/danabaxia/agent_mesh --jq '.permissions.push' → false; active identity is still github-actions[bot], not DEV_MESH_PAT. Same root cause tracked centrally at #771 (still open, unresolved).

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-846 branch deleted after the failed push (nothing lost — it never reached origin; full spec content is reproduced in the attempt-1 comment above). 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 from attempts 1–2 — no design changes)
at docs/superpowers/specs/2026-07-29-idea-risk-tiered-confirmation-flag-for-do-mode-writes-design.md
on branch spec/issue-846, commit bdf1541.

git push -u origin spec/issue-846 failed:

remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/danabaxia/agent_mesh.git/': The requested URL returned error: 403

Reconfirmed this run: gh api repos/danabaxia/agent_mesh --jq '.permissions' → push: false; active identity still github-actions[bot] (integration/15368 GitHub App install), not DEV_MESH_PAT. Same root cause tracked centrally at #771 (still open, unresolved as of 2026-07-29).

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-846 branch deleted after the failed push (nothing lost — it never reached origin; full spec content is reproduced in the attempt-1 comment above). This is the 3rd consecutive failed attempt — per the circuit-breaker protocol, the next sweep trips the breaker rather than re-authoring again.

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