ai-push-hooks 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,7 +4,28 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-No changes yet.
+## [0.2.1] - 2026-09-08
+
+This is a beta patch release. Python and npm both use `0.2.1`, the canonical
+Git tag is `v0.2.1`, npm uses the `beta` dist-tag, and GitHub marks the release
+as a prerelease.
+
+### Fixed
+
+- Restored OpenCode's built-in plugins, including built-in authentication such as
+  Codex OAuth, during isolated runs. `--pure` still excludes external plugins,
+  and project/global configuration and plugins remain isolated.
+- Restored forwarding of recognized provider environment variables, including
+  `OPENAI_API_KEY`, so OpenCode itself selects the authentication path.
+- Prevented hook-launched Beads alignment updates from inheriting schema and
+  remote-migration safety overrides.
+- Made post-publication PyPI verification tolerate bounded 404/partial metadata
+  propagation while retaining fail-closed artifact hash and authentication checks.
+
+### Documentation
+
+- Documented the native `bd` maintenance, backup, rehearsal, and remote
+  publication boundaries; Beads-Rust (`br`) is not supported.
 
 ## [0.2.0] - 2026-09-06
 
@@ -58,6 +79,7 @@ the exact `0.2.0` version rather than a PyPI beta channel.
 - Preserved Git porcelain paths and protected pre-existing dirty allowlisted files during apply steps.
 - Clarified module-local artifact references and standardized the repository hook integration.
 
