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

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

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-11-11
+
+### Changed
+
+- Installing an overlay allows its hooks: `overlays add` and `overlays sync` allow the overlay's hooks
+  at the digest they install, for that store, and log which are on (event and script). Before, hooks
+  stayed off until `overlays allow-hooks` at a terminal. `--no-hooks` on both installs without
+  allowing, and a sync then leaves them off. A sync that changes the digest allows the new one, so
+  an overlay installed by 0.9.2 with its hooks off is allowed by its next `overlays sync`. A
+  `revoke-hooks` is remembered: syncs keep the hooks off until `allow-hooks` or a fresh `add`. An
+  install through the default `dotagents mcp` server allows like the command line. `allow-hooks` stays
+  (not an MCP tool, asks at the terminal) for overlays installed with `--no-hooks` or revoked.
+  `tools/cloud-setup.sh` no longer has a separate allow step.
+
+### Added
+
+- `dotagents mcp --strict`, and the user-store setting `overlays/.dotagents-state/mcp.json`
+  `{"strict": true}` (read only from the user store, for a server started by `DOTAGENTS_MCP`): an
+  `overlays add` or `sync` through a strict MCP server installs without allowing hooks, says they are
+  off and that `allow-hooks` turns them on, and writes no allowance.
+
 ## [0.9.2] - 2026-11-11
 
 ### Added
@@ -1793,7 +1814,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.2...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.9.3...HEAD
+[0.9.3]: https://github.com/jose-pr/dotagents/compare/v0.9.2...v0.9.3
 [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

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

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

@@ -217,6 +217,7 @@ 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 mcp --strict                     # serve MCP tools; an add/sync through it allows no hooks
 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)
 ```

{dotagents_cli-0.9.2 → dotagents_cli-0.9.3}/docs/guide/overlay-hooks.md

@@ -27,25 +27,47 @@ event takes, and answers the harness itself, in the harness's words. A `decision
 fails (`grant`) and nothing of it applies. dotagents never states an approval and never rewrites
 a tool's input.
 
-## Off until you allow them
+## Allowed by installing
 
 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:
+sandbox. Installing an overlay is choosing to trust it, hooks included: `overlays add` and
+`overlays sync` allow the overlay's hooks at the digest they install and log which are on (event and
+script). A sync that changes the digest allows the new one, since you chose the source.
 
 ```
+dotagents overlays add NAME [--no-hooks]            # installs, and allows the hooks unless --no-hooks
+dotagents overlays sync [NAME] [--no-hooks]
 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 revoke-hooks NAME                # off, and a sync keeps them off
+dotagents overlays allow-hooks NAME                 # shows the same and the digest, then asks at the terminal
 dotagents overlays allow-hooks NAME --digest sha256:...
-dotagents overlays revoke-hooks NAME
 ```
 
+`--no-hooks` installs without allowing them, and a later `sync` leaves them off (it is remembered
+like a revoke). `revoke-hooks` turns them off and a `sync` keeps them off until `allow-hooks` or a
+fresh `overlays add`. An overlay installed by 0.9.2, whose hooks were off, is allowed by its next
+`overlays sync`, unless it was revoked.
+
+Hooks run **outside the agent's sandbox**, with your access. An agent that can write the project's
+`.claude/` (its own `settings.local.json`) or your user store can run code outside its sandbox
+anyway, so a hook is nothing it could not already add: installing an overlay is the trust decision,
+and `dotagents overlays add` and `sync` make it once. The default `dotagents mcp` server behaves as
+the command line does, so an add or sync an agent asks for through it allows hooks too. Start it
+**`dotagents mcp --strict`** (or put `{"strict": true}` in `overlays/.dotagents-state/mcp.json` of
+your user store, which a server started by `DOTAGENTS_MCP` reads) for a stricter server: an add or sync
+through it installs without allowing hooks, says the hooks are off and that `allow-hooks` at a terminal
+turns them on, and records nothing (what you allowed before stays allowed at its digest). The setting
+is read from the user store only; a project's files cannot make a server strict or lax.
+
 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.
+in an overlay or a project, per overlay and store. There is one digest per overlay: a change to the
+overlay that did not come through `overlays sync` or `add` (a hand edit, an update by other means)
+turns its hooks off until you allow the new digest, 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, and one that can run `dotagents overlays add` through a shell
+tool installs and allows as you would.
 
 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

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

