feat(json): per-command field allowlist + --jq filter

[christso]

Summary

Brings the gh-style --json[=field1,field2] --jq <expr> contract to allagents:

• AgentCommandMeta.jsonFields declares a per-command allowlist. --json=<fields> is validated against it at parse time; an unknown field exits 2 with a sorted Available fields: suggestion list.
• --jq <expr> pipes the envelope through the system jq binary (spawnSync, errors surfaced as Error: --jq failed: <msg> rather than raw stderr). --jq requires --json.
• Field projection is shape-aware: if data has a single top-level array of objects, the allowlist narrows each item; otherwise it projects the top-level data directly.
• --agent-help now emits json_fields when a meta declares an allowlist, so agents can discover the contract.
• Carries two prerequisite fixes the gate depends on:
  • The fix: --agent-help omits the skills subcommand group and metadata.command labels say 'plugin skills' #371 metadata wiring + command: label correction, so the runtime command path (skills list) matches the meta path used for validation.
  • addPlugin / getAllSkillsFromPlugins now thread workspacePath to resolvePluginSpecWithAutoRegister — without it, project-scope marketplaces (used by obra/superpowers) are invisible and the install in the gate fails before list can return any skills.

Test plan

• bun run build, bun run typecheck
• bun test — 1191 pass / 0 fail
• Verification gate from feat: --json field allowlist with --jq / --template filters per command #376 (using stable obra/superpowers):
  • Boolean --json skills list returns full envelope with data.skills array.
  • --json=name,plugin skills list → .data.skills[0] | keys == ["name","plugin"].
  • --json=bogus skills list → exit 2, Unknown JSON field + Available fields printed.
  • --json --jq '.data.skills | map(.name)' skills list → pipes through jq, returns array.
  • --jq without --json → exit 2.
  • --agent-help "skills list" exposes json_fields as an array.

Closes #376

[cloudflare-workers-and-pages]

Deploying allagents with    Cloudflare Pages

Latest commit:	e6299d9
Status:	✅  Deploy successful!
Preview URL:	https://003dacb7.allagents.pages.dev
Branch Preview URL:	https://feat-376-json-allowlist.allagents.pages.dev

View logs

[christso]

Code Review: ⚠️ APPROVE WITH SIGNIFICANT CONCERNS

Verification gate (#376)

All six gate checks pass on the diff:

• (1) Boolean --json returns full envelope ✓
• (2) --json=name,plugin skills list narrows to those keys ✓
• (3) Unknown field → exit 2 with sorted Available fields: ✓
• (4) --json --jq '.data.skills | map(.name)' pipes through jq ✓
• (5) --jq without --json rejected ✓
• (6) --agent-help "skills list" advertises json_fields ✓

CLAUDE.md compliance

• Conventional commit ✓
• No Co-Authored-By ✓
• Test coverage essentially absent for new behavior — see below.

---

Substantive concerns

1. Scope: only skillsListMeta actually declares jsonFields.

The issue's implementation notes are explicit: "Populate every existing meta in src/cli/metadata/*.ts from its existing outputSchema." The PR adds jsonFields: ['name', 'plugin', 'disabled'] to skillsListMeta only. Every other meta (pluginList, workspaceStatus, marketplaceList, etc.) has an outputSchema but no jsonFields. Consequence: for those commands, --json=anything is silently accepted (validation falls through on empty allowlist), so the new contract isn't actually enforced anywhere except skills list.

The gate uses skills list exclusively, so the gate passes, but the feature — a per-command allowlist — is one command short of being real.

2. --template is missing.

The issue calls for --json[=fields] / --jq / --template. The PR title only claims --json + --jq, and the gate doesn't test template, so it's been quietly dropped. Worth either:

• An explicit "deferred to follow-up" note in the squash commit, or
• Filing a follow-up issue.

If --template is intentionally cut, fine — but say so somewhere durable.

3. findMetaByCommand lookup is fragile against positional args.

const commandPath = finalArgs.filter((a) => !a.startsWith('-')).join(' ');
const meta = findMetaByCommand(commandPath);

For allagents --json=name,plugin skills add brainstorming, commandPath = "skills add brainstorming". No meta with that exact .command exists, so meta is undefined, so the allowlist falls through — any --json=<field> is accepted. The validation is silently bypassed for any command that takes a positional.

The fix is a longest-prefix match: walk finalArgs token-by-token and find the meta whose .command is the longest prefix.

4. runJq shells out to system jq.

const result = spawnSync('jq', [expr], { input, encoding: 'utf-8' });

The issue's implementation notes explicitly suggest "use a small embedded jq (e.g., node-jq, jq-wasm). Bun's runtime supports both." Shelling out has UX implications:

• Users without jq on PATH get Error: --jq failed: ENOENT (or similar) on every invocation.
• macOS / Windows defaults often don't ship jq.

Either:

• Switch to embedded jq (issue's recommendation), or
• Detect missing jq on PATH up-front and emit a friendly "Install jq from https://… to use --jq" message.

The gate passes because the test machine has jq installed.

5. Zero unit tests for the new behavior.

CLAUDE.md: "one test per distinct code path." New surface area without tests:

• extractJsonFlag — three branches (--json, --json=fields, neither)
• extractJqFlag — present / missing / missing-value-error
• validateJsonFields — no allowlist / unknown field / valid fields
• applyFieldFilter — single-top-level-array vs top-level-object data shapes
• projectFields — drops unknown keys
• findMetaByCommand — match / no-match (and the positional-args bug above)
• runJq — success and failure paths (can be done with a tiny shell script stub or by injecting a runner)

The verification gate is an E2E test; unit-level pinning of these branches is missing.

---

Minor

6. applyFieldFilter's keys.length >= 1 check is redundant — find() already returns the first matching key.

7. setJsonMode now takes an options object. The two existing call sites (only index.ts in this diff) are updated; module-level singleton state is still mutated. Consider whether the lifecycle is robust if setJsonMode is ever called after jsonOutput runs. (Probably fine for a CLI, but worth a comment that the contract is "call setJsonMode exactly once at startup.")

8. Carries the #371 metadata-wiring fix and the addPlugin workspacePath fix. Overlaps with #379 and #382. Whichever lands second rebases cleanly since the changes are identical, but worth noting in the PR description so reviewers don't re-litigate them.

---

Suggested merge order

Approve after items 1–3 are either addressed or explicitly deferred. Item 4 (embedded jq) and item 5 (tests) can be follow-ups, but the partial allowlist (item 1) and the positional-arg lookup bug (item 3) reduce the feature's real-world utility today.