dotagents-cli 0.3.1__tar.gz → 0.3.3__tar.gz

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/.gitignore

@@ -34,3 +34,7 @@ Thumbs.db
 .idea/
 .vscode/
 _staging/
+
+# `overlays` branch, checked out here as a worktree/clone for local editing
+# (D77: example overlays split off this repo's main branch).
+overlays/

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/CHANGELOG.md

@@ -7,6 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-16
+
+### Added
+
+- feat: `env` and `context` gained **`--agents-dir`** (from the shared
+  `DotAgentsArgs` base) to override the store for one run. Their `-g/--global`
+  keeps its existing, narrower meaning here — *skip the project-level files* —
+  and now says so in `--help`.
+
+### Removed
+
+- **`build-pyz` no longer bundles the repo's `tools/`** as `dotagents/_tools`
+  inside the built `.pyz`, and the `--tools-dir` flag is gone with it. Nothing
+  read `_tools`: the compiled `audit`/`leak-check` wrappers that shelled out to
+  it no longer exist. Every shipped artifact carried the dead weight while
+  `tools/audit.py` claimed it was "not shipped in the `.pyz`" — now true.
+- **`dotagents._sync`** — a `pathlib_next.PathSyncer` wrapper that existed only
+  to back the `install` subcommand's backup/copy report. `install` was removed
+  in 0.3.x; the module has had no callers since, no tests, and a return
+  annotation that disagreed with what it returned. `pathlib_next` remains a
+  dependency (duho, and `--from` URI support). Its API-reference page went with
+  it.
+
+### Fixed
+
+- docs: a cluster of "docs say X, tree does Y" corrections — `tools/audit.py`
+  no longer claims to ship as a bundled `audit` command module (it is repo CI
+  tooling and there is no `dotagents audit`) and its `--root` help names the
+  real default; `install.py`'s usage line drops the removed `install` and the
+  never-existing `audit`; the README's `tools/` row says where `leak-check`
+  actually lives; the API header names the real `_overlays` exports
+  (`install_overlay_dir` / `apply_overlay` / `run_overlay_setup`) and the real
+  package-data dirs (`_overlay` / `_overlays_src`, never a `skeleton/`); and
+  `_merge._extract_block`'s docstring now says it returns the block *including*
+  its marker lines, which is what it has always done and what callers rely on.
+- fix: **`stamp_identity` no longer pretends to emit `AGENTS_AGENT`.** The line
+  sourced the value from `$AGENTS_AGENT` and only assigned when that same key
+  was unset, so it could never emit anything — while the docstring and the
+  shipped API header both advertised the var. Line removed; the API header's
+  "emitted by the identity/env layer" list now drops both `AGENTS_AGENT` and
+  `AGENTS_CODE_SESSION_ID` (the latter was deliberately never emitted) and says
+  so explicitly, so nothing branches on a var that never arrives.
+- fix: **`dotagents env` and `dotagents context` now resolve their roots instead
+  of hardcoding them.** Both took `Path.cwd()` as the project root and
+  `~/.agents` as the user store, so `$AGENTS_PROJECT_ROOT` (or the agent-native
+  `$CLAUDE_PROJECT_DIR`) and `$AGENTS_HOME` were ignored by the two commands
+  that most needed them — a `SessionStart` hook runs `dotagents context` from
+  wherever the session happens to start, so a pinned project root was silently
+  dropped and a relocated store was never read. They now use
+  `_scope.project_root_default()` and the new
+  `dotagents.cli.resolve_user_store()` (`--agents-dir` → `$AGENTS_HOME` →
+  legacy `$DOTAGENTS_AGENTS_DIR` → `~/.agents`), matching what the package's own
+  `resolve_scope` docstring and command discovery already promised. Behavior is
+  unchanged when none of the vars are set.
+
+## [0.3.2] - 2026-07-25
+
+### Added
+
+- feat: **`AntigravityAgent`** — context injection for Google's Antigravity
+  CLI/IDE (a separate product from Gemini CLI, despite sharing the `~/.gemini/`
+  namespace for some files). Antigravity's hooks have no `SessionStart`
+  equivalent — only `PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/
+  `Stop` — so a `PreInvocation` hook gated on `invocationNum == 0` behaves like a
+  one-shot context load instead of resending it every model turn. Wires into
+  `~/.gemini/config/hooks.json`. No detection marker exists for Antigravity, so
+  it's explicit-`--agents antigravity`-only, never auto-detected.
+- feat: **Codex gets a `PreToolUse` env hook**, closing the one gap Codex had
+  versus Claude: Codex has no per-session env-persistence mechanism at any hook
+  event, so a deployed script prepends a guarded env-loader to every `Bash` tool
+  call via `updatedInput.command` — the same rewrite mechanism Claude's own
+  `PreToolUse` hook uses, confirmed directly against Codex's docs.
+- feat: **`init` wires a PowerShell `PreToolUse` env hook on Windows**, closing
+  a real gap: `$CLAUDE_ENV_FILE` only reaches Claude's *Bash* tool
+  (`$env:CLAUDE_ENV_FILE` is empty inside a live PowerShell tool call, confirmed
+  directly) — a fresh PowerShell tool call gets none of the SessionStart env.
+  The hook prepends a guarded env-loader to a PowerShell tool call's own command,
+  shipped as an inline command string (never a `.ps1` file — a script file is
+  subject to PowerShell's execution policy, and dotagents has no code-signing
+  certificate; the inline form runs even under `Restricted`).
+- feat: **`SessionStart`/`CwdChanged` now register two handlers each** — a
+  bash-syntax one and an explicit `shell: "powershell"` one — because Claude's
+  own hooks.md says the shell "defaults to bash, or to powershell on Windows
+  when Git Bash isn't installed": bash syntax fed to `powershell -Command` on
+  such a machine is a hard parse error, silently losing both env and context for
+  the whole session.
+- feat: **`DotAgentsArgs`** (`dotagents.cli`, re-exported for overlay-shipped
+  commands) — one shared `-g/--global` + `--agents-dir` base class. `init` and
+  all four `overlays` subcommands now inherit it instead of independently
+  redeclaring the same fields, so scope resolution can't silently drift between
+  commands (one previously defaulted `agents_dir` eagerly to `Path.home() /
+  ".agents"`; harmless in practice, but needless).
+
+### Fixed
+
+- fix: **`dotagents env --format powershell`/`cmd` left an already-POSIX `PATH`
+  unconverted**, the mirror of the export/dotenv/fish fix below going the other
+  direction. Found live: run from a genuine Windows PowerShell terminal whose
+  own inherited `PATH` already held WSL/MSYS-mount-style entries
+  (`/mnt/c/Program Files/...`), the emitted `${env:PATH} = '...'` was
+  syntactically valid PowerShell but a single opaque colon-joined string, not
+  the `;`-split list PowerShell's own PATH lookup needs — every subsequent
+  bare-command lookup broke for that session. Also handles the MIXED case
+  (dotagents' own native bin dirs prepended onto an already-POSIX inherited
+  PATH, one string with both separators at once), caught by sourcing real
+  output into a live PowerShell session and watching `git.exe` fail to
+  resolve before the second fix. A WSL-only segment with no Windows equivalent
+  (`/usr/bin`) is dropped rather than mangled into a broken relative path.
+- fix: **the built `.pyz` degraded `-g` on any discovered command inheriting a
+  dotagents-defined base class** (first hit by `DotAgentsArgs` above) — duho's
+  AST introspection walks the full MRO for a command's flags, but the zipapp
+  source-repoint shim only ever covered built-in command modules, not a base
+  class's own module (`dotagents.cli._common`). `--global` degraded to the
+  name-derived `--global-scope` and `-g` vanished silently. Fixed, with new CI
+  coverage asserting the exact short flag survives a real built pyz.
+- fix: **`harness_loads` relative entries matched by bare filename, not full
+  path** — a relative entry like Codex's `"AGENTS.md"` wrongly suppressed ANY
+  file sharing that basename anywhere on disk, including the unrelated
+  `~/.agents/AGENTS.md` user-store file Codex's harness never reads.
+  `dotagents context --agents codex` emitted an empty `sources: []` even with
+  real content present. Now resolved against `project_root` and compared by
+  full path, like the absolute (`~/`, `/`) forms already were.
+- fix: `dotagents context --format json` crashed with `UnicodeEncodeError` on
+  any character outside Latin-1 (a bare `print()` encoding with the console's
+  codepage) — the same class of bug already fixed for the markdown path, just
+  never covered for JSON.
+- fix: PowerShell format uses `${env:NAME}` (curly-brace form), not the bare
+  `$env:NAME` sigil — a handful of real Windows env vars have parens in their
+  names (`ProgramFiles(x86)`), and `$env:FOO(X86) = ...` is a PowerShell parse
+  error; the curly-brace form is valid for every name.
+
+## [0.3.1] - 2026-07-24
+
 ### Fixed
 
 - fix: **`dotagents env --format export`/`dotenv`/`fish` now emit a POSIX PATH on
@@ -27,8 +160,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   leading slash (`/server/share/...`) during the POSIX conversion above — MSYS
   requires the double-slash UNC root (`//server/share/...`) to resolve it.
 
