execweave 0.8.33__tar.gz → 0.8.35__tar.gz

{execweave-0.8.33 → execweave-0.8.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execweave
-Version: 0.8.33
+Version: 0.8.35
 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
@@ -42,6 +42,7 @@ Requires-Python: >=3.10
 Requires-Dist: psutil>=5.9
 Requires-Dist: watchdog>=4.0
 Provides-Extra: dev
+Requires-Dist: cryptography>=44; extra == 'dev'
 Requires-Dist: pillow>=10.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: pywinpty<4,>=3.0.5; (platform_system == 'Windows') and extra == 'dev'
@@ -56,8 +57,14 @@ Provides-Extra: release
 Requires-Dist: build>=1.2; extra == 'release'
 Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'release'
 Requires-Dist: twine>=6.0; extra == 'release'
+Provides-Extra: validation
+Requires-Dist: cryptography>=44; extra == 'validation'
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="docs/assets/shot5_brand.jpg" alt="ExecWeave" width="100%">
+</p>
+
 # ExecWeave
 
 <!-- i18n-nav:start -->
@@ -144,7 +151,15 @@ execweave top -- codex
 
 ### Provider integration approval
 
-Some agents and IDEs ask for permission before enabling a local hook or plugin. Approve the ExecWeave integration if you want provider-level prompt, response, tool, model, and conversation evidence. If you do not approve it, OS-runtime observation can still work, but semantic coverage may be reduced.
+Since 0.8.35, `live` only checks hook configuration; it never installs or rewrites it. Explicitly run `execweave hooks install antigravity` (or `claude`, `codex`, `cursor`, `opencode`) from your user-owned environment, without sudo. `execweave hooks status antigravity` checks setup without writing. Provider approval may still be required. **Configured does not mean evidence was delivered.** Missing delivery and incomplete observation are recorded independently of process exit.
+
+See [observation integrity and the negative example](docs/observation-integrity.md) for the three result axes and their honest limits. These changes ship in 0.8.35; earlier versions do not contain them.
+
+**Live privacy and authentication (0.8.35)**
+
+`execweave live` and `execweave top` record the complete provider/model content an integration exposes (prompts, responses, tool values) by default, because the run stays on your own machine for you to inspect. Add `--metadata-only` when a run must not store that plaintext; `--capture-content` remains accepted and selects the default explicitly. Invalid capture-policy values fail closed to metadata-only at automatic recorder boundaries.
+
+The live dashboard no longer puts its API credential in `?t=...`. The announced URL contains no credential. Browser access uses a one-time pairing code submitted in a POST body and then an `HttpOnly; SameSite=Strict` cookie; non-browser API clients use the private `X-ExecWeave-Token` header.
 
 Google Antigravity currently uses the `agy` CLI command. ExecWeave also accepts `antigravity` as a friendly alias.
 
@@ -182,6 +197,8 @@ execweave live --open -- ollama run deepseek-r1:1.5b
 
 This mode does not start an Ollama server. A reachable upstream server is still required.
 
+In both modes the relay forwards every request and, by default, records each inference exchange so the prompts and responses appear in the run and on the dashboard. Add `--metadata-only` (for example, `execweave live --metadata-only --open -- ollama serve`) when the conversation must not be stored.
+
 ## Dashboard
 
 The dashboard is designed to keep large, multi-agent runs inspectable without changing the underlying evidence.
@@ -345,7 +362,8 @@ Raw observations remain separate from derived semantic and correlation outputs.
 - **Failure ownership cleanup:** if the portable collector fails unexpectedly after launching a managed workload, it terminates the workload it owns before recording terminal session state. A filesystem observer that only partially starts is also torn down before the startup error propagates.
 - Linux also provides a `strace` reference backend with stronger syscall-attributed evidence for supported executions.
 - Provider semantics depend on what each integration actually exposes. Missing prompts, hidden reasoning, remote provider internals, and unexposed routing cannot be reconstructed reliably.
-- Full-fidelity provider content may contain credentials, secrets, source code, prompts, tool values, model responses, shell output, and file contents.
+- Full-fidelity provider content may contain credentials, secrets, source code, prompts, tool values, model responses, shell output, and file contents. `live`/`top` store it by default because the run stays on the local machine; the run directory is owner-private, and `--metadata-only` keeps that plaintext out of the run entirely.
+- Run artifacts are written through owner-private primitives. POSIX permissions are established before sensitive bytes are published; the Windows path applies a protected owner DACL. Final Windows guarantees still depend on the release CI matrix and are not inferred from Linux tests.
 - Conversation isolation is an attribution rule, not a redaction boundary. Explicitly routed content may legitimately appear at more than one participant.
 - A local integrity manifest detects changes relative to the manifest; it is not an adversary-resistant trusted logging system if both evidence and manifest remain inside the same writable trust boundary.
 - Review the complete run directory before sharing it.

{execweave-0.8.33 → execweave-0.8.35}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/assets/shot5_brand.jpg" alt="ExecWeave" width="100%">
+</p>
+
 # ExecWeave
 
 <!-- i18n-nav:start -->
@@ -84,7 +88,15 @@ execweave top -- codex
 
 ### Provider integration approval
 
-Some agents and IDEs ask for permission before enabling a local hook or plugin. Approve the ExecWeave integration if you want provider-level prompt, response, tool, model, and conversation evidence. If you do not approve it, OS-runtime observation can still work, but semantic coverage may be reduced.
+Since 0.8.35, `live` only checks hook configuration; it never installs or rewrites it. Explicitly run `execweave hooks install antigravity` (or `claude`, `codex`, `cursor`, `opencode`) from your user-owned environment, without sudo. `execweave hooks status antigravity` checks setup without writing. Provider approval may still be required. **Configured does not mean evidence was delivered.** Missing delivery and incomplete observation are recorded independently of process exit.
+
+See [observation integrity and the negative example](docs/observation-integrity.md) for the three result axes and their honest limits. These changes ship in 0.8.35; earlier versions do not contain them.
+
+**Live privacy and authentication (0.8.35)**
+
+`execweave live` and `execweave top` record the complete provider/model content an integration exposes (prompts, responses, tool values) by default, because the run stays on your own machine for you to inspect. Add `--metadata-only` when a run must not store that plaintext; `--capture-content` remains accepted and selects the default explicitly. Invalid capture-policy values fail closed to metadata-only at automatic recorder boundaries.
+
+The live dashboard no longer puts its API credential in `?t=...`. The announced URL contains no credential. Browser access uses a one-time pairing code submitted in a POST body and then an `HttpOnly; SameSite=Strict` cookie; non-browser API clients use the private `X-ExecWeave-Token` header.
 
 Google Antigravity currently uses the `agy` CLI command. ExecWeave also accepts `antigravity` as a friendly alias.
 
@@ -122,6 +134,8 @@ execweave live --open -- ollama run deepseek-r1:1.5b
 
 This mode does not start an Ollama server. A reachable upstream server is still required.
 
+In both modes the relay forwards every request and, by default, records each inference exchange so the prompts and responses appear in the run and on the dashboard. Add `--metadata-only` (for example, `execweave live --metadata-only --open -- ollama serve`) when the conversation must not be stored.
+
 ## Dashboard
 
 The dashboard is designed to keep large, multi-agent runs inspectable without changing the underlying evidence.
@@ -285,7 +299,8 @@ Raw observations remain separate from derived semantic and correlation outputs.
 - **Failure ownership cleanup:** if the portable collector fails unexpectedly after launching a managed workload, it terminates the workload it owns before recording terminal session state. A filesystem observer that only partially starts is also torn down before the startup error propagates.
 - Linux also provides a `strace` reference backend with stronger syscall-attributed evidence for supported executions.
 - Provider semantics depend on what each integration actually exposes. Missing prompts, hidden reasoning, remote provider internals, and unexposed routing cannot be reconstructed reliably.
-- Full-fidelity provider content may contain credentials, secrets, source code, prompts, tool values, model responses, shell output, and file contents.
+- Full-fidelity provider content may contain credentials, secrets, source code, prompts, tool values, model responses, shell output, and file contents. `live`/`top` store it by default because the run stays on the local machine; the run directory is owner-private, and `--metadata-only` keeps that plaintext out of the run entirely.
+- Run artifacts are written through owner-private primitives. POSIX permissions are established before sensitive bytes are published; the Windows path applies a protected owner DACL. Final Windows guarantees still depend on the release CI matrix and are not inferred from Linux tests.
 - Conversation isolation is an attribution rule, not a redaction boundary. Explicitly routed content may legitimately appear at more than one participant.
 - A local integrity manifest detects changes relative to the manifest; it is not an adversary-resistant trusted logging system if both evidence and manifest remain inside the same writable trust boundary.
 - Review the complete run directory before sharing it.

{execweave-0.8.33 → execweave-0.8.35}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execweave"
-# ExecWeave v0.8.33 release metadata
-version = "0.8.33"
+# ExecWeave v0.8.35 release metadata
+version = "0.8.35"
 description = "Turn AI-agent runtime behavior into a local interactive execution graph."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -42,7 +42,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+validation = ["cryptography>=44"]
 dev = [
+  "cryptography>=44",
   "pytest>=8.0",
   "PyYAML>=6.0",
   "pillow>=10.0",

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/__init__.py

@@ -1,3 +1,3 @@
 """ExecWeave runtime graph package."""
 
-__version__ = "0.8.33"
+__version__ = "0.8.35"

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/_conversation_records_core.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
-import json
 import re
+from collections import Counter
 from pathlib import Path
 from typing import Any
 from .content_store import _filesystem_path
+from .private_io import write_private_json, write_private_text
 
 from .agent_topology import (
     COMPLETENESS_ROUTING_ONLY,
@@ -491,6 +492,7 @@ def conversation_record_entries(
         for node in nodes
         if isinstance(node.get("id"), str) and node.get("id")
     }
+    source_counts = Counter(node.get("id") for node in nodes if isinstance(node.get("id"), str))
     entries: list[dict[str, Any]] = []
     for edge in edges:
         target_id = edge.get("target")
@@ -542,6 +544,36 @@ def conversation_record_entries(
         derived = preview.pop("derived_agent_previews", None) if isinstance(preview, dict) else None
         if preview is not None:
             entry["conversation_preview"] = preview
+        # Keep each framework model response attached to its own content reference.
+        # Conversation merging publishes only one aggregate preview and can otherwise
+        # leave the actual model bodies behind a later control/status message.
+        source_attrs = source.get("attributes") if isinstance(source, dict) else None
+        if (
+            isinstance(source_attrs, dict)
+            and source.get("type") == "agent"
+            and source_counts[source_id] == 1
+            and source_attrs.get("conversation_scope") == "framework_agent"
+            and reference["content_kind"] in {
+                "metagpt.model_response", "autogen.model_response", "camel.model_response"
+            }
+            and edge.get("relation") == "HAS_MODEL_CONTENT"
+            and all(
+                record.get(flag) is None or record.get(flag) is False
+                for record in (edge, edge.get("attributes") if isinstance(edge.get("attributes"), dict) else {})
+                for flag in ("inferred", "viewer_only")
+            )
+            and isinstance(preview, dict)
+        ):
+            agent_path = preview.get("agent_path")
+            entry["model_response_preview"] = {
+                "schema_version": "1",
+                "source_id": source_id,
+                "agent_path": agent_path,
+                "messages": [dict(message) for message in preview.get("messages", [])
+                             if isinstance(message, dict) and agent_path
+                             and message.get("sender") == agent_path],
+                "messages_truncated": bool(preview.get("messages_truncated")),
+            }
         entries.append(entry)
         if isinstance(derived, list):
             entries.extend(_derived_agent_entries(entry, derived))
@@ -810,14 +842,19 @@ def _mark_shared_evidence(entries: list[dict[str, Any]]) -> None:
 def conversation_index_payload(
     graph: dict[str, Any],
     run_root: str | Path,
+    *,
+    investigation_cache=None,
+    include_investigation: bool = False,
 ) -> dict[str, Any]:
-    """Build the conversation index exactly as ``conversations.json`` carries it.
+    """Build the shared conversation projection, with opt-in investigation.
 
-    The live dashboard and the finalized viewer both read this. Keeping one
-    builder is the point: a live run that computed its own projection would be
-    free to disagree with the file written at finalization, and the disagreement
-    would show up as an agent seeing conversations that are not its own.
+    The default is the historical, lightweight conversation contract used by
+    ordinary Live polling. Event-stream inspection is requested explicitly by
+    the investigation reader and offline exporters. Both modes publish exactly
+    the same conversation entries; the extended mode only adds an index.
     """
+    from .investigation_index import build_investigation_index
+
     root = Path(run_root).expanduser().resolve()
     entries = conversation_record_entries(graph, root)
     _mark_shared_injected_context(entries)
@@ -830,6 +867,10 @@ def conversation_index_payload(
     return {
         "schema_version": "0.3",
         "scope": "run_local_provider_neutral_conversation_projection",
+        "session_id": graph.get("session_id") if isinstance(graph.get("session_id"), str) else None,
+        "source_path": graph.get("source_path") if isinstance(graph.get("source_path"), str) else None,
+        **({"investigation": build_investigation_index(graph, root, cache=investigation_cache)}
+           if include_investigation else {}),
         "entry_count": len(entries),
         "visible_message_count": visible_message_count,
         "external_provider_folder_lookup_required": False,
@@ -852,13 +893,10 @@ def write_conversation_records(
     root = Path(run_root).expanduser().resolve()
     root.mkdir(parents=True, exist_ok=True)
     if payload is None:
-        payload = conversation_index_payload(graph, root)
+        payload = conversation_index_payload(graph, root, include_investigation=True)
     entries = payload["entries"]
     json_path = root / "conversations.json"
     markdown_path = root / "conversations.md"
-    json_path.write_text(
-        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
-        encoding="utf-8",
-    )
-    markdown_path.write_text(_render_markdown(entries), encoding="utf-8")
+    write_private_json(json_path, payload, replace=json_path.exists())
+    write_private_text(markdown_path, _render_markdown(entries), replace=markdown_path.exists())
     return json_path, markdown_path

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/_dashboard_shell_base.py

@@ -4,7 +4,13 @@ import json
 from typing import Any
 
 from .live_view import LIVE_HTML as _BASE_LIVE_HTML
+from .run_assessment import build_run_assessment
+from .viewer_run_assessment import inject_run_assessment
+from .viewer_investigation import inject_investigation
+from .viewer_runtime_evidence import inject_runtime_evidence
 from .viewer_agent_panel import inject_agent_panel
+from .viewer_framework_model_output import inject_framework_model_output
+from .viewer_content_browser import inject_content_browser
 from .viewer_dashboard_clean import fold_budget_bootstrap, inject_live_dashboard_clean
 from .viewer_dashboard_focus import inject_live_dashboard_focus
 from .viewer_dashboard_pr70 import inject_pr70_dashboard_repairs
@@ -84,7 +90,9 @@ def _build_dashboard_html() -> str:
     html = normalize_provider_execution_flow(
         harden_execution_flow_projection(inject_execution_flow(html))
     )
-    return _align_agent_panel_topology(inject_agent_panel(_guard_compact_live_snapshot(html)))
+    html = _align_agent_panel_topology(inject_agent_panel(_guard_compact_live_snapshot(html)))
+    html = inject_framework_model_output(html)
+    return inject_runtime_evidence(inject_investigation(inject_run_assessment(inject_content_browser(html))))
 
 
 DASHBOARD_HTML = _build_dashboard_html()
@@ -103,14 +111,21 @@ def render_static_dashboard_html(
     graph: dict[str, Any],
     *,
     conversation_entries: list[dict[str, Any]] | None = None,
+    investigation_index: dict[str, Any] | None = None,
 ) -> str:
     """Render the exact dashboard shell used by live, backed by embedded snapshots."""
+    # Derived presentation metadata belongs beside the raw graph, not in it.
+    assessment = graph.get("run_assessment")
+    if not isinstance(assessment, dict):
+        assessment = build_run_assessment(graph)
     bootstrap = (
         "<script>window.__execweaveStaticMode=true;"
         f"{fold_budget_bootstrap()}"
         f"{viewer_limits_bootstrap(resolve_viewer_limits())}"
+        f"window.__execweaveStaticRunAssessment={_safe_json(assessment)};"
         f"window.__execweaveStaticGraph={_safe_json(graph)};"
         f"window.__execweaveStaticConversations={_safe_json(conversation_entries or [])};"
+        f"window.__execweaveStaticInvestigation={_safe_json(investigation_index)};"
         "</script>\n"
     )
     html = DASHBOARD_HTML.replace("<script>", bootstrap + "<script>", 1)

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/_http_proxy_base.py

@@ -4,6 +4,7 @@ import http.client
 import ipaddress
 import json
 import sys
+import threading
 import uuid
 from dataclasses import dataclass
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -16,6 +17,7 @@ from .content_store import FullFidelityContentStore
 from .model_runtime_full_fidelity import runtime_exchange_to_content_events
 from .openai_compatible import append_openai_compatible_records
 from .openai_compatible_full_fidelity import exchange_to_content_events
+from .privacy import full_content_capture_enabled
 from .stream_assembly import (
     OLLAMA_NDJSON,
     OPENAI_CHAT_DELTA,
@@ -208,6 +210,8 @@ def record_exchange_fail_open(
     request_only: bool = False,
     request_recorded: bool = False,
 ) -> bool:
+    if not full_content_capture_enabled():
+        return False
     try:
         request = _json(request_body)
         if not isinstance(request, dict):
@@ -386,8 +390,30 @@ class ExecWeaveHTTPProxyServer(ThreadingHTTPServer):
         self.proxy_config = config
         self.upstream = _parse_upstream(config.upstream)
         self.recorder = recorder
+        # Handler threads are daemonic, so ThreadingMixIn.server_close() does not
+        # join them. A response can reach the client before its recording finishes,
+        # so closing the server waits for those recordings explicitly instead.
+        self._recordings = 0
+        self._recordings_done = threading.Condition()
         super().__init__(address, ExecWeaveHTTPProxyHandler)
 
+    def begin_recording(self) -> None:
+        with self._recordings_done:
+            self._recordings += 1
+
+    def end_recording(self) -> None:
+        with self._recordings_done:
+            self._recordings -= 1
+            self._recordings_done.notify_all()
+
+    def wait_for_recordings(self, timeout: float | None = None) -> bool:
+        with self._recordings_done:
+            return self._recordings_done.wait_for(lambda: self._recordings == 0, timeout)
+
+    def server_close(self) -> None:
+        super().server_close()
+        self.wait_for_recordings()
+
 
 class ExecWeaveHTTPProxyHandler(BaseHTTPRequestHandler):
     server: ExecWeaveHTTPProxyServer

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/_http_proxy_bounded.py

@@ -4,7 +4,9 @@ import http.client
 import itertools
 import json
 import os
+import socket
 import tempfile
+import threading
 from pathlib import Path
 from typing import Any, Iterator
 
@@ -486,34 +488,73 @@ def relay_default(handler: _base.ExecWeaveHTTPProxyHandler) -> None:
         return
     finally:
         connection.close()
+
+    def record() -> None:
+        try:
+            if capture is not None:
+                capture.finish()
+                _record_capture(
+                    handler.server.proxy_config,
+                    exchange_id=exchange_id,
+                    request_body=body,
+                    response_content_type=response_type,
+                    method=handler.command,
+                    request_path=target,
+                    status=status,
+                    capture=capture,
+                )
+            else:
+                handler.server.recorder(
+                    handler.server.proxy_config,
+                    exchange_id=exchange_id,
+                    method=handler.command,
+                    request_path=target,
+                    request_body=body,
+                    request_content_type=handler.headers.get("Content-Type"),
+                    status=status,
+                    response_body=bytes(response_body),
+                    response_content_type=response_type,
+                    request_recorded=request_recorded,
+                )
+        except Exception as exc:
+            print(f"ExecWeave HTTP proxy recorder warning: {exc}", file=_base.sys.stderr)
+        finally:
+            if capture is not None:
+                capture.cleanup()
+
+    _record_after_response(handler, record)
+
+
+# Recording normally finishes in well under this, so the client still sees the end
+# of the response only once its evidence is on disk. A slow disk, lock or scanner
+# must not hold the user's program, though: past this point the response is ended
+# while recording finishes, and closing the server waits for it.
+_CLIENT_RELEASE_SECONDS = 2.0
+
+
+def _record_after_response(handler: _base.ExecWeaveHTTPProxyHandler, record) -> None:
+    server = handler.server
+    server.begin_recording()
+
+    def run() -> None:
+        try:
+            record()
+        finally:
+            server.end_recording()
+
+    worker = threading.Thread(target=run, name="execweave-proxy-record", daemon=True)
     try:
-        if capture is not None:
-            capture.finish()
-            _record_capture(
-                handler.server.proxy_config,
-                exchange_id=exchange_id,
-                request_body=body,
-                response_content_type=response_type,
-                method=handler.command,
-                request_path=target,
-                status=status,
-                capture=capture,
-            )
-        else:
-            handler.server.recorder(
-                handler.server.proxy_config,
-                exchange_id=exchange_id,
-                method=handler.command,
-                request_path=target,
-                request_body=body,
-                request_content_type=handler.headers.get("Content-Type"),
-                status=status,
-                response_body=bytes(response_body),
-                response_content_type=response_type,
-                request_recorded=request_recorded,
-            )
-    except Exception as exc:
-        print(f"ExecWeave HTTP proxy recorder warning: {exc}", file=_base.sys.stderr)
-    finally:
-        if capture is not None:
-            capture.cleanup()
+        worker.start()
+    except RuntimeError:
+        run()
+        return
+    worker.join(_CLIENT_RELEASE_SECONDS)
+    if worker.is_alive():
+        # HTTP/1.0 with Connection: close and no Content-Length, so the client
+        # treats the end of the stream as the end of the response.
+        try:
+            handler.wfile.flush()
+            handler.connection.shutdown(socket.SHUT_WR)
+        except OSError:
+            pass
+        worker.join()

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/_http_proxy_stage.py

@@ -6,6 +6,7 @@ from . import _http_proxy_base as _base
 from . import model_runtime_full_fidelity as _runtime_ff
 from . import openai_compatible_full_fidelity as _openai_ff
 from ._http_proxy_base import *  # noqa: F403
+from .privacy import full_content_capture_enabled
 
 
 # OpenAI-compatible request config is request-side evidence too. Without this relation
@@ -435,6 +436,8 @@ def record_exchange_fail_open(
     request_only: bool = False,
     request_recorded: bool = False,
 ) -> bool:
+    if not full_content_capture_enabled():
+        return False
     try:
         if request_only:
             return _record_request_phase(

{execweave-0.8.33 → execweave-0.8.35}/src/execweave/agent_bootstrap.py

@@ -8,6 +8,8 @@ from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Mapping
 
+from .hook_command import hook_argv, hook_command, hook_markers
+
 _AUTO_FLAG = "--auto"
 _CONFIG_RETRIES = 3
 _SUPPORTED_AGENTS = {
@@ -73,7 +75,7 @@ def _read_bytes(path: Path) -> bytes | 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:
+        if isinstance(command, str) and any(value in command for value in hook_markers(marker)):
             return True
         return any(_contains_execweave_command(child, marker) for child in value.values())
     if isinstance(value, list):
@@ -81,6 +83,28 @@ def _contains_execweave_command(value: object, marker: str) -> bool:
     return False
 
 
+def _migrate_hook_commands(value: object, marker: str) -> bool:
+    """Upgrade only our old canonical bare entry point, retaining user settings."""
+    changed = False
+    if isinstance(value, dict):
+        command = value.get("command")
+        if isinstance(command, str):
+            prefix = f"{marker} --auto"
+            suffix = command[len(prefix):] if command.startswith(prefix) else None
+            valid_suffixes = {"", " --event PreInvocation", " --event PostInvocation",
+                              " --event PostToolUse", " --event Stop"}
+            if suffix in valid_suffixes:
+                provider = marker.removeprefix("execweave-").removesuffix("-hook")
+                value["command"] = hook_command(provider) + suffix
+                changed = True
+        for child in value.values():
+            changed = _migrate_hook_commands(child, marker) or changed
+    elif isinstance(value, list):
+        for child in value:
+            changed = _migrate_hook_commands(child, marker) or changed
+    return changed
+
+
 def _merge_hook_fragment(
     current: dict[str, Any],
     fragment: dict[str, Any],
@@ -88,7 +112,7 @@ def _merge_hook_fragment(
     marker: str,
 ) -> tuple[dict[str, Any], bool]:
     merged = deepcopy(current)
-    changed = False
+    changed = _migrate_hook_commands(merged, marker)
 
     for key, value in fragment.items():
         if key == "hooks":
@@ -135,8 +159,9 @@ def _merge_named_hook_fragment(
 ) -> tuple[dict[str, Any], bool]:
     """Merge Antigravity's named-hook ``hooks.json`` schema conservatively."""
     merged = deepcopy(current)
+    changed = _migrate_hook_commands(merged, marker)
     if _contains_execweave_command(merged, marker):
-        return merged, False
+        return merged, changed
     for name, definition in fragment.items():
         if name in merged:
             raise FileExistsError(
@@ -215,9 +240,11 @@ def _write_plugin_file(path: Path, content: str, *, marker: str) -> bool:
                 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:
+            if existing == content:
                 return False
-            raise FileExistsError(f"refusing to replace existing OpenCode plugin: {path}")
+            from .opencode_plugin_cli import plugin_text
+            if existing != plugin_text(("execweave-opencode-hook", _AUTO_FLAG)):
+                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}")
@@ -254,11 +281,11 @@ 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"
+        return claude_hook_config(hook_command("claude")), "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"
+        return codex_hook_config(hook_command("codex")), "execweave-codex-hook"
     if provider == "antigravity":
         from .antigravity_hook_cli import antigravity_hook_config
 
@@ -266,7 +293,7 @@ def _provider_fragment(provider: str) -> tuple[dict[str, Any], str]:
     if provider == "cursor":
         from .cursor_hook_cli import cursor_hook_config
 
-        return cursor_hook_config(f"execweave-cursor-hook {_AUTO_FLAG}"), "execweave-cursor-hook"
+        return cursor_hook_config(hook_command("cursor")), "execweave-cursor-hook"
     raise ValueError(f"provider does not use JSON hooks: {provider}")
 
 
@@ -293,7 +320,7 @@ def bootstrap_supported_agent(
         if provider == "opencode":
             from .opencode_plugin_cli import plugin_text
 
-            content = plugin_text(("execweave-opencode-hook", _AUTO_FLAG))
+            content = plugin_text(tuple(hook_argv("opencode")))
             changed = _write_plugin_file(target, content, marker="execweave-opencode-hook")
         else:
             fragment, marker = _provider_fragment(provider)
@@ -317,10 +344,10 @@ def bootstrap_supported_agent(
 
         return AgentBootstrapResult(
             provider=provider,
-            status="active",
+            status="configured_unverified",
             path=str(target),
             changed=changed,
-            detail="specialized hook/plugin bootstrap is configured",
+            detail="specialized hook/plugin configured; delivery unverified",
         )
     except (FileExistsError, OSError, RuntimeError, TypeError, ValueError) as exc:
         return AgentBootstrapResult(
@@ -330,3 +357,39 @@ def bootstrap_supported_agent(
             changed=False,
             detail=_bounded_detail(exc),
         )
+
+
+def inspect_supported_agent(
+    command: list[str], *, home: str | Path | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> AgentBootstrapResult:
+    """Read configuration only. Configuration is never proof of hook delivery."""
+    provider = supported_agent(command)
+    if provider is None:
+        return AgentBootstrapResult(provider=None, status="unavailable",
+                                    detail="no specialized lifecycle integration")
+    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:
+        raw = _read_bytes(target)
+        if raw is None:
+            return AgentBootstrapResult(provider=provider, status="not_configured", path=str(target),
+                                        detail=f"Run execweave hooks install {provider} explicitly; never use sudo")
+        if provider == "opencode":
+            present = any(marker in raw.decode("utf-8")
+                          for marker in hook_markers("execweave-opencode-hook"))
+        else:
+            config = _load_json_object(raw, path=target)
+            present = _contains_execweave_command(config, f"execweave-{provider}-hook")
+            if provider == "claude" and config.get("disableAllHooks") is True:
+                present = False
+            if provider == "antigravity":
+                group = config.get("execweave-observability", {})
+                present = present and isinstance(group, dict) and group.get("enabled") is True
+        return AgentBootstrapResult(provider=provider,
+                                    status="configured_unverified" if present else "not_configured",
+                                    path=str(target), detail="delivery must be verified from recorded evidence")
+    except (OSError, ValueError, UnicodeError) as exc:
+        return AgentBootstrapResult(provider=provider, status="bootstrap_failed", path=str(target),
+                                    detail=type(exc).__name__)