@@ -85,8 +85,6 @@ 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
 ```
 

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

@@ -53,6 +53,7 @@ and an error saying a command is required, and exits 2.
 | `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 add` / `overlays sync` `[--no-hooks]` | Besides installing, allow the overlay's hooks at the digest installed and log which are on (event, script); `--no-hooks` installs without allowing and remembers it. A sync that changes the digest allows the new one; hooks `revoke-hooks` turned off stay off across syncs until `allow-hooks` or a fresh `add`; an install made through the MCP tool allows nothing and says so. |
 | `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. |
@@ -63,7 +64,7 @@ and an error saying a command is required, and exits 2.
 | `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. The frontmatter is valid YAML (a value is double-quoted when it must be); `index --requote` fixes values written bare in existing files, touching nothing else. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
 | `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathapi-version V] [--extras a,b] [--with-pip]` | Build a zipapp from a source checkout; errors elsewhere. `--with-pip` vendors the pinned pip wheel (`_pipwheel`) as `dotagents/_vendor/`. |
-| `mcp [--prefix TEMPLATE]` | Serve command and active overlay MCP tools over stdio; `{name}` in the template is the skill or server name. |
+| `mcp [--prefix TEMPLATE] [--strict]` | Serve command and active overlay MCP tools over stdio (`--strict`, or the user store's `mcp.json` `{"strict": true}`: an `overlays add`/`sync` through it installs without allowing hooks); `{name}` in the template is the skill or server name. |
 
 **Every command but `env` and `mcp` is also an MCP tool.** `dotagents mcp` (or
 `DOTAGENTS_MCP=stdio dotagents`, the same server) serves the command set — built-in,
@@ -419,7 +420,7 @@ returns the exit code.
   `bundle_manifest() -> Optional[dict]`, `installed_packages() -> dict[str, str]`,
   `packages() -> tuple[dict[str, str], Optional[dict]]` (the bundle's packages, else
   the installed ones; the CLI itself in neither).
-- `mcp.Mcp` — `prefix: Optional[str]`; exits 2 when the template uses a placeholder
+- `mcp.Mcp` — `prefix: Optional[str]`, `strict: bool` (installs through it allow no hooks); exits 2 when the template uses a placeholder
   other than `{name}` or does not format to a tool-name segment.
 - `build_pyz`: `EXTRA_REQUIREMENTS` — `{extra: (requirement, ...)}`, what each
   dotagents-cli extra installs (`uri`, `http`, `mcp-http`, `sftp`, `s3`, `repo`),
@@ -976,8 +977,14 @@ its directory, bounded by `LIMITS`.
 - 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;
+- Installing allows: `record_install(user_store, overlay, *, fresh, no_hooks, dry_run=False) ->
+  (outcome, entries)` is what `overlays add` (`fresh=True`) and `overlays sync` do to the allowance
+  of the installed copy: `on` (allowed at the digest installed; a fresh add also forgets a revoke),
+  `declined` (`--no-hooks`, remembered), `strict` (`strict_mcp(user_store)`: a server started `dotagents mcp --strict`, or by `DOTAGENTS_MCP`
+  with the user's `mcp.json` `{"strict": true}`, installs without allowing and writes nothing; the
+  default server behaves as the command line; `mcp_settings_path`, `mcp_strict_setting` read the user
+  store only; `_MCP_STRICT` is the process flag), `revoked` (kept off across syncs), `none`; `read_revoked`,
+  `is_revoked`; `revoke` also records the revoke (the allowance file holds `allowed` and `revoked`).
 - `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

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

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

{dotagents_cli-0.9.2 → dotagents_cli-0.9.3}/src/dotagents/_overlay_hooks.py

