execweave 0.6.5__tar.gz → 0.6.7__tar.gz

{execweave-0.6.5 → execweave-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execweave
-Version: 0.6.5
+Version: 0.6.7
 Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
 Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
 Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
@@ -87,7 +87,7 @@ Install the latest published wheel/sdist from PyPI:
 python -m pip install -U execweave
 ```
 
-The package version on `main` is currently **v0.6.5**. The published release may lag main; test the exact mainline build with:
+The package version on `main` is currently **v0.6.6**. The published release may lag main; test the exact mainline build with:
 
 ```bash
 python -m pip install --upgrade --force-reinstall "execweave @ git+https://github.com/Irish-kw/ExecWeave.git@main"
@@ -108,13 +108,17 @@ Live OS-runtime telemetry works with **any local command**. Agent/runtime names
 ```bash
 execweave live --open -- claude
 execweave live --open -- codex
-execweave live --open -- gemini
+execweave live --open -- antigravity
 execweave live --open -- cursor
 execweave live --open -- opencode
 execweave live --open -- ollama serve
 execweave live --open -- python my_agent.py
 ```
 
+> **Approve the hook when prompted.** On the first provider-integrated run, the Agent/IDE may ask whether ExecWeave is allowed to enable its local hook integration. Choose **Allow / Yes**. If the hook is not approved, OS-runtime telemetry can still work, but provider-level tool, model, and supplied-content observability will be reduced or unavailable.
+
+Google Antigravity uses the current `agy` CLI command; ExecWeave also accepts `antigravity` as a friendly alias and resolves it to `agy`. For Cursor, `execweave live --open -- cursor` first uses a normal PATH launcher when one exists, then falls back to the standard Cursor desktop application binary on macOS and Windows.
+
 Or build the finalized artifact pipeline:
 
 ```bash
@@ -143,7 +147,7 @@ Full fidelity also changes the privacy boundary: application-level secrets embed
 | --- | --- | --- |
 | Claude Code | Yes | native hooks + full-fidelity supplied hook content |
 | OpenAI Codex | Yes | lifecycle hooks + full-fidelity supplied hook content |
-| Gemini CLI | Yes | native hooks + full-fidelity supplied hook content |
+| Google Antigravity / Antigravity CLI | Yes | passive native hooks for invocation/tool evidence + full-fidelity values explicitly supplied to those hooks |
 | Cursor | Yes | native hooks + full-fidelity supplied hook content |
 | OpenCode | Yes | project plugin + full-fidelity supplied plugin content |
 | Ollama | Yes | `execweave-model-runtime event/exchange/probe --runtime ollama` |
@@ -193,8 +197,8 @@ execweave-claude-record --open -- claude
 execweave-codex-hook --print-config
 execweave-codex-record --open -- codex
 
-execweave-gemini-hook --print-config
-execweave-gemini-record --open -- gemini
+execweave-antigravity-hook --print-config
+execweave-antigravity-record --open -- antigravity
 
 execweave-cursor-hook --print-config
 execweave-cursor-record --open -- cursor
@@ -203,7 +207,7 @@ execweave-opencode-plugin --install
 execweave-opencode-record --open -- opencode
 ```
 
-Provider-integrated recorders keep raw runtime, semantic, and correlated artifacts separate. Stable provider identifiers such as Cursor `tool_use_id` or OpenCode `sessionID + callID` prove logical provider identity; they are not OS PIDs.
+Provider-integrated recorders keep raw runtime, semantic, and correlated artifacts separate. Stable provider identifiers such as Cursor `tool_use_id` or OpenCode `sessionID + callID` prove logical provider identity; they are not OS PIDs. Legacy Gemini CLI hook entry points remain packaged for existing installations, but Gemini CLI is no longer advertised as a current integration; new Google CLI usage should use Antigravity (`agy`).
 
 ## Inference gateways and model runtimes
 
@@ -274,6 +278,7 @@ execweave doctor
 execweave run --backend portable -- your-command
 execweave run --backend strace -- your-command
 execweave graph-summary run.graph.json
+execweave graph-filter run.graph.json --causal-only --output causal.graph.json
 execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
 execweave path run.graph.json SOURCE TARGET --causal-only
 ```
@@ -325,7 +330,7 @@ Do not assume content has been secret-redacted. Commands, paths, endpoint metada
 
 ## Current status
 
-ExecWeave `main` is currently **v0.6.5** and under active release hardening. The latest published package/release can lag main until a GitHub Release is explicitly published; the publish workflow verifies that the release tag exactly matches the package version before PyPI upload.
+ExecWeave `main` is currently **v0.6.6** and under active release hardening. The latest published package/release can lag main until a GitHub Release is explicitly published; the publish workflow verifies that the release tag exactly matches the package version before PyPI upload.
 
 v0.6.5 combines cross-platform runtime collection, materialized execution graphs, standalone/live viewing, conservative provider↔runtime correlation, full-fidelity content-addressed provider evidence, evidence grades, bounded rule packs, an explicit runtime threat/fidelity contract, and honest local run-integrity sealing. Observed evidence and inference remain separate by design.
 
@@ -337,7 +342,7 @@ v0.6.5 combines cross-platform runtime collection, materialized execution graphs
 - [`Semantic Telemetry`](docs/semantic-telemetry.md)
 - [`Claude Code Hooks`](docs/claude-code-hooks.md)
 - [`OpenAI Codex Hooks`](docs/codex-hooks.md)
-- [`Gemini CLI Hooks`](docs/gemini-hooks.md)
+- [`Google Antigravity Hooks`](docs/antigravity-hooks.md)
 - [`Cursor Hooks`](docs/cursor-hooks.md)
 - [`OpenCode Plugin`](docs/opencode-plugin.md)
 - [`Inference Gateway / OpenRouter / LiteLLM`](docs/inference-gateway.md)

{execweave-0.6.5 → execweave-0.6.7}/README.md

@@ -31,7 +31,7 @@ Install the latest published wheel/sdist from PyPI:
 python -m pip install -U execweave
 ```
 
-The package version on `main` is currently **v0.6.5**. The published release may lag main; test the exact mainline build with:
+The package version on `main` is currently **v0.6.6**. The published release may lag main; test the exact mainline build with:
 
 ```bash
 python -m pip install --upgrade --force-reinstall "execweave @ git+https://github.com/Irish-kw/ExecWeave.git@main"
@@ -52,13 +52,17 @@ Live OS-runtime telemetry works with **any local command**. Agent/runtime names
 ```bash
 execweave live --open -- claude
 execweave live --open -- codex
-execweave live --open -- gemini
+execweave live --open -- antigravity
 execweave live --open -- cursor
 execweave live --open -- opencode
 execweave live --open -- ollama serve
 execweave live --open -- python my_agent.py
 ```
 
+> **Approve the hook when prompted.** On the first provider-integrated run, the Agent/IDE may ask whether ExecWeave is allowed to enable its local hook integration. Choose **Allow / Yes**. If the hook is not approved, OS-runtime telemetry can still work, but provider-level tool, model, and supplied-content observability will be reduced or unavailable.
+
+Google Antigravity uses the current `agy` CLI command; ExecWeave also accepts `antigravity` as a friendly alias and resolves it to `agy`. For Cursor, `execweave live --open -- cursor` first uses a normal PATH launcher when one exists, then falls back to the standard Cursor desktop application binary on macOS and Windows.
+
 Or build the finalized artifact pipeline:
 
 ```bash
@@ -87,7 +91,7 @@ Full fidelity also changes the privacy boundary: application-level secrets embed
 | --- | --- | --- |
 | Claude Code | Yes | native hooks + full-fidelity supplied hook content |
 | OpenAI Codex | Yes | lifecycle hooks + full-fidelity supplied hook content |
-| Gemini CLI | Yes | native hooks + full-fidelity supplied hook content |
+| Google Antigravity / Antigravity CLI | Yes | passive native hooks for invocation/tool evidence + full-fidelity values explicitly supplied to those hooks |
 | Cursor | Yes | native hooks + full-fidelity supplied hook content |
 | OpenCode | Yes | project plugin + full-fidelity supplied plugin content |
 | Ollama | Yes | `execweave-model-runtime event/exchange/probe --runtime ollama` |
@@ -137,8 +141,8 @@ execweave-claude-record --open -- claude
 execweave-codex-hook --print-config
 execweave-codex-record --open -- codex
 
-execweave-gemini-hook --print-config
-execweave-gemini-record --open -- gemini
+execweave-antigravity-hook --print-config
+execweave-antigravity-record --open -- antigravity
 
 execweave-cursor-hook --print-config
 execweave-cursor-record --open -- cursor
@@ -147,7 +151,7 @@ execweave-opencode-plugin --install
 execweave-opencode-record --open -- opencode
 ```
 
-Provider-integrated recorders keep raw runtime, semantic, and correlated artifacts separate. Stable provider identifiers such as Cursor `tool_use_id` or OpenCode `sessionID + callID` prove logical provider identity; they are not OS PIDs.
+Provider-integrated recorders keep raw runtime, semantic, and correlated artifacts separate. Stable provider identifiers such as Cursor `tool_use_id` or OpenCode `sessionID + callID` prove logical provider identity; they are not OS PIDs. Legacy Gemini CLI hook entry points remain packaged for existing installations, but Gemini CLI is no longer advertised as a current integration; new Google CLI usage should use Antigravity (`agy`).
 
 ## Inference gateways and model runtimes
 
@@ -218,6 +222,7 @@ execweave doctor
 execweave run --backend portable -- your-command
 execweave run --backend strace -- your-command
 execweave graph-summary run.graph.json
+execweave graph-filter run.graph.json --causal-only --output causal.graph.json
 execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
 execweave path run.graph.json SOURCE TARGET --causal-only
 ```
@@ -269,7 +274,7 @@ Do not assume content has been secret-redacted. Commands, paths, endpoint metada
 
 ## Current status
 
-ExecWeave `main` is currently **v0.6.5** and under active release hardening. The latest published package/release can lag main until a GitHub Release is explicitly published; the publish workflow verifies that the release tag exactly matches the package version before PyPI upload.
+ExecWeave `main` is currently **v0.6.6** and under active release hardening. The latest published package/release can lag main until a GitHub Release is explicitly published; the publish workflow verifies that the release tag exactly matches the package version before PyPI upload.
 
 v0.6.5 combines cross-platform runtime collection, materialized execution graphs, standalone/live viewing, conservative provider↔runtime correlation, full-fidelity content-addressed provider evidence, evidence grades, bounded rule packs, an explicit runtime threat/fidelity contract, and honest local run-integrity sealing. Observed evidence and inference remain separate by design.
 
@@ -281,7 +286,7 @@ v0.6.5 combines cross-platform runtime collection, materialized execution graphs
 - [`Semantic Telemetry`](docs/semantic-telemetry.md)
 - [`Claude Code Hooks`](docs/claude-code-hooks.md)
 - [`OpenAI Codex Hooks`](docs/codex-hooks.md)
-- [`Gemini CLI Hooks`](docs/gemini-hooks.md)
+- [`Google Antigravity Hooks`](docs/antigravity-hooks.md)
 - [`Cursor Hooks`](docs/cursor-hooks.md)
 - [`OpenCode Plugin`](docs/opencode-plugin.md)
 - [`Inference Gateway / OpenRouter / LiteLLM`](docs/inference-gateway.md)

execweave-0.6.7/docs/antigravity-hooks.md

@@ -0,0 +1,55 @@
+# Google Antigravity hooks
+
+ExecWeave supports the current Google Antigravity CLI through its native hooks and OS-runtime collection. The Antigravity CLI executable is `agy`.
+
+```bash
+execweave live --open -- antigravity
+# ExecWeave resolves this friendly name to the official `agy` CLI binary.
+```
+
+On the first provider-integrated run, Antigravity may ask whether the ExecWeave hook should be allowed. Choose **Allow / Yes** if you want provider-level tool and invocation evidence in addition to OS-runtime telemetry.
+
+## Automatic bootstrap
+
+For `agy` / `antigravity`, ExecWeave conservatively merges one named hook definition into:
+
+```text
+~/.gemini/config/hooks.json
+```
+
+The generated configuration can be inspected without writing it:
+
+```bash
+execweave-antigravity-hook --print-config
+```
+
+ExecWeave deliberately uses passive observation points:
+
+- `PostToolUse` for tool-call/result evidence.
+- `PreInvocation` and `PostInvocation` for invocation lifecycle metadata.
+- **No `PreToolUse` hook is installed**, because that hook participates in Antigravity's permission decision and ExecWeave must not approve, deny, or alter a user's tool permission flow.
+
+Existing unrelated named hooks are preserved. ExecWeave refuses to replace an existing hook definition with the same name rather than silently overwriting it.
+
+## Layered recorder
+
+```bash
+execweave-antigravity-record --open -- antigravity
+```
+
+The recorder keeps runtime evidence, Antigravity semantic evidence, and derived correlation artifacts separate. Normal `execweave live --open -- antigravity` also auto-bootstraps the hook integration and exposes the live graph.
+
+## Evidence scope
+
+Current Antigravity hook evidence is intentionally bounded to values actually supplied by the hook contract. ExecWeave can record:
+
+- invocation lifecycle metadata exposed by `PreInvocation` / `PostInvocation`;
+- tool identity, arguments, result/error status exposed by `PostToolUse`;
+- declared command or file targets when those fields are present in the supplied tool arguments;
+- complete hook-supplied values in the local content-addressed store where supported.
+
+This does **not** claim access to hidden model state, private chain-of-thought, an unseen provider-side request, or any content not delivered to the hook. OS-runtime evidence remains a separate layer.
+
+## Legacy Gemini CLI
+
+The older `execweave-gemini-*` entry points remain available for compatibility with existing installations and archived workflows. They are not the current Google CLI path documented by ExecWeave; new usage should target Antigravity with `agy`.

{execweave-0.6.5 → execweave-0.6.7}/docs/cursor-hooks.md

@@ -22,6 +22,10 @@ execweave-cursor-hook --print-config
 execweave-cursor-record --open -- cursor
 ```
 
+`cursor` does not have to be a shell-installed CLI launcher. ExecWeave first uses a normal PATH launcher when one exists; if it does not, macOS and Windows fall back to the standard Cursor desktop application binary. This also applies to `execweave live --open -- cursor`.
+
+If Cursor asks whether to allow the ExecWeave hook integration, choose **Allow / Yes** to enable provider-level tool/content evidence. OS-runtime observation can still operate without provider hook approval, but specialized evidence will be reduced or unavailable.
+
 The run-bound recorder keeps runtime, semantic, and correlated artifacts separate.
 
 ## Observation surface

{execweave-0.6.5 → execweave-0.6.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execweave"
-version = "0.6.5"
+version = "0.6.7"
 description = "Turn AI-agent runtime behavior into a local interactive execution graph."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -63,6 +63,9 @@ execweave-claude-hook = "execweave.claude_hook_cli:main"
 execweave-claude-record = "execweave.claude_record:main"
 execweave-codex-hook = "execweave.codex_hook_cli:main"
 execweave-codex-record = "execweave.codex_record:main"
+execweave-antigravity-hook = "execweave.antigravity_hook_cli:main"
+execweave-antigravity-record = "execweave.antigravity_record:main"
+# Legacy Gemini CLI entry points remain for compatibility with existing installs.
 execweave-gemini-hook = "execweave.gemini_hook_cli:main"
 execweave-gemini-record = "execweave.gemini_record:main"
 execweave-cursor-hook = "execweave.cursor_hook_cli:main"

{execweave-0.6.5 → execweave-0.6.7}/src/execweave/__init__.py

@@ -1,3 +1,3 @@
 """ExecWeave runtime graph package."""
 
-__version__ = "0.6.5"
+__version__ = "0.6.7"

execweave-0.6.7/src/execweave/agent_bootstrap.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+from copy import deepcopy
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+_AUTO_FLAG = "--auto"
+_CONFIG_RETRIES = 3
+_SUPPORTED_AGENTS = {
+    "claude": "claude",
+    "codex": "codex",
+    "agy": "antigravity",
+    "antigravity": "antigravity",
+    "cursor": "cursor",
+    "opencode": "opencode",
+    # Legacy compatibility only. Gemini CLI is no longer advertised as current.
+    "gemini": "gemini",
+}
+
+
+@dataclass(frozen=True)
+class AgentBootstrapResult:
+    provider: str | None
+    status: str
+    path: str | None = None
+    changed: bool = False
+    detail: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def _command_name(value: str) -> str:
+    name = value.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    for suffix in (".exe", ".cmd", ".bat", ".ps1"):
+        if name.endswith(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def supported_agent(command: list[str]) -> str | None:
+    if not command:
+        return None
+    return _SUPPORTED_AGENTS.get(_command_name(command[0]))
+
+
+def _bounded_detail(value: object, limit: int = 240) -> str:
+    text = " ".join(str(value).split())
+    return text if len(text) <= limit else text[: limit - 3] + "..."
+
+
+def _load_json_object(raw: bytes, *, path: Path) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid JSON in {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"configuration root must be an object: {path}")
+    return payload
+
+
+def _read_bytes(path: Path) -> bytes | None:
+    try:
+        return path.read_bytes()
+    except FileNotFoundError:
+        return None
+
+
+def _contains_execweave_command(value: object, marker: str) -> bool:
+    if isinstance(value, dict):
+        command = value.get("command")
+        if isinstance(command, str) and marker in command:
+            return True
+        return any(_contains_execweave_command(child, marker) for child in value.values())
+    if isinstance(value, list):
+        return any(_contains_execweave_command(child, marker) for child in value)
+    return False
+
+
+def _merge_hook_fragment(
+    current: dict[str, Any],
+    fragment: dict[str, Any],
+    *,
+    marker: str,
+) -> tuple[dict[str, Any], bool]:
+    merged = deepcopy(current)
+    changed = False
+
+    for key, value in fragment.items():
+        if key == "hooks":
+            continue
+        if key not in merged:
+            merged[key] = deepcopy(value)
+            changed = True
+
+    incoming_hooks = fragment.get("hooks")
+    if not isinstance(incoming_hooks, dict):
+        raise ValueError("ExecWeave hook fragment has no hooks object")
+
+    existing_hooks = merged.get("hooks")
+    if existing_hooks is None:
+        existing_hooks = {}
+        merged["hooks"] = existing_hooks
+        changed = True
+    if not isinstance(existing_hooks, dict):
+        raise ValueError("existing hooks value is not an object")
+
+    for event_name, incoming_groups in incoming_hooks.items():
+        if not isinstance(incoming_groups, list):
+            raise ValueError(f"ExecWeave hook event is not a list: {event_name}")
+        existing_groups = existing_hooks.get(event_name)
+        if existing_groups is None:
+            existing_hooks[event_name] = deepcopy(incoming_groups)
+            changed = True
+            continue
+        if not isinstance(existing_groups, list):
+            raise ValueError(f"existing hook event is not a list: {event_name}")
+        if _contains_execweave_command(existing_groups, marker):
+            continue
+        existing_groups.extend(deepcopy(incoming_groups))
+        changed = True
+
+    return merged, changed
+
+
+def _merge_named_hook_fragment(
+    current: dict[str, Any],
+    fragment: dict[str, Any],
+    *,
+    marker: str,
+) -> tuple[dict[str, Any], bool]:
+    """Merge Antigravity's named-hook ``hooks.json`` schema conservatively."""
+    merged = deepcopy(current)
+    if _contains_execweave_command(merged, marker):
+        return merged, False
+    for name, definition in fragment.items():
+        if name in merged:
+            raise FileExistsError(
+                f"refusing to replace existing Antigravity hook definition: {name}"
+            )
+        merged[name] = deepcopy(definition)
+    return merged, bool(fragment)
+
+
+def _write_bytes_optimistic(path: Path, original: bytes | None, payload: bytes) -> bool:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    current = _read_bytes(path)
+    if current != original:
+        return False
+
+    mode = None
+    if path.exists():
+        try:
+            mode = stat.S_IMODE(path.stat().st_mode)
+        except OSError:
+            mode = None
+
+    temporary = path.with_name(f".{path.name}.execweave-{os.getpid()}.tmp")
+    try:
+        temporary.write_bytes(payload)
+        if mode is not None:
+            try:
+                temporary.chmod(mode)
+            except OSError:
+                pass
+        os.replace(temporary, path)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+    return True
+
+
+def _merge_json_file(path: Path, fragment: dict[str, Any], *, marker: str) -> bool:
+    for _ in range(_CONFIG_RETRIES):
+        original = _read_bytes(path)
+        current = _load_json_object(original or b"", path=path)
+        merged, changed = _merge_hook_fragment(current, fragment, marker=marker)
+        if not changed:
+            return False
+        encoded = (
+            json.dumps(merged, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        ).encode("utf-8")
+        if _write_bytes_optimistic(path, original, encoded):
+            return True
+    raise RuntimeError(f"configuration changed concurrently while updating {path}")
+
+
+def _merge_named_hook_file(path: Path, fragment: dict[str, Any], *, marker: str) -> bool:
+    for _ in range(_CONFIG_RETRIES):
+        original = _read_bytes(path)
+        current = _load_json_object(original or b"", path=path)
+        merged, changed = _merge_named_hook_fragment(current, fragment, marker=marker)
+        if not changed:
+            return False
+        encoded = (
+            json.dumps(merged, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        ).encode("utf-8")
+        if _write_bytes_optimistic(path, original, encoded):
+            return True
+    raise RuntimeError(f"configuration changed concurrently while updating {path}")
+
+
+def _write_plugin_file(path: Path, content: str, *, marker: str) -> bool:
+    encoded = content.encode("utf-8")
+    for _ in range(_CONFIG_RETRIES):
+        original = _read_bytes(path)
+        if original is not None:
+            try:
+                existing = original.decode("utf-8")
+            except UnicodeDecodeError as exc:
+                raise ValueError(f"existing OpenCode plugin is not UTF-8: {path}") from exc
+            if existing == content or marker in existing:
+                return False
+            raise FileExistsError(f"refusing to replace existing OpenCode plugin: {path}")
+        if _write_bytes_optimistic(path, original, encoded):
+            return True
+    raise RuntimeError(f"plugin path changed concurrently while updating {path}")
+
+
+def _config_dir_from_env(environment: Mapping[str, str], key: str) -> Path | None:
+    raw = environment.get(key, "").strip()
+    return Path(raw).expanduser() if raw else None
+
+
+def _provider_target(
+    provider: str,
+    *,
+    home: Path,
+    environment: Mapping[str, str],
+) -> Path:
+    if provider == "claude":
+        root = _config_dir_from_env(environment, "CLAUDE_CONFIG_DIR") or home / ".claude"
+        return root / "settings.json"
+    if provider == "codex":
+        root = _config_dir_from_env(environment, "CODEX_HOME") or home / ".codex"
+        return root / "hooks.json"
+    if provider == "antigravity":
+        return home / ".gemini" / "config" / "hooks.json"
+    if provider == "gemini":
+        return home / ".gemini" / "settings.json"
+    if provider == "cursor":
+        return home / ".cursor" / "hooks.json"
+    if provider == "opencode":
+        root = _config_dir_from_env(environment, "XDG_CONFIG_HOME") or home / ".config"
+        return root / "opencode" / "plugins" / "execweave.ts"
+    raise ValueError(f"unsupported provider: {provider}")
+
+
+def _provider_fragment(provider: str) -> tuple[dict[str, Any], str]:
+    if provider == "claude":
+        from .claude_hook_cli import claude_hook_config
+
+        return claude_hook_config(f"execweave-claude-hook {_AUTO_FLAG}"), "execweave-claude-hook"
+    if provider == "codex":
+        from .codex_hook_cli import codex_hook_config
+
+        return codex_hook_config(f"execweave-codex-hook {_AUTO_FLAG}"), "execweave-codex-hook"
+    if provider == "antigravity":
+        from .antigravity_hook_cli import antigravity_hook_config
+
+        return antigravity_hook_config(), "execweave-antigravity-hook"
+    if provider == "gemini":
+        from .gemini_hook_cli import gemini_hook_config
+
+        return gemini_hook_config(f"execweave-gemini-hook {_AUTO_FLAG}"), "execweave-gemini-hook"
+    if provider == "cursor":
+        from .cursor_hook_cli import cursor_hook_config
+
+        return cursor_hook_config(f"execweave-cursor-hook {_AUTO_FLAG}"), "execweave-cursor-hook"
+    raise ValueError(f"provider does not use JSON hooks: {provider}")
+
+
+def bootstrap_supported_agent(
+    command: list[str],
+    *,
+    home: str | Path | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> AgentBootstrapResult:
+    provider = supported_agent(command)
+    if provider is None:
+        command_name = _command_name(command[0]) if command else "unknown"
+        return AgentBootstrapResult(
+            provider=None,
+            status="unavailable",
+            detail=f"no specialized lifecycle integration for {command_name}",
+        )
+
+    env = os.environ if environment is None else environment
+    home_path = Path.home() if home is None else Path(home).expanduser()
+    target = _provider_target(provider, home=home_path, environment=env)
+
+    try:
+        if provider == "opencode":
+            from .opencode_plugin_cli import plugin_text
+
+            content = plugin_text(("execweave-opencode-hook", _AUTO_FLAG))
+            changed = _write_plugin_file(target, content, marker="execweave-opencode-hook")
+        else:
+            fragment, marker = _provider_fragment(provider)
+            changed = (
+                _merge_named_hook_file(target, fragment, marker=marker)
+                if provider == "antigravity"
+                else _merge_json_file(target, fragment, marker=marker)
+            )
+
+        if provider == "claude":
+            raw = _read_bytes(target)
+            payload = _load_json_object(raw or b"", path=target)
+            if payload.get("disableAllHooks") is True:
+                return AgentBootstrapResult(
+                    provider=provider,
+                    status="unavailable",
+                    path=str(target),
+                    changed=changed,
+                    detail="Claude hooks are disabled by disableAllHooks",
+                )
+
+        return AgentBootstrapResult(
+            provider=provider,
+            status="active",
+            path=str(target),
+            changed=changed,
+            detail="specialized hook/plugin bootstrap is configured",
+        )
+    except (FileExistsError, OSError, RuntimeError, TypeError, ValueError) as exc:
+        return AgentBootstrapResult(
+            provider=provider,
+            status="bootstrap_failed",
+            path=str(target),
+            changed=False,
+            detail=_bounded_detail(exc),
+        )