idea: pre-write syntax guard hook for do-mode edits — inspired by SWE-agent's ACI edit-tool linting

[github-actions]

Summary

Add an optional PreToolUse hook check — sibling to hooks/path-guard.js, reusing its exact enforcement point — that syntax-checks the result of a write-tool call (Edit/Write/MultiEdit) before it lands on disk, and denies (exit 2) the individual tool call if the edit would leave the file syntactically invalid. This is a per-call, mechanical, parse-only gate — cheaper and earlier than either of the two "did the task succeed" checks already proposed for this repo.

Landscape basis

• SWE-agent's Agent-Computer Interface (arXiv 2405.15793, docs/background/aci.md): the edit command runs a linter (flake8 for Python) before applying the edit and refuses the edit outright if the result isn't syntactically valid — "does not let the edit command go through if the code isn't syntactically correct." This is described as the single most-imitated idea in coding-agent scaffolds today.
• Aider's lint-on-edit (aider.chat/2024/05/22/linting.html): also lints after edits, but after the write, then loops the same agent to fix — a different (post-write, auto-retry) shape, already the explicit citation for idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509.

Gap vs. the two existing validation ideas

This repo already has two adjacent, but mechanically distinct, proposals in the backlog:

• idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509 (post-do validation gate): runs declarative agent.json validator commands (lint/test) once, after the whole do-mode task completes. Opt-in, no re-edit loop (explicitly rejects Aider's auto-retry to preserve "failure is data").
• 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): an ask-mode second-agent review of task intent fidelity, after the task completes. Semantic, not syntactic.

Neither operates at the individual tool-call boundary. Both can only detect a broken build after the worker has already finished and handed back a result — by then a multi-file edit sequence may have compounded a syntax break across several files, and the caller only learns about it from the final report. SWE-agent's ACI instead blocks the specific malformed edit synchronously, the same instant it would be written — architecturally identical to how path-guard.js already blocks a specific out-of-root write synchronously. No existing issue proposes this per-call, pre-write mechanism (confirmed: no open/closed issue matches "syntax" or "PreToolUse" + "edit" combined).

Proposed design

