tool-plugin-settings-reference

# ToolFamily settings SHOW reference Use this for one bounded family-owner change at a time. Production families opt in only through their own reviewed vertical change; no owner document or another family's opt-in enables them implicitly. ## Opt in 1. Set `settings=True` on the `ToolPluginDeclaration` or `CuratedMcpPlugin`. 2. Bind a callable `settings_provider` to `ToolFamily`; the declaration opt-in plus this bound provider makes SHOW available. The presence of an owner document does not opt a family in. 3. The provider returns a fresh iterable of public `SettingRow` values and performs no configuration change. 4. Supply exactly `key`, `current`, `default`, `configurable`, and `comment`. `comment` is the exact family-manual section pointer. Use `None` when the owner has no meaningful default; raise if the current value is unavailable. 5. Put meaning, accepted values, source and precedence, config/environment key, apply timing, and the real change procedure in that manual section. Do not copy those details into each row. 6. Set the private `_sensitive=True` flag only when `current` and `default` must both render as `<redacted>`; the flag itself is never projected. System's `settings/system.json` is closed and versioned. A v1 document is exactly the cache-miss-budget source. A v2 document may carry any subset of the seven ordinary System runtime-policy fields, the cache field, and Notification's file-layer cap. It may be absent; documented defaults then apply and the declaration-bound SHOW provider remains available. File presence still does not opt the family into SHOW. ## Read contract `settings(input={})` is the only operation. Normal success is exactly this shape, with no projected `status` or extra row metadata: ```json {"settings":[{"key":"example.timeout","current":30,"default":15,"configurable":true,"comment":"example-manual#timeout"}]} ``` Any provider exception, unavailable current, malformed row, or non-JSON display value returns one fixed bounded failure with no partial rows or exception text. The complete response is measured while rows are consumed and stops at 65,536 UTF-8 bytes; oversize output becomes one fixed no-row failure. ## Verify Run `tests/test_tool_settings_contract.py` plus the opted-in family's real schema/dispatch/manual tests, and confirm all unrelated declarations remain opted out.