dotagents-cli 0.9.1__tar.gz → 0.9.2__tar.gz

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-11-11
+
+### Added
+
+- Overlay hooks, the AOS "Hooks" extension: an overlay's `hook.<ext>` and `[hooks]` table
+  run at a session's events (`pre-env`, `session-start`, `session-end`, `prompt`,
+  `turn-end`, `cd`, `pre-compact`, `pre-tool`, `post-tool`). dotagents fires `pre-env`
+  itself as it builds the environment, on every harness; `init` and
+  `overlays add/sync/remove` wire Claude Code's and Codex's own hooks to a new
+  `dotagents hook` command for the other events an installed overlay has a hook for (nothing
+  is wired, so no process starts, for a store without them). A hook is off until the user
+  allows it at the overlay's tree digest (`overlays hooks`, `overlays allow-hooks NAME
+  --digest D`, `overlays revoke-hooks`; kept in the user store, one digest per overlay), is
+  bounded (60 s a run, 120 s an event, 64 KiB of output, 1 MiB of payload, arguments as a
+  list, its own process group), and can only tighten: a `decision` other than
+  `block`, `deny` or `ask` is a refused attempt to grant, and the answer to the harness is
+  built by dotagents, never the hook's output. An overlay with a hook that refuses on failure
+  is not activated while its hooks are off. What a harness cannot fire or apply is reported
+  (`hook-unsupported`, `hook-partial`, `hook-not-applied`, `hook-ask-denied`,
+  `hook-not-allowed`, `hook-failed`), never dropped. Passes the specification's hook
+  vectors (the `OVERLAY.md` cases excepted: that form is not read yet). See
+  `docs/guide/overlay-hooks.md`.
+- The sensitive-variable list holds `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, which point a
+  harness at another configuration, with its own permissions and hooks.
+
+### Fixed
+
+- The session-start, PowerShell, Codex and Antigravity hook entries run the `dotagents` of the
+  store (`$AGENTS_HOME/bin`) or on PATH, never one in the project's own `.agents/bin`: the agent
+  can write there, and what it planted ran with the user's access.
+
+### Changed
+
+- `private-sync`'s session start and sync-back are now overlay hooks (`session-start` and
+  `turn-end`) instead of scripts you register in `~/.claude/settings.json`; it no longer ships
+  `hooks/settings.snippet.json`. Allow them once (`dotagents overlays allow-hooks private-sync`)
+  and run `dotagents init -g`; remove the old entries from `settings.json` or they run twice.
+  `tools/cloud-setup.sh` does both steps itself.
+
 ## [0.9.1] - 2026-11-06
 
 ### Fixed
@@ -1754,7 +1793,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.9.1...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.9.2...HEAD
+[0.9.2]: https://github.com/jose-pr/dotagents/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/jose-pr/dotagents/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/jose-pr/dotagents/compare/v0.8.3...v0.9.0
 [0.8.3]: https://github.com/jose-pr/dotagents/compare/v0.8.2...v0.8.3

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.9.1
+Version: 0.9.2
 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.9.1 → dotagents_cli-0.9.2}/docs/guide/commands.md

@@ -217,6 +217,8 @@ dotagents overlays list                    # installed (discovered) + available
 dotagents overlays sync 'py*'              # refresh installed overlays matching a glob
 dotagents overlays remove python           # delete the overlay dir, unpublish its skills, un-merge its rules
 dotagents overlays show python             # describe one: declarations, digest, pin, weakenings, source (--json)