• New pure module src/syntax-guard.js, mirroring src/path-guard.js's shape: given (toolName, toolInput), compute the resulting file content the write would produce (Edit/MultiEdit's old_string/new_string diff applied in-memory, Write's content directly) and run a fast, parse-only check keyed by file extension — no linting, no build, no tests (that's idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509's job). Start narrow: .json via JSON.parse, .js/.mjs/.cjs via node --check (or node:vm's Script constructor, sourceless, no execution) — extensible registry, silently skip unrecognized extensions (never block what it can't parse).
• hooks/path-guard.js (or a new sibling hook wired the same way in the do-mode --settings temp file) calls this check after the existing path/protected-config checks pass, same stdin payload, same deny()/allow() shape, same denial audit log.
• Opt-in via agent.json manifest (x-agentmesh.syntaxGuard: true, default false) — matches idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509's opt-in shape so no peer's behavior changes unless it asks in. A denied call is not a task failure: like an out-of-root path-guard denial, the worker sees the hook's stderr and can self-correct within the same session (no framework-level auto-retry — the invariant is upheld the same way path-guard already upholds it today).

Security / invariants

• No new write surface: purely an additional synchronous denial path on the existing PreToolUse hook, same as path-guard.
• Anti-spoof: the check reads only the tool's own tool_input, never caller-supplied bookkeeping fields.
• No Bash-in-do concern: applies only to WRITE_TOOLS (Edit/Write/MultiEdit/NotebookEdit), which are already the sole write surface.
• Fail-open on unsupported/unparseable-by-design file types (never false-block a .md/.py/binary write because the checker doesn't know that language) — matches the repo's "failure is data, not a silent block" spirit by scoping strictly to what it can prove is broken.

Dedup confirmation

Searched all open/closed issues for "syntax", "lint", "PreToolUse" (2026-07-28). #509 and #825 are the nearest matches and are cited above as explicitly distinct (post-task vs. per-call; mechanical-command vs. parse-only vs. semantic-review). No issue proposes a pre-write, tool-call-level syntax gate.

Sources

• SWE-agent ACI paper — https://arxiv.org/abs/2405.15793
• SWE-agent ACI background doc — https://github.com/SWE-agent/SWE-agent/blob/main/docs/background/aci.md
• Aider lint-on-edit (contrast case, already cited in idea: post-do validation gate — declarative validators in agent.json run after do-mode tasks #509) — https://aider.chat/2024/05/22/linting.html

[github-actions]

Spec ready attempt 1: drafted docs/superpowers/specs/2026-07-28-idea-pre-write-syntax-guard-hook-for-do-mode-edits-design.md (a PreToolUse syntax-check gate sibling to hooks/path-guard.js — parse-only, opt-in via x-agentmesh.syntaxGuard, distinct from #509's post-task validator commands and #825's semantic dual-agent review). Committed locally on branch spec/issue-849. git push origin spec/issue-849 failed: HTTP 403 (remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot]). Confirmed via gh api repos/danabaxia/agent_mesh --jq '.permissions' → push: false; active credential is the integration/15368 GitHub App installation, not DEV_MESH_PAT. Same root cause tracked centrally in #771 (still open). Local commit discarded (ephemeral runner). Labels: idea/spec:draft both present from creation — spec:draft is now the accurate state (this issue's scope was already clear from the initial write-up, no separate discussion step was needed).

[github-actions]

Spec ready — attempt 2 of 3 (push blocked, HTTP 403)

Re-authored the spec (content unchanged in substance from attempt 1, restructured
to match the repo's Goal/Non-goals/Design/Invariants/Risks convention) at
docs/superpowers/specs/2026-07-29-pre-write-syntax-guard-hook-design.md on a
fresh local branch spec/issue-849 (commit 95507da), committed.

git push origin spec/issue-849 failed: HTTP 403
(remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot]).
Confirmed via gh api repos/danabaxia/agent_mesh --jq '.permissions' → push: false;
active credential is the integration/15368 GitHub App installation, not
DEV_MESH_PAT. Same root cause tracked centrally in #771 (still open — 2026-07-29
sweep reconfirmed no change). Local branch deleted after the failed push (nothing
lost — full spec content below). One attempt remains before this issue's own
circuit breaker trips.

Labels unchanged (spec:draft / blocked / generated:analyst / needs-human —
all still accurate).

---

Full spec content (preserved since push failed)

Pre-Write Syntax Guard Hook for Do-Mode Edits — Design

1. Goal

Give the do-mode PreToolUse boundary a synchronous, per-call syntax check:
before an Edit/Write/MultiEdit is allowed to land on disk, compute the
resulting file content and — for a narrow, extensible set of file types — parse
it. If the parse fails, deny that single tool call (exit 2), the same way
hooks/path-guard.js already denies an out-of-root write. This closes the gap
between the two validation ideas already in the backlog (#509, #825), both
of which only see a broken result after the whole do-mode task has already
finished — by which point a multi-file edit sequence may have compounded a
break across several files with no way to attribute it to the specific call
that caused it.

2. Non-goals

• Not a linter and not a build/test runner. No flake8/eslint-equivalent
  style checking, no running the project's test suite. That is #509's job
  (post-task, opt-in, declarative validator commands).
• Not a semantic review. Whether the edit fulfills the task's intent is
  #825's job (post-task, ask-mode second-agent review). This spec only asks
  "does the resulting file parse," nothing about correctness of intent.
• No auto-retry. A denial is data, not a retry loop — consistent with the
  framework's path-guard.js precedent and the "failure is data, not an
  exception" invariant. The worker sees the hook's stderr and may self-correct
  within the same session; the framework never resubmits on its behalf.
• No new write surface, no new tool. This adds only a further synchronous
  denial path on the existing PreToolUse hook already wired for do mode.
• Fail-open on anything unrecognized. A file extension with no registered
  checker is never blocked — the guard only stops writes it can prove are
  syntactically broken, never ones it merely can't evaluate.

3. Background — current pipeline

• src/path-guard.js + hooks/path-guard.js are the existing enforcement
  point: the hook reads the PreToolUse call from stdin, extracts the write
  tool's explicit path argument, canonicalizes it, and exit(2)s if the path
  falls outside AGENT_MESH_ROOT. This spec reuses that exact call site and
  shape, adding a second, independent check after the path check passes.
• src/config.js's WRITE_TOOLS (Edit, Write, MultiEdit, NotebookEdit)
  is already the complete write-tool allowlist for do mode — this guard
  applies to the same set, no wider.
• #509 (post-do validation gate) and #825 (semantic dual-agent
  verification) both operate after delegate.js reports the task result —
  neither can localize a break to one call in a multi-edit sequence.

4. Design

4.1 src/syntax-guard.js — pure module

Mirrors src/path-guard.js's shape: a pure function taking (toolName, toolInput) and returning { ok: true } or { ok: false, reason }.

1. Reconstruct the resulting content — never touch disk:
   • Write: toolInput.content directly.
   • Edit: read the current file, apply old_string → new_string
     in-memory (same substitution the real tool performs), producing the
     post-edit content.
   • MultiEdit: apply each edit in toolInput.edits in sequence, in-memory,
     against the same in-memory buffer.
   • NotebookEdit: out of scope for v1 (not registered in the extension
     table below — falls through to fail-open).
2. Look up a checker by file extension in a small, explicit registry:
   • .json → JSON.parse (throws → syntax error).
   • .js / .mjs / .cjs → node --check semantics, via new vm.Script(source, { filename }) (constructs but never executes the
     script — a SyntaxError on construction is the parse failure signal; no
     side effects, no I/O, no network).
   • Any other extension → no checker registered → { ok: true } (fail-open).
3. Return { ok: false, reason: '<parser error message>' } on a caught parse
   error; { ok: true } otherwise.

4.2 Hook wiring

hooks/path-guard.js gains a second check, run only after the existing
path/protected-config checks pass (so an out-of-root write is still denied by
the cheaper check first): call src/syntax-guard.js with the same
already-parsed toolName/toolInput, and if it returns ok: false, write the
reason to stderr and exit(2) — identical denial shape to the existing path
check, so the worker sees one consistent kind of hook denial regardless of
which check fired.

No new hook file, no new hook registration — the same PreToolUse hook, same
--settings temp file already generated for do mode, one additional
synchronous branch.

4.3 Opt-in manifest gate

Off by default. A peer opts in via its agent.json:

{ "x-agentmesh": { "syntaxGuard": true } }

doctor/the do-mode settings-file generator reads this flag the same way it
already reads other x-agentmesh manifest markers; when absent or false, the
syntax-guard branch in the hook is skipped entirely (zero behavior change for
every peer that doesn't ask in) — matching #509's opt-in shape.

5. Invariants this must uphold

• Anti-spoof: the checker reads only tool_input fields the tool call
  itself already carries (content, old_string/new_string, edits) —
  never a caller-supplied bookkeeping field, never process env.
• No Bash-in-do: scope is strictly WRITE_TOOLS (Edit/Write/
  MultiEdit/NotebookEdit) — the existing write-tool allowlist, widened no
  further.
• Failure is data, not an exception: a syntax-guard denial surfaces to the
  worker as hook stderr + a non-zero exit, exactly like an existing path-guard
  denial — the framework does not retry or fail over on the worker's behalf.
• Single writable root is unaffected — this check runs strictly after the
  path check and never changes which root is writable.

6. Risks

• False sense of safety: a file that parses can still be logically wrong
  (that's #509/#825's job, not this). Docs for this feature should be
  explicit that it is a syntax floor, not a correctness guarantee.
• Checker drift from the real tool semantics: if Edit/MultiEdit's
  actual string-replacement semantics ever diverge from this module's in-memory
  reconstruction (e.g. multiple-occurrence handling), the guard could produce
  a false pass or false deny. Mitigate by unit-testing the reconstruction
  against the same fixtures used for the real tools, and keeping the checker
  registry intentionally narrow (only extensions with a cheap, exact parser)
  rather than guessing at looser languages.
• vm.Script construction cost: negligible for typical file sizes, but a
  pathological multi-megabyte single write could add latency to every edit —
  acceptable since this only runs for opted-in peers doing do-mode writes to
  the guarded extensions.

7. Dedup / prior art

• #509 — post-do declarative validator commands (lint/test), opt-in, runs
  once after the whole task. Distinct: post-task vs. this spec's per-call;
  mechanical shell commands vs. this spec's in-process parse-only check.
• #825 — semantic dual-agent verification of intent fidelity, post-task.
  Distinct: semantic review vs. this spec's syntax-only check.
• SWE-agent's Agent-Computer Interface (arXiv 2405.15793) — the edit command
  lints before applying and refuses the edit if syntactically invalid; the
  most directly analogous prior art for this design's shape.
• Aider's lint-on-edit (aider.chat/2024/05/22/linting.html) — lints after
  writing, then loops the same agent to fix. Explicitly not adopted here: this
  repo's do mode does not auto-retry (see Non-goals).

[github-actions]

Spec ready — attempt 3 of 3 (push blocked, HTTP 403)

Re-committed the spec (content unchanged in substance from attempts 1-2) at
docs/superpowers/specs/2026-07-29-pre-write-syntax-guard-hook-design.md on a
fresh local branch spec/issue-849 (commit 6638fef), committed.

git push -u origin spec/issue-849 failed: HTTP 403
(remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot]).
Reconfirmed via gh api repos/danabaxia/agent_mesh --jq '.permissions' →
push: false this same run; active credential is the integration/15368
GitHub App installation, not DEV_MESH_PAT. Same root cause tracked centrally
in #771 (still open as of 2026-07-29). Local branch deleted after the failed
push (nothing lost — full spec content is already preserved in the attempt-2
comment above, unchanged here).

This was the 3rd and final attempt — CIRCUIT BREAKER now trips. No further
spec-push retries on this issue until #771 (repo write access for the mesh's
push credential) is resolved by a human.

Labels unchanged (spec:draft / blocked / generated:analyst /
needs-human — all still accurate).

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.