-## [0.3.1] - 2026-07-24
-
 Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0).
 
 ## [0.3.0] - 2026-07-24

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.3.1
+Version: 0.3.3
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents
@@ -102,7 +102,7 @@ them. Everything else is repo infrastructure.
 | --- | --- |
 | `src/dotagents/` | The installable `dotagents` CLI (`init`/`overlays`/`context`/`env`/`build-pyz`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
 | `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
-| `tools/` | Required tooling (not an overlay): `cloud-setup.sh` (`leak-check` moved to the opt-in `leak-check` overlay, D84) |
+| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. `leak-check` is not here either — it is a personal command module you keep in your own private `.agents/dotagents/cmds/` |
 | `install.py` | Thin shim over `dotagents.cli.main()`, kept at this filename for muscle memory |
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/README.md

@@ -41,7 +41,7 @@ them. Everything else is repo infrastructure.
 | --- | --- |
 | `src/dotagents/` | The installable `dotagents` CLI (`init`/`overlays`/`context`/`env`/`build-pyz`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
 | `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
-| `tools/` | Required tooling (not an overlay): `cloud-setup.sh` (`leak-check` moved to the opt-in `leak-check` overlay, D84) |
+| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. `leak-check` is not here either — it is a personal command module you keep in your own private `.agents/dotagents/cmds/` |
 | `install.py` | Thin shim over `dotagents.cli.main()`, kept at this filename for muscle memory |
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/build.py

@@ -3,9 +3,9 @@
 
 Thin root-level wrapper over ``dotagents build-pyz`` (``dotagents.cli.build_pyz``):
 it vendors ``duho`` + ``pathlib_next`` into the archive (via ``pip install --target``,
-using **the Python that runs this script**), copies the ``dotagents`` package and the
-required ``tools/``, strips caches/metadata, and packages a runnable zipapp. The result
-needs no ``pip install`` on the target machine.
+using **the Python that runs this script**), copies the ``dotagents`` package, strips
+caches/metadata, and packages a runnable zipapp. The result needs no ``pip install``
+on the target machine. The repo's ``tools/`` is CI tooling and is NOT bundled.
 
 Usage:
     python build.py                      # -> dist/dotagents.pyz

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/docs/api/reference.md

