Repository navigation
Open
Labels
contract:hook-managerTool capability: git-hook managers under the secure setup (install target, sandbox / host homes)Tool capability: git-hook managers under the secure setup (install target, sandbox / host homes)family:setupsetup-* skillssetup-* skillsgood first issueGood for newcomersGood for newcomers
Description
The hook-manager contract (#1819) defines how the secure agent setup integrates a git-hook manager: where its install puts the hook, how its home is split between sandboxed and host runs, and how the setup detects that a repository uses it.
prek is the only adapter so far.
This issue adds pre-commit (Python).
What the source says (pre-commit v4.7.0)
- Install target.
pre-commit installalways writes$(git rev-parse --git-common-dir)/hooks/<type>(commands/install_uninstall.py:47-53,git.py:86-93), but refuses whengit config core.hooksPathreturns anything (git.py:180-182):
Cowardly refusing to install hooks with core.hooksPath set.(install_uninstall.py:123-127).
Under the whole-user setup the globalcore.hooksPathis always set, so a plain install always fails.
There is no--git-dirflag (main.py:273-293). - Fix.
GIT_CONFIG_GLOBAL=/dev/null pre-commit installhides the global value from that check, and the install lands in the common dir.
Do not useGIT_CONFIG_COUNTto overridecore.hooksPath: any non-empty value is refused, and git treats an empty value as set (hooks then resolve against/).
Do not usepre-commit init-templatediras a workaround: it forcesoverwrite=True, which moves a foreign hook to.legacyand then deletes it. - Home.
PRE_COMMIT_HOME, else$XDG_CACHE_HOME/pre-commit, else~/.cache/pre-commit(store.py:32-36).
Hook runs execute the repositories cloned and the environments built there (repository.py:177,196), so it needs the same sandbox/host split as prek.
PRE_COMMIT_HOMEdoes not expand~(onlyos.path.realpath), so the committed settings cannot spell the sandbox home as~/.cache/pre-commit-sandbox; it would become<cwd>/~/.cache/.... - Generated hook. It hardcodes the install-time Python (
INSTALL_PYTHON=...) with a fallback topre-commitonPATH, and passes--hook-dir "$(dirname "$0")", which is used only to find<type>.legacy(hook_impl.py:36-46).
The dispatcher execs it by its real path, so that works. - Detection. Config
.pre-commit-config.yaml(or a custom--configpath written into the hook); no nested configs.
Hook marker: the generated hook namespre-commit.
What to do
- Add a
hide-global-configinstall strategy totools/agent-isolation/hook-manager-shim.sh(run the install withGIT_CONFIG_GLOBAL=/dev/null) and toSTRATEGIESintools/dev/sync-hook-managers.py, with a shim test. - Decide how a home that does not expand
~gets a per-user sandbox value.
The contract requiresexpands_tilde: truetoday.
One option:sandbox-add-project-root.shwrites the absolutePRE_COMMIT_HOMEinto the per-user.claude/settings.local.json, andsandbox-lintaccepts it there.
Write the choice into the contract's Home section. - Add the
pre-commitadapter totools/hook-manager/registry.json(detect.config_files: [".pre-commit-config.yaml", ".pre-commit-config.yml"],nested: false,hook_marker: "pre-commit") and runtools/dev/sync-hook-managers.py. - The two YAML names are shared with prek, so a repository with either uses both managers as far as detection goes; check that both homes are set for it and nothing breaks.
- Update the adapter table in the contract, and
docs/setup/sandbox-troubleshooting.mdfor the "Cowardly refusing" error.
Acceptance
pre-commit installthrough~/.claude/bin/pre-commitsucceeds under a globalcore.hooksPathand writes to the common dir, including in a linked worktree.- A hook run outside the sandbox gets a host-only
PRE_COMMIT_HOME; a sandboxed run gets the sandbox home; a repository without a pre-commit config gets neither. prek run --all-files --skip workspace-pytestand the agent-isolation, sandbox-lint and dev tests pass.
Metadata
Metadata
Assignees
Labels
contract:hook-managerTool capability: git-hook managers under the secure setup (install target, sandbox / host homes)Tool capability: git-hook managers under the secure setup (install target, sandbox / host homes)family:setupsetup-* skillssetup-* skillsgood first issueGood for newcomersGood for newcomers
Activity
ninglinLiu commentedon Oct 25, 2026
I'd like to work on this one: add the
hide-global-configinstall strategy tohook-manager-shim.shandSTRATEGIES, the pre-commit registry entry (with the non-expandingPRE_COMMIT_HOMEhandled explicitly), regenerate withtools/dev/sync-hook-managers.py, and add shim tests for the new strategy. Could a maintainer assign it to me? I'll wait for the assignment before opening a PR.