agent-bios 0.16.0 → 0.17.0

package/compose/corpus_catalog.py

@@ -40,23 +40,59 @@ CLAUDE_HOOK_EVENTS = frozenset((
     "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart",
     "SubagentStop", "PreCompact", "PermissionRequest", "TeammateIdle",
     "TaskCompleted", "ConfigChange", "WorktreeCreate", "WorktreeRemove",
+    "Setup", "InstructionsLoaded", "UserPromptExpansion", "MessageDisplay",
+    "PermissionDenied", "PostToolBatch", "TaskCreated", "StopFailure",
+    "CwdChanged", "DirectoryAdded", "FileChanged", "PostCompact",
+    "PreModelSwitch", "PostModelSwitch", "Elicitation", "ElicitationResult",
 ))
+# Command-event vocabulary from the two hosts' hook references (2026-09-11).
+# Authoring accepts the union; compilation checks the selected host. A host-only
+# event stays authored and becomes unavailable on the other host, never renamed.
+CODEX_HOOK_EVENTS = frozenset((
+    "PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact",
+    "SessionStart", "SessionEnd", "UserPromptSubmit", "SubagentStart",
+    "SubagentStop", "Stop", "Interrupt",
+))
+HOOK_EVENTS_BY_HOST = {"claude": CLAUDE_HOOK_EVENTS, "codex": CODEX_HOOK_EVENTS}
+HOOK_EVENTS = CLAUDE_HOOK_EVENTS | CODEX_HOOK_EVENTS
 
 
 class CatalogError(ValueError):
     """A catalog cannot be compiled safely."""
 
 
-def validate_hook_binding(hook: Any) -> None:
+def validate_hook_binding(hook: Any, host: str | None = None) -> None:
     if not isinstance(hook, dict) or set(hook) != {"event", "matcher"}:
         raise CatalogError("hook binding must contain only event and matcher")
     event, matcher = hook.get("event"), hook.get("matcher")
-    if not isinstance(event, str) or event not in CLAUDE_HOOK_EVENTS:
-        raise CatalogError(f"unsupported Claude hook event {event!r}")
+    events = HOOK_EVENTS if host is None else HOOK_EVENTS_BY_HOST[host]
+    if not isinstance(event, str) or event not in events:
+        raise CatalogError(f"unsupported {host + ' ' if host else ''}hook event {event!r}")
     if not isinstance(matcher, str) or not matcher or any(char in matcher for char in "\n\r\x00"):
         raise CatalogError("hook matcher must be one non-empty line")
 
 
+def validate_native_hook_config(value: Any, host: str) -> None:
+    """Validate compiler-owned command registrations, not arbitrary host config."""
+    if not isinstance(value, dict):
+        raise CatalogError("native hooks must be an event mapping")
+    for event, groups in value.items():
+        if not isinstance(groups, list) or not groups:
+            raise CatalogError("native hook event must contain matcher groups")
+        for group in groups:
+            if not isinstance(group, dict) or set(group) != {"matcher", "hooks"}:
+                raise CatalogError("invalid native hook matcher group")
+            validate_hook_binding({"event": event, "matcher": group["matcher"]}, host)
+            handlers = group["hooks"]
+            if not isinstance(handlers, list) or not handlers:
+                raise CatalogError("native hook group must contain commands")
+            for handler in handlers:
+                if (not isinstance(handler, dict) or set(handler) != {"type", "command"}
+                        or handler["type"] != "command" or not isinstance(handler["command"], str)
+                        or not handler["command"] or "\x00" in handler["command"]):
+                    raise CatalogError("invalid native hook command")
+
+
 def _read_utf8(path: pathlib.Path) -> str:
     if path.is_symlink():
         raise CatalogError(f"symlink input is not a corpus member: {path}")
@@ -667,10 +703,10 @@ def _plugin_namespace(ref: str) -> str:
 def _native_hook_carrier(item: dict[str, Any]) -> tuple[str, dict[str, str]]:
     source = item.get("origin", {}).get("source_path")
     if item.get("kind") != "hook" or not isinstance(source, str):
-        raise CatalogError("event item has no installed Claude hook carrier provenance")
+        raise CatalogError("event item has no installed hook carrier provenance")
     matched = re.fullmatch(r"claude/hooks/([A-Za-z0-9][A-Za-z0-9._-]*\.py)", source)
     if not matched:
