boost-skill-cli 1.2.144__tar.gz → 1.2.145__tar.gz

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -70,6 +70,7 @@ GTM
 gzip
 gzipped
 hardcode
+hardcoded
 Helm
 hotspots
 Huashu
@@ -148,9 +149,11 @@ setuptools
 SHAs
 Shopify
 Sigstore
+snake_case
 Snyk
 SonarCloud
 stderr
+stdin
 Stdlib
 stdlib
 stdout

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/CLAUDE.md

@@ -542,9 +542,9 @@ nothing. Consequences for code you write:
     `workflows` flag exists and `agents.workflow_agents()` is the set that
     honours it. `~/.codex/rules/*.rules` is the `execpolicy` command-approval
     DSL, not an instructions dir — don't write there. Its **MCP host is wired
-    up** (`core/mcphost.py`, fourth row — see below); its **hooks** host is
-    not, because the hook `timeout` units are unestablished, so this file does
-    not record it as done.
+    up** (`core/mcphost.py`, fourth row — see below) and so is its **hooks**
+    host (`core/hookhost.py`, third row — the `timeout` units this file used
+    to record as unestablished are **seconds**, measured; see below).
   - **Its dir is the one agent path that is not fixed**, hence the
     `${CODEX_HOME:-~/.codex}/skills` default and `paths.expand`'s leading
     `${VAR:-fallback}` syntax. Only a *leading* reference expands and nesting
@@ -667,14 +667,14 @@ nothing. Consequences for code you write:
   no-op against a user-scope entry, and Claude, which needs none, is handed one
   so the argv cannot reach `<cwd>/.mcp.json`, the one scope outside every
   `$HOME` and so the one `mcphost.escapes_home` cannot judge.
-- **`core/hookhost.py` is the same idea for hooks, and two hosts have them.**
+- **`core/hookhost.py` is the same idea for hooks, and three hosts have them.**
   `boost hooks` writes Claude Code's `~/.claude/settings.json` (the default,
