sync: update from private repo (dfadcd5f)

pieces/SCHEMA.md

@@ -17,9 +17,40 @@ camelCase internally (see `Movement` in `src/engine/agent-loop.ts`).
 | `initial_movement` | string | yes | must reference a `movements[].name` |
 | `triggers.keywords` | string[] | no | classifier hint only |
 | `required_mcp` | string[] | no | `[a-z0-9_-]{1,64}` server slugs |
+| `shared_tools` | string[] | no | piece-level tools merged into **every** movement's effective `allowed_tools` (union). See below. |
 | `model` | string | no | preferred LLM model |
 | `movements` | Movement[] | yes | non-empty array |
 
+### `shared_tools`
+
+Tools listed here are added to every movement's allowed set, so they don't have
+to be repeated in each `movements[].allowed_tools`. The effective set for a
+movement is:
+
+```
+shared_tools ∪ movements[].allowed_tools ∪ META_TOOLS
+```
+
+`prepareMovementContext` (`src/engine/piece-runner.ts`) unions the first two
+via `mergeToolNames` (de-duplicates, preserves order) into
+`movement.allowedTools`; the always-on `META_TOOLS` are added later, when
+`getToolDefs` (`src/engine/tools/index.ts`) builds the tool list.
+
+The per-movement gates still apply on top of the union:
+
+- A movement with `edit: false` never exposes `Write`/`Edit`, even if listed in
+  `shared_tools`.
+- SSH tools (`SshExec` etc.) still require the movement's own
+  `allowed_ssh_connections` — a shared SSH tool is rejected at runtime in any
+  movement that has not declared connections (defense in depth).
+- Unknown tool names are silently dropped by `getToolDefs` (`name in allDefs`).
+
+Handled by two complementary layers (mirrors `required_mcp`): file-backed
+pieces are cleaned leniently at load time by `normalizeSharedTools`
+(`piece-runner.ts`, drops bad entries + warns), while API writes
+(`POST`/`PUT /api/pieces`, `CreatePiece`/`UpdatePiece`) are validated strictly
+by `validatePiece` (`pieces-api.ts`, rejects a non-array or non-string entry).
+
 ## Movement
 
 | Field | Type | Required | Notes |