[ccch1mneyyy]

Closes #328

What was wrong

The original report's top-level glob guidance was partly fixed already, but discovered file-tool parameter schemas still left fields such as search roots, output modes, sorting, grep patterns and preview flags unexplained. The glob pattern field only said a positive entry was required, without a quoted JSON-array example.

The change

• Add concise field-level help to discoverable core file tools, including quoted glob arrays, regex versus literal strings, search defaults, sorting, context and preview semantics.
• Keep resident read_files and the discovery-entry tool unchanged: richer help is paid only after discovery.
• Keep every structural validation constraint unchanged. Existing serialized-contract coverage now separates parameter descriptions from structural schema; an additional whole-file-parameter structural hash locks the original constraints.
• Add regressions for field help, quoted array examples and important defaults, with paired docs and changelog. No runtime behavior or dependency changes. This improves guidance, not a guarantee that models will always generate valid JSON.

Validation

node test/run.mjs file-contract capabilities discovery
  4 suites passed, 0 skipped, 0 failed
  file-contract: all 5 checks passed
  structural schema constraints retain the baseline hash

node scripts/verify-gate.mjs --skip-install
  linux-x64: gate green
  124 suites passed; 2 skipped (optional external tui-host/tui-native)
  manifest: 73 checks (minimum 59)
  native unit tests, worker staging and packed release closure: passed

Red/green: new field-help assertion against unmodified a9ff940
  file-contract: 1 of 5 checks fails
  fixed tree: all 5 checks pass

Schema/prompt impact: measured compact JSON {name,description,parameters} with js-tiktoken 1.0.21 / cl100k_base, not provider billing:

Surface	Before	After	Delta
All 15 file-tool schemas	14,867 bytes / 3,209 tokens	17,083 bytes / 3,682 tokens	+2,216 bytes / +473 tokens
Resident read_files	686 bytes / 150 tokens	686 bytes / 150 tokens	0

The real host's resident file+discovery core remains at its existing 242-token gate; the discovery-entry schema remains 95 tokens. Output schemas and model-facing top-level descriptions are unchanged.

Full gate uses the real Landlock backend to keep the unrelated main bwrap-cache defect (#337/#338) separate. No sandbox permission weakening is introduced.

PR-triggered CI: https://github.com/T-Auto/dsh-ops/actions/runs/39479811616 — pull_request, aggregate CI required: SUCCESS (Windows x64, Linux x64, macOS arm64 and required supporting jobs passed).

Environment

Arch Linux x64, Node 24.21.0, Rust 1.97.1; source checkout based on main a9ff940.

Combined local validation

The submitted heads of #338, #340, #341, #342, #343, #344 and #345 were applied together in an isolated local verification worktree, including their combined changelog entries. With ordinary PATH selecting real bwrap 0.13.0 and real dsh-TUI 0.16.1 host/worker/renderer suites enabled, node scripts/verify-gate.mjs --skip-install passed all 11 release-gate steps: 129 suites passed, 0 skipped; 46 Rust unit tests passed; manifest 73/59. This Linux combined-tree evidence is separate from each PR's own cross-platform CI; no upstream merge or host installation was performed.