-  unchanged) or, behind `--host gemini`, the `~/.gemini/settings.json` that
-  Gemini CLI reads;
+  unchanged), or behind `--host` the `~/.gemini/settings.json` that Gemini CLI
+  reads or the `$CODEX_HOME/hooks.json` that Codex CLI reads;
   `core/claude_settings.py` takes `host=` throughout and asks the table for the
   differences. The `hooks` key and the `{matcher, hooks: [{type, command,
-  timeout}]}` block shape are *identical* between them, which is exactly what
-  makes the three real differences easy to ship wrong:
+  timeout}]}` block shape are *identical* across all three, which is exactly
+  what makes the real differences easy to ship wrong. Gemini's three:
   - **`timeout` units.** Claude's is **seconds**; Gemini's is **milliseconds**
     (`DEFAULT_HOOK_TIMEOUT = 6e4`, fed straight to `setTimeout`). Callers pass
     seconds and `hookhost.hook_entry` converts, so boost's `--timeout 10` is ten
@@ -701,6 +701,73 @@ nothing. Consequences for code you write:
   sources are named at the top of `hookhost.py` so the next person can re-check
   them against a newer release.
 
+  **Codex's four are different differences, and two of them are not about the
+  block at all.** Measured against Codex CLI 0.156.1 on 2026-09-27, from four
+  sources named at the top of `hookhost.py` (`codex app-server
+  generate-json-schema`; `strings` over the binary the ChatGPT app ships;
+  observed `codex app-server` `hooks/list` runs; the 23 embedded draft-07
+  schemas its `schema_loader.rs` reads):
+  - **The filename is `hooks.json`**, not `settings.json` — the only host
+    where it is not, hence `hookhost.settings_file`. A `hooks` key in a
+    `settings.json` is a file Codex never opens, and nothing says so.
+  - **The user root moves.** `$CODEX_HOME` relocates it and a *relative* value
+    is honoured against the current directory — the measured grammar lives
+    once, in `mcphost.config_home`. The **project** root does not move: it is
+    the literal `<project>/.codex` whatever `CODEX_HOME` says. Because the
+    variable is ambient, `claude_settings.escaping_path` refuses a user-scope
+    write that lands outside this `$HOME` unless `--force` comes with it —
+    the same hole `test_mcp_install_sandbox_home.py` closes for `mcp add`,
+    where a sandboxed `HOME` does not move `CODEX_HOME` and a test run wrote
+    into the developer's live `~/.codex`. The sweeps in `commands/bmad.py`
+    **skip** such a host with a warning rather than inheriting the refusal:
+    an aborted `bmad on` would leave Claude without its hooks either. So
+    `boost bmad` carries its own `--force`, and needs to: `bmad doctor` reads
+    the relocated file and reports the hook that will actually run, and
+    without the flag no `bmad` command could act on what `doctor` had just
+    reported. `_autopilot_on` resolves its host list **before** writing the
+    personas, because that resolution is the only step that can refuse and
+    refusing after `write_personas` left files on disk that
+    `_set_scope_state` never recorded.
+  - **`timeout` is in seconds**, agreeing with Claude and not Gemini. (Also
+    measured: `timeoutSec` is the *wire* spelling only — as a config key it is
+    ignored and the hook silently falls back to Codex's 600-second default.)
+  - **Event names are matched exactly, and an unknown one is dropped in
+    silence.** Twelve PascalCase events; `NotARealEvent` and `sessionstart`
+    each produced no hook, no warning and no error. So Codex is
+    `strict_events` in the table and `translate` returns `None` rather than
+    taking Gemini's warn-but-add fallthrough — the "looks installed and never
+    fires" failure this module exists to prevent. `CLAUDE_TO_CODEX` maps all
+    ten Claude events explicitly; only `Notification` has no counterpart
+    (Codex *has* both sub-agent events, which is why the refusal's "has no
+    sub-agents" clause is now a per-host `no_counterpart_note` rather than one
+    hardcoded sentence).
+
+  Two more Codex facts shape the writer rather than the block. A hook's trust
+  key is positional — `<sourcePath>:<event>:<group_index>:<handler_index>` —
+  so a re-add that drops a group and appends a new one re-keys every group
+  after it and voids the user's trust grant on each (measured: an untouched
+  neighbour moved `:0:0` -> `:1:0`). `add_hook` therefore **replaces in
+  place**, for every host: shuffling a file boost does not own was never a
+  feature, only never load-bearing. And a new hook does not run until the user
+  trusts it at startup, with project scope also needing `trust_level =
+  "trusted"` — `commands/hooks.py` says so after a Codex add, because "added"
+  alone is true and useless.
+
+  **Hook stdin and stdout are schema-validated, and both schemas were read
+  rather than assumed.** Every event has an embedded pair,
+  `<event>.command.{input,output}`, each `"additionalProperties": false`. The
+  output side carries `hookSpecificOutput` -> `<Event>HookSpecificOutputWire`
+  with `additionalContext` and a required `hookEventName` pinned to that
+  event's PascalCase `const`, so `hookhost.context_output`'s Gemini-shaped
+  JSON is what Codex wants too — Claude's plain-text `SessionStart` shortcut
+  is the one thing that does not carry over. The input side uses Claude's
+  snake_case keys (`prompt`, `session_id`, `cwd`, `hook_event_name`) plus
+  Codex's own `model`/`permission_mode`/`turn_id`, so `bmad._read_hook_stdin`
+  needs no per-host branch. Both were worth measuring rather than inferring:
+  `_host_command` ends every non-Claude hook in `2>/dev/null || true`, so a
+  key spelled wrong on either side is a router that prints nothing, on every
+  prompt, with no error anywhere.
+
 `core/catalog.scan_dir` walks a tap's clone and classifies each file into one
 of the three item kinds (see Non-obvious rules above); `core/store.py` owns
 install, uninstall and sync — copying into the canonical store, symlinking into

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.144
+Version: 1.2.145
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -533,13 +533,15 @@ should show as Connected.
 
 ## Agent hooks and BMAD
 
-`boost hooks` manages hooks in `settings.json` for Claude Code and Gemini CLI,
+`boost hooks` manages hooks for Claude Code, Gemini CLI and Codex CLI —
+`settings.json` for the first two, `$CODEX_HOME/hooks.json` for Codex —
 translating between their event vocabularies and timeout units. `boost bmad on`
 uses them to put the BMAD Method's personas in charge of every task, in one
 command with no Node and no network.
 
 ```bash
 boost hooks add SessionStart -c 'echo hello' -n greet --scope project
