Proposal: optional cli:<name>@<range> version pins for ### Tools (+ a verified tools-lock)
Issue-first per CONTRIBUTING (this proposes new authored syntax, so it should be discussed before a PR).
Motivation
### Tools now declares host CLIs/MCP servers as fail-closed dependencies (presence-only — see the reactor/declared-tools work bringing the reactor harness to parity with the canonical VM tools_resolver). A natural, opt-in follow-on is letting an author pin a tool's acceptable version, e.g. cli:jq@>=1.7, and verify the host against it — useful when a contract depends on behavior added in a specific tool version.
Proposed surface (additive, opt-in; presence-only stays the default)
- Syntax:
cli:<name>@<range> where <range> is a single SemVer comparator (>=, >, <=, <, =, exact). Compound ranges / caret / tilde intentionally out of scope (YAGNI). mcp: pins are not supported (a server can't self-report a version) → tool_invalid.
- Compile: parse + record the pin in a byte-stable tools-lock; compile still never execs a tool (presence-only), so a pin is recorded but not enforced at compile.
- Opt-in verify: a new
reactor tools verify step is the only thing that runs a tool (just --version) and fails closed (tool_version_unsatisfied) when the host version is out of range.
- Spec: update
contract-markdown.md §Tools + the canonical compiler/index.prose.md tools_resolver together, so the VM and harness agree.
Status
A complete, stacked, offline-green working draft already exists locally on reactor/tool-version-pins (stacked on the ### Tools parity work) — happy to open it as a PR once the syntax/design is greenlit here.
Questions for maintainers
- Is
cli:<name>@<range> the syntax you want, or a different shape?
- Is a separate
reactor tools verify the right home for the (exec-gated) version check, vs. compile-time?
- Tools-lock format/location preferences?
Proposal: optional
cli:<name>@<range>version pins for### Tools(+ a verified tools-lock)Issue-first per CONTRIBUTING (this proposes new authored syntax, so it should be discussed before a PR).
Motivation
### Toolsnow declares host CLIs/MCP servers as fail-closed dependencies (presence-only — see thereactor/declared-toolswork bringing the reactor harness to parity with the canonical VMtools_resolver). A natural, opt-in follow-on is letting an author pin a tool's acceptable version, e.g.cli:jq@>=1.7, and verify the host against it — useful when a contract depends on behavior added in a specific tool version.Proposed surface (additive, opt-in; presence-only stays the default)
cli:<name>@<range>where<range>is a single SemVer comparator (>=,>,<=,<,=, exact). Compound ranges / caret / tilde intentionally out of scope (YAGNI).mcp:pins are not supported (a server can't self-report a version) →tool_invalid.reactor tools verifystep is the only thing that runs a tool (just--version) and fails closed (tool_version_unsatisfied) when the host version is out of range.contract-markdown.md§Tools + the canonicalcompiler/index.prose.mdtools_resolvertogether, so the VM and harness agree.Status
A complete, stacked, offline-green working draft already exists locally on
reactor/tool-version-pins(stacked on the### Toolsparity work) — happy to open it as a PR once the syntax/design is greenlit here.Questions for maintainers
cli:<name>@<range>the syntax you want, or a different shape?reactor tools verifythe right home for the (exec-gated) version check, vs. compile-time?