@@ -195,12 +195,32 @@ def allowed_digest(user_store: "str | os.PathLike[str]", identity: str,
     return read_allowances(user_store).get(_key(user_store, identity, store))
 
 
-def _write_allowances(user_store: "str | os.PathLike[str]", allowed: "dict[str, str]") -> None:
+def read_revoked(user_store: "str | os.PathLike[str]") -> "set[str]":
+    """The overlays (by store and name) whose hooks the user turned off or declined at install: a
+    later sync does not allow them again; `allow-hooks` or a fresh `overlays add` does."""
+    try:
+        data = json.loads(allowances_path(user_store).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return set()
+    revoked = data.get("revoked") if isinstance(data, dict) else None
+    return {str(item) for item in revoked} if isinstance(revoked, list) else set()
+
+
+def _write_allowances(user_store: "str | os.PathLike[str]", allowed: "dict[str, str]",
+                      revoked: "Optional[set[str]]" = None) -> None:
     from dotagents._fs import write_text_lf
 
     path = allowances_path(user_store)
     path.parent.mkdir(parents=True, exist_ok=True)
-    write_text_lf(path, json.dumps({"allowed": dict(sorted(allowed.items()))}, indent=2) + "\n", atomic=True)
+    if revoked is None:
+        revoked = read_revoked(user_store)
+    write_text_lf(path, json.dumps({"allowed": dict(sorted(allowed.items())), "revoked": sorted(revoked)},
+                                   indent=2) + "\n", atomic=True)
+
+
+def is_revoked(user_store: "str | os.PathLike[str]", identity: str,
+               store: "Optional[str | os.PathLike[str]]" = None) -> bool:
+    return _key(user_store, identity, store) in read_revoked(user_store)
 
 
 def allow(user_store: "str | os.PathLike[str]", identity: str, digest: str,
@@ -208,19 +228,80 @@ def allow(user_store: "str | os.PathLike[str]", identity: str, digest: str,
     """Allow ``identity``'s hooks (of the overlay installed in ``store``, default the user store) at
     ``digest``, replacing the digest allowed before: there is one."""
     allowed = read_allowances(user_store)
-    allowed[_key(user_store, identity, store)] = digest.lower()
-    _write_allowances(user_store, allowed)
+    key = _key(user_store, identity, store)
+    allowed[key] = digest.lower()
+    _write_allowances(user_store, allowed, read_revoked(user_store) - {key})
 
 
 def revoke(user_store: "str | os.PathLike[str]", identity: str,
            store: "Optional[str | os.PathLike[str]]" = None) -> bool:
+    """Turn the overlay's hooks off and keep them off across syncs. True when that changed anything."""
     allowed = read_allowances(user_store)
-    if allowed.pop(_key(user_store, identity, store), None) is None:
+    key = _key(user_store, identity, store)
+    revoked = read_revoked(user_store)
+    if allowed.pop(key, None) is None and key in revoked:
         return False
-    _write_allowances(user_store, allowed)
+    _write_allowances(user_store, allowed, revoked | {key})
     return True
 
 
+def mcp_settings_path(user_store: "str | os.PathLike[str]") -> Path:
+    return Path(user_store) / "overlays" / ".dotagents-state" / "mcp.json"
+
+
+def mcp_strict_setting(user_store: "str | os.PathLike[str]") -> bool:
+    """The user's own setting ``{"strict": true}`` for the MCP server, read from the user store only
+    (never from a project, whose MCP configuration an agent can write)."""
+    try:
+        data = json.loads(mcp_settings_path(user_store).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    return isinstance(data, dict) and data.get("strict") is True
+
+
+#: Set by `dotagents mcp --strict` (or the user's setting): installs through this server allow no hooks.
+_MCP_STRICT: "list[bool]" = []
+
+
+def strict_mcp(user_store: "str | os.PathLike[str]") -> bool:
+    """Whether this process serves MCP tools in strict mode, chosen when the server was started: an
+    add or sync through it installs without allowing hooks, as ``--no-hooks`` does. The default server
+    behaves as the command line does."""
+    return bool(_MCP_STRICT) or (bool(os.environ.get("DOTAGENTS_MCP")) and mcp_strict_setting(user_store))
+
+
+def record_install(user_store: "str | os.PathLike[str]", overlay: Any, *, fresh: bool, no_hooks: bool,
+                   dry_run: bool = False) -> "tuple[str, list[dict[str, Any]]]":
+    """What installing or syncing ``overlay`` (the installed copy) does to its hooks' allowance.
+    Returns ``(outcome, entries)``: ``none`` (it has no hooks), or ``on`` (allowed at the digest it
+    holds, which is the digest installed), ``declined`` (``--no-hooks``: recorded so a later sync
+    does not allow them), ``strict`` (installed through a strict MCP server: nothing is allowed or recorded),
+    ``revoked`` (turned off earlier and kept off by a sync). A fresh add allows, and forgets an
+    earlier revoke. With ``dry_run`` nothing is written."""
+    plan = overlay_plan(overlay, ANYWHERE, user_store)
+    entries = plan["hooks"]
+    if not entries:
+        return "none", []
+    key = _key(user_store, overlay.name, overlay.store)
+    if strict_mcp(user_store) and not no_hooks:
+        # Installs without allowing and writes nothing: what was allowed stays allowed at its own digest.
+        return "strict", entries
+    if no_hooks:
+        if not dry_run and plan["digest"] and key not in read_revoked(user_store):
+            allowed = read_allowances(user_store)
+            allowed.pop(key, None)
+            _write_allowances(user_store, allowed, read_revoked(user_store) | {key})
+        return "declined", entries
+    if not fresh and key in read_revoked(user_store):
+        return "revoked", entries
+    if plan["digest"] is None:
+        return "declined", entries
+    if not dry_run:
+        allow(user_store, overlay.name, plan["digest"], overlay.store)
+    return "on", entries
+
+
+
 # --------------------------------------------------------------------------- #
 # What an overlay's hooks are on this machine, for a harness.
 # --------------------------------------------------------------------------- #
@@ -357,20 +438,6 @@ def _token() -> str:
     return secrets.token_hex(4)
 
 
-def install_notice(overlay: Any, user_store: "str | os.PathLike[str]") -> "Optional[str]":
-    """A line for an install or sync: the overlay has hooks and they are off until the user allows
-    them. None when it has none, or they are allowed at this digest."""
-    from dotagents import _activate
-
-    entries, _ = _aos.hooks_of(overlay.document(), _activate.files(overlay), _aos.current_os(),
-                               sorted(_activate.interpreters()))
-    if not entries or overlay_plan(overlay, ANYWHERE, user_store)["on"]:
-        return None
-    return ("overlay %s has hooks (%s); they are off until you allow them at its digest: "
-            "dotagents overlays hooks %s" % (overlay.name, ", ".join(entry["event"] for entry in entries),
-                                              overlay.name))
-
-
 def declares_guard(overlay: Any) -> bool:
     """Whether the overlay has a hook with ``on_failure = "refuse"``."""
     from dotagents import _activate

{dotagents_cli-0.9.2 → dotagents_cli-0.9.3}/src/dotagents/cli/mcp.py

@@ -19,7 +19,18 @@ class Mcp(LoggingArgs, Cmd):
     "Name prefix template for forwarded tools; `{name}` is the skill or server name."
     ("--prefix",)
 
+    strict: bool = False
+    "Strict mode: an add or sync through this server installs without allowing the overlay's hooks."
+    ("--strict",)
+
     def __call__(self) -> int:
+        from dotagents import _overlay_hooks
+        from dotagents._scope import resolve_user_store
+
+        # Chosen when the server starts: by the flag, or by the user's own setting in the user store
+        # (never a project's: an agent can write a project's MCP configuration).
+        if self.strict or _overlay_hooks.mcp_strict_setting(resolve_user_store()):
+            _overlay_hooks._MCP_STRICT.append(True)
         if self.prefix is not None:
             try:
                 sample = self.prefix.format(name="server")

{dotagents_cli-0.9.2 → dotagents_cli-0.9.3}/src/dotagents/cli/overlays.py

@@ -241,12 +241,6 @@ def _prepare(scope, dest_dir: Path, name: str, *, change: str, no_setup=False, d
     except _aos.Refused as refused:
         logger.error("%s: %s %s (hash every requirement or none)", name, refused.code, refused.subject)
         return 1
-    if change != "remove":
-        from dotagents import _overlay_hooks
-
-        note = _overlay_hooks.install_notice(overlay, scope.user_root)
-        if note:
-            logger.warning("%s", note)
     if variant is None and change != "remove":
         # A default setup.<ext> present that this machine cannot run.
         plan = _aos.plan(overlay.document(), _activate.context(overlay), pinned=True)
@@ -543,9 +537,34 @@ def _log_install(logger, verb: str, name: str, result, dry_run: bool) -> None:
         logger.info("overlay %s: backed up %s", name, ", ".join(result.backed_up))
 
 
+def _record_hooks(scope, dest: Path, name: str, *, fresh: bool, no_hooks: bool, dry_run: bool, logger) -> None:
+    """Installing or syncing an overlay allows its hooks at the digest installed (the person chose
+    this source, and the overlay declares them), and says which are on. ``--no-hooks`` installs
+    without allowing and remembers it; an overlay whose hooks were revoked stays off across syncs;
+    a request through the MCP tool allows like any other, unless the server was started `--strict`
+    (or the user's own setting says so), when it installs without allowing."""
+    from dotagents import _overlay_hooks
+    from dotagents._overlays import Overlay
+
+    overlay = Overlay(dest if dest.is_dir() else dest, scope.agents_root)
+    outcome, entries = _overlay_hooks.record_install(scope.user_root, overlay, fresh=fresh, no_hooks=no_hooks,
+                                                     dry_run=dry_run)
+    if outcome == "none":
+        return
+    listed = ", ".join("%s (%s)" % (e["event"], e["path"] or "no hook.<ext> can run here") for e in entries)
+    if outcome == "on":
+        logger.info("overlay %s: %s its hooks, now on: %s (dotagents overlays hooks %s; revoke-hooks turns them off)",
+                    name, "would allow" if dry_run else "allowed", listed, name)
+    else:
+        why = {"declined": "--no-hooks", "revoked": "they were revoked and a sync keeps them off",
+               "strict": "installed through `dotagents mcp --strict`, which allows no hooks"}[outcome]
+        logger.warning("overlay %s: its hooks are off (%s): %s -- allow them with `dotagents overlays "
+                       "allow-hooks %s`", name, why, listed, name)
+
+
 def _install_one(scope, name: str, src: Path, origin, *, copy: bool, no_setup: bool,
                  dry_run: bool, logger, setup_timeout: "Optional[int]" = None,
-                 no_venv: bool = False, cache=None) -> "list[str]":
+                 no_venv: bool = False, cache=None, no_hooks: bool = False) -> "list[str]":
     """Install (or re-install) overlay ``name`` from ``src`` into the scope,
     publish its skills, install its Python dependencies into the scope's venv
     and run its setup (``install`` the first time, then ``sync``). Nothing is written for a source
@@ -634,6 +653,8 @@ def _install_one(scope, name: str, src: Path, origin, *, copy: bool, no_setup: b
                 "was last prepared for (fix it and run `overlays sync %s`)", what, name, name,
             )
         raise SystemExit("error: %s for overlay %r failed (exit %d)" % (what, name, rc))
+    _record_hooks(scope, dest if dest.is_dir() else src, name, fresh=True, no_hooks=no_hooks, dry_run=dry_run,
+                  logger=logger)
     return skills
 
 
@@ -737,6 +758,10 @@ class OverlayAdd(_RepoArgs):
     "Skip running an overlay's declared `setup` after install."
     ("--no-setup",)
 
+    no_hooks: bool = False
+    "Do not allow the overlay's hooks (installing allows them at the digest installed; `allow-hooks` does it later)."
+    ("--no-hooks",)
+
     setup_timeout: Optional[int] = None
     "Seconds setup may run (default: the setup variant's timeout, else 300; 0 = no limit)."
     ("--setup-timeout",)
@@ -805,7 +830,7 @@ class OverlayAdd(_RepoArgs):
                         scope, name, src, origin, copy=self.copy, no_setup=self.no_setup,
                         dry_run=self.dry_run, logger=self._logger_,
                         setup_timeout=self.setup_timeout, no_venv=self.no_venv,
-                        cache=source.cache,
+                        cache=source.cache, no_hooks=self.no_hooks,
                     )
                 except (SystemExit, OSError) as exc:
                     why = str(exc.code if isinstance(exc, SystemExit) else exc)
@@ -1273,6 +1298,10 @@ class OverlaySync(_RepoArgs):
     "Skip running each overlay's declared `setup` after sync."
     ("--no-setup",)
 
+    no_hooks: bool = False
+    "Do not allow the overlay's hooks (installing allows them at the digest installed; `allow-hooks` does it later)."
+    ("--no-hooks",)
+
     no_venv: bool = False
     "Do not create or update the scope's Python venv (overlay requirements, duho, the .pth layering)."
     ("--no-venv",)
@@ -1401,6 +1430,9 @@ class OverlaySync(_RepoArgs):
                     self._logger_.error("preparing overlay %s failed (exit %d); it is activated only for the "
                                         "digest it was last prepared for", name, rc)
                     failures.append(name)
+                else:
+                    _record_hooks(scope, dest_dir, name, fresh=False, no_hooks=self.no_hooks,
+                                  dry_run=self.dry_run, logger=self._logger_)
 
             # A `requires` added upstream: install what no store provides yet.
             have = frozenset(o.normalized_name for o in scope.overlays)
@@ -1425,7 +1457,7 @@ class OverlaySync(_RepoArgs):
                     skills += _install_one(
                         scope, dep, src, origin, copy=self.copy, no_setup=self.no_setup,
                         dry_run=self.dry_run, logger=self._logger_, setup_timeout=self.setup_timeout,
-                        no_venv=self.no_venv, cache=chain.cache,
+                        no_venv=self.no_venv, cache=chain.cache, no_hooks=self.no_hooks,
                     )
         finally:
             # Recompose over ALL installed overlays in (priority, name) order