@@ -21,4 +21,3 @@ form its API. Generated from docstrings, organized by module:
 - **[Hooks](hooks.md)** — additive, idempotent merge of dotagents' hooks into an
   agent's own settings/config file.
 - **[Skills](skills.md)** — publishing an overlay's skills into a scope's shared dir.
-- **[Sync](sync.md)** — the `PathSyncer` backup/copy wrapper for `install`.

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/docs/guide/commands.md

@@ -155,7 +155,14 @@ dotagents context --write-agent                # write each agent's native confi
 - `--write-agent` — write each agent's native config file instead of `[output]`.
 - `--agents <a,b>` — which agents to generate for (default: the active agent).
 - `--format markdown|system-reminder|json` — output shape.
-- `-g` / `--global` — user scope.
+- `-g` / `--global` — skip the project-level context files (the store is unaffected).
+- `--agents-dir <dir>` — user store override for this run.
+
+Roots: the store is `--agents-dir` → `$AGENTS_HOME` → `~/.agents`, and the project
+root is `$AGENTS_PROJECT_ROOT` → `$CLAUDE_PROJECT_DIR` → the cwd. A `SessionStart`
+hook runs this from wherever the session started, so pinning
+`AGENTS_PROJECT_ROOT` is what keeps the assembled context the same in every
+subdirectory.
 
 ## env
 
