Skip to content

REQ-F-023: Tool Version in Every Response

Tier: Framework-Automatic | Priority: P1

Source: §22 Schema Versioning & Output Stability · §32 Self-Update & Auto-Upgrade Behavior

Addresses: Severity: High / Token Spend: High / Time: High / Context: Medium

Description

The framework MUST automatically inject meta.tool_version (semver string of the running tool binary) and, when an update is available, meta.update_available (semver string of the latest version) into every response. The update availability check MUST be non-blocking and MUST NOT delay command execution. If the update check fails, meta.update_available MUST be omitted (not set to an error value).

Acceptance Criteria

  • Every response includes meta.tool_version
  • meta.tool_version matches the output of tool --version
  • meta.update_available is absent (not null, absent) when no update is available or check failed
  • The update check does not add measurable latency to command execution

Schema

Types: response-envelope.md

meta.tool_version and the optional meta.update_available are injected by the framework into every response's meta object.

Wire Format

Response meta with tool_version and optional update_available:

{
  "ok": true,
  "data": { "id": "deploy-99", "status": "complete" },
  "error": null,
  "warnings": [],
  "meta": {
    "request_id":       "req_08MN",
    "command":          "deploy",
    "timestamp":        "2024-06-01T12:00:00Z",
    "schema_version":   "1.0.0",
    "tool_version":     "2.4.1",
    "update_available": "2.5.0"
  }
}

When no update is available or the check failed, update_available is absent (not null):

{
  "meta": {
    "tool_version": "2.4.1"
  }
}

Example

Framework-Automatic: no command author action needed. The framework reads its own version at startup and injects it into every response. The update check runs in a background goroutine/thread and its result is included only if available before serialization completes.

$ tool --version
2.4.1

$ tool deploy --env prod
→ meta.tool_version: "2.4.1"
→ meta.update_available: "2.5.0"   ← background check completed in time

$ tool deploy --env prod
→ meta.tool_version: "2.4.1"
# meta.update_available absent — check timed out, not null
Requirement Tier Relationship
REQ-F-022 F Composes: schema_version accompanies tool_version in every response meta
REQ-F-021 F Enforces: tool_version is a volatile field and belongs in meta
REQ-F-029 F Composes: update check that populates update_available is suppressed in non-interactive mode
REQ-F-004 F Provides: response envelope whose meta carries tool_version