fix(plugins): a node:-prefixed builtin must disclose what the bare one does

[rimusz]

Two defects in the plugin capability-disclosure path, found while building a plugin from the skill and watching the build reject it.

Independent of #70 and #71 — no shared files.

1. A node:-prefixed builtin disclosed nothing

CAPABILITY_DETECTORS['spawn-process'] matched child_process but not node:child_process. They are the same module, and the filesystem detectors two lines below already accept both spellings (fs and node:fs) — so the inconsistency lived inside a single object literal, one rule written two ways.

It is not theoretical. A plugin on this machine imports node:child_process and shells out to python3. Its build reported:

🔍 Scanning capabilities (first-party source only)...
   Detected: filesystem, env-access

No spawn-process. The call-shape patterns did not cover it either — execFile(...)/spawn(...) only match when the first argument is a quoted literal, and a plugin resolving its binary from a variable or process.env never has one:

import { execFile } from 'node:child_process';
const python = process.env.GROKBOT_PYTHON || 'python3';
execFile(python, args, cb);          // ← invisible to every pattern

Scanning that same plugin directory before and after:

	detected
before	env-access, filesystem
after	env-access, filesystem, **spawn-process**

That plugin declared spawn-process by hand, so the union model granted it. A plugin that stayed quiet would have shipped a shell-out with no disclosure at the consent modal and no cost to its trust tier — which is the whole point of the scan.

2. The plugin-builder skill never mentioned the block the build requires

cli/build-plugin.js:216 refuses to package a manifest without a structured permissions block. backend/skills/agnt-plugin-builder/SKILL.md — the instructions an agent follows to build a plugin from chat — contained the word permissions zero times, and its manifest example omitted the block entirely.

So a plugin built by following the skill exactly fails at step 3, and the only way forward is to read the build script. That is how I found it.

Adds: the block in the manifest example, a rule stating it is required, a section covering all six capabilities and what domains means, the verbatim error string, and the draft-permissions.js escape hatch. It also states that declared and detected need not match — effective permissions are the union, so over-declaring is safe and is the right call when the plugin does something a regex scan cannot see.

The capability table is derived from CAPABILITY_DETECTORS rather than invented. draft-permissions.js takes no arguments and writes one draft per dev plugin — verified against the script, after I first documented it wrongly.

Testing

25 tests. 8 fail without this change (5 scanner, 3 documentation contract).

The suite includes a parity ratchet over every builtin the import detectors recognise: both spellings must yield the same capability set. It fails when a new builtin is added in one form only — which is how this gap arrived.

Three contract tests keep the skill honest against the code: every detectable capability is documented, the failure message is quoted as build-plugin.js actually emits it, and the manifest example carries a permissions block.

Mutation tested — 8 mutants, 7 killed, 1 equivalent:

mutant	result
un-prefix the static-import detector	killed (3)
un-prefix the require detector	killed (1)
un-prefix the dynamic-import detector	killed (1)
break filesystem parity (drop node:fs)	killed (2)
remove the block from the manifest example	killed (1)
stop documenting one capability	killed (1)
paraphrase the quoted build failure	killed (1)
paraphrase one of two searchable copies	equivalent — survives by design

The last one changes the document without violating the contract: the message must be findable, two contiguous copies exist, and removing one leaves it findable. Killing it would require asserting an exact occurrence count, which breaks on any legitimate third mention.

Two of these mutants initially survived, and both were real weaknesses in my own tests — fixed in 03edc590 and 55b37622. Both assertions searched the whole document while their names claimed a specific location, so deleting the copy that mattered left the other holding them green. One now extracts the manifest example and asserts inside it; the other scopes to the fenced error block and compares against the exact string the build script emits, plus a deliberately unscoped check for an unbroken copy — because the fenced block wraps mid-sentence and cannot be found by pasting the error into a search box.

Full backend suite: 290 passed / 291 files. The single failure, UpdateScheduler.status.test.js > replaces the previous pass rather than accumulating, is pre-existing and unrelated — it passes in isolation, imports nothing here, and does not fire on CI.

Notes for the reviewer

• net is a known remaining gap, asserted rather than fixed. It has a method-shape detector (net.connect(...)) but no import detector in either spelling, so it is a missing module rather than a missing prefix. A test documents it so it stays visible.
• backend/plugins/tests/disclosure.test.js reports 19/20 both before and after this change (D4a spicy legacy plugin backfilled → unverified) — pre-existing, verified on pristine origin/main. Those files are excluded from vitest as standalone scripts.
• validate-core.js is vendored into the api.agnt.gg server repo via cli/sync-validate-core.js, and no CI job checks the copies agree. This change alters the canonical file, so the server copy needs re-vendoring for the publish gate to enforce the same rule. I cannot reach that repo.

[Copilot]

🟡 Changes recommended

The newly added parity/ratchet tests have correctness and portability issues (multi-scan directory contamination and non-portable import.meta.url pathname handling) that can allow false passes or fail on Windows.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR tightens AGNT’s plugin capability-disclosure pipeline by ensuring node:-prefixed builtins are detected the same as their bare equivalents, and by updating the plugin-builder skill documentation to reflect the build-time requirement for a structured permissions block.

Changes:

• Fix spawn-process capability detection to recognize both child_process and node:child_process imports.
• Add a capability detector parity/ratchet test suite and documentation contract tests to prevent scanner/doc drift.
• Update backend/skills/agnt-plugin-builder/SKILL.md to require and explain permissions (capabilities + domains), including the exact build failure message and draft-permissions.js usage.

File summaries

File	Description
backend/plugins/lib/validate-core.js	Expands the spawn-process import detectors to match both bare and node:-prefixed child_process.
backend/src/plugins/capabilityDetectors.test.js	Adds parity/ratchet tests for builtin import spelling and contract tests tying scanner capabilities and build failure messaging to documentation.
backend/skills/agnt-plugin-builder/SKILL.md	Documents required permissions block, capability vocabulary, domains semantics, and the builder’s exact refusal message + drafting helper.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.