feat: Add ability to download specific tool versions used by hooks. TLDR: add --hook-config=--tool-version=1.2.3 for pinning wrapped tool version. Works for all tools (even terraform and tofu) except checkov

[MaxymVlasov]

Warning

Do not even try to merge this PR before test from #1004 will be merged to this PR

Important

Testing that it is actually working as expected was not done by me yet. But some tests were already generated in #1004

• This PR introduces breaking change.
• This PR fixes a bug.
• This PR adds new functionality.
• This PR enhances existing functionality.

Description of your changes

What

_{This section was generated by AI.}

• Adds --hook-config=--tool-version=X.Y.Z version pinning to every hook that wraps a downloadable release binary (terraform_tflint, terraform_docs, terraform_tfsec/terraform_trivy, terrascan, infracost_breakdown, tfupdate, terragrunt_*, and Terraform/OpenTofu via terraform_validate/terraform_fmt/terraform_providers_lock), resolved and cached on demand by invoking the existing tools/install/<tool>.sh installer scripts - opt-in, zero effect on hooks that don't set it.
• Adds --hook-config=--tool-version-mode=strict|prefer-local to control whether a pinned version always wins (strict, default) or an already-on-$PATH binary is preferred when present (prefer-local).
• On terraform_validate/terraform_fmt/terraform_providers_lock, --tf-path can now also be set to the literal value terraform, opentofu, or tofu (instead of an actual binary path) when combined with --tool-version, to explicitly pick which of the two to pin rather than relying on $PATH-based auto-detection.
• Adds an actionable error (naming the missing tool and the hook, suggesting --hook-config=--tool-version=) when a hook's tool is neither pinned nor found on $PATH, instead of deferring to a generic "command not found" failure later.
• checkov/terraform_checkov is explicitly excluded (pip-distributed, not a GitHub-release binary - forcing it through this path would fight its actual, already-working distribution model).
• New README.md section documenting usage, a cache-directory-mounting note for persisting across Docker container runs, and a Renovate customManagers recipe for keeping pins auto-bumped.
• Updates .github/CONTRIBUTING.md's "Add new hook" checklist to mention the new runtime call site alongside the existing Docker build-time one.
• One small, backward-compatible change to tools/install/_common.sh: source /.env is now conditional on the file existing, so the installer scripts also run correctly when invoked directly at hook run-time (not just inside a Docker build).
• Fixes a bug where a failed tool resolution (common::resolve_tool_path) was silently swallowed by local -r tool_path=$(...), letting terraform_tflint, terraform_docs, infracost_breakdown, and the shared per_dir_hook continue with an empty tool path instead of aborting with the resolver's own error message.
• Corrects stale tool_path doc comments left over from the tf_path->tool_path rename in 9 hooks, and fixes invalid YAML indentation in 3 --tool-version README examples.
• Fixes terragrunt_validate/terragrunt_validate_inputs/terragrunt_fmt/terragrunt_providers_lock picking their pre/post-0.78 CLI syntax off whatever terragrunt is on $PATH instead of the resolved/pinned tool_path binary that actually runs - a pinned version on the other side of the 0.78 boundary from $PATH picked the wrong syntax and broke.

Why

This enables multi-version testing and the ability to pin the same versions of underlying tools by users, which is a decent improvement towards reproducibility.

Fix: #188, #270
Related: #722

How can we test changes

_{This section was generated by AI.}

- id: terraform_tflint
  args:
    - --hook-config=--tool-version=0.50.0

Run pre-commit run terraform_tflint - first run downloads and caches tflint 0.50.0 into $XDG_CACHE_HOME/pre-commit-terraform (or $HOME/.cache/pre-commit-terraform), subsequent runs hit the cache with no network call. Same pattern works for terraform_validate/terraform_fmt/terraform_providers_lock (pins Terraform/OpenTofu), optionally combined with --hook-config=--tf-path=opentofu to force OpenTofu specifically regardless of what's on $PATH.

Assisted-by

_{Specific models used per commit are specified in the commit messages.}

• Assisted-by: Sisyphus:claude-sonnet-5 opencode (b85f444, a5e62cc, a432cff, a475d47)
• Assisted-by: Sisyphus:claude-sonnet-5 claude (869f6b6)

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Hooks now support version-pinned tool resolution, cached installers, and resolved executable paths across Terraform, Terragrunt, and auxiliary tools. Documentation covers version pinning, Renovate configuration, cache persistence, and runtime installer usage.

Changes

Version-aware hook execution

