dotagents-cli 0.6.2__tar.gz → 0.6.3__tar.gz

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.3] - 2026-09-30
+
+### Added
+
+- `env --into FILE` writes the output into FILE as the one block `env` owns
+  there, replacing the block an earlier run wrote and keeping every other line.
+- With `--diff --format export`, a `PATH` that is the caller's own with entries
+  put in front is written as `export PATH='<entries>'"${PATH:+:$PATH}"`, so it
+  stays short and keeps what the sourcing shell has.
+- When `dotagents` runs from a `.pyz`, `env` exports `AGENTS_PYLIB`, the path
+  of that archive. The libraries it bundles (duho, pathlib_next) import from
+  it, so an overlay built on duho works even when the interpreter in
+  `AGENTS_PYTHON` has no duho installed. An installed `dotagents` sets nothing:
+  its libraries are already importable from `AGENTS_PYTHON`. The archive is
+  never put on `PYTHONPATH`, where it would shadow a project's own copy; a
+  consumer adds it to `sys.path` itself when its import fails.
+
+### Fixed
+
+- The Claude Code SessionStart hook no longer appends the whole environment to
+  `$CLAUDE_ENV_FILE` every time it runs (startup, resume, compact, clear). Claude
+  Code inlines that file into every Bash command, and once it passed about 8 KB,
+  Git for Windows' bash truncated the command and every Bash call failed with an
+  unterminated quote. The hook now uses `env --into`, which keeps one block.
+  Re-run `dotagents init -g` to update an installed hook.
+
 ## [0.6.2] - 2026-09-28
 
 ### Added
@@ -1308,7 +1334,8 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.6.2...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.6.3...HEAD
+[0.6.3]: https://github.com/jose-pr/dotagents/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/jose-pr/dotagents/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/jose-pr/dotagents/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/jose-pr/dotagents/compare/v0.5.1...v0.6.0

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.6.2
+Version: 0.6.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

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/docs/guide/commands.md

@@ -87,7 +87,7 @@ the store's, else `dotagents` on `PATH`.
 
 | Hook | Command | Why |
 | --- | --- | --- |
-| `SessionStart` | appends `dotagents env --diff --format export` to `$CLAUDE_ENV_FILE`, then runs `dotagents context` | Claude sources `$CLAUDE_ENV_FILE` before each Bash command, so the env layers reach every command in the session; and it injects the hook's **stdout into the session context**, which is how the assembled context reaches the model. |
+| `SessionStart` | writes `dotagents env --diff --format export` into `$CLAUDE_ENV_FILE` (`--into`: one block, replaced on every run; `PATH` as a prefix on the shell's own), then runs `dotagents context` | Claude sources `$CLAUDE_ENV_FILE` before each Bash command, so the env layers reach every command in the session; and it injects the hook's **stdout into the session context**, which is how the assembled context reaches the model. |
 | `CwdChanged` | when the new directory has a `.agents/`, appends `export AGENTS_PROJECT_ROOT=<it>` to `$CLAUDE_ENV_FILE`; then prints the directory's `AGENTS.md` if there is one | Re-pins the project root after a `cd` into another project, and surfaces that directory's `AGENTS.md`. |
 
 On Windows each event gets a second, PowerShell-native handler (`shell:
@@ -272,6 +272,11 @@ dotagents env --diff --format json   # only vars that differ from the caller's e
   environment, the working directory, the stores, the overlays, every env and `lib`
   file), for at most five minutes; the per-command env loaders use it. The cache is
   owner-only, under `<user store>/.cache/env/`.
+- `--into <file>` — write into `<file>` instead of stdout, as the one block this
+  command owns there (between `: dotagents-env-begin` / `: dotagents-env-end`):
+  an earlier block is replaced, anything else in the file is kept. The SessionStart
+  hook writes `$CLAUDE_ENV_FILE` this way, so the file stays one block however often
+  the hook runs. `export` format only.
 - `-g` / `--global` — skip the project-level env files (the store is unaffected).
 - `--agents-dir <dir>` — user store override for this run.
 
@@ -307,7 +312,12 @@ form and drop names that are not shell identifiers.
    overlay, where `NAME` is the overlay's name upper-cased with `-` turned into `_`
    (`my-ov` → `MY_OV_OVERLAY_ROOT`). That is the same name `context` expands as a
    `<NAME_OVERLAY_ROOT>` placeholder, so an env file and a context file refer to an
-   overlay's install dir by one name.
+   overlay's install dir by one name. When `dotagents` runs from a `.pyz`,
+   `AGENTS_PYLIB` names that archive: the libraries it bundles (duho,
+   pathlib_next) import from it, so an overlay built on them appends it to
+   `sys.path` when its own import fails. An installed `dotagents` sets nothing,
+   since those libraries are already in `AGENTS_PYTHON`'s site-packages. It is
+   never put on `PYTHONPATH`, where it would shadow a project's own copy.
 3. **`PATH`** — every level's `bin/` (each store's overlays, then the store) goes
    to the front in that order, including ones that do not exist yet, so an `env.py`
    and every subprocess can call an overlay's helpers by name. The order holds even

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/AGENTS.md

@@ -38,7 +38,7 @@ and an error saying a command is required, and exits 2.
 | `overlays show NAME [-g] [--repo SPEC]... [--json]` | One overlay: the copy a session would use, else the source's; manifest, setup, skills, file count, recorded source. No name: exit 2. |
 | `context [OUT] [-g] [--agents a,b] [--format markdown\|system-reminder\|json] [--write-agent] [--inline]` | Print (or write to `OUT`) the assembled context. `--write-agent` merges it into each agent's `context_target` under the project root (not with `-g`). Exits 2 when `--agents` names no known agent. |
 | `path [-g] [--lib] [--format list\|native\|posix\|json]` | Print the bin dirs `env` puts on `PATH` (`--lib`: the existing lib dirs it puts on `PYTHONPATH`), highest precedence first; runs no env file. `posix` is `:`-joined, MSYS2 form on Windows. |
-| `env [-g] [--format F] [--diff] [--cache]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
+| `env [-g] [--format F] [--diff] [--cache] [--into FILE]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`; `--into FILE`: write it into FILE as the one block this command owns there) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
 | `launch [AGENT] [-g] [--command PROG] [--no-context] [--inline] [--write-agent] [--dry-run] [-- ARGS...]` | Run the agent's CLI with the env applied and the context handed over; the exit code is the harness's (`128+N` on signal N). |
 | `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
@@ -108,6 +108,10 @@ The package's own data; library code, importing nothing from `dotagents.cli`.
   store at `dest`: the project template for a project store when the base has one,
   else the user template, else `<src>/AGENTS.md`; `{{AGENTS_MD}}` rendered as the
   absolute POSIX path of `<dest>/AGENTS.md`.
+- `pyz_archive() -> str | None` — the `.pyz` this dotagents is imported from (the
+  ancestor of the module's `__file__` that is a file), or `None` for a plain
+  install. The archive also holds the vendored duho and pathlib_next; `env`
+  exports it as `AGENTS_PYLIB`.
 
 ## Commands — `dotagents.cli.init`, `dotagents.cli.overlays`, `dotagents.cli.context`, `dotagents.cli.env`, `dotagents.cli.path`, `dotagents.cli.about`, `dotagents.cli.build_pyz`
 
@@ -119,6 +123,13 @@ returns the exit code.
   ("markdown", "system-reminder", "json")`); `env.Env`; `path.PathCmd`
   (`PATH_FORMATS = ("list", "native", "posix", "json")`); `build_pyz.BuildPyz`;
   `about.About`.
+- `env`: `write_into(path, text, output_format)` — what `--into` does: the file
+  keeps ONE block between `INTO_BEGIN = ": dotagents-env-begin"` and
+  `INTO_END = ": dotagents-env-end"` (no-op commands, not comments, so a `; cmd`
+  appended to the last line still runs; earlier blocks removed, other lines kept,
+  the new block last), written atomically; `INTO_FORMATS = ("export",)`. With
+  `--diff --format export`, a `PATH` that is the caller's with entries in front is
+  written as `export PATH='<prefix>'"${PATH:+:$PATH}"`.
 - `about`: `DISTRIBUTION = "dotagents-cli"`, `BUNDLE_FILE = "_bundle.json"` (written
   by `build-pyz` into the package), `RUNTIME_PACKAGES = ("duho", "pathlib_next",
   "uritools", "netimps", "requests")` (the only packages a plain install reports);