@@ -174,7 +181,12 @@ python -m dotagents env --diff --format json   # only vars that differ from the
   (`bat`/`batch`, `set "KEY=value"`), `fish` (`set -gx KEY value`). Data forms:
   `json`, `ini`, `yaml`. An explicit `--format` always wins.
 - `--diff` — emit only the change set vs. the caller's environment.
-- `-g` / `--global` — user scope.
+- `-g` / `--global` — skip the project-level env files (the store is unaffected).
+- `--agents-dir <dir>` — user store override for this run.
+
+Roots resolve exactly as for `context` above (`$AGENTS_HOME` /
+`$AGENTS_PROJECT_ROOT`, both of which `env` also emits — so a subprocess reading
+them agrees with the parent that wrote them).
 
 !!! warning
     `env` output is sensitive by design — it prints resolved values. Treat the

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/install.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Entry point for the dotagents CLI (init / install / overlays / build-pyz / ...).
+"""Entry point for the dotagents CLI (init / overlays / context / env / build-pyz).
 
 Thin front over ``dotagents.cli.main()``, kept at this filename so existing
 muscle-memory/docs pointing at ``python install.py`` still work.
@@ -14,7 +14,7 @@ bare ``pip`` off PATH) guarantees the install lands in *this* Python, so the
 import that follows actually sees it. When everything is already importable it
 just dispatches -- no pip is ever run.
 
-Usage: python install.py <init|install|overlays|audit|build-pyz|...> [options]
+Usage: python install.py <init|overlays|context|env|build-pyz|...> [options]
 Run `python install.py --help` for the full subcommand/flag reference.
 """
 import os

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/mkdocs.yml

@@ -46,7 +46,6 @@ nav:
       - Merge: api/merge.md
       - Hooks: api/hooks.md
       - Skills: api/skills.md
-      - Sync: api/sync.md
   - Changelog: changelog.md
 
 plugins:

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "hatchling.build"
 # redirect/placeholder before someone else does, but the CLI ships under -cli.
 [project]
 name = "dotagents-cli"
-version = "0.3.1"
+version = "0.3.3"
 authors = [{ name = "Jose A." }]
 description = "The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents"
 readme = "README.md"

dotagents_cli-0.3.3/src/dotagents/AGENTS.md

@@ -0,0 +1,220 @@
+# dotagents — package API header
+
+Public API of the installed `dotagents` package: the CLI umbrella plus the `_*.py`
+helper modules that back it. This file ships inside the package so a consuming agent
+can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
+
+## Entry points
+
+- `dotagents.cli.main(argv=None) -> int` — the `install.py` shim and
+  `python -m dotagents` entry point. Repoints zipapp sources, then dispatches through
+  `duho.app` with the discovered command set. Also the `dotagents` console script
+  (`[project.scripts]`).
+- `dotagents.cli.Dotagents(LoggingArgs, Cli)` — the umbrella CLI class.
+- `dotagents.cli.DotAgentsArgs` — mix-in base carrying the shared `-g/--global` +
+  `--agents-dir` pair and `resolve_scope()`; an overlay-shipped command module
+  should inherit it (as the FIRST base) rather than redeclare the flags.
+- `dotagents.cli.resolve_user_store(agents_dir=None) -> Path` — the USER store
+  root: `agents_dir` (`--agents-dir`) → `$AGENTS_HOME` → legacy
+  `$DOTAGENTS_AGENTS_DIR` → `~/.agents`. Use it (not `resolve_scope`) when the
+  store is always the user store and the project scope only adds/removes tiers,
+  as in `env` / `context`.
+- Compiled command classes live in `dotagents.cli.<name>` (`init`, `overlays`,
+  `context`, `env`, `build_pyz`); each is a `class X(LoggingArgs, Cmd)` — or
+  `class X(DotAgentsArgs)`, which is that pair transitively — with a
+  `__call__`. That is the WHOLE shipped surface — dotagents bundles no command
+  module of its own. `link` / `sync` left the package with their logic (D85): the
+  opt-in **private-sync** overlay ships them, renamed `link-project` /
+  `sync-project`, from its own `cmds/` + `lib/_link.py`. `leak-check` is likewise
+  not in the repo — a personal command module the user keeps in their private
+  `<scope>/dotagents/cmds/` (D84). `audit` is repo CI tooling (`tools/audit.py`),
+  not a command.
+- Command discovery layers sources, later wins: built-ins < bundled `cmds` <
+  overlay `cmds` (`<overlay-root>/cmds`) < scope `cmds` dirs (user + project) <
+  `$AGENTS_CMDS_PATH` < `--cmdspath`. The overlay + scope tiers come from one
+  Contract-A `get_file_paths` walk (`cli._cmds_dirs`), the same resolver that
+  backs `bin`/PATH.
+
+## Helper modules (public surface)
+
+- `_agents` — `Agent` base type + per-agent adapters; `stamp_identity(...)` emits the
+  standardized `AGENTS_*` / `AGENT` identity vars.
+- `_overlays` — `install_overlay_dir` (copy an overlay into a scope, self-describing)
+  / `apply_overlay` (lay its files down) / `read_manifest` / `find_setup_script` /
+  `run_overlay_setup`; installs an overlay's files and collects its `routing` / `rules`
+  contributions to the managed `AGENTS.md` block. `DEFAULT_PRIORITY = 500`.
+- `_scope` — `resolve_scope(global_scope, agents_dir=None)` and `resolve_source(...)`;
+  scope = *where installed overlays live* (user = the configurable store, project =
+  `<project>/.agents`), source = *where an overlay comes from* (bundled by default).
+  Installed overlays are **discovered** by presence, not tracked in a registry.
+- `_context` — assemble the effective per-agent context (Plan 04); reads overlay
+  `priority` from the manifest (lower sorts earlier).
+- `_env` — chained env-file assembly + `env.py` execution (frozen contract B):
+  `get_environment` / `get_diff` / `resolve_env_files` / `get_env_from_py` /
+  `get_env_from_file`. Bins onto PATH first, then two tiers (`pre.env*` then `env*`),
+  later-overrides-earlier. Identity seeded before the chain; proxy vars applied after.
+- `_resolve` — `get_file_paths(*names, agents_dir, project_root, global_scope=False,
+  include_missing=False)`: the Contract-A precedence walk / filename resolution.
+- `_merge` — managed-block merge for `init`'s `AGENTS.md` / `CLAUDE.md`, delimited by
+  `<!-- dotagents:begin -->` / `<!-- dotagents:end -->`. Detection is by marker
+  presence only, so it survives user reformatting. `begin_marker`/`end_marker`
+  override the pair for other comment syntaxes (`#` for TOML), and `append=True`
+  puts a first-time block at the END of the file — required for TOML, where a
+  `[table]` header captures every key line after it and a prepended block would
+  swallow the user's top-level keys.
+- `_skills` — publish an overlay's `skills/<name>/` into a scope's shared skills dir
+  (symlink-preferred, copy fallback); unpublish removes only what the overlay
+  published, then sweeps broken symlinks. Pure stdlib.
+- `_hooks` — additive, idempotent merge of our hooks into an agent's `settings.json`.
+  `hooks.<Event>` is a **list of matcher-objects** each holding its own `hooks` list,
+  not a flat command list. Foreign hooks are preserved verbatim, malformed entries
+  are dropped rather than raising, and invalid JSON raises `SystemExit` instead of
+  silently overwriting the user's file. `shell` (Claude: `"bash"`/`"powershell"`,
+  picks the interpreter for the hook's own command) and `command_windows`
+  (Codex: emitted as `commandWindows`, a separate Windows-only command OVERRIDE,
+  not an interpreter choice) are both supported. Pure stdlib. Consumed by
+  `ClaudeAgent.wire_hooks` (`~/.claude/settings.json`: env via `$CLAUDE_ENV_FILE`
+  + context via stdout, plus `CwdChanged`, plus a `PreToolUse` env-loader for the
+  PowerShell tool) and `CodexAgent.wire_hooks` (`<CODEX_HOME|~/.codex>/hooks.json`,
+  never `config.toml`: `SessionStart` context-only, plus a `PreToolUse` env-loader
+  matched on `matcher: "Bash"`). Codex's hook JSON is structurally identical to
+  Claude's, including the SAME `updatedInput.command` rewrite mechanism on
+  `PreToolUse` — confirmed directly against Codex's own docs
+  (learn.chatgpt.com/docs/hooks), not assumed from Claude parity.
+  Gemini/Cursor/Copilot keep the base no-op — Gemini CLI proper has no hook
+  mechanism documented at all (checked directly). **Antigravity is a separate
+  product** from Gemini CLI (Antigravity CLI/IDE/SDK family, shares only the
+  `~/.gemini/` namespace for some files) and DOES wire a hook: see
+  `AntigravityAgent.wire_hooks` below. `PreToolUse` there is still allow/deny/ask
+  only — no `updatedInput`, so no command-rewrite/env-loader path exists to hang
+  on it, unlike Claude/Codex. Revisit both conclusions if either framework changes.
+- **`AntigravityAgent.wire_hooks`** (`<AGENTS_HOME_ANTIGRAVITY|~/.gemini/config>/hooks.json`,
+  keyed under a `"dotagents"` name per the docs' own example shape — a named-entry
+  object, not Claude/Codex's flat `hooks.<Event>`): wires a single `PreInvocation`
+  entry, context-only, no env mechanism. Antigravity's hooks
+  (antigravity.google/docs/hooks) have exactly five events — `PreToolUse`,
+  `PostToolUse`, `PreInvocation`, `PostInvocation`, `Stop` — no SessionStart
+  equivalent. `PreInvocation` fires every model turn (`invocationNum`, 0-indexed),
+  so the deployed script (`preinvocation_antigravity_context.py`,
+  `_overlay/dotagents/hooks/`) gates on `invocationNum == 0` to behave like a
+  one-shot SessionStart rather than resending context every turn. Output shape is
+  a bare `{"injectSteps": [{"ephemeralMessage": "..."}]}`, no `hookSpecificOutput`
+  wrapper — confirmed against the primary docs after an earlier pass here wrongly
+  concluded no useful injection was possible; `ephemeralMessage` is the one of the
+  three step types meant for free text (`toolCall` executes a tool,
+  `userMessage` impersonates the user). No detection marker exists anywhere in
+  Antigravity's docs, so `detect_env_vars = []` — explicit `--agents antigravity`
+  only, same posture as Codex's env-block precedent (writes touching an agent's
+  own live config are opt-in, never inferred).
+- **`SessionStart`/`CwdChanged` register TWO handlers each**, bash-syntax
+  (default shell) and a PowerShell-native equivalent (`shell: "powershell"`).
+  hooks.md: `shell` "Defaults to bash, or to powershell on Windows when Git Bash
+  isn't installed" — verified directly that bash syntax fed to `powershell
+  -Command` on such a machine is a hard parse error, not a soft failure, so
+  every session there would silently get neither env nor context. Every handler
+  in a matched group fires unconditionally (hooks.md), so both always run; the
+  one whose interpreter is absent fails harmlessly. The PowerShell
+  `SessionStart` variant is context-only (`dotagents context`), not
+  env+context: `$CLAUDE_ENV_FILE`'s documented effect is "subsequent BASH
+  commands" regardless of which shell wrote it, so writing to it from a
+  PowerShell-shelled hook would feed nothing.
+- **Windows only**: `ClaudeAgent._wire_powershell_pretooluse` additionally wires
+  a no-matcher `PreToolUse` hook (fires on every tool call), `shell:
+  "powershell"`, running `PRETOOLUSE_POWERSHELL_COMMAND` INLINE — deliberately
+  not a `.ps1` file, since a script file is subject to PowerShell's execution
+  policy (RemoteSigned/AllSigned/Restricted) and dotagents has no code-signing
+  certificate; verified directly that the inline form runs successfully even
+  under `Restricted`, which blocks every `.ps1` file outright. Closes a real
+  gap: `$CLAUDE_ENV_FILE` is Bash-tool-only (confirmed empirically that
+  `$env:CLAUDE_ENV_FILE` is empty inside a live PowerShell tool call), so the
+  SessionStart env half never reaches the PowerShell tool. Uses `PreToolUse`'s
+  `updatedInput` to prepend a guarded env-loader (`AGENTS_RUNTIME_SET`,
+  matching the precursor's convention) to a `PowerShell` tool call's own
+  command — not by trying to persist state across hook invocations, which are
+  each their own fresh process and cannot. Whether the guard is visible across
+  separate PowerShell tool calls is UNVERIFIED. Every literal `\` in the
+  command constant must be a raw string — a bare `\b` in a normal Python string
+  literal silently becomes a backspace character, corrupting the emitted path;
+  caught once by testing a draft through a real PowerShell spawn.
+- **`CodexAgent._deploy_pretooluse_script`** covers the same env gap for Codex,
+  which has NO env-persistence mechanism at any hook event (not Bash-only like
+  Claude — none). Ships `pretooluse_codex_env.py` (`_overlay/dotagents/hooks/`),
+  deployed to `<codex-home>/hooks/` (create-or-refresh), wired as `PreToolUse`
+  with `matcher: "Bash"` — Codex's one shell tool, so (unlike Claude's
+  no-matcher hook) filtering happens at the settings level, no runtime
+  `tool_name` check needed in the script. A FILE, not inlined like Claude's:
+  Codex's docs show every hook example as `python3 <path>`, and a `.py` file
+  has no execution-policy/signing concern (PowerShell-specific). Sets
+  `commandWindows` to `python "<path>"` (not `python3`) — verified directly
+  that `python3` resolves to the Microsoft Store app-execution-alias stub and
+  fails outright on this dev machine (exit 49), the same trap noted elsewhere
+  for `py`/venv creation.
+
+## Environment variables
+
+The prefix split (D80): **`AGENTS_*`** names everything about the `.agents` / agent
+world (paths, scope, overlays, sync) — non-secret, safe to emit; **`DOTAGENTS_*`** is
+reserved for genuinely tool-internal config and secrets, so the "never print
+`DOTAGENTS_*` values" leak guard (D48) stays a simple blanket ban over exactly the
+sensitive set.
+
+Config / path / sync vars (`AGENTS_*`, non-secret — read, and some emitted):
+
+- `AGENTS_HOME` — the configurable user-scope store path (default `~/.agents`). Also
+  **emitted** by `dotagents env` (D79) and set for overlay setup scripts / sync hooks.
+- `AGENTS_STORE_DIR` — per-project store location (absolute paths allowed).
+- `AGENTS_OVERLAYS_SRC` — default overlay source dir for `overlays`.
+- `AGENTS_CMDS_PATH` — extra command-module search paths (os.pathsep-split).
+- `AGENTS_OVERLAY_DIR` — set for an overlay's setup script (its own installed dir).
+- `AGENTS_REMOTE` / `AGENTS_SYNC_MESSAGE` — private-store sync (tokenless remote URL /
+  commit message).
+
+Every reader above prefers the `AGENTS_*` name and falls back to the old
+`DOTAGENTS_*` name (`DOTAGENTS_AGENTS_DIR`, `DOTAGENTS_STORE_DIR`,
+`DOTAGENTS_OVERLAYS_SRC`, `DOTAGENTS_CMDS_PATH`, `DOTAGENTS_OVERLAY_DIR`,
+`DOTAGENTS_AGENTS_REMOTE`, `DOTAGENTS_SYNC_MESSAGE`) for one release — deprecated,
+removable next. Setters emit both names this release.
+
+Tool-internal / secret vars (`DOTAGENTS_*` — kept; read, **never printed**):
+
+- `DOTAGENTS_AGENTS_TOKEN` — **secret** (fine-grained PAT) for private-store auth.
+- `DOTAGENTS_CLI_INSTALL` — pip spec to install the CLI itself (tool-specific).
+- `DOTAGENTS_AUDIT_PATTERNS` — path to the machine-local audit-pattern file (tooling).
+
+Emitted by the identity/env layer (safe to branch on in env files):
+`AGENTS_HARNESS`, `AGENTS_VENDOR`, `AGENTS_MODEL`, `AGENT`, `AGENTS_PROXY`,
+`AGENTS_WEBFETCH_PROXY_URL`, plus the two
+scope roots — `AGENTS_HOME` (the user store, `agents_dir`/`~/.agents`) and
+`AGENTS_PROJECT_ROOT` (this project's root). Both are seeded only if unset, so a
+harness/env can pin them. Deliberately NOT emitted, despite looking like they
+would be: `AGENTS_AGENT` (a named persona — nothing derives one, so there is
+nothing to emit) and `AGENTS_CODE_SESSION_ID` (dropped with the precursor's
+blanket `CLAUDE_*`→`AGENTS_*` rewrite). Do not branch on either. `resolve_scope` READS `AGENTS_PROJECT_ROOT` (then the
+agent-native `CLAUDE_PROJECT_DIR`, then cwd) for the project scope's root.
+
+Every command READS both back, so the pin actually holds: `env` and `context`
+resolve their user store through `cli.resolve_user_store()` (`--agents-dir` →
+`$AGENTS_HOME` → legacy `$DOTAGENTS_AGENTS_DIR` → `~/.agents`) and their project
+root through `_scope.project_root_default()` — neither is taken from the cwd or a
+hardcoded home. This matters for hook-invoked runs: a `SessionStart` hook runs
+`dotagents context` / `dotagents env` from wherever the session started, and only
+the pinned root makes that cwd-independent. `-g/--global` on these two means
+*skip the project tier*, not *use a different store*.
+
+## Gotchas
+
+- **Python 3.9 floor.** Files using bare `X | Y` unions in runtime-evaluated positions
+  need `from __future__ import annotations`. `Path.write_text(..., newline=...)` is
+  3.10+, so wrapper-script writers use `open(path, "w", newline="")`.
+- **Zipapp source shim.** Inside a `.pyz`, `Path(__file__)` is not a real file, so
+  duho's AST flag/help introspection degrades (`--from` → `--from-`, positionals lost).
+  `cli.main()` calls `_repoint_zipapp_sources()` first, extracting the built-in command
+  modules to real temp files. Discovered `cmds` modules are extracted by
+  `_package_data_dir` before import, so they need no repoint.
+- **Package data in a `.pyz`.** `_package_data_dir(name)` resolves a package-data dir
+  by name — `_overlay` (the base overlay `init` writes) and `_overlays_src` (bundled
+  example overlays, when a build includes them) — via `importlib.resources` (a
+  zip-backed `Traversable` is extracted to a temp dir once), never
+  `Path(__file__).exists()` (always False in a zipapp).
+- **`pathlib_next` needs `typing_extensions` on Python < 3.10** (an upstream gap); a
+  3.9 environment must `pip install typing_extensions`.

{dotagents_cli-0.3.1 → dotagents_cli-0.3.3}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.3"