+dotagents overlays hooks private-sync      # its hooks: what runs where, and whether they are allowed
+dotagents overlays allow-hooks private-sync --digest sha256:...   # allow them at that digest (see overlay-hooks)
 ```
 
 - **`add`** takes names or globs: `'*'` is every overlay the repos offer, so with

dotagents_cli-0.9.2/docs/guide/overlay-hooks.md

@@ -0,0 +1,213 @@
+# Overlay hooks
+
+An overlay can run a program at a named moment of a session: before the environment is built,
+when a session starts or ends, when you send a prompt, before a tool runs. This is the
+[Agent Overlay Specification's hooks](https://boriken-dev.github.io/agent-overlay-spec/spec/v0/hooks/)
+(an optional extension); this page is what dotagents does with them.
+
+```toml
+# overlay.cfg
+[hooks]
+session-start = "hooks/start.py"
+pre-tool = { run = "hooks/guard.sh", match = ["execute"], timeout = 5, on_failure = "refuse" }
+turn-end = false
+```
+
+A `hook.<ext>` at the overlay root (chosen by runtime, as `env.<ext>` is) receives every event
+that carries no content by default. `prompt`, `pre-tool` and `post-tool` carry what you typed or
+what a tool was given, so they fire only for an event `[hooks]` names. The hook is told its event
+as its first argument and in `AOS_HOOK_EVENT`, and its payload as one JSON object on standard
+input; it answers with nothing or one JSON object (`context`, `decision`, `reason`, `env`).
+
+## A hook tightens and never grants
+
+Nothing a hook prints reaches the harness. dotagents reads the output, accepts only what the
+event takes, and answers the harness itself, in the harness's words. A `decision` other than
+`block`, `deny` or `ask` (`allow`, `approve`, anything) is a refused attempt to grant: the run
+fails (`grant`) and nothing of it applies. dotagents never states an approval and never rewrites
+a tool's input.
+
+## Off until you allow them
+
+A hook is the overlay's code, running at every session with your access, outside the harness's
+sandbox. An overlay's hooks do not run until you allow them at the overlay's digest:
+
+```
+dotagents overlays hooks NAME                       # what runs, where, and whether it is allowed
+dotagents overlays allow-hooks NAME                 # shows the same and the digest
+dotagents overlays allow-hooks NAME --digest sha256:...
+dotagents overlays revoke-hooks NAME
+```
+
+The allowance is kept in your user store (`overlays/.dotagents-state/hooks-allowed.json`), never
+in an overlay or a project, per overlay and store. There is one digest per overlay: any change to
+the overlay turns its hooks off until you allow the new one, and going back to an earlier digest
+needs a new yes. `allow-hooks` asks at the terminal itself (`/dev/tty`, `CONIN$`), refuses to run
+inside an agent harness's session and is not an MCP tool; `--no-prompt` is for your own setup
+script. The allowance is only as strong as the agent's lack of write access to your user store:
+an agent that can write there can write an allowance.
+
+An overlay with a hook that has `on_failure = "refuse"` (a guard) is **not activated** while its
+hooks are off, and its guards **fail** meanwhile: a prompt is blocked, a tool call denied, as if
+the hook had run and failed (`hook-not-allowed` at the next session start). A guard that is
+missing must not let everything through.
+
+## Which events fire where
+
+| Event | Claude Code | Codex | Any other harness |
+| --- | --- | --- | --- |
+| `pre-env` | dotagents fires it as it builds the environment | same | same |
+| `session-start` | `SessionStart`: context, and variables for Bash through the env file | `SessionStart`: context | cannot |
+| `session-end` | `SessionEnd` | `SessionEnd` | cannot |
+| `prompt` | `UserPromptSubmit`: context, block | same | cannot |
+| `turn-end` | `Stop` (notification only) | `Stop` | cannot |
+| `cd` | `CwdChanged`: variables | no such event: cannot | cannot |
+| `pre-compact` | `PreCompact`: context, block | `PreCompact`: block (no context) | cannot |
+| `pre-tool` | `PreToolUse`: deny, ask, context | `PreToolUse`: deny, context (`ask` is applied as `deny`) | cannot |
+| `post-tool` | `PostToolUse`: context | `PostToolUse`: context | cannot |
+
+What cannot fire is reported (`hook-unsupported`), as is an event that fires for only some
+occurrences (`hook-partial`: Claude Code's `PostToolUse` is for calls that ended well; Codex's
+tool hooks were measured on its shell tool), an output the harness cannot take
+(`hook-not-applied`: variables from `prompt` or `pre-tool`, context from Codex's `pre-compact`,
+refusing a session start), an `ask` turned into a `deny` (`hook-ask-denied`), a hook that is off
+(`hook-not-allowed`), and a failed run (`hook-failed`, with its cause, never its output). The
+reports reach you in the session-start message of the harness and in the log of `dotagents env`.
+`dotagents overlays hooks` lists the table above per hook.
+
+`init` and `overlays add/sync/remove` wire the harness's own hook for an event only when an
+installed overlay has a hook for it (`dotagents hook` is the program they run, through a small
+forwarder script `overlay_hook.py` deployed in your user config directory), so a store with no
+hooks starts no extra process. A project's entries (`settings.local.json`) run the same forwarder
+from your user config directory. The text of an entry holds no guard flag and no overlay name, so
+it does not change when overlays do. Codex asks you to trust a hook by its hash; dotagents never
+writes that trust.
+
+## Limits and failures
+
+Every hook runs with the overlay root as its working directory, outside the sandbox, in its own
+process group (a job object on Windows) that ends with it, with arguments as a list (no shell
+reads the overlay's strings) and the environment of that overlay's own processes. Defaults:
+60 s a run (and the entry's `timeout`, default 30, if shorter), 120 s an event, 64 KiB of
+output (more stops the run), 64 KiB of standard error kept for the log, 1 MiB of payload. A
+failed hook applies nothing of its output; with `on_failure = "report"` the event goes on, with
+`"refuse"` it is refused (a prompt blocked, a call denied, a session start reported as not
+refusable). `pre-env` stops the session only under `dotagents launch`, where the harness does not
+exist yet; under `dotagents env` (a harness already running, a setup) it is reported as
+`hook-not-applied` and nothing of the hook applies. An oversize or unreadable payload is a failure
+of the event, refused when it has a guard.
+
+The limits are settings, read from your user store only
+(`overlays/.dotagents-state/hooks-settings.json`; a project's file is never read), each in
+bounds: `timeout`, `event_timeout`, `deadline`, `max_output`, `max_payload`. The deadline
+(default 150 s, at most 580) covers everything a harness's hook entry does from the process's
+start: building the scope, hashing, env scripts and hooks; at it the whole process tree ends. The
+harness's own timeout for the entry is derived from it and written at wiring time, so run
+`dotagents init -g` after changing it.
+
+Context a hook adds is wrapped in a marker holding a random nonce chosen after the hooks ran, so
+the text cannot imitate it. Variables for Bash are written to Claude Code's env file as
+single-quoted values of names the hook declared in `sets`; a value holding a line separator of
+any kind (CR, LF, VT, FF, U+0085, U+2028, U+2029, NUL) is not written (`hook-not-applied`), and a
+sensitive name (`PATH`, `BASH_ENV`, `LD_*`, ...) that is set is reported (`env-sensitive`). What a
+hook writes to standard error goes to `<user store>/.cache/hooks.log` (bounded), never to the
+harness.
+
+## What a hook cannot reach
+
+This is about the **overlay-hook path**: a hook of an installed overlay, fired through the
+forwarder (or by `pre-env`). It is the hardened path. It is not the whole of dotagents: see
+"Where project code does run" below.
+
+- **Bytes that were not hashed.** At each event the overlay's tree is read once, hashed, compared
+  with the allowed digest, and written to a snapshot under `<user store>/.cache/hook-snapshots/`
+  from those same bytes. The manifest the event is planned from, the env scripts that build the
+  hook's environment, the `lib/` and `bin/` paths they declare, the hook, and its working
+  directory are all the snapshot's; Python hooks run under `-I` with the snapshot's libraries on
+  the path explicitly. A file swapped after hashing, or a `node_modules`, `__pycache__` or
+  `.venv` (not part of a digest) planted beside the overlay, do not run. An existing snapshot is
+  hashed again before it is used, and copies of other digests are removed only when unused for a
+  week (a session started before an update still runs from its own). The overlay's state
+  directory is the live one, so a hook keeps what it wrote.
+- **Anything the project holds.** The hook entries run an absolute interpreter, isolated (`-I`),
+  a forwarder script in your user config directory, and a fixed entry of the `dotagents` that
+  `init` recorded there (`dotagents._hook_main`). That entry is not the `dotagents` command line:
+  it discovers no command and adds no library, so `<project>/.agents/dotagents/cmds/`, a
+  project overlay's `cmds/` and `lib/` and the project's own modules never load in it. For a
+  user-level hook its scope has no project store at all, so a project folder cannot shadow a hook
+  of yours (a same-named one is reported, `hook-shadowed`, and your hook still runs), cannot add
+  anything to it, and cannot choose its Python.
+- **A stand-in for dotagents.** The forwarder gives the entry a fresh nonce and accepts only an
+  answer that carries it back. A program that exits 0 with no output, or answers without the
+  nonce, is a failed guard (a refusal) and nothing at all for an event with no guard; an
+  "everything is fine" is never inferred from silence. When the forwarder's record lists a guard
+  for an event and the entry finds none, that is a refusal too. The forwarder passes the harness
+  only a refusal, context and a message, in the harness's own shape.
+- **A project's interpreters.** `pwsh`, `node`, `bash` and the like, for a hook and for the env
+  scripts that build its environment, are found by dotagents itself (never the current
+  directory, which Windows searches first) on the `PATH` the session was started from, less every
+  relative entry, store or overlay `bin`, venv, and anything below the project or the user store
+  (`.venv/Scripts`, `node_modules/.bin`, `.agents/bin`). A Windows bash is looked for only beside
+  a `git` on that PATH and in the standard install directories.
+- **A project's Python.** A hook, and the env scripts that build its environment, run with the
+  user store's Python chosen before any declaration runs, never a project's venv, and never the
+  session's `AGENTS_PYTHON`.
+- **Other overlays' secrets.** `dotagents launch` records what it changed in
+  `AGENTS_SESSION_BASE`; a hook starts from the environment the session was started from, so a
+  secret another overlay was granted does not reach it. The harness's own variables
+  (`CLAUDE_ENV_FILE`, `CLAUDE_CODE_*`, `CODEX_*`) are dropped too. The project's own name for
+  itself (`AGENTS_PROJECT_ROOT`, `CLAUDE_PROJECT_DIR`) is kept.
+- **The harness itself.** `dotagents launch` looks for a bare program name (`claude`) on the PATH
+  the shell had, less the same places, not on the session's PATH that starts with the project's
+  `.agents/bin`.
+
+## Where project code does run
+
+Not everything dotagents does is hardened this way, by design (the owner's decision, recorded in
+dotagents' decisions):
+
+- The session-start, Codex and Antigravity entries that `init` wrote before overlay hooks existed
+  run `dotagents env` and `dotagents context` **in the project**. Those are the full command line:
+  they load `<project>/.agents/dotagents/cmds/`, and `env` runs the env scripts of the overlays
+  active there, outside the harness's sandbox. They run the store's `dotagents` (never one found in
+  the project or on PATH), but what that program loads from the project, it runs.
+- A project overlay's own `env`/env scripts run whenever the environment is built for a session
+  there (`env`, `launch`, `setup`), as any active overlay's do.
+- **Project-level guards are advisory.** A project-level hook entry lives in
+  `<project>/.claude/settings.local.json`, which the agent can write: it can remove the entry. The
+  forwarder and the user-level entries in your own config are not affected, but a guard that only
+  a project overlay declares is only as strong as that file. Put a guard you rely on in an overlay
+  of your user store.
+
+An agent that can write the project's `.agents`, or your user store, can run code through those
+paths; the overlay-hook path is the one that does not depend on either being safe from the agent.
+
+## The limit, generally
+
+All of this assumes the places dotagents runs code *from* are not the agent's to write. A
+deployment gets no barrier where:
+
+- the recorded `code_root` is inside a checkout the agent works in (a `dist/dotagents.pyz` of a
+  repository, a source tree on `PYTHONPATH`), or a venv's `.pth` points dotagents into such a
+  place: what the agent writes there runs with your access. Install dotagents where the agent
+  cannot write, then run `dotagents init -g`;
+- the agent can write your user store (`~/.agents`): it holds the allowances, the snapshots, the
+  settings and the wrappers, so it can allow and run anything.
+
+`--no-prompt` and the harness-session check of `allow-hooks` stop accidents, not an agent: an
+agent can clear its environment (`env -i`) and run the command. What keeps an agent from allowing
+its own hooks is that `allow-hooks` is not an MCP tool and that the allowance is in a store it
+cannot write.
+
+Smaller limits: a hook that detaches into a new session (`setsid`) can outlive the tree kill on
+POSIX; an overlay whose manifest is refused cannot show its guards; a hook can still read what
+its overlay `requires` puts on its paths, live, and the packages an overlay's setup installed; an
+entry whose interpreter has been uninstalled cannot run to say so (`dotagents overlays hooks` and
+every `init` check the recorded one); and Codex asks you to trust an entry by its hash, which
+dotagents cannot read: `overlays hooks` says the event fires natively once you have trusted it,
+and a change of the entry text is warned about when it is wired.
+
+## Not done yet
+
+Hooks declared by your own configuration or a project's (outside overlays), a `pre-tool`
+variable loader, `OVERLAY.md` front matter, and harnesses other than Claude Code and Codex.

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/docs/guide/private-sync.md

@@ -77,12 +77,20 @@ leaves the machine is a perfectly valid setup.
 
 ## Cloud sessions
 
-The `private-sync` overlay ships SessionStart / Stop hook scripts that clone or pull
-the private repo and link/sync the project each session. `overlays add` does not
-register them: add them to your runner's settings yourself (for Claude Code,
-`~/.claude/settings.json`), using the snippet the overlay ships in
-`$PRIVATE_SYNC_OVERLAY_ROOT/hooks/settings.snippet.json`. The bootstrap below does that
-merge for you.
+The `private-sync` overlay declares two [overlay hooks](overlay-hooks.md) that clone or pull
+the private repo and link/sync the project each session: `session-start` pulls and links,
+`turn-end` pushes the session's changes back. They are off until you allow them at the
+overlay's digest, and `dotagents init -g` wires Claude Code's and Codex's own hooks to run
+them:
+
+```bash
+dotagents overlays hooks private-sync            # what runs, on which harness, and whether it is allowed
+dotagents overlays allow-hooks private-sync      # shows the same and the digest to allow
+dotagents overlays allow-hooks private-sync --digest sha256:<the digest shown>
+dotagents init -g
+```
+
+The bootstrap below does all of that for you.
 
 For a **fresh container** with no config yet, point the web environment's setup-script
 field at the self-contained bootstrap shipped in this repo — it fetches the latest each

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/mkdocs.yml

@@ -32,6 +32,7 @@ nav:
       - Install: guide/install.md
       - Commands: guide/commands.md
       - Overlays: guide/overlays.md
+      - Overlay hooks: guide/overlay-hooks.md
       - Private sync: guide/private-sync.md
       - Authoring an overlay: guide/authoring.md
   - API Reference:

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/src/dotagents/AGENTS.md

@@ -52,6 +52,10 @@ and an error saying a command is required, and exits 2.
 | `overlays sync [GLOB] [-g] [--repo SPEC]... [--copy] [--no-setup] [--setup-timeout S] [--no-venv] [--dry-run]` | Refresh installed overlays from the repo recorded at install (`--repo` replaces it), checked as `add` checks a source: the install is made to hold exactly the overlay's members (new and changed files land, everything else goes, caches and setup output left inside it included); a file edited here is backed up first under `<store>/install_backup/<timestamp>/overlays/<name>/`. Installs new `requires`, then prepares each synced overlay in its `sync` phase (`install` when no preparation succeeded here yet), whether its digest changed or not: its environments rebuilt, then its setup. Exits 1 when an overlay's repo cannot be loaded, its source lies inside `<store>/overlays/` or is refused, or its dependencies or setup fail. |
 | `overlays list [-g] [--repo SPEC]... [--json]` | Installed overlays per store (shadowed copies marked, unmet `requires` and refused overlays flagged) and what the repos offer. |
 | `overlays show NAME [-g] [--repo SPEC]... [--json]` | One overlay: the copy a session would use, else the source's; its declarations, a refused manifest's problems, tree digest, pin, what this machine lacks for it, its weakenings, skills, member count, recorded source and commit. No name: exit 2. |
+| `overlays hooks [NAME] [-g]` | An installed overlay's hooks (every overlay with some, without a name): per event the script and its settings, whether the hooks are allowed at the overlay's current digest, and per harness whether the event fires natively, is fired by dotagents itself (`pre-env`) or cannot fire. |
+| `overlays allow-hooks NAME [--digest D] [--no-prompt] [-g]` | Show the same, then allow the overlay's hooks at digest `D`, which must be the current one: without `--digest` it prints the digest to pass and allows nothing (exit 0); a wrong digest exits 2. Then it asks at the terminal itself (`/dev/tty`, `CONIN$`): `allow NAME` to confirm; `--no-prompt` is for the user's own setup script. It refuses (exit 2) inside an agent harness's session and is not an MCP tool. The allowance is kept in the user store (`overlays/.dotagents-state/hooks-allowed.json`), one digest per overlay and store, and is only as strong as an agent's lack of write access to the user store. |
+| `overlays revoke-hooks NAME [-g]` | Take back the allowance. |
+| `hook EVENT --harness claude-code\|codex [--level user\|project] [--guard]` | Not for typing: what a harness's own hook entry runs (through `overlay_hook.py`). Reads the harness's payload on standard input, fires the overlays' hooks for the event (`user`: the user and system stores' overlays, `project`: the project store's), and answers in the harness's words; a hook's output never reaches the harness and the answer is never an approval. `--guard`: a failure of this program answers with a refusal where the event can be refused. Always exits 0 (2 for a bad argument). Not an MCP tool. |
 | `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 dirs `env` adds to `PATH` -- each store's `bin` and each active overlay's `PATH` additions (`--lib`: the existing agent library dirs, `PYTHONPATH`) -- highest precedence first; runs no env file. `posix` is `:`-joined, MSYS2 form on Windows. |
 | `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`. |
@@ -269,6 +273,24 @@ conformance vectors (`tests/aos_vectors/`, revision in `REVISION`).
   `activates`; a failed sync keeps only the recorded digest active).
 - Resolution: `class ResolveError(Exception)` (`chain`), `resolve(requires_of,
   requested) -> (visiting order, missing)`, `order_key(priority, name, identity)`.
+- Hooks (the hook vectors in `tests/aos_vectors/hooks*.json` pass): `HOOK_EVENTS`
+  (event → class, runs `hook.<ext>` by default, outputs, refusal, what `match` selects),
+  `SESSION_REASONS`, `TOOL_KINDS`; `[hooks]` and `[defaults] hooks` validate in
+  `validate`. `default_hook(files, os_name, interpreters)`, `hooks_of(manifest, files,
+  os_name, interpreters) -> (entries, script-not-run files)`, `hook_plan(manifest, facts)
+  -> {hooks, on, activates, needs, reports, non_defaults}` (`on` only while the digest is
+  the one allowed; `activates` false for a guard that is off), `hook_matches(event, match,
+  value)`, `hook_payload(event, known)` with `PAYLOAD_COMMON`, `PAYLOAD_KEYS`, `TOOL_KEYS`;
+  `read_hook_output(event, data, sets)` / `hook_result(event, run, limits)` raise
+  `HookFailure` (`.cause`: `not-run`, `payload-too-large`, `timeout`, `too-large`, `exit`,
+  `grant`, `output`) with `HOOK_OUTPUT_KEYS`, `MAX_HOOK_REASON`; `fire_event(event, runs,
+  applies, limits, windows) -> dict` combines hooks to the tightest (a run holding `start`, a
+  function, is started only when its turn comes); `apply_pre_env(env, identities, runs,
+  limits, reports, non_defaults)` applies `pre-env` output (raises `Refused("hook-refused")`);
+  `DEFAULT_HOOK_TIMEOUT = 30`, `DEFAULT_HOOK_LIMITS` (60 s a run, 120 s an event, 64 KiB
+  output and error, 1 MiB payload). `tree_entries(root, *, with_data=False)` hands back each
+  file's bytes (read once, at most `MAX_TREE_BYTES = 256 MiB`) instead of its digest, so a digest
+  and a copy can be made from the same bytes.
 
 ## `dotagents._activate`
 
