feat(discord): read-only tools for the Discord Sage through a Mosaic pi extension confined to declared roots (#1509)

A binding may declare `tools` with named roots. pi starts with
--no-builtin-tools and the package's own extension, allowlisting
list_dir, read_file and search. src/tools.mjs holds the rules: names
not paths, per-segment lstat walk, one checked descriptor read that
refuses symlinks, swaps, FIFOs, hard links and oversize files, credential
shapes refusing the whole read, and a per-message call budget. The engine
settles on agent_end and records tool calls in the turn record.

Jason's rulings R1-R7 in the brief, section 7. rev-code-02 approved
round 2 (comment 26276) on tree 43f0329b after four round 1 fixes.
Suite 48/48, node tests 116. Not pushed.

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/TOOLS.md

@@ -181,9 +181,13 @@ user entry may carry `channels`, an allowlist of listed channel ids.
 `scripts/discord-service.sh install` renders and writes the systemd user
 unit `[email protected]` (one instance per binding, restart on
 failure, exit 3 never retried, SIGTERM on `systemctl --user stop`, SIGHUP on
-`systemctl --user reload`). Records
+`systemctl --user reload`). An optional `tools` key in the binding declares
+read-only roots; pi then runs with its own tools off and the package's
+extension providing `list_dir`, `read_file` and `search` confined to those
+roots, with each call in the turn record. `tools` is a fixed key: changing
+it needs a stop and start. Records
 under `<dataRoot>/discord/<binding>/`: `inbox.jsonl`, `outbox.jsonl`,
-`drops.jsonl`, `admissions.jsonl`, `notices.jsonl`, write-once `turns/<id>.json`. Suite:
+`drops.jsonl`, `admissions.jsonl`, `notices.jsonl`, `reloads.jsonl`, write-once `turns/<id>.json`. Suite:
 `scripts/test-discord.sh`.
 Exit codes: 0 ok, 1 operation failed, 2 invalid data or configuration, 3
 refused by a brake (a supervisor must not retry), 4 usage. Details: