# jp-tools silently ignores unknown tool options

- **Status**: Todo
- **Kind**: Bug
- **Authors**: jp
- **Date**: 2026-08-18
- **Label**: domain=tooling
- **Label**: type=bug

`jp-tools` reads per-tool settings from a free-form `options` map and drops
anything it does not recognise.
`Tool::option_or` returns the default both when the key is missing and when the
value fails to deserialize, so an option the running binary does not implement
is indistinguishable from one that was never set.

The failure that surfaced this: `cargo_check` and `cargo_test` were configured
with `options.root` pointing at a second cargo workspace, but the installed
binary predated that option.
Both ran against the default workspace and reported success.
The results were green, plausible, and about the wrong code.
The only thing that caught it was recognising the test count from an earlier
run.

## Why this is worse than an ordinary silent default

A verification tool's whole job is to answer "is this code correct?".
When it silently answers about *different* code, every conclusion drawn from it
is wrong, and nothing in the output hints at it.

The skew is easy to hit: tool config lives in the repository and updates on
pull, while the binary updates only on `just install-tools`.

## Existing precedent

`web_fetch` already parses its settings into a typed `WebFetchOptions`
(`.config/jp/tools/src/web/fetch/options.rs`) rather than reaching into the map
directly.
Generalising that pattern is most of the work.

## Directions to investigate

- Give each tool or tool group a typed options struct, deserialized once at
  dispatch, replacing ad-hoc `option_or` lookups.
- `#[serde(deny_unknown_fields)]`, so a typo or an option meant for a newer
  binary is a loud error rather than a no-op.
- Decide the failure mode deliberately: reject the call, or run and report the
  ignored keys.
  Silence should not be one of the choices.
- Have tools state the effective setting they acted on (for the cargo tools, the
  workspace root), so a misdirect is visible in the result itself.
  This is the cheapest mitigation and is independent of the typed-options work.
- Consider whether tool configs should declare a minimum binary version, since
  typed options alone still cannot distinguish "unknown" from "not yet
  implemented" in a useful message.

## Scope

`jp_config` forwards unknown options untouched by design, which is correct: it
cannot know each tool's schema.
The gap is that the receiving end discards them just as quietly.
The fix belongs in `.config/jp/tools`, which is developer tooling rather than
shipped surface.