@@ -342,6 +364,14 @@ started suspended until it is in the job) so nothing it started outlives it.
   `run_step(argv, *, cwd, env, timeout, capture=False, max_output=1 MiB) ->
   (status, stdout)`. `pycache_prefix(user_store) -> str` — where Python run for an
   overlay keeps bytecode (`<user store>/.cache/pycache`), never inside an overlay.
+  `which_in(name, path) -> Optional[str]` finds a program on the absolute directories of `path`,
+  never the current directory (Windows searches it first with `shutil.which`); `interpreter_command(...,
+  trusted=False)` with `trusted` looks for a Windows bash only via `find_bash_on`.
+  `run_hook(argv, *, cwd, env, timeout, stdin, max_output, max_stderr) -> dict` runs a hook
+  bounded: `stdin` written without waiting on the child, stdout kept to `max_output` (a run
+  that writes more is stopped: `too_large`), stderr kept to `max_stderr` and the rest read and
+  dropped, ended at `timeout` (`timed_out`), every process it started ended with it; returns
+  `exit`, `stdout`, `stderr`, `timed_out`, `too_large`, `not_run`, `seconds`.
 
 ## `dotagents._resources`
 
@@ -364,13 +394,14 @@ The package's own data; library code, importing nothing from `dotagents.cli`.
   install. The archive also holds the vendored duho and pathapi; `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`, `dotagents.cli.mcp`