-        raise CatalogError("event item origin is not an installed Claude hooks/*.py carrier")
+        raise CatalogError("event item origin is not an installed canonical hooks/*.py carrier")
     member = f"hooks/{matched.group(1)}"
     if member not in item["members"]:
         raise CatalogError("event item no longer retains its installed hook entrypoint")
@@ -680,7 +716,7 @@ def _native_hook_carrier(item: dict[str, Any]) -> tuple[str, dict[str, str]]:
         raise CatalogError(f"native hook entrypoint is not valid Python: {exc.msg}") from exc
     binding = item.get("hook")
     if not isinstance(binding, dict):
-        raise CatalogError("event item has no registered Claude hook binding")
+        raise CatalogError("event item has no registered hook binding")
     return member, binding
 
 
@@ -716,9 +752,9 @@ def _assert_native_member_safety(item: dict[str, Any], carrier: str, surface: st
         raise CatalogError("delegated item must retain exactly its one agents/*.md carrier")
     for member in item["members"]:
         first = pathlib.PurePosixPath(member).parts[0]
-        if first in {"skills", "commands", ".claude-plugin"}:
+        if first in {"skills", "commands", ".claude-plugin", ".codex-plugin", ".mcp.json"}:
             raise CatalogError(f"native plugin member would auto-discover {member!r}")
-        if member == "hooks/hooks.json" or member == "settings.json":
+        if member in {"hooks/hooks.json", "hooks.json", "settings.json", "config.toml"}:
             raise CatalogError(f"native plugin member would override generated registration {member!r}")
         if first == "agents" and member != carrier:
             raise CatalogError(f"native plugin member adds an unselected agent carrier {member!r}")
@@ -736,15 +772,19 @@ def _write_plugin_manifest(root: pathlib.Path, namespace: str, item: dict[str, A
     return relative.as_posix()
 
 
-def _emit_native_claude_item(
+def _emit_native_item(
     item: dict[str, Any], destination: pathlib.Path, namespace: str, base_instruction_text: str,
+    host: str, reference_root: pathlib.Path,
 ) -> tuple[list[str], dict[str, Any] | None]:
     root = destination / "items" / _safe_ref_path(item["ref"])
     if item["surface"] == "event":
         member, binding = _native_hook_carrier(item)
+        validate_hook_binding(binding, host)
         _assert_native_member_safety(item, member, "event")
-        emitted = [_write_plugin_manifest(root, namespace, item)]
-        command = f'{shlex.quote(sys.executable)} "${{CLAUDE_PLUGIN_ROOT}}/{member}"'
+        emitted = [_write_plugin_manifest(root, namespace, item)] if host == "claude" else []
+        reference = reference_root / "items" / _safe_ref_path(item["ref"]) / member
+        target = f'"${{CLAUDE_PLUGIN_ROOT}}/{member}"' if host == "claude" else shlex.quote(str(reference))
+        command = f'{shlex.quote(sys.executable)} {target}'
         hooks = {"hooks": {binding["event"]: [{
             "matcher": binding["matcher"],
             "hooks": [{"type": "command", "command": command}],
@@ -752,8 +792,11 @@ def _emit_native_claude_item(
         relative = pathlib.PurePosixPath("hooks") / "hooks.json"
         _write_private(root / relative, json.dumps(hooks, ensure_ascii=False, separators=(",", ":")) + "\n")
         emitted.append(relative.as_posix())
-        return emitted, {"ref": item["ref"], "plugin": namespace, "hook": binding, "entrypoint": member}
+        return emitted, {"ref": item["ref"], "plugin": namespace, "hook": binding,
+                         "entrypoint": member, "hooks": hooks["hooks"]}
     if item["surface"] == "delegated":
+        if host != "claude":
+            raise CatalogError("native delegated adapter is unsupported for codex: authored Claude agent frontmatter requires a Codex agent projection")
         member, name = _native_agent_carrier(item)
         _assert_native_member_safety(item, member, "delegated")
         # Carrier validation happens before any plugin write. The child receives
@@ -764,11 +807,11 @@ def _emit_native_claude_item(
         emitted = [_write_plugin_manifest(root, namespace, item)]
         return emitted, {"ref": item["ref"], "plugin": namespace, "agent_name": name,
                          "route": f"{namespace}:{name}"}
-    raise CatalogError(f"unsupported native Claude surface {item['surface']!r}")
+    raise CatalogError(f"unsupported native surface {item['surface']!r}")
 
 
 def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host: str,
-                  native: bool = False) -> dict[str, Any]:
+                  native: bool = False, reference_root: pathlib.Path | None = None) -> dict[str, Any]:
     """Emit selected items into one private destination.
 
     ``host`` is currently a validation seam for adapters.  Claude and Codex use
@@ -782,6 +825,9 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
     if not isinstance(items, list):
         raise CatalogError("compiler requires an item list")
     destination = pathlib.Path(destination)
+    # Emit bytes into staging while quoting paths for their final location. A
+    # string replacement after shell/Python quoting cannot relocate all paths.
+    reference_root = pathlib.Path(reference_root) if reference_root is not None else destination
     if destination.exists() and destination.is_symlink():
         raise CatalogError(f"compiler destination must not be a symlink: {destination}")
     destination.mkdir(parents=True, exist_ok=True)
@@ -790,7 +836,7 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
     unresolved = [item["ref"] for item in normalized if item.get("content_conflict")]
     if unresolved:
         raise CatalogError(f"content_conflict: selected item needs reconciliation: {', '.join(unresolved)}")
-    rewrites = _resource_rewrites(normalized, destination)
+    rewrites = _resource_rewrites(normalized, reference_root)
     files: list[str] = []
     for item in normalized:
         emitted: dict[str, str] = {}
@@ -799,10 +845,10 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
             relative = pathlib.PurePosixPath("items") / _safe_ref_path(item["ref"]) / member
             target = _destination_path(destination, relative.as_posix())
             rewritten = _rewrite_resources(content, rewrites)
-            if native and host == "claude" and item["surface"] == "event":
+            if native and item["surface"] == "event":
                 rewritten = _rewrite_native_hook_guide(item, rewritten, rewrites)
             _write_private(target, rewritten)
-            emitted[member] = str(target)
+            emitted[member] = str(reference_root / relative)
             files.append(relative.as_posix())
         item["_emitted_members"] = emitted
 
@@ -822,7 +868,7 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
         instruction_parts.extend(_rewrite_resources(item["body"], rewrites).rstrip("\n") for item in always)
         instruction_parts.append("")
     if router_path is not None:
-        instruction_parts.append(f"Relevant procedures: {router_path}")
+        instruction_parts.append(f"Relevant procedures: {reference_root / 'router/relevant.md'}")
     if requested:
         instruction_parts.append("Requested procedures:")
         for item in requested:
@@ -834,6 +880,7 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
     assets: dict[str, Any] = {}
     plugin_names: dict[str, str] = {}
     plugin_roots: list[str] = []
+    hook_config: dict[str, list[dict[str, Any]]] = {}
     agent_routes: list[dict[str, str]] = []
     for item in normalized:
         if item["surface"] not in {"event", "delegated"}:
@@ -842,27 +889,29 @@ def compile_items(items: list[dict[str, Any]], destination: pathlib.Path, host:
             unavailable.append({"ref": item["ref"], "surface": item["surface"],
                                 "reason": f"native {item['surface']} consumption is disabled; opt in with --corpus-native"})
             continue
-        if host != "claude":
-            unavailable.append({"ref": item["ref"], "surface": item["surface"],
-                                "reason": f"native {item['surface']} adapter is unsupported for {host}"})
-            continue
         namespace = _plugin_namespace(item["ref"])
         prior = plugin_names.get(namespace)
         if prior is not None and prior != item["ref"]:
-            raise CatalogError(f"Claude plugin namespace collision: {prior} and {item['ref']}")
+            raise CatalogError(f"native namespace collision: {prior} and {item['ref']}")
         plugin_names[namespace] = item["ref"]
         try:
-            emitted, route = _emit_native_claude_item(item, destination, namespace, base_instruction_text)
+            emitted, route = _emit_native_item(item, destination, namespace, base_instruction_text, host, reference_root)
         except CatalogError as exc:
             unavailable.append({"ref": item["ref"], "surface": item["surface"], "reason": str(exc)})
             continue
         root_relative = (pathlib.PurePosixPath("items") / _safe_ref_path(item["ref"])).as_posix()
-        plugin_roots.append(root_relative)
+        if host == "claude":
+            plugin_roots.append(root_relative)
+        else:
+            for event, groups in route["hooks"].items():
+                hook_config.setdefault(event, []).extend(groups)
         files.extend((pathlib.PurePosixPath(root_relative) / path).as_posix() for path in emitted)
         if route and item["surface"] == "delegated":
             agent_routes.append(route)
     if native and host == "claude":
         assets["claude_plugins"] = sorted(plugin_roots)
+    if native and host == "codex":
+        assets["codex_hooks"] = hook_config
     instruction_text = base_instruction_text
     if agent_routes:
         instruction_text += "\nNative delegated agents:\n"

package/compose/corpus_install.py

@@ -33,6 +33,7 @@ from corpus_transaction import (
     operation_scope,
     operation_scope_active,
     pending_status,
+    reject_symlink_ancestors,
     transaction_lock,
 )
 
@@ -395,11 +396,17 @@ class CorpusInstaller:
             "mode": "private-session-scoped",
         }) + b"\n"
 
+    @staticmethod
+    def _safe_transaction_target(path: Path) -> None:
+        try:
+            reject_symlink_ancestors(path)
+        except TransactionError as exc:
+            raise InstallError(str(exc)) from exc
+
     @staticmethod
     def _file_version(path: Path, *, allow_bytes: bool = True) -> dict[str, Any]:
         """A journaled exact-state predicate; secrets use hash-only predicates."""
-        if path.is_symlink():
-            raise InstallError(f"refusing symlink transaction target: {path}")
+        CorpusInstaller._safe_transaction_target(path)
         if not path.exists():
             return {"exists": False}
         if not path.is_file():
@@ -419,7 +426,9 @@ class CorpusInstaller:
 
     @staticmethod
     def _matches_version(path: Path, version: dict[str, Any]) -> bool:
-        if path.is_symlink():
+        try:
+            CorpusInstaller._safe_transaction_target(path)
+        except InstallError:
             return False
         if not version.get("exists"):
             return not path.exists()
@@ -436,6 +445,7 @@ class CorpusInstaller:
         _atomic_json(journal, value)
 
     def _write_planned(self, path: Path, version: dict[str, Any], mode: int) -> None:
+        self._safe_transaction_target(path)
         encoded = version.get("bytes_b64")
         if not isinstance(encoded, str):
             if not version.get("exists"):
@@ -445,12 +455,19 @@ class CorpusInstaller:
         _atomic_bytes(path, base64.b64decode(encoded.encode("ascii"), validate=True), mode)
 
     def _assert_preflight_paths(self, paths: list[dict[str, Any]]) -> None:
+        for entry in paths:
+            self._safe_transaction_target(Path(entry["path"]))
         conflicts = [entry["path"] for entry in paths
                      if not self._matches_version(Path(entry["path"]), entry["before"])
                      and not self._matches_version(Path(entry["path"]), entry["after"])]
         if conflicts:
             raise InstallError("owned path changed during transaction preflight: " + ", ".join(conflicts))
 
+    def _projection_matches(self, entry: dict[str, Any]) -> bool:
+        path, after = Path(entry["path"]), entry["after"]
+        return self._matches_version(path, after) and (
+            not after.get("exists") or path.stat().st_mode & 0o777 == int(entry["mode"]))
+
     def _old_record(self) -> dict[str, Any] | None:
         return _read_json(self.record_path) if self.record_path.exists() else None
 
@@ -518,6 +535,31 @@ class CorpusInstaller:
                 f"export AGENT_BIOS_PACKAGE_ROOT={quoted}\n"
                 "exec python3 \"$AGENT_BIOS_PACKAGE_ROOT/launch/agent-launch.py\" \"$@\"\n").encode("utf-8")
 
+    def _shell_manager(self):
+        path = Path(__file__).resolve().parent.parent / "launch/shell_integration.py"
+        spec = importlib.util.spec_from_file_location("agent_bios_shell_integration", path)
+        if spec is None or spec.loader is None:
+            raise InstallError("shell connection manager is unavailable")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module.ShellIntegration(self.env, self.repo)
+
+    def _shell_paths(self, action: str) -> list[dict[str, Any]]:
+        try:
+            manager = self._shell_manager()
+            # A receipt-less managed script may survive an interrupted opt-in.
+            # With neither, do not inspect or claim the user's startup file.
+            if not manager.has_connection():
+                return []
+            # Install owns and validates the upcoming launcher projection; it
+            # must also be able to repair a missing/non-executable entrypoint.
+            changes = manager.plan(action, installing=action == "restore")["changes"]
+        except (OSError, RuntimeError) as exc:
+            raise InstallError(str(exc)) from exc
+        return [{"path": str(row["path"]), "before": self._planned_version(row["before"]),
+                 "after": self._planned_version(row["after"]), "mode": row["mode"], "archive": False}
+                for row in changes]
+
     @_serialized
     def install(self, domains: str | None = None, dry_run: bool = False) -> dict[str, Any]:
         files = self._package_files()
@@ -540,6 +582,7 @@ class CorpusInstaller:
         if dry_run:
             return {"dry_run": True, "release": str(release), "release_digest": digest,
                     "files": len(entries), "selection": requested}
+        shell_paths = self._shell_paths("restore")
         # Stage the immutable baseline before publishing either source pointers
         # or launcher projections.  Store owns those source pointers; this
         # coordinator owns all cross-owner ordering.
@@ -581,6 +624,7 @@ class CorpusInstaller:
         paths = [{"path": str(path), "before": self._file_version(path),
                   "after": self._planned_version(content), "mode": mode}
                  for path, content, mode in owned]
+        paths.extend(shell_paths)
         paths.extend([
             {"path": str(self.record_path), "before": self._file_version(self.record_path),
              "after": self._planned_version(_canonical(record) + b"\n"), "mode": 0o600},
@@ -621,7 +665,7 @@ class CorpusInstaller:
         # is harmless to readers because the journal guard is already durable.
         for entry in data["paths"]:
             path = Path(entry["path"])
-            if not self._matches_version(path, entry["after"]):
+            if not self._projection_matches(entry):
                 self._write_planned(path, entry["after"], int(entry["mode"]))
         data["phase"] = "source"
         self._journal_write(journal, data)
@@ -645,7 +689,7 @@ class CorpusInstaller:
 
     def _verify_transaction_install(self, data: dict[str, Any]) -> None:
         for entry in data["paths"]:
-            if not self._matches_version(Path(entry["path"]), entry["after"]):
+            if not self._projection_matches(entry):
                 raise InstallError(f"transaction projection did not verify: {entry['path']}")
         record = _read_json(self.record_path)
         release = Path(record["package_root"])
@@ -756,13 +800,21 @@ class CorpusInstaller:
     @_serialized
     def uninstall(self, dry_run: bool = False) -> dict[str, Any]:
         record = self._old_record()
+        if record is not None:
+            release = Path(record.get("package_root", ""))
+            if not _inside(release, self.runtime / "releases") or release.is_symlink() or not release.is_dir():
+                raise InstallError("private install record has unsafe package root")
+            self._validate_owned_record(record, release)
+        shell_removed: list[str] = []
+        try:
+            manager = self._shell_manager()
+            if manager.has_connection():
+                shell_removed = manager.apply("remove", dry_run)["changed_paths"]
+        except (OSError, RuntimeError) as exc:
+            raise InstallError(str(exc)) from exc
         if record is None:
-            return {"removed": [], "preserved": ["no private install record"]}
-        release = Path(record.get("package_root", ""))
-        if not _inside(release, self.runtime / "releases") or release.is_symlink() or not release.is_dir():
-            raise InstallError("private install record has unsafe package root")
-        self._validate_owned_record(record, release)
-        removed: list[str] = []
+            return {"removed": shell_removed, "preserved": ["no private install record"]}
+        removed: list[str] = list(shell_removed)
         preserved: list[str] = []
         for entry in [record.get("launcher"), *(record.get("config_files") or [])]:
             if not isinstance(entry, dict):
@@ -794,7 +846,7 @@ class CorpusInstaller:
     def _reset_layout(self, record: dict[str, Any], release: Path) -> tuple[list[Path], Path, Path, list[tuple[Path, bytes, int]]]:
         local = [self.launch_root / name for name in ("presets.local.toml", "review-methods.local.toml", "launcher.local.toml")]
         connections = self.launch_root.parent / "agent-bios"
-        cleanup = [*local, connections / "ingest-url"]
+        cleanup = [*local, connections / "ingest-url", self.user_root / "understand" / "state.json"]
         owned = [(self.bin_root / "agent-launch", self._launcher_body(release), 0o755),
                  (self.launch_root / "profiles.toml", (release / "launch" / "agent-launch.toml").read_bytes(), 0o644)]
         owned.extend((self.launch_root / "i18n" / p.name, p.read_bytes(), 0o644)
@@ -817,6 +869,7 @@ class CorpusInstaller:
         cleanup, secret, _connections, owned = self._reset_layout(record, release)
         targets = [{"path": str(path), "before": self._file_version(path), "after": {"exists": False}, "mode": 0o600,
                     "archive": True} for path in cleanup]
+        targets.extend(self._shell_paths("remove"))
         targets.extend({"path": str(path), "before": self._file_version(path), "after": self._planned_version(body),
                         "mode": mode, "archive": False} for path, body, mode in owned)
         status_path = self.state_root / "corpus-status.json"
@@ -913,7 +966,7 @@ class CorpusInstaller:
                 result = self._store(release).apply(data["intent"]["plan_id"], data["intent"]["expected_revision"])
             data["result"] = result; data["phase"] = "projections"; _atomic_json(journal, data)
             for entry in targets:
-                if not entry.get("archive") and not self._matches_version(Path(entry["path"]), entry["after"]): self._write_planned(Path(entry["path"]), entry["after"], int(entry["mode"]))
+                if not entry.get("archive") and not self._projection_matches(entry): self._write_planned(Path(entry["path"]), entry["after"], int(entry["mode"]))
             if prior.get("exists"):
                 if self._matches_version(secret, prior):
                     secret.unlink()

package/compose/corpus_session.py

@@ -216,10 +216,20 @@ class CodexServer:
 
 
 def config_flags(argv, exclude_developer=False):
+    argv = argv[:argv.index('--')] if '--' in argv else argv
     result = []
     index = 0
     while index < len(argv):
         token = argv[index]
+        if token in ('--enable', '--disable'):
+            if index + 1 >= len(argv):
+                raise SessionError(f"missing value for {token}")
+            result += ['-c', f"features.{argv[index + 1]}={'true' if token == '--enable' else 'false'}"]
+            index += 2
+            continue
+        if token.startswith(('--enable=', '--disable=')):
+            name, feature = token.split('=', 1)
+            result += ['-c', f"features.{feature}={'true' if name == '--enable' else 'false'}"]
         if token in ('-c', '--config'):
             if index + 1 >= len(argv):
                 raise SessionError(f"missing value for {token}")
@@ -274,6 +284,8 @@ def named_profile(argv):
 
 
 def replace_developer(argv, text):
+    boundary = argv.index('--') if '--' in argv else len(argv)
+    argv, tail = argv[:boundary], argv[boundary:]
     result, index = [], 0
     while index < len(argv):
         token = argv[index]
@@ -286,7 +298,7 @@ def replace_developer(argv, text):
             continue
         result.append(token)
         index += 1
-    return [*result, '-c', 'developer_instructions=' + json.dumps(text)]
+    return [*result, '-c', 'developer_instructions=' + json.dumps(text), *tail]
 
 
 def instruction_value(argv, host):
@@ -300,10 +312,15 @@ def instruction_value(argv, host):
     return ''
 
 
-def _claude_plugin_paths(snapshot):
+def _native_assets(snapshot):
     assets = snapshot.get('assets') or {}
-    if not isinstance(assets, dict) or set(assets) - {'claude_plugins'}:
+    if not isinstance(assets, dict) or set(assets) - {'claude_plugins', 'codex_hooks'}:
         raise SessionError('invalid native snapshot assets')
+    return assets
+
+
+def _claude_plugin_paths(snapshot):
+    assets = _native_assets(snapshot)
     values = assets.get('claude_plugins', [])
     if not isinstance(values, list) or not all(isinstance(value, str) for value in values):
         raise SessionError('invalid native plugin paths')
@@ -324,6 +341,82 @@ def _claude_plugin_paths(snapshot):
     return result
 
 
+def _codex_hook_config(snapshot):
+    from corpus_catalog import CatalogError, validate_native_hook_config
+    hooks = _native_assets(snapshot).get('codex_hooks', {})
+    try:
+        validate_native_hook_config(hooks, 'codex')
+    except CatalogError as exc:
+        raise SessionError(f'invalid native snapshot hooks: {exc}') from exc
+    return hooks
+
+
+def _toml_value(value):
+    """Serialize the JSON values used by hook config as TOML inline values."""
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, list):
+        return '[' + ', '.join(_toml_value(item) for item in value) + ']'
+    if isinstance(value, dict):
+        return '{' + ', '.join(_toml_value(key) + ' = ' + _toml_value(item)
+                               for key, item in value.items()) + '}'
+    raise SessionError('hook config contains a value that TOML cannot represent')
+
+
+def _with_codex_hooks(argv, hooks, config):
+    if not hooks:
+        return argv
+    # Codex loads every config layer's hooks independently. Copy only existing
+    # session-flag groups; copying effective user/project groups would run them twice.
+    layers = config.get('layers')
+    if not isinstance(layers, list):
+        raise SessionError('Codex native hooks require config/read layer provenance')
+    session_layers = [layer for layer in layers if layer.get('name', {}).get('type') == 'sessionFlags']
+    if len(session_layers) > 1:
+        raise SessionError('Codex reported ambiguous session hook configuration')
+    existing = session_layers[0].get('config', {}).get('hooks', {}) if session_layers else {}
+    if not isinstance(existing, dict):
+        raise SessionError('Codex session hooks are not an event mapping')
+    flags = []
+    for event, groups in sorted(hooks.items()):
+        prior = existing.get(event, [])
+        if not isinstance(prior, list):
+            raise SessionError(f'Codex session hooks.{event} is not a matcher list')
+        flags += ['-c', f'hooks.{event}={_toml_value(prior + groups)}']
+    boundary = argv.index('--') if '--' in argv else len(argv)
+    return [*argv[:boundary], *flags, *argv[boundary:]]
+
+
+def validate_codex_hooks(command, snapshot, argv, cwd, env):
+    """Prove discovery on this runtime; preserve native enablement and trust."""
+    hooks = _codex_hook_config(snapshot)
+    if not hooks:
+        return
+    expected = {(event[0].lower() + event[1:], group['matcher'], handler['command'])
+                for event, groups in hooks.items() for group in groups for handler in group['hooks']}
+    with CodexServer(command, config_flags(argv), cwd, env) as server:
+        result = server.call('hooks/list', {'cwds': [str(cwd)]})
+        config = server.call('config/read', {'cwd': str(cwd), 'includeLayers': False})
+    rows = result.get('data')
+    if not isinstance(rows, list) or len(rows) != 1 or rows[0].get('errors'):
+        raise SessionError('Codex could not discover the selected session hooks')
+    found = {(row.get('eventName'), row.get('matcher'), row.get('command')): row
+             for row in rows[0].get('hooks', []) if row.get('source') == 'sessionFlags'}
+    if not expected.issubset(found):
+        raise SessionError('Codex did not discover every selected session hook; check host hook policy and runtime support')
+    if config.get('config', {}).get('features', {}).get('hooks') is False:
+        print('agent-bios: selected Codex hooks are disabled by the effective native hooks feature setting.', file=sys.stderr)
+    pending = sum(not found[key].get('enabled') or found[key].get('trustStatus') != 'trusted'
+                  for key in expected)
+    if pending:
+        print(f'agent-bios: {pending} selected Codex hook(s) need native review or enablement; '
+              'open /hooks in this session. Registration does not establish execution.', file=sys.stderr)
+
+
 def validate_claude_plugins(command, snapshot, cwd, env):
     """Native validation is manifest-only; assert actual carriers separately."""
     for raw in _claude_plugin_paths(snapshot):
@@ -386,12 +479,14 @@ def compose_argv(command, argv, host, snapshot, cwd=None, env=None, include_glob
                 'effective developer instructions cannot be read without rebuilding native '
                 'profile semantics'
             )
+        hooks = _codex_hook_config(snapshot)
         with CodexServer(command, config_flags(argv, exclude_developer=True), cwd, env) as server:
-            config = server.call('config/read', {'cwd': str(cwd or pathlib.Path.cwd()), 'includeLayers': False})
+            config = server.call('config/read', {'cwd': str(cwd or pathlib.Path.cwd()), 'includeLayers': bool(hooks)})
         native = config.get('config', {}).get('developer_instructions') or ''
         if not isinstance(native, str):
             raise SessionError('effective developer_instructions is not text')
-        return replace_developer(argv, '\n\n'.join(x for x in (native, content, contract) if x))
+        result = replace_developer(argv, '\n\n'.join(x for x in (native, content, contract) if x))
+        return _with_codex_hooks(result, hooks, config)
     boundary = argv.index('--') if '--' in argv else len(argv)
     options, tail = argv[:boundary], argv[boundary:]
     result, index = [], 0
@@ -682,14 +777,18 @@ def launch(command, argv, state_root, host, snapshot, cwd=None, env=None, resume
         env = restore_environment(record, env)
         if not _record_instruction_choice(record, env):
             _claude_exclusion_version(command, record['cwd'], env)
+        pinned = _verified_launch_snapshot(state_root, {'path': record['snapshot_path'], 'content_ref': record['content_ref']})
         if host == 'claude':
-            pinned = _verified_launch_snapshot(state_root, {'path': record['snapshot_path'], 'content_ref': record['content_ref']})
             validate_claude_plugins(command, pinned, record['cwd'], env)
+        else:
+            validate_codex_hooks(command, pinned, record['argv'], record['cwd'], env)
         argv = record['argv']
         native = ['resume', resume_id, *argv] if host == 'codex' else ['--resume', resume_id, *argv]
         return subprocess.call([command, *native], cwd=record['cwd'], env=env)
     snapshot = _verified_launch_snapshot(state_root, snapshot)
     argv = compose_argv(command, argv, host, snapshot, cwd, env, include_global_instructions)
+    if host == 'codex':
+        validate_codex_hooks(command, snapshot, argv, cwd, env)
     if host == 'claude':
         validate_claude_plugins(command, snapshot, cwd, env)
     record = prepare(state_root, host, snapshot, argv, cwd, env, include_global_instructions)

package/compose/corpus_store.py

@@ -174,8 +174,17 @@ def _snapshot_file_digests(root: Path, files: list[str]) -> dict[str, str]:
 
 
 def _snapshot_assets(value: Any, files: list[str]) -> dict[str, Any]:
-    if not isinstance(value, dict) or set(value) - {"claude_plugins"}:
+    if not isinstance(value, dict) or set(value) - {"claude_plugins", "codex_hooks"}:
         raise ValidationError("invalid snapshot native assets")
+    if "codex_hooks" in value:
+        try:
+            from corpus_catalog import CatalogError, validate_native_hook_config
+        except ImportError:
+            from .corpus_catalog import CatalogError, validate_native_hook_config
+        try:
+            validate_native_hook_config(value["codex_hooks"], "codex")
+        except CatalogError as exc:
+            raise ValidationError(f"invalid snapshot native hooks: {exc}") from exc
     plugins = value.get("claude_plugins", [])
     if not isinstance(plugins, list) or not all(isinstance(path, str) for path in plugins):
         raise ValidationError("snapshot plugins must be relative paths")
@@ -1304,7 +1313,7 @@ class CorpusStore:
                     staging = root.with_name(f".{root.name}.staging-{uuid.uuid4().hex}")
                     staging.mkdir(parents=True, exist_ok=False)
                 try:
-                    compiled = catalog.compile_items(_copy_json(selected), staging, host, native=True) if native else catalog.compile_items(_copy_json(selected), staging, host)
+                    compiled = catalog.compile_items(_copy_json(selected), staging, host, native=True, reference_root=root) if native else catalog.compile_items(_copy_json(selected), staging, host)
                     if not isinstance(compiled, dict) or not isinstance(compiled.get("instruction_text"), str):
                         raise CorpusStoreError("catalog compiler returned invalid output")
                     files = _snapshot_relative_paths(compiled.get("files"))

package/compose/corpus_transaction.py

@@ -14,6 +14,7 @@ import hashlib
 import json
 import os
 from pathlib import Path
+import sys
 import threading
 from typing import Any, Iterator
 
@@ -30,6 +31,25 @@ class TransactionPendingError(TransactionError):
     pass
 
 
+def reject_symlink_ancestors(path: Path) -> None:
+    """Refuse redirected user paths, allowing only macOS's fixed system aliases.
+
+    /var, /tmp and /etc are root-owned aliases to /private on macOS. They precede
+    ordinary temporary HOME/state roots and are not user-controlled redirections.
+    The exception names their exact destinations and never applies to the leaf,
+    a same-named link elsewhere, or a user-owned link.
+    """
+    for ancestor in (path, *path.parents):
+        if not ancestor.is_symlink():
+            continue
+        system_alias = (sys.platform == "darwin" and ancestor != path
+                        and ancestor in {Path("/var"), Path("/tmp"), Path("/etc")}
+                        and ancestor.lstat().st_uid == 0
+                        and ancestor.parent / os.readlink(ancestor) == Path("/private") / ancestor.name)
+        if not system_alias:
+            raise TransactionError(f"refusing symlink transaction target: {ancestor}")
+
+
 def _key(state_root: Path) -> str:
     return str(Path(state_root).expanduser().resolve())