+boost hooks add SessionStart --host codex -c 'echo hello' -n greet
 boost bmad on
 ```
 

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/README.md

@@ -491,13 +491,15 @@ should show as Connected.
 
 ## Agent hooks and BMAD
 
-`boost hooks` manages hooks in `settings.json` for Claude Code and Gemini CLI,
+`boost hooks` manages hooks for Claude Code, Gemini CLI and Codex CLI —
+`settings.json` for the first two, `$CODEX_HOME/hooks.json` for Codex —
 translating between their event vocabularies and timeout units. `boost bmad on`
 uses them to put the BMAD Method's personas in charge of every task, in one
 command with no Node and no network.
 
 ```bash
 boost hooks add SessionStart -c 'echo hello' -n greet --scope project
+boost hooks add SessionStart --host codex -c 'echo hello' -n greet
 boost bmad on
 ```
 

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.144'
-__version_tuple__ = version_tuple = (1, 2, 144)
+__version__ = version = '1.2.145'
+__version_tuple__ = version_tuple = (1, 2, 145)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/boost_cli/cli.py

@@ -129,7 +129,7 @@ COMMANDS = [
     ("schedule",    "cfg", "configuration", "Manage automatic skill-sync scheduling"),
     ("serve",       "cfg", "configuration", "Browse the catalogue in a browser: search, facets and a tap graph"),
     ("mcp",         "cfg", "configuration", "Register boost as an MCP server (Claude Code, Gemini CLI, Antigravity CLI, Codex CLI)"),
-    ("hooks",       "cfg", "hooks", "Manage agent hooks (Claude Code, Gemini CLI) in settings.json"),
+    ("hooks",       "cfg", "hooks", "Manage agent hooks (Claude Code, Gemini CLI, Codex CLI)"),
     ("bmad",        "cfg", "bmad", "BMAD Method autopilot — `bmad on` routes every task to a persona"),
     ("self-update", "cfg", "configuration", "Update boost itself to the latest version"),
     # Team & Collaboration (6)

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/boost_cli/commands/bmad.py

@@ -113,6 +113,10 @@ def cmd_bmad(argv) -> int:
                    help="enable the startup toggle right after install")
     p.add_argument("--plain", action="store_true",
                    help="route: print the banner as text, not as hook JSON")
+    p.add_argument("--force", action="store_true",
+                   help="reach hosts whose settings file lies outside this "
+                        "$HOME (a relocated $CODEX_HOME), which on/off/"
+                        "startup/uninstall/disable otherwise skip")
     p.add_argument("--host", metavar="H", default=None,
                    choices=(*hookhost.hosts(), "auto"),
                    help="on/startup: hosts to hook (%s; default auto: "
@@ -121,9 +125,9 @@ def cmd_bmad(argv) -> int:
     args = p.parse_args(argv)
 
     if args.action == "on":
-        return _autopilot_on(args.scope, args.host)
+        return _autopilot_on(args.scope, args.host, args.force)
     if args.action == "off":
-        return _autopilot_off(args.scope)
+        return _autopilot_off(args.scope, args.force)
     if args.action == "route":
         return _route(args.value, args.plain, args.scope, _one_host(args.host))
     if args.action == "personas":
@@ -133,13 +137,14 @@ def cmd_bmad(argv) -> int:
     if args.action == "init":
         return _init(args.modules, args.startup)
     if args.action == "startup":
-        return _startup(args.value or "status", args.scope, args.host)
+        return _startup(args.value or "status", args.scope, args.host,
+                        args.force)
     if args.action == "orient":
         return _orient(args.scope, _one_host(args.host))
     if args.action == "uninstall":
-        return _uninstall(args.scope, args.yes)
+        return _uninstall(args.scope, args.yes, args.force)
     if args.action == "disable":
-        return _disable(args.scope)
+        return _disable(args.scope, args.force)
     if args.action == "enable":
         return _enable(args.scope)
     return _doctor()  # doctor | status
@@ -187,7 +192,7 @@ def _one_host(host) -> str:
     return hookhost.CLAUDE if host in (None, "auto") else host
 
 
-def _hook_hosts(scope: str, requested=None) -> list[str]:
+def _hook_hosts(scope: str, requested=None, force: bool = False) -> list[str]:
     """Hosts to write hooks into: Claude always, others on evidence of use.
 
     Claude is unconditional. It is boost's primary host and the behaviour every
@@ -205,20 +210,55 @@ def _hook_hosts(scope: str, requested=None) -> list[str]:
 
     ``requested`` (`--host`) overrides the rule: naming one host writes that
     host only, so Claude-only no longer means hand-editing Gemini's settings
-    after every `on`.
+    after every `on`. It does **not** override the escape guard — naming a
+    host whose file lies outside this `$HOME` raises here, before the caller
+    has written anything, rather than from `add_hook` half a command later.
+    `--force` is what gets past it, on either path.
+
+    Resolved once per command and passed around, not recomputed per hook:
+    `on` installs two hooks, and a host list that decided itself twice said
+    "skipping Codex CLI" twice for one decision.
     """
     if requested not in (None, "auto"):
-        return [requested]
+        cs.refuse_escape(scope, str(requested), force=force)
+        return [str(requested)]
     chosen = [hookhost.CLAUDE]
     for host in hookhost.hosts():
         if host == hookhost.CLAUDE:
             continue
         dotdir = cs.settings_path(scope, host=host).parent
-        if shutil.which(hookhost.cli(host)) or dotdir.is_dir():
-            chosen.append(host)
+        if not (shutil.which(hookhost.cli(host)) or dotdir.is_dir()):
+            continue
+        # After the evidence check: warning about a host that was never a
+        # candidate is noise, and it is the only thing this warning is for.
+        if _skip_escaping(scope, host, force):
+            continue
+        chosen.append(host)
     return chosen
 
 
+def _skip_escaping(scope: str, host: str, force: bool = False) -> bool:
+    """True — and says so — when `host`'s file lies outside this `$HOME`.
+
+    `bmad on`/`off` sweep every host they find, so one host boost must not
+    write is a reason to leave that host alone, not to abort the sweep: an
+    unguarded `add_hook` raises and Claude's hook never gets installed either.
+
+    The deliberate case is `--force`, on `bmad` itself and not only on `boost
+    hooks`. Without it here, `bmad doctor` could report a hook in a relocated
+    `$CODEX_HOME` — it reads what will actually run — that `bmad off` then
+    refused to remove, with nothing in the command able to reconcile the two.
+    """
+    if force:
+        return False
+    target = cs.escaping_path(scope, host)
+    if target is None:
+        return False
+    out.warn("skipping %s — %s is outside this $HOME"
+             % (hookhost.label(host), target), wrap=True)
+    return True
+
+
 #: (Claude event, hook name, matcher). The matcher is Claude's own
 #: `SessionStart` source vocabulary, and `hookhost` deliberately does not
 #: translate matchers — they pass through host-native — so it is applied only
@@ -243,11 +283,16 @@ def _host_command(host: str, command: str) -> str:
 
 
 def _add_hook_everywhere(scope: str, spec: tuple, command: str,
-                         requested=None) -> list[str]:
-    """Install one hook on every chosen host. Returns the hosts written."""
+                         hosts: list[str], force: bool = False) -> list[str]:
+    """Install one hook on each of `hosts`. Returns the ones written.
+
+    Takes the list rather than resolving it, because resolving it is where
+    the escape guard and its warning live and a caller installing two hooks
+    must make that decision once.
+    """
     event, name, matcher = spec
     written = []
-    for host in _hook_hosts(scope, requested):
+    for host in hosts:
         target = hookhost.translate(host, event)
         if target is None:
             # Refused out loud rather than dropped: a hook the user asked for
@@ -257,12 +302,13 @@ def _add_hook_everywhere(scope: str, spec: tuple, command: str,
             continue
         cs.add_hook(scope, target, name, _host_command(host, command),
                     matcher=matcher if host == hookhost.CLAUDE else None,
-                    host=host)
+                    host=host, force=force)
         written.append(host)
     return written
 
 
-def _remove_hook_everywhere(scope: str, *specs: tuple) -> int:
+def _remove_hook_everywhere(scope: str, *specs: tuple,
+                            force: bool = False) -> int:
     """Remove hooks from every host, installed or not. Returns how many were.
 
     Unlike install this does not filter on `shutil.which`: someone who removed
@@ -273,21 +319,30 @@ def _remove_hook_everywhere(scope: str, *specs: tuple) -> int:
     """
     removed = 0
     for host in hookhost.hosts():
+        if _skip_escaping(scope, host, force):
+            continue
         for event, name, _matcher in specs:
             target = hookhost.translate(host, event)
             if target is not None:
-                removed += cs.remove_hook(scope, target, name, host=host)
+                removed += cs.remove_hook(scope, target, name, host=host,
+                                          force=force)
     return removed
 
 
-def _autopilot_on(scope, requested_host=None) -> int:
+def _autopilot_on(scope, requested_host=None, force: bool = False) -> int:
     """The one command. Personas + orientation + router, in one idempotent pass.
 
     Global by default: the point of the autopilot is that a task arriving in
     *any* repo already knows which persona owns it, and per-project setup would
     make that a per-repo chore.
+
+    The host list is resolved **first**, before anything is written. It is the
+    only step that can refuse — a `--host` whose settings file lies outside
+    this `$HOME` — and refusing after `write_personas` left persona files on
+    disk that `_set_scope_state` never got to record.
     """
     scope = scope or "global"
+    chosen = _hook_hosts(scope, requested_host, force)
     agents = _agents_dir(scope)
     # Asked before writing: whether this run *creates* the directory decides
     # what running sessions can see (see the restart line below).
@@ -302,10 +357,10 @@ def _autopilot_on(scope, requested_host=None) -> int:
     launcher = shlex.quote(str(paths.launcher()))
     hosts = _add_hook_everywhere(
         scope, _ORIENT_HOOK, "%s bmad orient --scope %s" % (launcher, scope),
-        requested_host)
+        chosen, force)
     _add_hook_everywhere(scope, _ROUTE_HOOK,
                          "%s bmad route --scope %s" % (launcher, scope),
-                         requested_host)
+                         chosen, force)
     _set_scope_state(scope, autopilot=True, startup=True, personas=present,
                      enabled_at=util.now_iso())
     journal.log("bmad-autopilot", "on", scope=scope, personas=present)
@@ -335,9 +390,10 @@ def _autopilot_on(scope, requested_host=None) -> int:
     return 0
 
 
-def _autopilot_off(scope) -> int:
+def _autopilot_off(scope, force: bool = False) -> int:
     scope = scope or "global"
-    hooks_removed = _remove_hook_everywhere(scope, _ORIENT_HOOK, _ROUTE_HOOK)
+    hooks_removed = _remove_hook_everywhere(scope, _ORIENT_HOOK, _ROUTE_HOOK,
+                                            force=force)
     removed = core.remove_personas(_agents_dir(scope))
     _set_scope_state(scope, autopilot=False, startup=False, personas=0)
     journal.log("bmad-autopilot", "off", scope=scope, personas=len(removed))
@@ -350,6 +406,15 @@ def _autopilot_off(scope) -> int:
 def _read_hook_stdin() -> dict:
     """Claude Code's UserPromptSubmit payload, or {} for anything unreadable.
 
+    One reader for every host, because the payload keys are the same on all
+    three. Measured for Codex, not assumed: its
+    ``user-prompt-submit.command.input`` schema requires ``prompt``,
+    ``session_id``, ``cwd`` and ``hook_event_name`` under exactly Claude's
+    snake_case spellings (plus ``model``/``permission_mode``/``turn_id`` of
+    its own). A different spelling would have reached ``_route`` as an empty
+    prompt, classified TRIVIAL, and printed nothing — silently, because
+    ``_host_command`` ends the hook in ``2>/dev/null || true``.
+
     Accepts plain text too, so `echo "add tests for the scanner" | boost bmad
     route` works for a human debugging the routing table. (Give it a real
     prompt: anything under `core.MIN_WORDS` words classifies as trivial and
@@ -632,12 +697,14 @@ def _drop_retired_skills(before: dict, installed: list[str],
 
 # ----------------------------------------------------------------------- toggle
 
-def _startup(value, scope, requested_host=None) -> int:
+def _startup(value, scope, requested_host=None, force: bool = False) -> int:
     scope = scope or "project"
     if value == "on":
         cmd = "%s bmad orient --scope %s" % (
             shlex.quote(str(paths.launcher())), scope)
-        started = _add_hook_everywhere(scope, _ORIENT_HOOK, cmd, requested_host)
+        started = _add_hook_everywhere(
+            scope, _ORIENT_HOOK, cmd,
+            _hook_hosts(scope, requested_host, force), force)
         _set_scope_state(scope, startup=True)
         journal.log("bmad-startup", "on", scope=scope)
         out.ok("BMAD startup ON (%s) — new sessions get orientation" % scope)
@@ -645,7 +712,7 @@ def _startup(value, scope, requested_host=None) -> int:
             out.dim("  hook → %s" % cs.settings_path(scope, host=host))
         return 0
     if value == "off":
-        _remove_hook_everywhere(scope, _ORIENT_HOOK)
+        _remove_hook_everywhere(scope, _ORIENT_HOOK, force=force)
         _set_scope_state(scope, startup=False)
         journal.log("bmad-startup", "off", scope=scope)
         out.ok("BMAD startup OFF (%s) — skills stay installed" % scope)
@@ -692,14 +759,14 @@ def _status(scope) -> int:
 
 # ------------------------------------------------------------------- teardown
 
-def _uninstall(scope, yes) -> int:
+def _uninstall(scope, yes, force: bool = False) -> int:
     scope = scope or "project"
     if not (yes or out.confirm(
             "Remove BMAD (%s)? deletes bmad-* skills%s" % (
                 scope, " + _bmad/, _bmad-output/" if scope == "project" else ""))):
         out.info("aborted")
         return 1
-    _remove_hook_everywhere(scope, _ORIENT_HOOK, _ROUTE_HOOK)
+    _remove_hook_everywhere(scope, _ORIENT_HOOK, _ROUTE_HOOK, force=force)
     removed = _rm_skills(_skills_dir(scope))
     removed += len(core.remove_personas(_agents_dir(scope)))
     if scope == "project":
@@ -714,10 +781,10 @@ def _uninstall(scope, yes) -> int:
     return 0
 
 
-def _disable(scope) -> int:
+def _disable(scope, force: bool = False) -> int:
     """Quarantine: turn startup off and move skills aside (recoverable)."""
     scope = scope or "project"
-    _remove_hook_everywhere(scope, _ORIENT_HOOK)
+    _remove_hook_everywhere(scope, _ORIENT_HOOK, force=force)
     qdir = _quarantine_dir(scope)
     qdir.mkdir(parents=True, exist_ok=True)
     moved = 0

{boost_skill_cli-1.2.144 → boost_skill_cli-1.2.145}/boost_cli/commands/hooks.py

@@ -1,23 +1,28 @@
 # Copyright the boost contributors.
 # SPDX-License-Identifier: Apache-2.0
-"""boost hooks — scope- and host-aware management of agent hooks in settings.json.
+"""boost hooks — scope- and host-aware management of agent hooks.
 
     boost hooks add SessionStart --command 'boost bmad orient' --name bmad \
         --scope global --matcher 'startup|resume|clear'
     boost hooks add PreToolUse --host gemini -c 'boost check' -n guard
+    boost hooks add SessionStart --host codex -c 'boost bmad orient' -n bmad
     boost hooks list
     boost hooks remove --name bmad
 
-Two hosts have hooks: Claude Code (`~/.claude/settings.json`, the default and
-unchanged) and Gemini CLI (`~/.gemini/settings.json`). What differs between
-them is a pure table in core/hookhost.py; this layer only picks a host, spells
-the event the way that host spells it, and reports what it did.
-
-Event names mostly differ, so `--host gemini` accepts either vocabulary and
-says which translation it applied. Two Claude events — SubagentStop and
-SubagentStart — have no Gemini counterpart at all, and are refused rather than
-silently dropped: a hook that looks installed and never fires is the failure
-mode worth being loud about.
+Three hosts have hooks: Claude Code (`~/.claude/settings.json`, the default and
+unchanged), Gemini CLI (`~/.gemini/settings.json`) and Codex CLI
+(`$CODEX_HOME/hooks.json` — a different filename, and a root the environment
+can move). What differs between them is a pure table in core/hookhost.py; this
+layer only picks a host, spells the event the way that host spells it, and
+reports what it did.
+
+Event names differ, so `--host` accepts either vocabulary and says which
+translation it applied. An event with no counterpart on the named host is
+refused rather than silently dropped — SubagentStop/SubagentStart on Gemini,
+Notification on Codex — and so is an *unrecognised* name on Codex, which
+matches keys exactly and ignores what it does not know without a word. A hook
+that looks installed and never fires is the failure mode worth being loud
+about.
 
 Only hooks boost created (tagged `# boost:<name>`) are ever touched; user hooks
 are left untouched. See core/claude_settings.py.