Layer / File(s)	Summary
Shared resolver and cache foundation hooks/_common.sh, tools/install/_common.sh	Adds shared configuration parsing, OS/architecture detection, version-aware resolution, caching, Terraform/OpenTofu selection, and resolved Terragrunt version checks.
Generic hook wiring hooks/infracost_breakdown.sh, hooks/terraform_docs.sh, hooks/terraform_tflint.sh, hooks/terraform_checkov.sh, hooks/terraform_tfsec.sh, hooks/terraform_trivy.sh, hooks/terrascan.sh, hooks/tfupdate.sh	Passes tool names and resolved paths through wrappers and executes the selected binaries.
Terraform hook path propagation hooks/terraform_fmt.sh, hooks/terraform_providers_lock.sh, hooks/terraform_validate.sh	Routes formatting, provider locking, validation, initialization, and retry commands through resolved Terraform/OpenTofu paths.
Terragrunt hook path propagation hooks/terragrunt_*.sh	Routes Terragrunt per-directory and whole-repository commands through resolved binaries and version-dependent subcommands.
Documentation and contributor workflow README.md, .github/CONTRIBUTING.md	Documents pinned versions, Renovate configuration, cache mounting, and runtime installer usage.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Hook as Hook
  participant Common as common::per_dir_hook
  participant Resolver as common::resolve_tool_path
  participant Tool as Resolved tool
  Hook->>Common: pass tool_name and HOOK_CONFIG
  Common->>Resolver: resolve version and executable
  Resolver-->>Common: return tool_path
  Common->>Tool: execute per-directory or whole-repository command

Loading

Suggested reviewers: yermulnik

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 68.42% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: pinning downloadable hook tool versions with --hook-config=--tool-version.
Description check	✅ Passed	The description is directly about tool-version pinning, caching, exclusions, docs, and related fixes in this changeset.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch downloadable_and_version_controlled_hooks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[yermulnik]

I didn't read any of the Spec DMs — that (along with coding part of the PR) is too much of text for a single PR to be read be a human. Please split into separate PRs to ease review process and to separate entities. Thanks.

[Copilot]

Pull request overview

This PR adds opt-in, per-hook tool version pinning via --hook-config=--tool-version=... for hooks that wrap downloadable binaries, resolving/caching pinned versions on demand by reusing the existing tools/install/<tool>.sh installers. It also updates docs to explain usage (including a Docker cache mount pattern) and adjusts hook plumbing so wrapped tools are invoked via a resolved tool_path.

Changes:

• Extend common::per_dir_hook to resolve a wrapped tool binary path (optionally pinned + cached) and pass it into hook implementations.
• Add common::resolve_tool_path + supporting helpers (--tool-version, --tool-version-mode, OS/arch detection) and wire affected hooks to use the resolved tool path.
• Document the new pinning feature and add contributor guidance about the new runtime installer call site.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tools/install/_common.sh	Make /.env sourcing conditional to allow installer scripts to run outside Docker builds.
README.md	Document --tool-version / --tool-version-mode, Renovate custom manager, and Docker cache mounting.
hooks/_common.sh	Add tool resolution + caching utilities and update common::per_dir_hook signature/behavior to pass a resolved tool_path.
hooks/terraform_fmt.sh	Route hook execution through resolved Terraform/OpenTofu binary path.
hooks/terraform_validate.sh	Route validate/init flow through resolved Terraform/OpenTofu binary path.
hooks/terraform_providers_lock.sh	Route providers lock through resolved Terraform/OpenTofu binary path.
hooks/terraform_tflint.sh	Resolve tflint path (incl. for --init) and pass into per-dir execution.
hooks/terraform_docs.sh	Resolve terraform-docs path (optionally pinned) before building the command.
hooks/terraform_tfsec.sh	Resolve tfsec path and pass into per-dir/whole-repo execution.
hooks/terraform_trivy.sh	Resolve trivy path and pass into per-dir/whole-repo execution.
hooks/terrascan.sh	Resolve terrascan path and pass into per-dir/whole-repo execution.
hooks/tfupdate.sh	Resolve tfupdate path and pass into per-dir/whole-repo execution.
hooks/terragrunt_fmt.sh	Resolve terragrunt path and pass into per-dir/whole-repo execution.
hooks/terragrunt_validate.sh	Resolve terragrunt path and pass into per-dir/whole-repo execution.
hooks/terragrunt_validate_inputs.sh	Resolve terragrunt path and pass into per-dir/whole-repo execution.
hooks/terragrunt_providers_lock.sh	Resolve terragrunt path and pass into per-dir/whole-repo execution.
hooks/terraform_checkov.sh	Adapt to new per_dir_hook signature while keeping checkov unpinned/no resolved binary.
hooks/infracost_breakdown.sh	Resolve infracost path (optionally pinned) before running breakdown.
AGENTS.md	Extend skill routing table with OpenSpec-related skills.
.github/CONTRIBUTING.md	Note that tools/install/<tool>.sh is now used at runtime for --tool-version pinning.
.github/AI_POLICY.md	Add a “Recommended tooling” section referencing OpenSpec workflow.

Comments suppressed due to low confidence (2)

README.md:460

• This YAML example is not valid as written because args must be indented under the hook item. Update the indentation so users can copy/paste it.

    - id: terraform_validate
    args:
        - --hook-config=--tf-path=opentofu
        - --hook-config=--tool-version=1.12.0
    ```

README.md:481

• This YAML example is not valid as written because args must be indented under the hook item. The current indentation will fail YAML parsing if copied.

    - id: terraform_tflint
    args:
        - --hook-config=--tool-version=0.50.0
        - --hook-config=--tool-version-mode=prefer-local
    ```

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

hooks/_common.sh (1)

615-628: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Unrecognized --tool-version-mode values fall through to strict silently.

A typo (prefer_local, preferlocal) is indistinguishable from strict, so users get a download instead of the local binary with no hint why. A small validation on the accepted set would surface config mistakes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@hooks/_common.sh` around lines 615 - 628, Validate tool_version_mode in the
configuration handling around common::get_hook_config_value and accept only the
supported modes, including prefer-local and strict. For any unrecognized value,
emit a clear configuration warning or error instead of silently proceeding
through the strict download behavior; preserve the existing behavior for valid
values.

hooks/terragrunt_fmt.sh (1)

40-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Terragrunt hooks document tool_path as a Terraform/OpenTofu binary. The tf_path → tool_path rename carried the Terraform-specific wording into all four Terragrunt wrappers, which actually receive a resolved terragrunt binary; each file's run_hook_on_whole_repo block already uses the correct generic wording.

• hooks/terragrunt_fmt.sh#L40-L40: change the description to "resolved path to the wrapped tool's binary".
• hooks/terragrunt_providers_lock.sh#L42-L42: apply the same wording change.
• hooks/terragrunt_validate.sh#L42-L42: apply the same wording change.
• hooks/terragrunt_validate_inputs.sh#L42-L42: apply the same wording change.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@hooks/terragrunt_fmt.sh` at line 40, Update the tool_path description in the
run_hook_on_whole_repo blocks to say “resolved path to the wrapped tool's
binary” instead of Terraform/OpenTofu-specific wording. Apply this change in
hooks/terragrunt_fmt.sh (line 40), hooks/terragrunt_providers_lock.sh (line 42),
hooks/terragrunt_validate.sh (line 42), and hooks/terragrunt_validate_inputs.sh
(line 42).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hooks/_common.sh`:
- Around line 333-340: Check the exit status of common::resolve_tool_path
immediately after the tool_path assignment in the hook flow, and return or exit
non-zero before invoking run_hook_on_whole_repo when resolution fails. Apply the
same propagation to the early tool-path resolution in terraform_tflint.sh, and
ensure resolve_tool_path consistently returns a non-zero status for every
failure path.

In `@hooks/terraform_docs.sh`:
- Around line 24-26: Update the argument-rewriting loop in terraform_docs.sh so
the --config value is prefixed with the repository path only when it is
relative. Preserve values beginning with / unchanged, while retaining the
existing conversion for relative --config paths.

In `@README.md`:
- Line 443: Update the version-pinning description near the wrapped-tool
download behavior to replace the GitHub-specific wording with “the tool’s
upstream release assets” or equivalent, while preserving the existing caching
and first-use download behavior.
- Around line 447-460: Correct the indentation of args in both YAML examples,
terraform_tflint and terraform_validate, so args is nested beneath its
corresponding - id entry and the examples form valid pre-commit configuration.

---

Nitpick comments:
In `@hooks/_common.sh`:
- Around line 615-628: Validate tool_version_mode in the configuration handling
around common::get_hook_config_value and accept only the supported modes,
including prefer-local and strict. For any unrecognized value, emit a clear
configuration warning or error instead of silently proceeding through the strict
download behavior; preserve the existing behavior for valid values.

In `@hooks/terragrunt_fmt.sh`:
- Line 40: Update the tool_path description in the run_hook_on_whole_repo blocks
to say “resolved path to the wrapped tool's binary” instead of
Terraform/OpenTofu-specific wording. Apply this change in
hooks/terragrunt_fmt.sh (line 40), hooks/terragrunt_providers_lock.sh (line 42),
hooks/terragrunt_validate.sh (line 42), and hooks/terragrunt_validate_inputs.sh
(line 42).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: bc8e303e-4ccc-4c41-bad1-d1e6a6a03c0a

📥 Commits

Reviewing files that changed from the base of the PR and between bf9dd9c and a5e62cc.

📒 Files selected for processing (21)

• .github/AI_POLICY.md
• .github/CONTRIBUTING.md
• AGENTS.md
• README.md
• hooks/_common.sh
• hooks/infracost_breakdown.sh
• hooks/terraform_checkov.sh
• hooks/terraform_docs.sh
• hooks/terraform_fmt.sh
• hooks/terraform_providers_lock.sh
• hooks/terraform_tflint.sh
• hooks/terraform_tfsec.sh
• hooks/terraform_trivy.sh
• hooks/terraform_validate.sh
• hooks/terragrunt_fmt.sh
• hooks/terragrunt_providers_lock.sh
• hooks/terragrunt_validate.sh
• hooks/terragrunt_validate_inputs.sh
• hooks/terrascan.sh
• hooks/tfupdate.sh
• tools/install/_common.sh

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Avoid claiming every binary is downloaded from GitHub releases.

Terraform/OpenTofu resolution uses HashiCorp release installers, so this should say “the tool’s upstream release assets” (or similar) rather than specifically “GitHub releases.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 443, Update the version-pinning description near the
wrapped-tool download behavior to replace the GitHub-specific wording with “the
tool’s upstream release assets” or equivalent, while preserving the existing
caching and first-use download behavior.

[MaxymVlasov]

I don't see an issue here. "Github release" is more undersandable, IMO.
@yermulnik ?

[yermulnik]

"GitHub releases" describes the feature, but e.g. "GitHub releases page" (or with capitalized "Releases" to mark the section on the web-site) describes the actual location where we download assets from.
So I'd add "page" after "releases" to provide clarity. However, tech-savvies do indeed often say "Github releases" meaning "Github Releases page" =)
Up to you 👍

[coderabbitai]

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

hooks/terragrunt_validate_inputs.sh (1)

25-28: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Use the configured Terragrunt binary for version-gated subcommands.

common::terragrunt_version_ge_0.78 checks the terragrunt binary in PATH, but terragrunt_validate_inputs.sh selects SUBCOMMAND/RUN_ALL_SUBCOMMAND before common::per_dir_hook resolves --tool-version into tool_path. A pinned Terragrunt target crossing the 0.78 boundary can use the wrong CLI syntax; gate the subcommand selection against the configured/resolved tool version, or perform it where tool_path is available.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@hooks/terragrunt_validate_inputs.sh` around lines 25 - 28, Update
terragrunt_validate_inputs.sh so SUBCOMMAND and RUN_ALL_SUBCOMMAND selection
uses the configured or resolved Terragrunt binary represented by tool_path,
rather than the PATH terragrunt checked by common::terragrunt_version_ge_0.78.
Move the version-gated selection into the flow where tool_path is available, or
pass that binary explicitly, preserving the correct CLI syntax across the 0.78
boundary.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@hooks/terragrunt_validate_inputs.sh`:
- Around line 25-28: Update terragrunt_validate_inputs.sh so SUBCOMMAND and
RUN_ALL_SUBCOMMAND selection uses the configured or resolved Terragrunt binary
represented by tool_path, rather than the PATH terragrunt checked by
common::terragrunt_version_ge_0.78. Move the version-gated selection into the
flow where tool_path is available, or pass that binary explicitly, preserving
the correct CLI syntax across the 0.78 boundary.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 12a46dd1-a722-4db4-ae27-3d3c5d421e45

📥 Commits

Reviewing files that changed from the base of the PR and between 4438ee8 and b85f444.

📒 Files selected for processing (13)

• README.md
• hooks/_common.sh
• hooks/infracost_breakdown.sh
• hooks/terraform_docs.sh
• hooks/terraform_tflint.sh
• hooks/terraform_tfsec.sh
• hooks/terraform_trivy.sh
• hooks/terragrunt_fmt.sh
• hooks/terragrunt_providers_lock.sh
• hooks/terragrunt_validate.sh
• hooks/terragrunt_validate_inputs.sh
• hooks/terrascan.sh
• hooks/tfupdate.sh

🚧 Files skipped from review as they are similar to previous changes (12)

• hooks/infracost_breakdown.sh
• hooks/terraform_trivy.sh
• hooks/terraform_tflint.sh
• hooks/tfupdate.sh
• README.md
• hooks/terragrunt_validate.sh
• hooks/terraform_tfsec.sh
• hooks/terragrunt_fmt.sh
• hooks/terrascan.sh
• hooks/terraform_docs.sh
• hooks/terragrunt_providers_lock.sh
• hooks/_common.sh

[yermulnik]

Other than the below comment, the PR looks good to me 👍🏻