-[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.1.19...v0.2.0
 [0.1.19]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.1.18...v0.1.19

package/README.md

@@ -12,7 +12,7 @@ Use it to keep docs aligned with code, check branch/task consistency, or prepare
 - [Python 3.10–3.13](https://www.python.org/downloads/). Python is required even when installing the npm wrapper. The wrapper probes Python 3.14, 3.13, 3.12, 3.11, 3.10, then `python`; the 3.14 probe is not a beta support claim. Python 3.10 additionally needs the `tomli` package available to that interpreter.
 - [OpenCode](https://opencode.ai/docs/#install) is optional for workflows that use only deterministic steps, but the `minimal-docs` starter uses `llm` and `apply`. Those steps also need a provider/model and authentication; check with `opencode auth list`.
 - [GitHub CLI (`gh`)](https://cli.github.com/manual/installation) is optional and needed only for `gh_pr_create`.
-- [Beads (`bd`)](https://github.com/steveyegge/beads) is optional and needed only for Beads alignment steps.
+- [Beads (`bd`)](https://github.com/steveyegge/beads) is optional and needed only for Beads alignment steps. The integration requires the native `bd` CLI; Beads-Rust (`br`) is not a supported substitute.
 - [Lefthook](https://lefthook.dev/installation/) and [Mise](https://mise.jdx.dev/getting-started.html) are optional hook-manager/tool-version alternatives described below.
 
 ### Install ai-push-hooks
@@ -21,7 +21,7 @@ This is the shortest path. It installs the package, writes the exact starter
 configuration filename, and installs a repository-local `pre-push` delegate:
 
 ```bash
-python -m pip install ai-push-hooks==0.2.0
+python -m pip install ai-push-hooks==0.2.1
 ai-push-hooks init --template minimal-docs
 ai-push-hooks install
 ```
@@ -33,9 +33,9 @@ the bare remote. The first command above can instead be `uv tool install
 ai-push-hooks` or `pipx install ai-push-hooks` when using an isolated
 application environment.
 
-These instructions describe the `0.2.0` beta release. npm exposes it through
+These instructions describe the `0.2.1` beta release. npm exposes it through
 the `beta` dist-tag; PyPI has no separate beta channel, so Python installation
-must select the exact `0.2.0` version. Published `0.1.19` artifacts retain
+must select the exact `0.2.1` version. Published `0.1.19` artifacts retain
 historical provenance and must not be assumed to contain this release's
 `install` command.
 
@@ -55,7 +55,7 @@ npx --no-install ai-push-hooks install
 # or: pnpm add -D ai-push-hooks && pnpm exec ai-push-hooks install
 ```
 
-Use `ai-push-hooks@0.2.0` instead of `@beta` when an exact npm version pin is
+Use `ai-push-hooks@0.2.1` instead of `@beta` when an exact npm version pin is
 required.
 
 The npm package does not contain a Python runtime. Ensure the Python
@@ -85,14 +85,14 @@ resolved. The fallback delegate fails clearly with status 127 if
 Pin an approved published release in the consuming repository:
 
 ```bash
-mise use npm:ai-push-hooks@0.2.0
+mise use npm:ai-push-hooks@0.2.1
 ```
 
 This adds the following project-level tool entry to `mise.toml` and installs it:
 
 ```toml
 [tools]
-"npm:ai-push-hooks" = "0.2.0"
+"npm:ai-push-hooks" = "0.2.1"
 ```
 
 After checking in `mise.toml`, other contributors can install the pinned tool with `mise install`.
@@ -101,12 +101,30 @@ After checking in `mise.toml`, other contributors can install the pinned tool wi
 
 OpenCode runs in `--pure` mode with project configuration disabled, isolated home/config/cache/state directories, sharing disabled, and an ai-push-hooks-owned custom agent configuration. Read-only steps run in an empty scratch directory, receive only hook-owned artifacts through `--file`, and have every tool denied. Apply steps run against a private temporary workspace containing only unignored regular files matching `allow_paths`; their agent permits only reads and allowlisted edits in that workspace. Casefolded, Unicode-normalized `.git` and `AGENTS.md` paths are always protected.
 
-Global and repository OpenCode instructions, custom agents, MCP servers, formatters, LSP configuration, sharing, and plugins are not inherited. The existing XDG data directory is retained for OpenCode authentication/session state, and recognized provider environment variables are forwarded. Custom providers defined only in global OpenCode configuration are therefore unsupported; use a built-in provider with OpenCode auth state or environment credentials.
+Built-in OpenCode plugins remain enabled, including built-in authentication plugins such as Codex OAuth. Normal `--pure` execution disables external plugins, while the hook's empty plugin configuration and project-config disablement prevent project and global plugins and configuration from being inherited. The existing XDG data directory is retained for OpenCode authentication/session state, and recognized provider environment variables, including `OPENAI_API_KEY`, are forwarded; OpenCode itself chooses the authentication path using its normal precedence. Custom providers defined only in global OpenCode configuration are therefore unsupported; use a built-in provider with OpenCode auth state or environment credentials.
 
 After OpenCode session finalization, apply verifies that the Git-visible checkout, index, current-worktree control state, and critical shared `HEAD`/config/packed-refs/refs/hooks state still match their baselines. Pre-existing symlinks in monitored Git metadata fail closed before OpenCode runs, and symlinks introduced during execution fail before propagation. Apply then preflights every destination against its exact baseline type, content digest, and mode before propagating anything, performs atomic file replacement, and verifies the resulting checkout and protected Git state again. Safe existing ordinary `rwx` modes are preserved, existing special bits are stripped, new or group/world-writable modes become owner-only, and staged files carrying setuid/setgid/sticky bits are rejected before any propagation. Hook-owned runtime files default to `0600` and runtime directories to `0700`.
 
 These controls are OpenCode permission and workspace isolation, not an operating-system sandbox. Compare-and-swap preflight minimizes lost updates but cannot make the interval between preflight and filesystem replacement atomic against an independent local process. Ignored worktree trees, Git object/LFS stores, shared reflogs, and metadata belonging only to other linked worktrees are intentionally excluded from bounded snapshots; direct changes there may not be detected. Critical shared refs/config/hooks remain monitored. Automatic rollback is avoided so pre-existing user changes are not overwritten.
 
+### Beads maintenance boundary
+
+The `beads_alignment` executor is for ordinary native `bd update` and `bd close`
+operations only. It does not run migrations, synchronize embedded Dolt, or
+publish Dolt refs. Hook-launched Beads commands also discard
+`BD_ALLOW_REMOTE_MIGRATE`, `BD_IGNORE_SCHEMA_SKEW`, and `BD_SMART_GATE` from
+their inherited environment so an operator maintenance override cannot leak
+into a push hook.
+
+Treat a Beads schema migration as separate operator maintenance. Pin and
+verify the native `bd` version, stop Beads writers and hooks, take a cold full
+backup of `.beads`, and rehearse against a disposable copy before opening the
+live embedded-Dolt store. Verify the schema, semantic issue/dependency data,
+memories, and a clean Dolt working set before and after the live cutover.
+Remote publication, including `bd dolt push`, is a separate explicit action;
+a successful local migration does not authorize it. Do not replace this flow
+with Beads-Rust (`br`).
+
 ## Full-featured alternative: Lefthook
 
 Use Lefthook when the repository needs several hook commands, shared hook
@@ -160,7 +178,7 @@ Configure modules and steps in the [configuration reference](#configuration-refe
 ## Troubleshooting
 
 - **`opencode is required but not installed`:** install OpenCode and ensure `opencode` (or `opencode-cli`) is on `PATH` for the Git hook process.
-- **Provider/model authentication fails:** run `opencode auth list`, authenticate a built-in provider, and verify `[llm].model`. Project/global custom-provider configuration is intentionally not loaded; see [OpenCode isolation limits](#opencode-isolation-limits).
+- **Provider/model authentication fails:** run `opencode auth list`, authenticate a built-in provider, and verify `[llm].model`. Built-in auth plugins remain available, while project/global custom-provider configuration is intentionally not loaded. Recognized provider environment variables, including `OPENAI_API_KEY`, are forwarded and OpenCode chooses authentication. See [OpenCode isolation limits](#opencode-isolation-limits).
 - **The hook does not run:** rerun `lefthook install`, check `git config --get core.hooksPath`, and verify the pre-push path with the command above.
 - **The push is blocked after docs changed:** this is the expected edit-review-commit flow. Review `git diff`, validate and commit the changes, then push again.
 - **Find logs or transcripts:** inspect `.git/ai-push-hooks/logs`, `.git/ai-push-hooks/summaries`, and (when enabled) `.git/ai-push-hooks/transcripts`.

package/SECURITY.md

@@ -8,7 +8,7 @@ Please do not open a public issue for a suspected vulnerability. Report it priva
 
 ai-push-hooks treats repository content, Git paths and metadata, configuration, model output, and concurrent local filesystem changes as potentially unsafe. Its controls constrain model-visible inputs and apply destinations, protect Git metadata and instruction files, validate filesystem state before propagation, and fail closed by default. They are designed to prevent accidental or model-directed changes outside configured boundaries, not to protect against a malicious user or process with the same operating-system permissions.
 
-OpenCode is a separate local process and communicates with the model provider selected in `[llm].model`. Diffs, changed-file context, prompts, and step artifacts can therefore leave the machine under that provider's terms. ai-push-hooks forwards recognized provider credential environment variables and retains OpenCode's existing authentication data directory, but disables sharing and does not inherit project/global plugins, MCP servers, instructions, or custom-provider configuration. Do not commit secrets, and review provider retention and privacy policies before use on sensitive repositories.
+OpenCode is a separate local process and communicates with the model provider selected in `[llm].model`. Diffs, changed-file context, prompts, and step artifacts can therefore leave the machine under that provider's terms. ai-push-hooks retains OpenCode's existing authentication data directory and forwards recognized provider credential environment variables, including `OPENAI_API_KEY`; OpenCode itself chooses authentication using its normal precedence. Built-in authentication plugins remain available, while `--pure` excludes external plugins and the isolated project/config setup excludes project/global plugins, MCP servers, instructions, and custom-provider configuration. Do not commit secrets, and review provider retention and privacy policies before use on sensitive repositories.
 
 Hook logs, summaries, run artifacts, and transcripts are stored locally under `.git/ai-push-hooks/` with private runtime permissions. Transcript capture defaults to **on** at `.git/ai-push-hooks/transcripts`; set `logging.capture_llm_transcript = false` to disable it. OpenCode session deletion defaults to on, but provider-side retention is controlled by the provider.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.2.0"
+version = "0.2.1"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"

package/src/ai_push_hooks/executors/exec.py

@@ -78,6 +78,13 @@ BEADS_ENV_NAMES = frozenset(
     }
 )
 BEADS_ENV_PREFIXES = ("AWS_", "BD_", "BEADS_", "DOLT_")
+BEADS_MIGRATION_OVERRIDE_ENV_NAMES = frozenset(
+    {
+        "BD_ALLOW_REMOTE_MIGRATE",
+        "BD_IGNORE_SCHEMA_SKEW",
+        "BD_SMART_GATE",
+    }
+)
 GITHUB_REPOSITORY_COMPONENT = re.compile(r"[A-Za-z0-9_.-]+\Z")
 GIT_DIFF_CHUNK_BYTES = 64 * 1024
 GIT_ERROR_BYTES = 64 * 1024
@@ -950,7 +957,8 @@ def beads_alignment_env() -> dict[str, str]:
     return {
         name: value
         for name, value in os.environ.items()
-        if name in BEADS_ENV_NAMES or name.startswith(BEADS_ENV_PREFIXES)
+        if name not in BEADS_MIGRATION_OVERRIDE_ENV_NAMES
+        and (name in BEADS_ENV_NAMES or name.startswith(BEADS_ENV_PREFIXES))
     }
 
 

package/src/ai_push_hooks/executors/llm.py

@@ -100,7 +100,6 @@ def opencode_isolation_env(
         "OPENCODE_DISABLE_CLAUDE_CODE": "true",
         "OPENCODE_DISABLE_CLAUDE_CODE_PROMPT": "true",
         "OPENCODE_DISABLE_CLAUDE_CODE_SKILLS": "true",
-        "OPENCODE_DISABLE_DEFAULT_PLUGINS": "true",
         "OPENCODE_DISABLE_LSP_DOWNLOAD": "true",
         "OPENCODE_DISABLE_SHARE": "true",
         "OPENCODE_DISABLE_AUTOUPDATE": "true",