@@ -36,7 +41,8 @@ from ..errors import BoostError
 def cmd_hooks(argv) -> int:
     p = cliparse.parser(
         prog="boost hooks",
-        description="Manage agent hooks (scope- and host-aware) in settings.json")
+        description="Manage agent hooks (scope- and host-aware) in an agent's "
+                    "settings")
     p.add_argument("action", choices=("add", "remove", "list"),
                    help="add | remove | list")
     p.add_argument("event", nargs="?",
@@ -44,7 +50,7 @@ def cmd_hooks(argv) -> int:
                         "(required for add; filters remove/list)")
     p.add_argument("--host", metavar="H", default=None,
                    choices=(*hookhost.hosts(), "auto"),
-                   help="agent CLI whose settings.json to manage: %s "
+                   help="agent CLI whose hook settings to manage: %s "
                         "(default: claude for add/remove, all of them for list)"
                         % ", ".join(hookhost.hosts()))
     p.add_argument("-c", "--command", help="command the hook runs (add)")
@@ -57,6 +63,8 @@ def cmd_hooks(argv) -> int:
                    help="hook timeout in seconds (default: 10)")
     p.add_argument("--json", action="store_true", dest="as_json",
                    help="machine-readable output (list)")
+    p.add_argument("--force", action="store_true",
+                   help="write even when $CODEX_HOME points outside this $HOME")
     args = p.parse_args(argv)
 
     if args.action == "list":
@@ -132,13 +140,30 @@ def _where(host: str, scope: str) -> str:
 
 
 def _native_event(host: str, event: str) -> str:
-    """`event` as `host` spells it, saying so, or refusing if it cannot."""
+    """`event` as `host` spells it, saying so, or refusing if it cannot.
+
+    The two refusals are different problems and read differently. A *known*
+    Claude event with no counterpart is a gap in the host (`hookhost` says
+    which, per host — the note used to be a hardcoded "has no sub-agents",
+    which is Gemini's gap and not Codex's). An *unrecognised* name reaching
+    here at all means a `strict_events` host, where boost refuses because the
+    host would accept the write and never fire the hook.
+    """
     native = hookhost.translate(host, event)
     if native is None:
+        known = ", ".join(hookhost.events(host))
+        if event in hookhost.unmappable(host):
+            raise BoostError(
+                "'%s' has no %s counterpart" % (event, hookhost.label(host)),
+                hint="%s; its events are: %s"
+                     % (hookhost.no_counterpart_note(host), known))
         raise BoostError(
-            "'%s' has no %s counterpart" % (event, hookhost.label(host)),
-            hint="%s has no sub-agents; its events are: %s"
-                 % (hookhost.label(host), ", ".join(hookhost.events(host))))
+            "'%s' is not a known %s hook event"
+            % (event, hookhost.event_label(host)),
+            hint="%s matches an event name exactly and ignores one it does "
+                 "not know — with no warning and no error — so boost refuses "
+                 "rather than writing a hook that never fires. Its events "
+                 "are: %s" % (hookhost.label(host), known))
     if native != event:
         out.info("Claude's '%s' is %s's '%s' — using that"
                  % (event, hookhost.event_label(host), native))
@@ -163,16 +188,38 @@ def _add(args) -> int:
                  % (event, hookhost.event_label(host)))
     snapshot = cs.add_hook(scope, event, args.name, args.command,
                            matcher=args.matcher, timeout=args.timeout,
-                           host=host)
+                           host=host, force=args.force)
     journal.log("hook-add", args.name, scope=scope, event=event, host=host)
     out.ok("added %s hook '%s' (%s) → %s"
            % (event, args.name, _where(host, scope), args.command))
     out.dim("  settings: %s" % cs.settings_path(scope, host=host))
     if snapshot is not None:
         out.dim("  backup:   %s" % snapshot)
+    for line in _after_add(host, scope):
+        out.info(line, wrap=True)
     return 0
 
 
+def _after_add(host: str, scope: str) -> list[str]:
+    """What the user still has to do before this hook can run, if anything.
+
+    Empty for Claude and Gemini, which load a hook as soon as it is written.
+    Codex gates one behind a trust grant: an untrusted hook does not run, and
+    a project-scope one is not even listed until the repo itself is trusted —
+    `hooks/list` returns an empty list with no warning at all. Saying "added"
+    and nothing else would be true and useless.
+    """
+    if host != hookhost.CODEX:
+        return []
+    lines = ["Codex reviews new hooks at startup — it will ask you to trust "
+             "this one before it runs."]
+    if scope == "project":
+        lines.append("A project hook is also ignored until the repo is "
+                     "trusted (`trust_level = \"trusted\"` in "
+                     "$CODEX_HOME/config.toml).")
+    return lines
+
+
 def _remove(args) -> int:
     if not args.name:
         raise BoostError("hooks remove needs --name",
@@ -180,7 +227,8 @@ def _remove(args) -> int:
     scope = args.scope or "project"
     host = _write_host(args.host)
     event = _native_event(host, args.event) if args.event else None
-    removed = cs.remove_hook_by_name(scope, args.name, event, host=host)
+    removed = cs.remove_hook_by_name(scope, args.name, event, host=host,
+                                     force=args.force)
     journal.log("hook-remove", args.name, scope=scope, host=host)
     if removed:
         out.ok("removed %d hook(s) named '%s' (%s)"