202504-2: Strict versioning for tools.yaml file

Date: 08/04/2025

Context

With tools.yaml being externalized and allowing user customization, there’s a risk of incompatibility between the tool definitions and the application code. Changes to the schema or expected tool definitions could lead to runtime errors that are difficult to diagnose.

Decision

Implement strict versioning for the tools.yaml file with version validation at startup. The application will define a required/current version, check if the provided tools.yaml file uses this version, and fail fast if there’s a version mismatch.

Rationale

1. Compatibility Assurance
   • Prevents runtime errors caused by incompatible tool definitions
   • Clearly communicates version requirements to users
   • Makes version mismatches immediately apparent
2. Error Handling
   • Provides clear error messages about version mismatches
   • Fails fast instead of letting subtle errors occur during operation
   • Guides users toward proper resolution
3. Recovery Path
   • Users can update their tools.yaml file manually to match the required version
   • Alternatively, users can simply delete their customized file and let the application regenerate it
   • Regeneration uses the embedded version which is guaranteed to be compatible
4. Upgrade Management
   • Clear versioning creates explicit upgrade paths
   • Version checks provide a mechanism to enforce schema migrations
   • Makes breaking changes in tool definitions more manageable

Trade-offs

Benefits

• Prevents subtle runtime errors
• Provides clear error messages
• Offers straightforward recovery options
• Makes version incompatibilities immediately apparent
• Simplifies upgrade paths

Challenges

• Need to manage version numbers across releases
• Must communicate version changes to users
• Requires additional validation logic at startup
• Necessitates documentation of version compatibility