ai-push-hooks 0.3.1 → 0.3.3

package/docs/configuration.md

@@ -0,0 +1,339 @@
+# Configuration
+
+Define workflows in `ai-push-hooks.toml` at the repository root. Start with the [README example](../README.md#example-check-your-rules) or the [starter configuration](../ai-push-hooks.toml).
+
+## Installation
+
+The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. It needs Node 18+ and Python 3.10-3.13 on the hook's `PATH`; the npm package does not bundle Python.
+
+For pnpm:
+
+```bash
+pnpm add -D ai-push-hooks@beta
+pnpm exec ai-push-hooks init --template minimal-docs
+pnpm exec ai-push-hooks install
+```
+
+For a Python-only installation:
+
+```bash
+python -m pip install ai-push-hooks
+ai-push-hooks init --template minimal-docs
+ai-push-hooks install
+```
+
+`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command. npm uses the `beta` tag while the package is in beta.
+
+AI steps need the selected CLI installed and authenticated with an available model. Deterministic-only workflows do not need one. `init` and `install` refuse to overwrite existing files; `--force` explicitly replaces them.
+
+## Modules And Steps
+
+`[workflow].modules` selects the modules to run. Define each module under `modules.<name>` with a non-empty list of steps. Modules are enabled by default; set `enabled = false` to disable one.
+
+Step inputs refer to earlier artifacts in the same module: `collect/push.diff`, for example. Cross-module inputs are not supported. Independent `collect` and `ask` work may run concurrently; built-in `exec`, `assert`, and `apply` steps are serialized. Trusted custom command runners, including project-access `ask` commands, are not enforced read-only.
+
+| Field | Used by | Meaning |
+| --- | --- | --- |
+| `id` | All | Unique step name within the module. |
+| `type` | All | `collect`, `ask`, `apply`, `exec`, or `assert`. |
+| `inputs` | Non-collector steps | Earlier module-local artifacts. |
+| `when_env` | All | Run only when the named environment variable is true. |
+| `collector` | `collect` | Built-in collector name. |
+| `prompt` | `ask`, `apply` | Inline instructions. |
+| `prompt_file` | `ask`, `apply` | Repository-relative prompt file. |
+| `fallback_prompt_id` | `ask`, `apply` | Built-in prompt name. |
+| `runner` | `ask`, `apply` | Override the default runner profile. |
+| `output` | `ask` | Required response artifact filename. |
+| `schema` | `ask` | Optional JSON schema name. Omit for plain text. |
+| `allow_paths` | `apply` | Required list of permitted edit globs. |
+| `executor` | `exec` | Built-in action name. |
+| `assertion` | `assert` | Built-in assertion name. |
+| `python` | `collect`, `exec`, `assert` | Repository-local callback reference. |
+| `options` | Python steps | JSON-compatible callback options. |
+| `command` | `exec`, `assert` | Direct argv command. |
+| `stdin` | Command steps | One declared input to send on stdin. |
+| `timeout_seconds` | Command steps | Positive timeout; default `60`. |
+
+Choose one handler per deterministic step: a built-in, a callback, or a command. Prompt resolution uses `prompt`, then `prompt_file`, then `fallback_prompt_id`.
+
+`ask` produces a response, not an automatic policy verdict. Use `assert` to evaluate findings when they should block. `apply` can run without a preceding `ask`; an input ending in `issues.json` containing `[]` skips the apply step.
+
+Upgrading from 0.2.1? Rename `type = "llm"` steps to `type = "ask"`.
+
+## Runner Profiles
+
+`[llm].runner` selects the default; a step's `runner` overrides it. Referenced profiles must exist under `[runners.<name>]`, except for the implicit OpenCode default.
+
+OpenCode, Codex, and Claude are first-class adapters. The generic `command` type is for other agentic CLIs and follows the custom runner contract below.
+
+| Profile field | Values / behavior |
+| --- | --- |
+| `type` | Required: `opencode`, `codex`, `claude`, or `command`. |
+| `model` | Runner-specific model identifier. |
+| `project_access` | `artifacts` or `project`; OpenCode defaults to `artifacts`, others to `project`. |
+| `variant` | Optional OpenCode variant. |
+| `command` | Required argv array for command runners. |
+| `prompt_transport` | Command runners: `stdin` (default) or `argv`. |
+
+Without an explicit OpenCode profile, `[llm].model` and `[llm].variant` configure it. Explicit profiles use their own model settings. `AI_PUSH_HOOKS_MODEL` overrides the selected profile's model.
+
+Artifact mode supplies collected inputs in a scratch directory. Project mode lets analysis inspect the checkout. Apply always uses a temporary staging copy, with propagation limited by `allow_paths`.
+
+OpenCode runs with isolated configuration and permissions; project/global configuration, external plugins, and MCP servers are not loaded. Codex uses read-only analysis and workspace-write apply modes. Claude Code uses separate analysis and editing permissions. Authenticate the CLI before using it in a hook.
+
+Apply requires a single pushed branch whose local commit is the checked-out `HEAD`. Staging excludes Git metadata, `AGENTS.md`, ignored files, symlinks, and special files. These controls are not an OS sandbox or an automatic rollback system. See [Security](../SECURITY.md).
+
+### Live validation snapshot
+
+Live read/review and apply checks on Linux:
+
+| Date | Runner (CLI; model) | Review | Apply |
+| --- | --- | --- | --- |
+| 2026-09-12 | OpenCode (1.18.29; `openai/gpt-5.6-luna`) | Passed | Passed |
+| 2026-09-12 | Claude Code (2.1.220; `sonnet`) | Passed | Passed |
+| 2026-09-14 | Codex (0.152.0; `gpt-5.6-luna`) | Passed | Passed |
+
+The Codex check read a random value from a disposable repository, then verified
+that only the allowlisted README changed. These checks establish the tested
+operations, not compatibility with every model or platform.
+
+#### Local troubleshooting: Codex sandbox
+
+For Codex 0.152, the standalone no-AI sandbox syntax is
+`codex sandbox -- /usr/bin/true`. Resolve host restrictions rather than disabling
+protections, and use a deterministic postcondition to verify the desired checkout
+outcome after an apply.
+
+### Apply and manual commits
+
+`apply` is generic: it can edit any eligible checkout file matching `allow_paths`; it is not limited to Markdown. The runner edits a temporary staging copy, and only validated changes propagate back to the checkout. Those edits do not enter the commit already being pushed, and `apply` never creates a Git commit.
+
+The existing `docs_apply_requires_manual_commit` assertion is a workflow gate, not human-review enforcement. It prevents the original push from passing after `apply` changes files; it cannot prove that anyone reviewed the edits or that they conform to policy. Add it after the `apply` step when that gate is desired:
+
+```toml
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+The assertion checks `apply/result.json`'s `changed_files` and intentionally blocks when edits were propagated. Review `git diff`, run the relevant checks, commit the approved changes, and retry the push. On the retry, the assertion passes when the apply step reports no changes.
+
+### Deterministic postconditions after apply
+
+An apply process succeeding, or reporting `changed_files = []`, is not proof that
+the requested result is present. The latter can simply mean that the apply was a
+legitimate no-op because the checkout was already correct. Add a deterministic
+postcondition after `apply` and before the manual-commit gate when the desired
+file content has a precise representation:
+
+```toml
+[general]
+require_clean_worktree = true
+
+[workflow]
+modules = ["docs"]
+
+[modules.docs]
+enabled = true
+
+[[modules.docs.steps]]
+id = "apply"
+type = "apply"
+prompt = "In the existing README.md, replace 'Release note: DRAFT.' with 'Release note: READY.' and make no other changes."
+allow_paths = ["README.md"]
+
+[[modules.docs.steps]]
+id = "postcondition"
+type = "assert"
+command = [
+  "{python}",
+  "-c",
+  "import pathlib, sys; sys.exit(0 if pathlib.Path('README.md').read_text(encoding='utf-8') == 'Release note: READY.\\n' else 1)",
+]
+inputs = ["apply/result.json"]
+
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+This is an intentional synthetic example, not a recommendation to overwrite a
+real README: its fixture starts with exactly `Release note: DRAFT.\n`, and its
+desired full content is exactly `Release note: READY.\n`.
+The command is a direct argv vector rather than a Python `assert`; Python
+optimization must not be able to remove the check. The postcondition reads the
+checkout after apply, not the commit being pushed. Keep the clean-worktree
+workflow setting for the hook's starting state and the manual-commit gate for
+the intentionally dirty post-apply checkout: review the resulting diff, run
+relevant checks, commit it, and retry the push. This gate and postcondition
+still do not prove human review, semantic correctness, or that an agent
+complied with every instruction.
+
+## Custom Runners
+
+Use a `command` profile to invoke any other agentic CLI, including Pi, directly or through a thin wrapper. A wrapper can normalize JSONL events into a final response. The runner must be noninteractive: read the prompt from stdin or argv, write only the final response to stdout, and use exit codes to report success or failure.
+
+```toml
+[runners.custom]
+type = "command"
+command = ["/absolute/path/to/scripts/review-agent"]
+prompt_transport = "stdin"
+project_access = "project"
+```
+
+Select it with `runner = "custom"` on an `ask` or `apply` step. The runner receives the full instruction and artifact packet. For apply, its working directory is the staging copy.
+
+Commands are argv arrays, not shell strings. Whole-argument placeholders are `{model}`, `{cwd}`, `{stage}`, and `{prompt}`. The `argv` transport requires exactly one `{prompt}` argument; stdin avoids exposing prompts in process listings. Custom programs inherit the user's environment, including authentication variables, and manage their own permissions and session setup/cleanup. For apply, the working directory is the staging copy.
+
+## Commands And Callbacks
+
+Command steps run in the real repository, with no implicit shell. Exit zero means success; a nonzero exit blocks the workflow. stdout, stderr, and a `result.json` report are saved as step artifacts.
+
+```toml
+[[modules.verify.steps]]
+id = "tests"
+type = "exec"
+command = ["{python}", "-m", "pytest", "-q"]
+timeout_seconds = 300
+```
+
+Available whole-argument placeholders are `{repo}`, `{python}`, and `{input:<step/artifact>}`. Input placeholders must also appear in `inputs`. Stdin is closed unless `stdin` names a declared input. Command output is bounded to 16 MiB per stream.
+
+For custom context or policy, reference a top-level synchronous Python function:
+
+```toml
+[[modules.policy.steps]]
+id = "change-size"
+type = "assert"
+python = "checks/hooks.py:check_size"
+options = { max_files = 25 }
+```
+
+In `checks/hooks.py`:
+
+```python
+from ai_push_hooks.plugins import PluginContext
+
+
+def check_size(context: PluginContext) -> dict:
+    ok = len(context.push.changed_files) <= context.options["max_files"]
+    return {"ok": ok, "message": "Change exceeds the configured file limit." if not ok else ""}
+```
+
+Add `policy` to `[workflow].modules` to enable it. Callbacks receive repository and step identifiers, push facts, input paths, options, prior module metadata, and a logger.
+
+| Callback type | Return value |
+| --- | --- |
+| `collect` | `CollectorResult` from `ai_push_hooks.plugins`, with artifacts and metadata. |
+| `exec` | JSON-serializable dictionary, saved as `result.json`. |
+| `assert` | Dictionary with boolean `ok` and optional string `message`; false blocks. |
+
+Callbacks run as trusted in-process code with already-installed dependencies. There is no callback timeout or automatic dependency installation. Collectors may run concurrently, so custom collectors must be concurrency-safe.
+
+## Built-In Handlers
+
+| Kind | Name | Purpose |
+| --- | --- | --- |
+| Collector | `docs_context` | Push diff, changed files, docs excerpts, recent commits. |
+| Collector | `beads_status_context` | Branch and Beads task context. |
+| Collector | `pr_context` | Context for a pull request. |
+| Action | `beads_alignment` | Apply supported `bd update` / `bd close` operations. |
+| Action | `gh_pr_create` | Create or reuse a PR through `gh`. |
+| Assertion | `docs_apply_requires_manual_commit` | Block after applied docs changes. |
+| Assertion | `beads_alignment_clean` | Block on unresolved task alignment. |
+
+Beads steps need the native `bd` CLI; PR creation needs `gh`. Gate optional actions with `when_env = "AI_PUSH_HOOKS_CREATE_PR"`, for example. Beads schema and database maintenance remain separate from hook execution.
+
+| JSON schema | Payload |
+| --- | --- |
+| `string_array` | Array of strings. |
+| `docs_issue_array` | Array of objects with `file` and `description`. |
+| `beads_alignment_result` | Object with optional `commands` string array. |
+| `pr_create_payload` | Object containing PR creation fields. |
+
+Built-in prompts: `docs-query-basic`, `docs-analysis-basic`, `docs-apply-basic`, `beads-plan-basic`, and `pr-compose-basic`.
+
+## Settings
+
+These optional settings supplement the workflow and runner definitions:
+
+| Section | Key | Default |
+| --- | --- | --- |
+| `general` | `enabled` | `true` |
+| `general` | `allow_push_on_error` | `false` |
+| `general` | `require_clean_worktree` | `false` |
+| `general` | `skip_on_sync_branch` | `true` |
+| `general` | `base_branch` | `"main"` |
+| `llm` | `runner` | `"opencode"` |
+| `llm` | `model` | `"openai/gpt-5.6-luna"` (implicit OpenCode profile) |
+| `llm` | `variant` | `""` |
+| `llm` | `timeout_seconds` | `800` |
+| `llm` | `max_parallel` | `2` |
+| `llm` | `json_max_retries` | `2` |
+| `llm` | `invalid_json_feedback_max_chars` | `6000` |
+| `llm` | `json_retry_new_session` | `true` |
+| `llm` | `delete_session_after_run` | `true` |
+| `llm` | `max_diff_bytes` | `180000` |
+| `llm` | `session_title_prefix` | `"ai-push-hooks"` |
+| `logging` | `level` | `"status"` (`info` and `debug` also available) |
+| `logging` | `jsonl` | `true` |
+| `logging` | `capture_llm_transcript` | `true` (OpenCode only) |
+| `logging` | `print_llm_output` | `false` |
+| `logging` | `dir` | `".git/ai-push-hooks/logs"` |
+| `logging` | `transcript_dir` | `".git/ai-push-hooks/transcripts"` |
+| `logging` | `summary_dir` | `".git/ai-push-hooks/summaries"` |
+
+Model availability depends on the provider. Select one available to your account rather than assuming the starter's model is accessible.
+
+## Environment Overrides
+
+| Variable | Effect |
+| --- | --- |
+| `AI_PUSH_HOOKS_SKIP=1` | Skip the hook before loading configuration. |
+| `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR=1` | Log errors but allow the push. |
+| `AI_PUSH_HOOKS_REQUIRE_CLEAN=1` | Require a clean worktree. |
+| `AI_PUSH_HOOKS_ALLOW_DIRTY=1` | Allow a dirty worktree. |
+| `AI_PUSH_HOOKS_BASE_BRANCH` | Override the base branch. |
+| `AI_PUSH_HOOKS_MODEL` | Override the selected runner's model. |
+| `AI_PUSH_HOOKS_VARIANT` | Override the OpenCode variant. |
+| `AI_PUSH_HOOKS_TIMEOUT_SECONDS` | Override the runner timeout. |
+| `AI_PUSH_HOOKS_LOG_LEVEL` | Set console verbosity. |
+| `AI_PUSH_HOOKS_PRINT_LLM_OUTPUT=1` | Print normalized, redacted final responses; sensitive opt-in. |
+
+Boolean values accept `1/0`, `true/false`, `yes/no`, `y/n`, and `on/off`. Skips and fail-open settings are explicit policy choices, not successful checks.
+
+## Hook Managers
+
+The built-in `install` command creates a repository-local pre-push hook without changing Git configuration. Existing hooks require explicit `--force` replacement; shared/external paths and symlinks are refused. Keep the installed Python executable or local npm package available at its installed location.
+
+For Lefthook, use this in `lefthook.yml` instead of the built-in installer:
+
+```yaml
+pre-push:
+  commands:
+    ai-checks:
+      run: npx --no-install ai-push-hooks hook {1} {2}
+      use_stdin: true
+```
+
+Run `lefthook install`. For a Python installation, omit the `npx --no-install` prefix. Other hook managers must likewise forward Git's remote arguments, ref-update stdin, and exit status. If earlier commands consume stdin, capture it first and replay it to ai-push-hooks.
+
+To remove the generated hook, inspect `git rev-parse --git-path hooks/pre-push` and remove only the ai-push-hooks delegate or its entry in your hook manager. Preserve unrelated hook commands.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Hook does not run | Reinstall with your chosen hook manager and inspect `git config --get core.hooksPath`. |
+| Missing runner or authentication failure | Ensure the CLI is on the hook's `PATH`, authenticated, and configured with an available model. |
+| Unknown profile | Match `runner` to an existing `[runners.<name>]`. |
+| Runner capability error | Update the CLI to a version with the required adapter flags. |
+| Invalid JSON | Check the prompt and schema; invalid JSON is retried twice by default. |
+| Push blocked after edits | Review `git diff`, run checks, commit approved changes, and retry the push. |
+| Need diagnostics | Inspect `.git/ai-push-hooks/logs` and `.git/ai-push-hooks/summaries`. |
+
+For validation commands, see [Contributing](../CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {
@@ -30,7 +30,7 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --no-project --with pytest --with build --with pip --with \"tomli; python_version < '3.11'\" pytest tests -q",
+    "test": "uv run --no-project --with \".[dev]\" python -m pytest tests -q",
     "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
@@ -38,9 +38,9 @@
     "src/**/*.py",
     "vendor",
     "README.md",
+    "docs/configuration.md",
     "CHANGELOG.md",
     "SECURITY.md",
-    "run.sh",
     "pyproject.toml",
     "LICENSE",
     "ai-push-hooks.toml"

package/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.1"
+version = "0.3.3"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,7 +34,7 @@ Changelog = "https://github.com/shanebishop1/ai-push-hooks/blob/main/CHANGELOG.m
 ai-push-hooks = "ai_push_hooks.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "build", "pip", "ruff", "twine"]
 
 [tool.setuptools]
 include-package-data = true
@@ -44,3 +44,12 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

package/src/ai_push_hooks/artifacts.py

@@ -45,11 +45,17 @@ class ArtifactStore:
         step_name = validate_path_component(step_id, "Artifact step id")
         lexical_module_path = self.run_dir / module_name
         if path_has_symlink(self.run_dir, lexical_module_path):
-            raise HookError(f"Artifact module path must not traverse a symlink: {module_id}")
-        module_path = resolve_contained_path(self.run_dir, module_name, "Artifact module path")
+            raise HookError(
+                f"Artifact module path must not traverse a symlink: {module_id}"
+            )
+        module_path = resolve_contained_path(
+            self.run_dir, module_name, "Artifact module path"
+        )
         lexical_step_path = module_path / f"{step_index:02d}-{step_name}"
         if path_has_symlink(self.run_dir, lexical_step_path):
-            raise HookError(f"Artifact step path must not traverse a symlink: {step_id}")
+            raise HookError(
+                f"Artifact step path must not traverse a symlink: {step_id}"
+            )
         path = resolve_contained_path(
             module_path,
             f"{step_index:02d}-{step_name}",
@@ -125,7 +131,9 @@ class ArtifactStore:
         payload: Any,
     ) -> pathlib.Path:
         path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
-        write_text_no_follow(path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n")
+        write_text_no_follow(
+            path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n"
+        )
         return self.register(state, step_id, artifact_name, path)
 
     def serialize_plugin_artifacts(
@@ -152,7 +160,10 @@ class ArtifactStore:
             try:
                 if isinstance(payload, (dict, list)) or artifact_name.endswith(".json"):
                     content = (
-                        json.dumps(payload, ensure_ascii=True, indent=2, allow_nan=False) + "\n"
+                        json.dumps(
+                            payload, ensure_ascii=True, indent=2, allow_nan=False
+                        )
+                        + "\n"
                     ).encode("utf-8")
                 elif isinstance(payload, str):
                     content = payload.encode("utf-8")
@@ -169,7 +180,9 @@ class ArtifactStore:
                 )
             total_bytes += len(content)
             if total_bytes > max_total_bytes:
-                raise HookError("CollectorResult artifacts exceed the aggregate size limit")
+                raise HookError(
+                    "CollectorResult artifacts exceed the aggregate size limit"
+                )
             serialized[artifact_name] = content
         return serialized
 

package/src/ai_push_hooks/cli.py

@@ -43,30 +43,44 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         except FileNotFoundError:
             metadata = None
         except OSError as exc:
-            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+            raise HookError(
+                f"Could not inspect config path {config_path}: {exc}"
+            ) from exc
         if metadata is not None:
             if path_is_link_or_reparse(config_path):
-                raise HookError(f"Refusing to replace symlink or reparse point: {config_path}")
+                raise HookError(
+                    f"Refusing to replace symlink or reparse point: {config_path}"
+                )
             if not stat.S_ISREG(metadata.st_mode):
-                raise HookError(f"Refusing to replace non-regular config path: {config_path}")
+                raise HookError(
+                    f"Refusing to replace non-regular config path: {config_path}"
+                )
         try:
             write_text_no_follow(config_path, MINIMAL_DOCS_TEMPLATE)
         except HookError:
             raise
         except OSError as exc:
-            raise HookError(f"Could not write config file {config_path}: {exc}") from exc
+            raise HookError(
+                f"Could not write config file {config_path}: {exc}"
+            ) from exc
     else:
         try:
             metadata = config_path.lstat()
         except FileNotFoundError:
             metadata = None
         except OSError as exc:
-            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+            raise HookError(
+                f"Could not inspect config path {config_path}: {exc}"
+            ) from exc
         if metadata is not None:
             if path_is_link_or_reparse(config_path):
-                raise HookError(f"Refusing to overwrite symlink or reparse point: {config_path}")
+                raise HookError(
+                    f"Refusing to overwrite symlink or reparse point: {config_path}"
+                )
             if not stat.S_ISREG(metadata.st_mode):
-                raise HookError(f"Refusing to overwrite non-regular config path: {config_path}")
+                raise HookError(
+                    f"Refusing to overwrite non-regular config path: {config_path}"
+                )
         flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
         flags |= getattr(os, "O_NOFOLLOW", 0)
         try:
@@ -76,7 +90,9 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
                 f"Refusing to overwrite existing config without --force: {config_path}"
             ) from exc
         except OSError as exc:
-            raise HookError(f"Could not create config file {config_path}: {exc}") from exc
+            raise HookError(
+                f"Could not create config file {config_path}: {exc}"
+            ) from exc
         try:
             with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
                 descriptor = -1