+## Commands — `dotagents.cli.init`, `dotagents.cli.overlays`, `dotagents.cli.context`, `dotagents.cli.env`, `dotagents.cli.path`, `dotagents.cli.about`, `dotagents.cli.build_pyz`, `dotagents.cli.mcp`, `dotagents.cli.hook`
 
 One `duho` command class per command above; fields are the flags, `__call__()`
 returns the exit code.
 
 - `init.Init`; `overlays.Overlays` (umbrella) with `OverlayAdd`, `OverlayRemove`,
-  `OverlayList`, `OverlaySync`, `OverlayShow`; `context.Context` (`FORMATS =
+  `OverlayList`, `OverlaySync`, `OverlayShow`, `OverlayHooks`, `OverlayAllowHooks`,
+  `OverlayRevokeHooks`; `hook.Hook`; `context.Context` (`FORMATS =
   ("markdown", "system-reminder", "json")`); `env.Env`; `path.PathCmd`
   (`PATH_FORMATS = ("list", "native", "posix", "json")`); `build_pyz.BuildPyz`;
   `about.About`.
@@ -724,6 +755,9 @@ API:
   included, from before/after snapshots taken in one bash process (MSYS2 `*PATH`
   values converted back to Windows form). No bash, a failed `source` or an `exit`
   in the file → empty, with a warning.
+- `find_bash_on(path) -> Optional[str]` — a Windows bash for a hook, looked for only beside a `git` on `path`,
+  in the standard install dirs and as a `bash` on `path` (never `os.environ["PATH"]`, never the
+  working directory), proved MSYS2/Cygwin, not cached.
 - `find_bash(logger=None) -> Optional[str]` — the bash for plain env files, resolved
   once per process: `bash` on `PATH` on POSIX; on Windows Git's bash (beside `git`
   on `PATH`, then the standard install dirs, then `PATH`), accepted only if it is
@@ -879,6 +913,15 @@ API:
   derivable, for the runtime agent only (`{}` in a plain shell); never replaces a
   value in `environ` unless `explicit` names a known agent. `root` is unused.
 
+- `Agent.wire_overlay_hooks(dest, *, dry_run, logger, config_root=None)` — wire the
+  harness's own hooks to `dotagents hook` for the events the overlays installed in the
+  store `dest` have a hook for, and retract an entry no overlay uses any more; a no-op on
+  the base class. `ClaudeAgent` writes `settings.json` (user) or `settings.local.json`
+  (project) with a bash entry per event and, on Windows, a PowerShell one that selects itself
+  when there is no Git Bash; `CodexAgent` writes the user `hooks.json` (with
+  `commandWindows`). `init -g` and `overlays add/sync/remove` call it; the entries are
+  labelled `dotagents: Overlay hooks: <native event>` and run `overlay_hook.py`.
+
 ## `dotagents._merge`
 
 Marker lines (a marker counts only on a line of its own, outside fenced code):
@@ -911,6 +954,109 @@ Marker lines (a marker counts only on a line of its own, outside fenced code):
 - `timestamped_backup_root(dest) -> Path` — `<dest>/install_backup/<timestamp>`, one
   per store per process.
 
+## `dotagents._overlay_hooks`
+
+Firing overlay hooks (the model is `dotagents._aos`; the user-facing page is
+`docs/guide/overlay-hooks.md`). A hook is the overlay's code: it runs only while its
+overlay's tree digest is the one the user allowed, as an argv list with the overlay root as
+its directory, bounded by `LIMITS`.
+
+- `LIMITS` (`DEFAULT_HOOK_LIMITS`, a copy tests may change), `NO_HARNESS = "dotagents"`,
+  `class Harness` (`id`, `native`: AOS event → native name, `applies`: event → outputs
+  dotagents can apply, `reasons`, `fires`), `CLAUDE`, `CODEX`, `ANYWHERE` (no
+  harness known: nothing reported as unfireable), `HARNESSES`, `harness_of(ident) -> Harness`
+  (an unknown id fires only `pre-env`), `partial_events(harness)`.
+- Settings, read from the user's own store only (never an overlay or a project):
+  `SETTING_BOUNDS` (`timeout`, `event_timeout`, `deadline`, `max_output`, `max_payload`, each
+  with its bounds), `settings_path(user_store)` (`overlays/.dotagents-state/hooks-settings.json`),
+  `read_settings`, `limits_for(user_store)` (`LIMITS` under them), `deadline_for` (default
+  `DEFAULT_DEADLINE = 150` s for everything a hook entry does, from the process's start),
+  `entry_timeout(user_store)` (the harness's own timeout for the entry: deadline + 20 s, at
+  most `ENTRY_TIMEOUT_CAP = 600`).
+- Allowances, in the user store only, keyed by the overlay's store and name:
+  `allowances_path(user_store)`, `read_allowances`, `allowed_digest(user_store, identity,
+  store=None)`, `allow(user_store, identity, digest, store=None)`, `revoke(...) -> bool`.
+- `install_notice(overlay, user_store) -> Optional[str]` — the line `overlays add/sync` logs
+  when an overlay has hooks that are off;
+- `read_tree(overlay, keep=False) -> (digest, files)` (the bytes the digest covers when `keep`),
+  `snapshot(user_store, overlay, digest, files) -> Path` — the copy a hook runs from, one directory
+  per digest under `<user store>/.cache/hook-snapshots/` made from exactly the bytes hashed (what
+  `AOS` excludes from a digest, `node_modules` and `__pycache__` included, is not in it) and
+  hashed again before an existing one is reused; others go after `SNAPSHOT_MAX_AGE` (7 days) unused;
+  `SnapshotOverlay(path, live)` — an overlay read from its snapshot (manifest, files, paths,
+  scripts), whose `state_dir`, `preparation_path` and `install_record_path` are the live overlay's;
+  `overlay_plan(..., keep_tree=True)` makes the snapshot and plans from its manifest
+  (`plan["snap"]`), so env scripts, paths and the cwd are the hashed bytes; `PYTHON_BOOT` runs a
+  Python hook under `-I` with the libraries explicit; `project_roots(environ, cwd)` — where the agent
+  works, for `clean_path(path, user_store, roots)`; `fresh_digest(overlay)` (never memoized),
+  `overlay_plan(overlay, harness, user_store) ->
+  plan` (`hook_plan` plus `digest`, `identity`), `declares_guard(overlay)`,
+  `refusal(overlay) -> Optional[str]` (a guard that is off keeps its overlay out of
+  `_activate.active`), `planned(overlays, harness, user_store)`, `has_live_pre_env(scope,
+  harness_id)` (`env --cache` is not replayed for it).
+- `class Subject`, `execute(subject, event, payload, env, *, limits=None) -> run`,
+  `printable(data, bound=4096)` (stderr made fit for a log), `class Fired` (`result`, `reports`,
+  `errors`: what each hook wrote to standard error, for the log, `decision`), `session_id(harness, native_id)` (a hash,
+  never the harness's id), `value_for_match`, `fire(event, facts, plans, harness, *,
+  environment, limits=None) -> Fired`, `unsupported_reports(plans)`, `describe(report)`,
+  `pre_env(plans, session, base, harness, *, cwd=None) -> (reports, non_defaults)`.
+- Wiring: `STATUS_PREFIX`, `FORWARDER = "overlay_hook.py"`, `wanted_events(store, harness) ->
+  {event: guarded}`, `level_token(dest, user_store)` (`user` or `project-<hash>`: the only thing
+  in an entry's text besides the harness and the event), `sh_quote` / `ps_quote` (single-quote a
+  path for bash / PowerShell), `code_root()`, `forwarder_record(user_store, guards)`,
+  `record_path`, `write_record`, `remove_record`, `interpreter_problem(config_dir, token)` (the
+  recorded interpreter or dotagents is gone). The forwarder and its record live in the user's
+  harness config directory only; the entry runs `<python> -I <forwarder> <harness> <event>
+  <token>`.
+- `TOKEN_FORM` / `valid_token(token)` — a store token is `user` or `project-` and ten hex digits,
+  checked before it is part of a path; `clean_path(path, user_store)` — a `PATH` without relative
+  entries, any store's or overlay's `bin` or a venv, which is where hook and env-script
+  interpreters (`pwsh`, `node`) are found; `shadowed_with_hooks(scope)` — the user's overlays
+  with a hook that a nearer store's same-named folder hides (they still fire at `pre-env`).
+- Sessions: `KEEP_PROJECT` (the project's own names, `AGENTS_PROJECT_ROOT` and
+  `CLAUDE_PROJECT_DIR`, that `session_base` leaves alone), `session_base(environ)` — the environment a hook starts from: what `dotagents
+  launch` recorded in `AGENTS_SESSION_BASE` (each changed name's earlier value, null if unset)
+  undone, and the harness's own variables (`CLAUDE_ENV_FILE`, `CLAUDE_CODE_*`, `CODEX_*`)
+  dropped; `log_path`, `log_errors(user_store, errors)` and `LOG_LIMIT` — a hook's standard
+  error goes to `<user store>/.cache/hooks.log`, never to the harness.
+
+## `dotagents._hook_main`
+
+The fixed entry the hook forwarder runs, in place of the `dotagents` command line: it discovers
+no command and adds no library (discovery reads what the project's `.agents` holds). `main(argv)`
+takes `EVENT --harness H --level user|project --agents-dir DIR --nonce N`, builds the scope
+(:func:`dotagents._hook_dispatch.scope_for`) and prints one JSON object, `{"nonce": N,
+"answer": <text for the harness>}`; the forwarder accepts nothing that does not carry its nonce.
+
+## `dotagents._hook_dispatch`
+
+The program a harness's own hook runs (`dotagents hook`). Nothing a hook printed reaches the
+harness: the answer is built from the output that was accepted, and can only deny, ask or
+block.
+
+- `scope_for(level, user_store)` — the scope a hook of `level` is looked for in: `user` has no
+  project store in it (nothing a project holds can shadow a user hook, add commands or
+  libraries, or choose the Python); `dispatch(..., shadow_scope=None)` reports, at session start,
+  the user hooks a project folder of the same name hides (`hook-shadowed`).
+- `MAX_NATIVE`, `tool_kind(harness, name) -> kind` (a tool not placed is `other`, which runs
+  every hook of its event), `facts_of(harness, event, native) -> known`, `context_text(parts)`
+  (each part inside a marker with a nonce chosen after the hooks ran),
+  `write_env_block(path, label, changes)` (single-quoted values of validated names into
+  Claude's env file; the file is split at line feeds only and a value holding any of
+  `LINE_SEPARATORS` is refused, `env_file_safe(changes)`), `hook_environment(scope, overlay,
+  environ)` (the overlay's process environment from `session_base`, with the user store's Python,
+  never a project's venv), `answer(harness, event, fired, env_file) -> (stdout, stderr)`,
+  `refusal_answer(harness, event, why)`, `plans_for(scope, harness, level, event=None)`,
+  `dispatch(harness_id, event, stdin, scope, level, environ) ->
+  (stdout, stderr)`.
+
+## `dotagents.cli.hook`
+
+`Hook` — the `hook` command (see the command table). Packaged beside the harness's hook
+configuration by `init`: `_overlay/dotagents/hooks/overlay_hook.py`, the forwarder that finds
+`dotagents`, runs `dotagents hook` with the payload, and answers a refusal itself when it
+cannot (`--guard`).
+
 ## `dotagents._hooks`
 
 Settings schema (Claude Code and Codex): `hooks.<Event>` is a list of matcher
@@ -919,10 +1065,10 @@ objects `{"matcher"?: str, "hooks": [{"type": "command", "command": str, ...}]}`
 - `STATUS_PREFIX = "dotagents: "` — our hooks' `statusMessage` is
   `STATUS_PREFIX + label`; that label is the hook's identity.
 - `build_hook_entry(command, *, matcher=None, status_message=None, shell=None,
-  command_windows=None) -> dict` — one matcher object; `None` keys omitted;
+  command_windows=None, timeout=None) -> dict` — one matcher object; `None` keys omitted;
   `command_windows` is written as `commandWindows`.
 - `merge_hook(existing, command, *, matcher=None, status_message=None, shell=None,
-  command_windows=None) -> tuple[list, bool]` — `(entries, changed)`. An identical
+  command_windows=None, timeout=None) -> tuple[list, bool]` — `(entries, changed)`. An identical
   entry is kept; ours in another shape (same status label, or the bare label on a
   command running dotagents) is refreshed in place, keeping keys the user added;
   duplicates dropped; foreign and malformed entries kept verbatim; a foreign hook

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/src/dotagents/__init__.py

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

{dotagents_cli-0.9.1 → dotagents_cli-0.9.2}/src/dotagents/_activate.py

@@ -111,6 +111,11 @@ def refusal(overlay: Any, *, prepared: bool = True) -> "Optional[str]":
         foreign = _aos.foreign_entries(overlay.path)
         if foreign:
             return "its copy holds %s, which is not part of the overlay" % ", ".join(foreign[:5])
+    from dotagents import _overlay_hooks
+
+    held = _overlay_hooks.refusal(overlay)
+    if held is not None:
+        return held
     try:
         needs = needs_preparation(overlay)
     except _aos.Refused as refused: