Skip to content

feat(git-hooks): inspect what runs at each hook stage, and detect Husky.Net - #16627

Merged
kyle-sexton merged 8 commits into
mainfrom
feat/git-hooks-inspect
Nov 16, 2026
Merged

kyle-sexton merged 8 commits into
mainfrom
feat/git-hooks-inspect

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: extends the shared git-hook installer with a read-only stage inspect and Husky.Net detection; no tracked issue covers it.

Summary

Nothing showed what a repository's git hooks run at each stage across hook managers, or how long this marketplace's entries take there, which is the number the check-placement duration budgets need. The shared installer (lib/git-hooks/install.mjs, synced into the 11 carrier plugins) gains a read-only inspect action, exposed as setup check inspect, and detect now recognizes Husky.Net.

Fix

  • inspect lists, per git hook stage, every item that runs under the detected manager: plain dispatcher markers and a chained <event>.pre-checks, each line of .husky/<event>, the Husky.Net tasks a husky run --group/--name line selects, lefthook jobs from lefthook dump, git config hooks, and any other hook file. It runs only the calling plugin's own installed entries that rewrite nothing and whose tools are present (staged set, a message file outside the repo, or the branch against its upstream) and reports median, range, input and exit codes; every other item is notMeasured with the reason. lefthook dump is read-only: lefthook v2.2.2 loader.go loadRemotes reads only already-fetched remote folders.
  • detect returns husky with variant: "husky.net" when .husky/task-runner.json exists, so Husky.Net installs through the husky adapter as before (no new conflict). The husky-config decision now says a new .husky/<event> under Husky.Net must be #!/bin/sh, executable and staged 100755, since core.hooksPath=.husky makes git run it directly (Husky.Net InstallCommand).
  • Docs: check-placement contract (port block and inspect), adopting guide (Husky.Net install, "See what runs at each stage"), each carrier's setup body (check inspect section and allowed-tools), one minor changelog fragment per carrier (11).

Notes: setup never exposed list, so inspect is a new check inspect sub-action in each body; the argument-hint keeps [check|apply] first, as the argument-hint contract requires. In this repository the lefthook remote jobs list as plain lefthook jobs, not entries, because .lefthook/<event>/ holds same-named local scripts.

Verification

  • node --test --test-concurrency=4 lib/git-hooks/install.test.mjs: 238 tests, 234 pass, 0 fail, 4 skipped (config-hook cases need git 2.54; host has 2.53.0). The 12 new cases cover plain (own entry timed, another plugin's entry, chained hook not run, nothing staged, rewrites, missing tool, commit-msg, pre-push with and without upstream), husky 9, Husky.Net (detect, plan, --group tasks, bare run), lefthook (canned dump, binary absent), a foreign manager, config hooks, --runs bounds, and that inspect leaves the repository tree byte-identical. Removing the own-plugin gate made the "runs nothing else" case fail.
  • lib/git-hooks/install.test.sh passes; sh-entries.test.sh: 181 passed. scripts/sync-shared-copies.sh --check: all registered copies match. scripts/check-changelog-fragments.sh --check-required origin/main: 11 of 11. scripts/validate-plugins.sh on the 11 carriers, typos and check-as-of-recheck.sh: clean. The pre-push check-affected run passed.
  • Smoke run of inspect on this repository under lefthook 2.2.2: four stages listed from the merged config, remotes included.
  • Left out: no eval cases were added and the carriers' existing setup eval suites were not run (the change adds a read-only section; the installer behavior is covered by the unit tests above).

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC

kyle-sexton and others added 4 commits November 16, 2026 14:57
…ky.Net

The shared git-hook installer gains a read-only `inspect` action. For each
git hook stage it lists every item that runs under the repository's hook
manager (plain dispatcher markers and chained hooks, .husky/<event> lines,
lefthook jobs from `lefthook dump`, git config hooks, any other hook file),
names stamped entry copies by plugin and entry, and times only the calling
plugin's own installed entries that rewrite nothing and whose tools are
present. Every other item is reported not run, with the reason. Each
carrier's setup exposes it as `check inspect`.

`detect` recognizes Husky.Net's .husky/task-runner.json as husky with
variant "husky.net": Husky.Net runs .husky/<event> as husky does, so the
husky adapter drives it unchanged, and inspect lists the tasks a
`husky run --group` or `--name` line selects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC
Husky.Net points core.hooksPath at .husky, so git runs .husky/<event>
directly and skips it unless it is executable. The husky-config decision
now says so, and the adopting guide links Husky.Net's install steps for
contributors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC
… action

The argument-hint contract requires setup skills to lead with "[check|apply]";
`check inspect` stays documented in each body's own section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 20:05
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T20:08:44.730235Z 395e9f2 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 395e9f27e4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread lib/git-hooks/install.mjs Resolved
The plain dispatcher runs an installed copy whose first line is not
#!/bin/sh by its own shebang, so timing it under sh measured a shell
failure, not the check. inspect now reports such a copy as not measured,
naming the refresh that makes it timeable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC
@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Held for the owner's review of the decisions behind this change. The hold comes off when the owner confirms them.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 43946186308

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Hold lifted: the owner reviewed and confirmed the decisions behind this change (2026-11-16), and the no-per-stack-examples rule is applied (29f7c52).

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-security-review: 1 inline finding(s) on e55300c22869c575d6e7ce4926405b09bee59556; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

Comment thread lib/git-hooks/install.mjs Resolved
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 210a14f828aed2f2d4c3b5d7fa353ab6918a39ee: read 36 of 36 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16627, incremental (e55300c → 210a14f)

This was an incremental, blocking-only review: this lane already reviewed an earlier head, so it reports CRITICAL and IMPORTANT findings only. I read all 16 files in scope. The other 10 changelog fragments are identical to .changes/actionlint/..., and the other 10 install.mjs carrier copies are identical to plugins/actionlint/lib/git-hooks/install.mjs. Each copy's path is the same kind of plugin-lib or changelog path as its first path, so none of them behaves differently.

I found no security issues in this push.

Prior finding (IMPORTANT, forged stamp run by inspect): fixed

I checked the fix against the code rather than the thread reply.

  • timing() checks content before it runs anything. At lib/git-hooks/install.mjs#L1498-L1503 it now requires entry.event === event and copyState(found.file, entry, sourceHash(plugin, entry)) === "ok". Only then does it reach spawnSync("sh", [found.file, …]) at L1515.
  • copyState hashes the real file. At L584-L595 it computes stampHash over the copy's actual body (every line except the stamp, per readStamp at L387-L392), the check-lib.sh beside it and the manifest assets beside it. The result must match the stamp, and the stamp must match the hash of what the plugin ships now (sourceHash, L372-L377).
  • A forged copy cannot pass. A zero-hash stamp, a stamp that matches its own content, or an edited copy all fail. Passing would need a SHA-256 collision with the shipped content.
  • Script paths are confined. stampOf() (L1449-L1459) follows a script path only when its realpath is strictly inside the work tree or the hooks directory, both resolved through realOr. This applies to husky lines, lefthook commands, dispatcher markers and lefthook local scripts.
  • The new tests cover the bypasses. They plant forged stamps that would each touch a marker file, and assert the marker file never appears. They also cover a wrong event and a path outside the work tree.

Other changes checked, no finding

  • configHookItems. It now uses --null --name-only --get-regexp, then --get-all for each hook name. These are argv arrays with no shell, and git config keys cannot carry a NUL. It only reads data and runs none of it.
  • Setup SKILL.md bodies (11). The changes are routing text for check inspect, new argument-hint and description text, and the "still match what the plugin ships" wording, which now matches the code. No allowed-tools change is in this push.
    • The guardrails description dropped "and safe" and "verification" to stay under its length cap. No rule was removed.
    • No instruction-surface deletion maps to a protected class. I did not consult the register file; I judged by consequence.
  • Docs. The docs/contracts/check-placement/README.md and changelog fragment edits only describe the new behavior.

Other checks

  • No manifest (plugin.json / marketplace.json) changes.
  • No changes to trust controls, tokens, the kill switch or merge holds.
  • Nothing here can bill or spend credit.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 2 inline finding(s) on e55300c22869c575d6e7ce4926405b09bee59556; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment thread lib/git-hooks/install.mjs Resolved
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 210a14f828aed2f2d4c3b5d7fa353ab6918a39ee: read 36 of 36 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental, e55300c → 210a14f, blocking only)

This lane already reviewed an earlier head, so this pass posts only blocking findings. I read all 16 files on the to-read list in .claude-lane/incremental.diff. The other 10 plugins/*/lib/git-hooks/install.mjs copies and the other 10 changelog fragments are identical to the files I read. None of them sits at a path that changes what it does.

What changed

  • timing()
    • It now runs an installed copy only when two things hold:
      • copyState(found.file, entry, sourceHash(plugin, entry)) is ok: the stamp hash covers the body, the lib beside it and the assets, and it equals the hash of what the plugin ships now.
      • entry.event === event.
    • A stale copy gets a refresh hint. An edited or forged copy is reported not run.
    • The old #!/bin/sh check is gone. It is not needed, because a copy that matches the shipped hash already has the shipped first line.
  • stampOf(info, file) follows a script path only when its realpath is inside the work tree or the hooks directory. entryInCommand now uses path.resolve, so absolute paths and .. paths go through that check.
  • configHookItems now lists names with --null --name-only --get-regexp. For each name it:
    • reads the events with --null --get-all;
    • keeps only the values after the last empty one;
    • reports hook.<name>.enabled=false as disabled, checked before the git-version check.
  • The 11 setup skills gain a check inspect route, a check inspect (read-only) entry in each description, and argument hints of the form [check|apply] [inspect|…].
  • Tests cover a forged stamp, a self-consistent forged stamp, an edited copy, a hook on the wrong event, a path outside the tree, a linked worktree's absolute lefthook path, and the config-hook reset and disabled cases.

What I checked

  • copyState (L584-595). A self-consistent forged stamp hashes correctly but differs from currentHash, so it comes back stale and is not run; the test expects exactly that. A missing asset changes the hash, so that copy comes back modified. Getting a non-shipped body to read ok would take a hash collision.
  • within().
    • It uses realOr on both sides, so a symlink inside the tree that points outside it is rejected.
    • It rejects .. and ../….
    • It rejects an absolute relative path, which is what path.relative returns across Windows drives.
  • git config --null --get-all parsing. Every value ends with NUL, so slice(0, -1) drops only the trailing empty string. An empty value stays in the list as a "" element, and lastIndexOf("") uses it as the reset point. When the call fails, the result is an empty list.
  • configBool (L515) returns "false" for a bool-typed false value, which is what the new check compares against.

Earlier findings. All three are resolved, with no lines changed since resolution:

  • the forged-stamp execution finding;
  • the configHookItems finding about disabled hooks and the empty-value reset;
  • the setup-skill routing finding.

The owner states that each fix is in 210a14f, and the diff above matches those fixes. I did not raise any of them again. The owner's change to the argument-hint shape, [check|apply] [inspect|…] in place of [check [inspect]|…], follows the docs/contracts/argument-hint/README.md setup-skill rule they cite. I accept it.

Closing issue. There is none: the PR states that no issue covers it.

Manifests. This push changes no plugin.json or marketplace.json. The fragments keep bump: minor.

Verification. The test results are the author's claim. I did not run them, because this lane has no shell.

Spend. None. inspect runs locally and starts nothing that bills.

Verifier dropped 0 of 0 candidates. No verifier subagent ran; I reviewed the diff in this session.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Held: the security-review thread on install.mjs:1507 is valid (inspect runs a stamped file without checking its content against the shipped entry's hash). A fix for it and the two claude-review threads is in progress; the hold lifts once they are pushed and both lanes review that head.

…spect

inspect timed any file whose second line parsed as this plugin's stamp,
so a repository's .husky or lefthook line naming a forged script ran it.
It now times a copy only when its script, lib and assets hash to what the
plugin ships now (copyState is ok) and the entry's own event matches the
stage; an edited or forged copy is reported not run, an older one gets a
refresh hint. A script path from a husky or lefthook command, a
dispatcher marker or a lefthook script is followed only inside the work
tree or the hooks directory, which holds a linked worktree's local copies.

Config hooks honor an empty hook.<name>.event value's reset and report
hook.<name>.enabled=false as disabled.

Each setup skill that carries the inspect section routes `check inspect`
to it: the routing sentence, the description's action list and an
argument-hint of `[check|apply] [inspect|...]`, the setup shape the
argument-hint contract and validator accept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Hold lifted: the three findings are fixed in 210a14f (inspect runs a copy only when its script, lib and assets hash to the shipped entry, on that entry's event, from inside the work tree or hooks dir) and resolved; both review lanes reviewed 210a14f with no new thread.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 3259265 Nov 16, 2026
112 of 113 checks passed
@kyle-sexton
kyle-sexton deleted the feat/git-hooks-inspect branch November 16, 2026 22:05
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant