Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

bug: invalid JSON in agent-format.md `allowedTools` Examples block (JS `//` comments + unquoted `@builtin`) breaks copy-paste

Aperta Adatta ai principianti
  • Qualcosa non va?
#3,851 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

@ken-jo ci sta già lavorando.

Dal 19/6/2026.

  • #3852 di @ken-jo — aperta

Valutazione

Difficoltà
1/5
Tempo stimato
Meno di un'ora
Idoneità per principianti
90/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
rust
Ambito
documentation

Direzione di ricerca

Apri docs/agent-format.md e ispeziona il blocco Examples di allowedTools sotto l'intestazione Examples. Rimuovi i commenti inline e assicurati che la voce @builtin sia racchiusa tra virgolette, quindi convalida il blocco copiato con il parser JSON di Python. Il lavoro è terminato quando l'esempio delimitato è JSON rigoroso, copiabile e incollabile, accettato dal loader dell'agente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Checks
  • I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
  • N/A — this is a documentation defect, not a runtime bug (q doctor not applicable)
  • N/A — this is a documentation defect, not a runtime bug (q restart not applicable)
Operating system

N/A (documentation defect — applies on all platforms)

Expected behaviour

The allowedTools "Examples" block in docs/agent-format.md is fenced as ```json, so copy-pasting it into an agent config file should produce a valid agent that loads.

Actual behaviour

The block is not valid JSON, so pasting it into an agent config breaks loading. Agent files are parsed with strict serde_json::from_str — crates/agent/src/agent/agent_config/mod.rs:243 (match serde_json::from_str(&entry_contents); a second loader at :371), which rejects both comments and bare/unquoted tokens.

Two problems in the block (docs/agent-format.md, ### Examples, lines ~219–244):

  1. JS-style // comments on most lines (e.g. // Exact matches, // All filesystem tools). JSON has no comment syntax.
  2. Unquoted bare token @builtin, (line 231) — it must be the string "@builtin". The same document quotes it correctly elsewhere: the field-name list at line 124 (Use \@builtin` to include all built-in tools`) and the prose at line 215.

Verified the failure independently with a JSON parser:

$ python3 -c "import json,sys; json.load(open(sys.argv[1]))" allowedtools-example.json
json.decoder.JSONDecodeError: Expecting value: line 3 column 5

(line 3 = the first // Exact matches comment).

Steps to reproduce
  1. Open docs/agent-format.md, copy the ```json fenced block under ### Examples (the `allowedTools` example).
  2. Save it as e.g. ~/.aws/amazonq/cli-agents/example.json (or paste the allowedTools array into an existing agent file).
  3. The agent fails to parse — serde_json rejects the // comments and the unquoted @builtin token. Equivalent parser check: python3 -c "import json; json.load(open('example.json'))" → Expecting value: line 3 column 5.
Why it matters

The "Examples" block is the canonical reference a user reaches for when authoring allowedTools, and it is fenced as JSON, so it reads as copy-pasteable. Because agent configs are parsed with strict serde_json (no comment/trailing-comma leniency), the documented example cannot round-trip. We hit this while building a cross-platform agent-config adapter that emits these files as strict JSON: the documented form our integration pointed implementers at simply does not parse.

This is a sibling of the existing docs-accuracy gap on the same file, #3231 (the name field is no longer optional) — both are cases where agent-format.md drifted from what the loader actually accepts.

Proposed fix

Move the explanatory // annotations into prose/bullets above the snippet (or drop them), and quote the token as "@builtin", leaving a strictly-valid block:

{
  "allowedTools": [
    "fs_read",
    "knowledge",
    "@server/specific_tool",
    "fs_*",
    "execute_*",
    "*_test",
    "@builtin",
    "@server/api_*",
    "@server/read_*",
    "@git-server/get_*_info",
    "@*/status",
    "@fetch",
    "@git-*"
  ]
}

The per-entry meanings (exact match / native wildcard / @builtin = all native tools / MCP wildcards / server-level) are already explained in the surrounding "Pattern Matching Rules" and the bullet list at lines 119–125, so no information is lost by removing the inline comments.

I'm happy to open a PR with this change if that's welcome.

Environment

N/A (documentation defect)

Lingua principale
Rust
Stelle
2k
Fork
442
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aws/amazon-q-developer-cli

Tutte le issue di aws/amazon-q-developer-cli

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.