@@ -322,7 +333,11 @@ proxy model.
   user-scope walk `AGENTS_PROJECT_ROOT` is set only when unset. Only when unset:
   `AGENTS_PYTHON` (`sys.executable`) and one `<NAME>_OVERLAY_ROOT` per
   `scope.overlays` (a value pinned to the user store's copy is re-pointed when a
-  project copy shadows it).
+  project copy shadows it). `AGENTS_PYLIB` (`_env.PYLIB_VAR`): the `.pyz` when
+  dotagents runs from one (`_resources.pyz_archive()`), else not set — where its
+  own libraries (duho, pathlib_next) import from by zipimport for an overlay
+  built on them. Never added to `PYTHONPATH`: a consumer appends it to
+  `sys.path` when its import fails.
 - `PATH`: every level's `bin` (contract A, not project-root, missing dirs included)
   at the front in that order, whatever the caller's `PATH` held; empty and
   cwd-relative inherited entries are dropped.
@@ -631,6 +646,8 @@ Read:
 - `AGENTS_HARNESS` — the running harness (registry name or harness id), for
   identity. `AGENTS_PYTHON` — the interpreter for `env.py`. `AGENTS_PYTHONPATH` —
   the overlay/store `lib` dirs `env` put on `PYTHONPATH`, highest precedence first.
+  `AGENTS_PYLIB` — the `.pyz` dotagents runs from (duho and pathlib_next import
+  from it), unset for an installed dotagents.
 - Harness config dirs: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`.
   Harness markers: `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `GEMINI_CLI`,
   `CODEX_SANDBOX*`, `CURSOR_AGENT`, `PI_CODING_AGENT`. Model vars: `ANTHROPIC_MODEL`,
@@ -644,7 +661,7 @@ Read:
 
 Emitted by `env` (and applied by `launch`): `AGENTS_HARNESS`, `AGENTS_VENDOR`,
 `AGENT`, `AGENTS_MODEL`, `AGENTS_HOME`, `AGENTS_PROJECT_ROOT`, `AGENTS_PYTHON`,
-`<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
+`AGENTS_PYLIB` (from a `.pyz` only), `<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
 proxy vars, plus whatever the env files set. `AGENTS_AGENT` is never emitted.
 `launch` also exports `AGENTS_CONTEXT_FILE`.
 

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/__init__.py

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

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/_agents.py

@@ -500,14 +500,21 @@ class ClaudeAgent(Agent):
     # SessionStart does two things, in one `type: command` hook (SessionStart
     # supports only command/mcp_tool hooks, and env must run before context):
     #
-    # 1. `dotagents env --diff` output is appended to $CLAUDE_ENV_FILE
+    # 1. `dotagents env --diff` output goes into $CLAUDE_ENV_FILE
     #    (code.claude.com/docs/en/env-vars + hooks.md "Persist environment
     #    variables"): Claude sources that file before each Bash command. It is
     #    set only inside SessionStart/Setup/CwdChanged/FileChanged hook
     #    processes, never in the session's own environment.
-    #      * APPEND (`>>`), never truncate -- other hooks write to the same file.
+    #      * `--into`, not `>>`: the block a previous run wrote is REPLACED
+    #        and anything else in the file (another hook's lines) is kept.
+    #        SessionStart re-runs on resume, compact and clear; appending
+    #        grew the file by the whole env each time, and Claude Code inlines
+    #        it into every Bash command's `bash -c` argument, which Git for
+    #        Windows' bash truncates at about 8 KB -- every Bash call then
+    #        failed with an unterminated quote. PATH is written relative to
+    #        the shell's own ($PATH), which keeps the block small.
     #      * Guard on non-empty (`[ -n "$CLAUDE_ENV_FILE" ]`) -- when unset,
-    #        `>> ""` would create a file literally named "".
+    #        `--into ""` has nowhere to write.
     #
     # 2. `dotagents context`: Claude injects a SessionStart hook's stdout into
     #    the session context.
@@ -534,7 +541,7 @@ class ClaudeAgent(Agent):
     SESSION_START_COMMAND = (
         _HOOK_DOTAGENTS
         + 'if [ -n "$CLAUDE_ENV_FILE" ]; then '
-        '"$d" env --diff --format export >> "$CLAUDE_ENV_FILE"; '
+        '"$d" env --diff --format export --into "$CLAUDE_ENV_FILE"; '
         "fi; "
         '"$d" context'
     )

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/_env.py

@@ -59,7 +59,10 @@ The identity/proxy model is wired into the output around the file chain:
     the same set :func:`get_overlay_roots` lists, named by
     :attr:`_overlays.Overlay.root_var` --
     the same name ``dotagents context`` expands as a placeholder), so an env
-    file can reference an overlay's install dir by name.
+    file can reference an overlay's install dir by name. ``AGENTS_PYLIB``
+    (:data:`PYLIB_VAR`) names the ``.pyz`` when dotagents runs from one --
+    where its own libraries (duho, pathlib_next) import from for an overlay
+    built on them; never put on ``PYTHONPATH``.
   * **Proxy** is normalized AFTER the file chain: ``AGENTS_PROXY`` is seeded if
     unset (from ``AGENTS_WEBFETCH_PROXY_URL`` else the global
     HTTPS/HTTP/ALL_PROXY, either case); any proxy var that *already exists* is
@@ -94,6 +97,11 @@ from typing import Iterable, Optional
 
 from dotagents._scope import Scope, project_root_default
 
+#: Names the ``.pyz`` dotagents runs from (unset for an installed dotagents,
+#: whose libraries are in ``AGENTS_PYTHON``'s site-packages): an overlay built
+#: on duho appends it to ``sys.path`` when ``import duho`` fails.
+PYLIB_VAR = "AGENTS_PYLIB"
+
 
 class EnvChanges(dict):
     """A change set: the vars set (``dict[str, str]``, as before) plus
@@ -1047,6 +1055,17 @@ def get_environment(
     # `sys.executable` is '' or None under an embedding host: then nothing is
     # exported rather than an empty command name.
     _seed("AGENTS_PYTHON", sys.executable)
+    # --- AGENTS_PYLIB --- where dotagents' own libraries (duho, pathlib_next)
+    # import from for an overlay that builds on them. Set only when dotagents
+    # runs from a .pyz: the archive, importable by zipimport. An installed
+    # dotagents has them in AGENTS_PYTHON's site-packages already. Never put on
+    # PYTHONPATH, which would shadow a project's own copy: a consumer appends
+    # it to sys.path when its import fails.
+    from dotagents._resources import pyz_archive
+
+    pylib = pyz_archive()
+    if pylib and osenv.get(PYLIB_VAR) != pylib:
+        _apply({PYLIB_VAR: pylib})
 
     # --- Overlay roots --- one `<NAME>_OVERLAY_ROOT` per installed overlay, the
     # same name `dotagents context` expands as a `<NAME_OVERLAY_ROOT>` placeholder
@@ -1208,10 +1227,11 @@ def env_cache_key(scope: Scope, base_env: "dict[str, str]", *parts: str) -> str:
     import hashlib
 
     from dotagents import __version__
+    from dotagents._resources import pyz_archive
 
     scope = _absolute_scope(scope)
     items = [
-        __version__, sys.executable or "", os.getcwd(), scope.level,
+        __version__, sys.executable or "", pyz_archive() or "", os.getcwd(), scope.level,
         str(scope.user_root), str(scope.agents_root), str(scope.project_root),
         str(scope.system_root), *parts,
     ]

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/_resources.py

@@ -37,6 +37,18 @@ def _scratch_dir() -> Path:
     return _scratch
 
 
+def pyz_archive() -> "str | None":
+    """The ``.pyz`` this dotagents is imported from, or None for a plain
+    install. Inside a zipapp a module's ``__file__`` is a path INTO the
+    archive (``.../dotagents.pyz/dotagents/_resources.py``), so the archive
+    is the ancestor that is a file. It also holds the vendored runtime
+    dependencies (duho, pathlib_next), importable from it by zipimport."""
+    for parent in Path(__file__).parents:
+        if parent.is_file():
+            return str(parent)
+    return None
+
+
 def _package_data_dir(name: str) -> "Path | None":
     """Resolve a directory under the installed `dotagents` package (e.g.
     `_overlay`) to a real filesystem Path, working whether the package is a

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/src/dotagents/cli/env.py

@@ -232,10 +232,63 @@ def _looks_like_posix_path_list(key: str, value: str) -> bool:
     return any(_looks_like_posix_chunk(chunk) for chunk in value.split(";") if chunk)
 
 
+#: The lines around the block `env --into` owns in a file. No-op COMMANDS,
+#: not `#` comments: a harness that inlines the file and appends `; cmd` or
+#: `&& cmd` to its last line would otherwise comment the command out.
+INTO_BEGIN = ": dotagents-env-begin"
+INTO_END = ": dotagents-env-end"
+#: The formats `--into` writes: a POSIX shell's, where `:` is the no-op.
+INTO_FORMATS = ("export",)
+
+
+def write_into(path: Path, text: str, output_format: str) -> None:
+    """Put ``text`` into ``path`` as the ONE block ``env --into`` owns there:
+    every earlier block (between :data:`INTO_BEGIN` / :data:`INTO_END`) is
+    removed, anything else in the file -- another hook's lines -- is kept in
+    place, and the new block goes at the end, where a sourced file's later
+    lines win (what an append did). Atomic, LF-only. A hook that re-runs
+    (resume, compact, clear) used to append its whole output each time, and
+    the file Claude Code inlines into every Bash command grew past what Git
+    for Windows' bash accepts as a ``-c`` argument (about 8 KB)."""
+    from dotagents._env import FORMAT_ALIASES
+    from dotagents._fs import write_text_lf
+
+    fmt = FORMAT_ALIASES.get(output_format, output_format)
+    if fmt not in INTO_FORMATS:
+        raise SystemExit("error: --into writes the %s format only, not %r" % ("/".join(INTO_FORMATS), fmt))
+    kept: "list[str]" = []
+    inside = False
+    try:
+        current = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        current = ""
+    for line in current.splitlines():
+        if line.strip() == INTO_BEGIN:
+            inside = True
+        elif line.strip() == INTO_END and inside:
+            inside = False
+        elif not inside:
+            kept.append(line)
+    block = [INTO_BEGIN] + [ln for ln in text.splitlines() if ln] + [INTO_END]
+    write_text_lf(path, "\n".join(kept + block) + "\n", atomic=True)
+
+
+def _prefixed_path_line(new: str, old: str, sep: str) -> "Optional[str]":
+    """``export PATH='<prefix>'"${PATH:+:$PATH}"`` when ``new`` is ``old``
+    with entries put in front, else ``None``. The sourcing shell's own PATH
+    completes it, so the line stays short however long PATH is (the env file
+    is inlined into every Bash command) and keeps what the shell adds."""
+    if not old or not new.endswith(sep + old) or len(new) == len(old) + 1:
+        return None
+    prefix = new[: -(len(old) + 1)]
+    return 'export PATH=%s"${PATH:+%s$PATH}"' % (_sh_quote(prefix), sep)
+
+
 def _format_env(
     env: "dict[str, str]",
     output_format: str,
     removed: "Optional[Iterable[str]]" = None,
+    base: "Optional[dict[str, str]]" = None,
 ) -> str:
     """Render the assembled env in the requested (canonical or aliased) format.
 
@@ -369,9 +422,17 @@ def _format_env(
              for k in keys]
             + ["set -e %s" % k for k in gone if _POSIX_IDENTIFIER_RE.match(k)]
         )
-    # default / "export"
+    # default / "export". With the caller's env (`--diff`), a PATH that is the
+    # caller's own with entries in front is written relative to the sourcing
+    # shell's $PATH rather than in full (see `_prefixed_path_line`).
+    path_line = None
+    if base is not None and "PATH" in env:
+        old = base.get("PATH") or ""
+        if windows_host and _looks_like_path_list("PATH", old):
+            old = _to_posix_path_list(old)
+        path_line = _prefixed_path_line(env["PATH"], old, ":")
     return "\n".join(
-        ["export %s=%s" % (k, _sh_quote(env[k])) for k in keys]
+        [path_line if k == "PATH" and path_line else "export %s=%s" % (k, _sh_quote(env[k])) for k in keys]
         + ["unset %s" % k for k in gone if _POSIX_IDENTIFIER_RE.match(k)]
     )
 
@@ -568,6 +629,14 @@ class Env(DotAgentsArgs):
     )
     ("--cache",)
 
+    into: "Optional[Path]" = None
+    (
+        "Write into this file instead of stdout (a hook's $CLAUDE_ENV_FILE), "
+        "replacing the block an earlier run wrote there and keeping the rest: "
+        "the file holds one current block however often the hook runs."
+    )
+    ("--into",)
+
     # Both flags come from `DotAgentsArgs`; only their HELP is restated here
     # (same flags, defaults and types), because this command's `-g` is narrower
     # than the base's and its store is always the user store.
@@ -631,8 +700,13 @@ class Env(DotAgentsArgs):
 
         # UTF-8 straight to the buffer: a bare print() encodes with the console
         # codepage and dies on the first non-Latin-1 character in any value.
-        text = _format_env(env, output_format, removed) + "\n"
+        # With --diff, PATH may be written relative to the caller's own PATH
+        # (see `_format_env`): the base is what the diff was taken against.
+        text = _format_env(env, output_format, removed, base=base if self.diff else None) + "\n"
         if key is not None:
             _env.write_env_cache(scope, key, text)
+        if self.into is not None:
+            write_into(Path(self.into), text, output_format)
+            return 0
         _write_stdout(text)
         return 0

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/tests/test_env.py

@@ -489,6 +489,43 @@ def test_agents_python_is_not_exported_when_the_interpreter_is_unknown(tree, mon
     assert "AGENTS_PYTHON" not in env
 
 
+def test_agents_pylib_names_the_pyz_only_when_running_from_one(tree, tmp_path, monkeypatch):
+    """An installed dotagents has its libraries in AGENTS_PYTHON's
+    site-packages: nothing to export. From a .pyz the archive is where they
+    import from; the walk's value replaces another, and it never reaches
+    PYTHONPATH (a project's own duho must not be shadowed)."""
+    from dotagents import _resources
+
+    agents_dir, project_root = tree
+    assert _resources.pyz_archive() is None, "the suite runs from the source tree"
+    env = _run(agents_dir, project_root, {"PATH": "/usr/bin"})
+    assert _env.PYLIB_VAR not in env
+    pyz = tmp_path / "dotagents.pyz"
+    pyz.write_bytes(b"PK")
+    monkeypatch.setattr(_resources, "pyz_archive", lambda: str(pyz))
+    env = _run(agents_dir, project_root, {"PATH": "/usr/bin"})
+    assert env[_env.PYLIB_VAR] == str(pyz)
+    assert str(pyz) not in env.get("PYTHONPATH", "")
+    env = _run(agents_dir, project_root, {"PATH": "/usr/bin", _env.PYLIB_VAR: str(pyz)})
+    assert _env.PYLIB_VAR not in env, "already right: no change"
+    env = _run(agents_dir, project_root, {"PATH": "/usr/bin", _env.PYLIB_VAR: "/old/dotagents.pyz"})
+    assert env[_env.PYLIB_VAR] == str(pyz), "another archive's value is replaced"
+
+
+def test_pyz_archive_finds_the_archive_a_module_is_imported_from(tmp_path):
+    """Run from a real zipapp: the archive is the ancestor of __file__ that is a file."""
+    import subprocess
+    import zipfile
+
+    src = Path(_env.__file__).resolve().parents[1]
+    pyz = tmp_path / "t.pyz"
+    with zipfile.ZipFile(str(pyz), "w") as zf:
+        zf.write(str(src / "dotagents" / "_resources.py"), "probe_resources.py")
+    code = "import sys; sys.path.insert(0, sys.argv[1]); import probe_resources as r; print(r.pyz_archive())"
+    out = subprocess.run([sys.executable, "-c", code, str(pyz)], capture_output=True, text=True, check=True)
+    assert out.stdout.strip() == str(pyz)
+
+
 def test_env_py_runs_under_a_pinned_agents_python(tree, tmp_path, monkeypatch):
     """The pin `env` exports for shims is honoured for dotagents' own
     subprocesses too (only when it names an existing file)."""

dotagents_cli-0.6.3/tests/test_env_into.py

@@ -0,0 +1,89 @@
+"""`env --into FILE` keeps ONE dotagents block in a hook's env file however
+often the hook runs, leaves other hooks' lines alone, and `--diff --format
+export` writes PATH relative to the sourcing shell's own -- so the file
+Claude Code inlines into every Bash command stays small. (A SessionStart hook
+that appended on every resume/compact grew it past Git for Windows' ~8 KB
+`bash -c` limit, and every Bash call failed.)"""
+import os
+import subprocess
+
+import pytest
+
+from dotagents.cli.env import INTO_BEGIN, INTO_END, _format_env, _prefixed_path_line, write_into
+from _shell import real_bash
+
+
+def test_write_into_replaces_only_its_own_block(tmp_path):
+    env_file = tmp_path / "hook.sh"
+    env_file.write_text("export OTHER_HOOK='kept'\n", encoding="utf-8")
+    for value in ("one", "two", "three"):
+        write_into(env_file, "export A='%s'\nexport B='x'\n" % value, "export")
+    text = env_file.read_text(encoding="utf-8")
+    assert text.count(INTO_BEGIN) == 1 and text.count(INTO_END) == 1, "one block, however often"
+    assert "export OTHER_HOOK='kept'" in text, "another hook's line stays"
+    assert "export A='three'" in text and "one" not in text and "two" not in text
+    assert text.index("OTHER_HOOK") < text.index(INTO_BEGIN), "ours last: it wins, as an append did"
+    assert b"\r" not in env_file.read_bytes()
+
+
+def test_write_into_creates_the_file_and_refuses_formats_without_comments(tmp_path):
+    env_file = tmp_path / "new.sh"
+    write_into(env_file, "export A='1'\n", "export")
+    assert env_file.read_text(encoding="utf-8") == "%s\nexport A='1'\n%s\n" % (INTO_BEGIN, INTO_END)
+    with pytest.raises(SystemExit):
+        write_into(tmp_path / "x.cmd", 'set "A=1"\n', "cmd")
+
+
+def test_a_command_appended_to_the_block_still_runs(tmp_path):
+    """The markers are no-op COMMANDS: a harness that inlines the file and
+    joins the command onto its last line (`; cmd`, `&& cmd`) must not have it
+    commented out."""
+    bash = real_bash()
+    if not bash:
+        pytest.skip("no bash")
+    env_file = tmp_path / "hook.sh"
+    write_into(env_file, "export A='1'\n", "export")
+    body = env_file.read_text(encoding="utf-8").rstrip("\n")
+    for joiner in ("; ", " && ", "\n"):
+        out = subprocess.run([bash, "-c", body + joiner + 'printf "%s" "$A"'], capture_output=True, text=True)
+        assert out.stdout == "1", (joiner, out.stderr)
+    with pytest.raises(SystemExit):
+        write_into(tmp_path / "x.env", "A=1\n", "dotenv")
+
+
+def test_prefixed_path_line():
+    assert _prefixed_path_line("/a:/b:/usr/bin", "/usr/bin", ":") == 'export PATH=\'/a:/b\'"${PATH:+:$PATH}"'
+    assert _prefixed_path_line("/usr/bin", "/usr/bin", ":") is None, "nothing in front"
+    assert _prefixed_path_line("/a:/usr/local/bin", "/usr/bin", ":") is None, "not a prefix: full value"
+    assert _prefixed_path_line("/a", "", ":") is None
+
+
+@pytest.mark.skipif(os.name == "nt", reason="a POSIX PATH; the Windows conversion is covered below")
+def test_diff_export_writes_path_as_a_prefix_on_posix():
+    out = _format_env({"PATH": "/opt/x/bin:/usr/bin:/bin", "A": "1"}, "export", base={"PATH": "/usr/bin:/bin"})
+    assert "export PATH='/opt/x/bin'\"${PATH:+:$PATH}\"" in out
+    assert _format_env({"PATH": "/opt/x/bin:/usr/bin"}, "export") == "export PATH='/opt/x/bin:/usr/bin'", "no base: full"
+
+
+def test_diff_export_prefix_survives_the_windows_conversion(monkeypatch):
+    from dotagents.cli import env as env_cli
+
+    monkeypatch.setattr(env_cli, "_host_is_windows", lambda: True)
+    base = {"PATH": r"C:\Windows\System32;C:\Windows"}
+    new = {"PATH": r"C:\Tools\dotagents\bin;C:\Windows\System32;C:\Windows"}
+    out = _format_env(new, "export", base=base)
+    assert out == "export PATH='/c/Tools/dotagents/bin'\"${PATH:+:$PATH}\""
+
+
+def test_a_sourced_block_really_prepends(tmp_path):
+    """Source the rendered line in a real POSIX shell: the prefix lands in
+    front of that shell's own PATH."""
+    bash = real_bash()
+    if not bash:
+        pytest.skip("no bash")
+    line = _prefixed_path_line("/opt/dotagents/bin:/usr/bin", "/usr/bin", ":")
+    script = tmp_path / "env.sh"
+    script.write_text(line + "\n", encoding="utf-8")
+    out = subprocess.run([bash, "-c", "PATH=/shell/own; . ./env.sh; printf %s \"$PATH\""],
+                         cwd=str(tmp_path), capture_output=True, text=True)
+    assert out.stdout == "/opt/dotagents/bin:/shell/own", out.stderr

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/tests/test_wire_hooks.py

@@ -110,15 +110,18 @@ def test_hook_finds_dotagents_by_path_not_by_splicing_path():
         assert "PATH=" not in cmd
 
 
-def test_env_hook_appends_and_is_guarded():
-    """Two documented requirements, both load-bearing.
-
-    `>` would discard variables other hooks wrote to the same file; an unguarded
-    redirect with CLAUDE_ENV_FILE unset would create a file named "".
+def test_env_hook_replaces_its_own_block_and_is_guarded():
+    """Three requirements, all load-bearing.
+
+    `>` would discard variables other hooks wrote to the same file; `>>`
+    grew it by the whole env on every SessionStart (resume, compact, clear)
+    until the file Claude Code inlines into each Bash command passed Git for
+    Windows' ~8 KB `bash -c` limit -- so `env --into` replaces only its own
+    block. An unguarded write with CLAUDE_ENV_FILE unset has nowhere to go.
     """
     cmd = ClaudeAgent.SESSION_START_COMMAND
-    assert '>> "$CLAUDE_ENV_FILE"' in cmd, "must append, never truncate"
-    assert ">>" in cmd and not _has_truncating_redirect(cmd)
+    assert 'env --diff --format export --into "$CLAUDE_ENV_FILE"' in cmd
+    assert ">>" not in cmd and not _has_truncating_redirect(cmd), "no shell redirect into the env file"
     assert '[ -n "$CLAUDE_ENV_FILE" ]' in cmd, "must guard against an unset var"
     assert cmd.index('"$d" env') < cmd.index('"$d" context'), (
         "env must be written before context runs"

{dotagents_cli-0.6.2 → dotagents_cli-0.6.3}/tools/pyz_smoke.sh

@@ -181,6 +181,13 @@ has "$(pinned_env --format powershell)" "\${env:FROM_PINNED_STORE} = 'yes'"
 has "$(pinned_env --format cmd)" 'set "FROM_PINNED_STORE=yes"'
 has_re "$(pinned_env --format dotenv)" "^FROM_PINNED_STORE=yes$"
 has "$(pinned_env)" "FROM_PINNED_STORE"
+# Run from a .pyz, env names it in AGENTS_PYLIB, and the vendored duho imports
+# from it by zipimport: what an overlay built on duho (the net overlay's curl
+# fallback) relies on when AGENTS_PYTHON has no duho of its own.
+has_re "$(pyz env --diff --format dotenv -g)" "^AGENTS_PYLIB=.*\.pyz"
+# -S -E: no site-packages, no PYTHONPATH -- a runner that has duho installed
+# must still prove the archive alone provides it.
+"$PYTHON" -S -E -c "import sys; sys.path.insert(0, sys.argv[1]); import duho; assert '.pyz' in duho.__file__, duho.__file__" "$(native "$PYZ")"
 
 # overlays add: positional and aliased flags.
 h=$(pyz overlays add --help)