openreflex 0.5.2__tar.gz → 0.7.0__tar.gz

{openreflex-0.5.2/src/openreflex.egg-info → openreflex-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.5.2
-Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
+Version: 0.7.0
+Summary: Ambient project muscle memory for AI coding agents: learns and reuses project Reflexes automatically
 Author: vishnu-77
 License-Expression: MIT
 Project-URL: Homepage, https://openreflex.cc
@@ -54,9 +54,10 @@ Dynamic: license-file
 
 ## What is OpenReflex
 
-OpenReflex gives AI coding agents muscle memory across coding, investigation, and reasoning work. It plugs into
-Claude Code, Codex, Cursor, and OpenCode through lifecycle hooks and MCP, quietly records how each task actually
-went, and hands the next similar task the useful parts of that experience.
+OpenReflex gives AI coding agents ambient project muscle memory across coding, investigation, and reasoning work.
+Lifecycle hooks quietly record how work actually goes, compile repeated project behaviour into reusable Reflexes,
+and inject only the relevant project procedure into new tasks. The model does not need to remember to call OpenReflex,
+and MCP diagnostics are opt-in rather than loaded into normal agent context.
 
 You install it once and keep working normally. Core memory stays on your machine in a local SQLite database.
 There is no OpenReflex account or hosted service. Optional Claude token accounting uses Claude Code's local
@@ -64,17 +65,18 @@ OpenTelemetry export to a loopback-only OpenReflex receiver and stores counts on
 
 <p align="center">
   <a href="docs/walkthrough.md">
-    <img alt="Recording of a real Claude Code session with OpenReflex: OpenReflex reports one similar past task and adds 162 context tokens, Claude finds and fixes the coupon bug, runs the tests, records the verified outcome through OpenReflex's MCP tool, and OpenReflex shows the completion recap with the path taken and observed cost" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
+    <img alt="Recording of a Claude Code session with OpenReflex: OpenReflex injects compact prior context, Claude fixes the task and runs verification, and lifecycle hooks close the outcome automatically" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
   </a>
   <br>
-  <sub>A real Claude Code session, recorded from the terminal and sped up. OpenReflex had seen one similar task in this repository, so it adds 162 tokens of context before the first tool call; after the fix, Claude records the outcome through OpenReflex's MCP tool. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
+  <sub>A recorded Claude Code session. OpenReflex injects compact relevant context before work; lifecycle hooks capture tools and verification and close the execution automatically. MCP is not required for the normal path. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
 </p>
 
 ## Why OpenReflex
 
-- **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
-  compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
-  such as which edit resolved a recurring error.
+- **It learns how the project behaves.** OpenReflex compiles successful work into project-scoped Reflexes such as
+  authentication changes, Helm configuration, database migrations or CI work. Resolution combines semantic intent,
+  task family and module/file locality, so a novel task can reuse a project procedure without repeating an
+  earlier task.
 - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
   runaway context growth raise one alert that says whether to continue, pivot to another approach, or stop and
   check in with you, never a stream of nags.
@@ -98,7 +100,7 @@ Requires Python 3.11 or newer.
 ```bash
 pipx install openreflex            # or: uv tool install openreflex
 cd your-project
-openreflex install claude-code     # writes hooks + MCP config and enables this project
+openreflex install claude-code     # hooks-only ambient runtime; enables this project
 ```
 
 ```
@@ -106,8 +108,8 @@ OPENREFLEX / CONNECT
   agent       claude-code
   project     D:\demo\shop
   config      updated 2 files
+              D:\demo\shop\.openreflex.json
               D:\demo\shop\.claude\settings.json
-              D:\demo\shop\.mcp.json
   memory      enabled
   storage     local
 
@@ -134,10 +136,10 @@ OpenReflex installs per project with `openreflex install <agent>`, or as a plugi
 
 | Agent | Connects through | Install | Verified |
 |---|---|---|---|
-| **Claude Code** | Plugin, or hooks + MCP | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
-| **Codex** | Plugin, or hooks + MCP | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
-| **Cursor** | Hooks + MCP | `openreflex install cursor` | Protocol and fuzz tests |
-| **OpenCode** | Plugin + MCP | `openreflex install opencode` | Protocol and fuzz tests |
+| **Claude Code** | Plugin hooks, or project hooks | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
+| **Codex** | Plugin hooks, or project hooks | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
+| **Cursor** | Lifecycle hooks | `openreflex install cursor` | Protocol and fuzz tests |
+| **OpenCode** | Local lifecycle plugin | `openreflex install opencode` | Protocol and fuzz tests |
 
 With a plugin install, enable each project with `openreflex approve`. Per-agent guides:
 [Claude Code](https://openreflex.cc/claude-code), [Codex](https://openreflex.cc/codex), [Cursor](https://openreflex.cc/cursor),
@@ -166,8 +168,9 @@ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
   left and with the best untried alternative. The alert ends with a recommendation to **continue**, **pivot**
   to another strategy, or **stop** and ask the user. Each problem, pivot, or stop is raised once, with a cooldown
   between messages.
-- **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
-  available, and are otherwise inferred from work-mode-appropriate evidence. The **Path check** says either
+- **After a task:** lifecycle hooks close the execution automatically from work-mode-appropriate evidence; the model
+  does not need to call OpenReflex. Explicit MCP outcome/path operations remain available only for manual or diagnostic
+  workflows. The **Path check** says either
   `better option: <path>` when comparable completed tasks support it or `better option: none proven`.
   Recommendations are never presented as paths that were actually executed.
 
@@ -180,10 +183,13 @@ Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=
 Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
 `~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
 
-Agents can also query OpenReflex directly through its MCP server.
+Normal work does **not** load OpenReflex MCP tools. If you explicitly want model-facing introspection for a project,
+enable it with `openreflex diagnostics enable <agent>`. Disable it again with
+`openreflex diagnostics disable <agent>`. The standalone MCP Registry package remains available for users who
+deliberately install OpenReflex as an MCP server.
 
 <details>
-<summary><strong>The 12 MCP tools</strong></summary>
+<summary><strong>The optional MCP diagnostics/admin tools</strong></summary>
 
 | Tool | What it does |
 |---|---|
@@ -206,8 +212,9 @@ Agents can also query OpenReflex directly through its MCP server.
 
 | Command | Purpose |
 |---|---|
-| `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
-| `uninstall <agent> [--dry-run]` | Remove OpenReflex's project hooks and MCP config; captured memory is kept |
+| `install <agent> [--dry-run]` | Install the hooks-only ambient runtime and enable the project |
+| `diagnostics enable/disable <agent>` | Explicitly opt in/out of model-facing MCP diagnostics |
+| `uninstall <agent> [--dry-run]` | Remove OpenReflex's integration entries; captured memory is kept |
 | `update [--check] [--reinstall]` | Check or update a managed pipx/uv-tool installation; optionally force a reinstall |
 | `self reinstall` | Repair/reinstall the managed OpenReflex package while preserving memory/config |
 | `self uninstall --yes` | Remove only the managed OpenReflex package; memory/config remain on disk |
@@ -219,7 +226,8 @@ Agents can also query OpenReflex directly through its MCP server.
 | `forget --yes` | Delete the project's data |
 | `tokens enable` / `tokens status` / `tokens disable` | Opt in to local Claude Code token accounting, inspect it, or remove OpenReflex-owned telemetry settings |
 | `benchmark` | Run the simulated benchmark |
-| `hook <agent> <event>` / `mcp` | Used by agent configs |
+| `hook <agent> <event>` | Used by ambient agent integrations |
+| `mcp` | Run the optional diagnostics/admin MCP server explicitly |
 
 ## Privacy
 

{openreflex-0.5.2 → openreflex-0.7.0}/README.md

@@ -22,9 +22,10 @@
 
 ## What is OpenReflex
 
-OpenReflex gives AI coding agents muscle memory across coding, investigation, and reasoning work. It plugs into
-Claude Code, Codex, Cursor, and OpenCode through lifecycle hooks and MCP, quietly records how each task actually
-went, and hands the next similar task the useful parts of that experience.
+OpenReflex gives AI coding agents ambient project muscle memory across coding, investigation, and reasoning work.
+Lifecycle hooks quietly record how work actually goes, compile repeated project behaviour into reusable Reflexes,
+and inject only the relevant project procedure into new tasks. The model does not need to remember to call OpenReflex,
+and MCP diagnostics are opt-in rather than loaded into normal agent context.
 
 You install it once and keep working normally. Core memory stays on your machine in a local SQLite database.
 There is no OpenReflex account or hosted service. Optional Claude token accounting uses Claude Code's local
@@ -32,17 +33,18 @@ OpenTelemetry export to a loopback-only OpenReflex receiver and stores counts on
 
 <p align="center">
   <a href="docs/walkthrough.md">
-    <img alt="Recording of a real Claude Code session with OpenReflex: OpenReflex reports one similar past task and adds 162 context tokens, Claude finds and fixes the coupon bug, runs the tests, records the verified outcome through OpenReflex's MCP tool, and OpenReflex shows the completion recap with the path taken and observed cost" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
+    <img alt="Recording of a Claude Code session with OpenReflex: OpenReflex injects compact prior context, Claude fixes the task and runs verification, and lifecycle hooks close the outcome automatically" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
   </a>
   <br>
-  <sub>A real Claude Code session, recorded from the terminal and sped up. OpenReflex had seen one similar task in this repository, so it adds 162 tokens of context before the first tool call; after the fix, Claude records the outcome through OpenReflex's MCP tool. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
+  <sub>A recorded Claude Code session. OpenReflex injects compact relevant context before work; lifecycle hooks capture tools and verification and close the execution automatically. MCP is not required for the normal path. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
 </p>
 
 ## Why OpenReflex
 
-- **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
-  compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
-  such as which edit resolved a recurring error.
+- **It learns how the project behaves.** OpenReflex compiles successful work into project-scoped Reflexes such as
+  authentication changes, Helm configuration, database migrations or CI work. Resolution combines semantic intent,
+  task family and module/file locality, so a novel task can reuse a project procedure without repeating an
+  earlier task.
 - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
   runaway context growth raise one alert that says whether to continue, pivot to another approach, or stop and
   check in with you, never a stream of nags.
@@ -66,7 +68,7 @@ Requires Python 3.11 or newer.
 ```bash
 pipx install openreflex            # or: uv tool install openreflex
 cd your-project
-openreflex install claude-code     # writes hooks + MCP config and enables this project
+openreflex install claude-code     # hooks-only ambient runtime; enables this project
 ```
 
 ```
@@ -74,8 +76,8 @@ OPENREFLEX / CONNECT
   agent       claude-code
   project     D:\demo\shop
   config      updated 2 files
+              D:\demo\shop\.openreflex.json
               D:\demo\shop\.claude\settings.json
-              D:\demo\shop\.mcp.json
   memory      enabled
   storage     local
 
@@ -102,10 +104,10 @@ OpenReflex installs per project with `openreflex install <agent>`, or as a plugi
 
 | Agent | Connects through | Install | Verified |
 |---|---|---|---|
-| **Claude Code** | Plugin, or hooks + MCP | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
-| **Codex** | Plugin, or hooks + MCP | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
-| **Cursor** | Hooks + MCP | `openreflex install cursor` | Protocol and fuzz tests |
-| **OpenCode** | Plugin + MCP | `openreflex install opencode` | Protocol and fuzz tests |
+| **Claude Code** | Plugin hooks, or project hooks | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
+| **Codex** | Plugin hooks, or project hooks | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
+| **Cursor** | Lifecycle hooks | `openreflex install cursor` | Protocol and fuzz tests |
+| **OpenCode** | Local lifecycle plugin | `openreflex install opencode` | Protocol and fuzz tests |
 
 With a plugin install, enable each project with `openreflex approve`. Per-agent guides:
 [Claude Code](https://openreflex.cc/claude-code), [Codex](https://openreflex.cc/codex), [Cursor](https://openreflex.cc/cursor),
@@ -134,8 +136,9 @@ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
   left and with the best untried alternative. The alert ends with a recommendation to **continue**, **pivot**
   to another strategy, or **stop** and ask the user. Each problem, pivot, or stop is raised once, with a cooldown
   between messages.
-- **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
-  available, and are otherwise inferred from work-mode-appropriate evidence. The **Path check** says either
+- **After a task:** lifecycle hooks close the execution automatically from work-mode-appropriate evidence; the model
+  does not need to call OpenReflex. Explicit MCP outcome/path operations remain available only for manual or diagnostic
+  workflows. The **Path check** says either
   `better option: <path>` when comparable completed tasks support it or `better option: none proven`.
   Recommendations are never presented as paths that were actually executed.
 
@@ -148,10 +151,13 @@ Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=
 Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
 `~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
 
-Agents can also query OpenReflex directly through its MCP server.
+Normal work does **not** load OpenReflex MCP tools. If you explicitly want model-facing introspection for a project,
+enable it with `openreflex diagnostics enable <agent>`. Disable it again with
+`openreflex diagnostics disable <agent>`. The standalone MCP Registry package remains available for users who
+deliberately install OpenReflex as an MCP server.
 
 <details>
-<summary><strong>The 12 MCP tools</strong></summary>
+<summary><strong>The optional MCP diagnostics/admin tools</strong></summary>
 
 | Tool | What it does |
 |---|---|
@@ -174,8 +180,9 @@ Agents can also query OpenReflex directly through its MCP server.
 
 | Command | Purpose |
 |---|---|
-| `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
-| `uninstall <agent> [--dry-run]` | Remove OpenReflex's project hooks and MCP config; captured memory is kept |
+| `install <agent> [--dry-run]` | Install the hooks-only ambient runtime and enable the project |
+| `diagnostics enable/disable <agent>` | Explicitly opt in/out of model-facing MCP diagnostics |
+| `uninstall <agent> [--dry-run]` | Remove OpenReflex's integration entries; captured memory is kept |
 | `update [--check] [--reinstall]` | Check or update a managed pipx/uv-tool installation; optionally force a reinstall |
 | `self reinstall` | Repair/reinstall the managed OpenReflex package while preserving memory/config |
 | `self uninstall --yes` | Remove only the managed OpenReflex package; memory/config remain on disk |
@@ -187,7 +194,8 @@ Agents can also query OpenReflex directly through its MCP server.
 | `forget --yes` | Delete the project's data |
 | `tokens enable` / `tokens status` / `tokens disable` | Opt in to local Claude Code token accounting, inspect it, or remove OpenReflex-owned telemetry settings |
 | `benchmark` | Run the simulated benchmark |
-| `hook <agent> <event>` / `mcp` | Used by agent configs |
+| `hook <agent> <event>` | Used by ambient agent integrations |
+| `mcp` | Run the optional diagnostics/admin MCP server explicitly |
 
 ## Privacy
 

{openreflex-0.5.2 → openreflex-0.7.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openreflex"
-version = "0.5.2"
-description = "Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live"
+version = "0.7.0"
+description = "Ambient project muscle memory for AI coding agents: learns and reuses project Reflexes automatically"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]

{openreflex-0.5.2 → openreflex-0.7.0}/src/openreflex/__init__.py

@@ -1,3 +1,3 @@
 """Ambient, local execution intelligence."""
 
-__version__ = "0.5.2"
+__version__ = "0.7.0"

{openreflex-0.5.2 → openreflex-0.7.0}/src/openreflex/cli.py

@@ -80,6 +80,33 @@ def cmd_install(args) -> int:
     return 0
 
 
+def cmd_diagnostics(args) -> int:
+    from .install import install_diagnostics, uninstall_diagnostics
+
+    project = _project(args.project)
+    operation = install_diagnostics if args.diagnostics_action == "enable" else uninstall_diagnostics
+    changes = operation(args.agent, project, dry_run=args.dry_run)
+    verb = "would update" if args.dry_run else ("enabled" if args.diagnostics_action == "enable" else "disabled")
+    print("OPENREFLEX / DIAGNOSTICS")
+    print(f"  action      {args.diagnostics_action}")
+    print(f"  agent       {args.agent}")
+    print(f"  project     {project}")
+    if changes:
+        print(f"  config      {verb} {len(changes)} file{'s' if len(changes) != 1 else ''}")
+        for change in changes:
+            print(f"              {change}")
+    else:
+        state = "already enabled" if args.diagnostics_action == "enable" else "already disabled"
+        print(f"  config      {state}")
+    print("  runtime     ambient hooks remain active")
+    if not args.dry_run and args.diagnostics_action == "enable":
+        print("\n  [ok] optional MCP diagnostics enabled")
+        print("  note        normal OpenReflex work does not require MCP calls")
+    elif not args.dry_run:
+        print("\n  [ok] model-facing MCP diagnostics disabled")
+    return 0
+
+
 def cmd_uninstall(args) -> int:
     from .install import uninstall
 
@@ -122,6 +149,8 @@ def cmd_status(args) -> int:
     print(f"OpenReflex {__version__} - {project}")
     print(f"  enabled: {data['enabled']}   agents: {', '.join(data['engagement']['agents']) or '-'}")
     print(f"  tasks: {data['engagement']['tasks']}   experiences: {data['engagement']['experiences']}   lessons: {data['lessons']}")
+    print(f"  project reflexes: {data['project_reflexes']['visible']} "
+          f"({data['project_reflexes']['learned']} learned / {data['project_reflexes']['proven']} proven)")
     print(f"  first session captured: {data['activation']['first_session_captured']}   "
           f"seconds to first task: {data['activation']['seconds_to_first_task']}")
     print(f"  tasks that used prior experience: {reuse['benefit_rate']}")
@@ -132,6 +161,13 @@ def cmd_status(args) -> int:
           f"{eff['without_prior_experience']['model_tokens']} (observational)")
     print(f"  path checks: {path_check['comparisons']}   better option found: {path_check['better_option_found']}   "
           f"routing agreement: {routing['agreement']}")
+    overhead = data["openreflex_overhead"]
+    print(f"  OpenReflex context: {overhead['estimated_context_tokens']:,} estimated tokens across "
+          f"{overhead['context_injected_tasks']} task(s); {overhead['zero_injection_tasks']} substantial task(s) at zero")
+    print(f"  diagnostic MCP: {overhead['diagnostic_mcp_calls']} call(s), "
+          f"{overhead['diagnostic_mcp_tokens_estimate']:,} estimated result tokens")
+    if overhead["estimated_context_tax"] is not None:
+        print(f"  estimated context tax: {overhead['estimated_context_tax']:.2%} of observed model-token usage")
     print(f"  live alerts: {data['live_alerts'] or '-'}")
     control = data["execution_control"]
     print(f"  verdicts: {control['verdicts'] or '-'}   tasks within tool-call budget: {control['tasks_within_tool_call_budget']}")
@@ -240,7 +276,8 @@ def cmd_update(args) -> int:
         print(f"  note        expected {status.latest}; executable reports {installed}")
     print("  memory      preserved")
     print("  config      preserved")
-    print("\nRestart active Claude Code, Codex, Cursor, or OpenCode sessions to reload hooks and MCP.")
+    print("\nRestart active Claude Code, Codex, Cursor, or OpenCode sessions to reload hooks"
+          " (and diagnostics MCP if you explicitly enabled it).")
     return 0
 
 
@@ -266,7 +303,8 @@ def cmd_self(args) -> int:
         print("\n  [ok] package reinstalled")
         print("  memory      preserved")
         print("  config      preserved")
-        print("\nRestart active agent sessions to reload hooks and MCP.")
+        print("\nRestart active agent sessions to reload hooks"
+              " (and diagnostics MCP if you explicitly enabled it).")
         return 0
 
     if args.self_action == "uninstall":
@@ -397,7 +435,7 @@ def cmd_benchmark(args) -> int:
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="openreflex", description="Ambient execution intelligence for coding agents.",
-        epilog="Also available: tui, memory, tokens, statusline (run `openreflex <name> --help` for details).",
+        epilog="Also available: tui, memory, reflexes, tokens, statusline (run `openreflex <name> --help` for details).",
     )
     parser.add_argument("--version", action="version", version=__version__)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -420,14 +458,26 @@ def build_parser() -> argparse.ArgumentParser:
         command.add_argument("--project")
         command.set_defaults(func=func)
 
-    for name, func, text in (("install", cmd_install, "Connect OpenReflex hooks + MCP for an agent"),
-                             ("uninstall", cmd_uninstall, "Disconnect OpenReflex hooks + MCP while preserving memory")):
+    for name, func, text in (("install", cmd_install, "Connect the ambient OpenReflex hook runtime for an agent"),
+                             ("uninstall", cmd_uninstall, "Disconnect OpenReflex while preserving memory")):
         command = sub.add_parser(name, help=text)
         command.add_argument("agent", choices=AGENT_CHOICES)
         command.add_argument("--project")
         command.add_argument("--dry-run", action="store_true")
         command.set_defaults(func=func)
 
+    diagnostics = sub.add_parser(
+        "diagnostics",
+        help="Opt in/out of the model-facing MCP diagnostics surface; ambient hooks do not require it",
+    )
+    diagnostics_sub = diagnostics.add_subparsers(dest="diagnostics_action", required=True)
+    for action in ("enable", "disable"):
+        command = diagnostics_sub.add_parser(action, help=f"{action.capitalize()} optional MCP diagnostics")
+        command.add_argument("agent", choices=AGENT_CHOICES)
+        command.add_argument("--project")
+        command.add_argument("--dry-run", action="store_true")
+        command.set_defaults(func=cmd_diagnostics)
+
     update = sub.add_parser("update", help="Check PyPI and safely update the managed OpenReflex installation")
     update_group = update.add_mutually_exclusive_group()
     update_group.add_argument("--check", action="store_true", help="Only report whether an update is available")

{openreflex-0.5.2 → openreflex-0.7.0}/src/openreflex/decision.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import asdict, dataclass, field
 from typing import Iterable
 
-from .models import CandidatePath, Experience
+from .models import CandidatePath, Execution, Experience, Task
 from .policy import Policy
 
 
@@ -46,6 +46,7 @@ class DecisionSnapshot:
     outcome: str | None = None
     model_tokens: int | None = None
     token_usage: dict[str, int | float] = field(default_factory=dict)
+    reflex_name: str | None = None
 
     def as_dict(self) -> dict:
         return asdict(self)
@@ -102,7 +103,8 @@ def make_snapshot(*, now: float, phase: str, action: str, best: CandidatePath |
                   actual_tool_calls: int | None = None, actual_tokens: int | None = None,
                   elapsed_seconds: float | None = None, outcome: str | None = None,
                   expected_regret: float | None = None, model_tokens: int | None = None,
-                  token_usage: dict[str, int | float] | None = None) -> DecisionSnapshot:
+                  token_usage: dict[str, int | float] | None = None,
+                  reflex_name: str | None = None) -> DecisionSnapshot:
     if best is None:
         components = {name: 0.0 for name in policy.table("score.weights")}
         score = reflex_score(components, policy)
@@ -116,7 +118,7 @@ def make_snapshot(*, now: float, phase: str, action: str, best: CandidatePath |
             reason_codes=[], visibility=_visibility(phase, event, policy), event=event,
             actual_tool_calls=actual_tool_calls, actual_tokens=actual_tokens,
             elapsed_seconds=elapsed_seconds, outcome=outcome, model_tokens=model_tokens,
-            token_usage=token_usage or {},
+            token_usage=token_usage or {}, reflex_name=reflex_name,
         )
 
     components = score_components(best, paths, experiences, policy)
@@ -139,7 +141,7 @@ def make_snapshot(*, now: float, phase: str, action: str, best: CandidatePath |
         score_components=components, reason_codes=reason_codes, visibility=_visibility(phase, event, policy),
         event=event, actual_tool_calls=actual_tool_calls, actual_tokens=actual_tokens,
         elapsed_seconds=elapsed_seconds, outcome=outcome, model_tokens=model_tokens,
-        token_usage=token_usage or {},
+        token_usage=token_usage or {}, reflex_name=reflex_name,
     )
 
 
@@ -148,8 +150,8 @@ def render_recap(snapshot: DecisionSnapshot, previous: DecisionSnapshot | None =
         summary = []
         if snapshot.outcome:
             summary.append(snapshot.outcome)
-        if snapshot.strategy:
-            summary.append(snapshot.strategy)
+        if snapshot.reflex_name:
+            summary.append(snapshot.reflex_name)
 
         cost = []
         if snapshot.actual_tool_calls is not None:
@@ -164,9 +166,9 @@ def render_recap(snapshot: DecisionSnapshot, previous: DecisionSnapshot | None =
         comparison = None
         if snapshot.outcome != "unknown":
             if snapshot.expected_regret is not None and snapshot.next_best_strategy:
-                comparison = f"Path check · better option: {snapshot.next_best_strategy}"
+                comparison = "Path check · another approach may be better"
             else:
-                comparison = "Path check · better option: none proven"
+                comparison = "Path check · no better option proven"
 
         state = {
             "success": "COMPLETE",
@@ -191,11 +193,13 @@ def render_recap(snapshot: DecisionSnapshot, previous: DecisionSnapshot | None =
         success = "?" if snapshot.success_probability is None else f"{snapshot.success_probability:.0%}"
         calls = "?" if snapshot.estimated_tool_calls is None else f"~{snapshot.estimated_tool_calls:.0f} calls"
         tokens = "?" if snapshot.estimated_tokens is None else f"~{snapshot.estimated_tokens / 1000:.0f}k tokens"
-        return (f"{first}\n{snapshot.evidence_count} experiences · {snapshot.strategy or 'unplanned'} {success} · "
+        label = snapshot.reflex_name or "working approach"
+        return (f"{first}\n{snapshot.evidence_count} experiences · {label} · {success} · "
                 f"{calls} · {tokens} · +{snapshot.context_tokens} context tokens")
 
     success = "?" if snapshot.success_probability is None else f"{snapshot.success_probability:.0%}"
-    message = (f"{first}\n{snapshot.action} · {snapshot.strategy or 'unplanned'} {success} · "
+    label = snapshot.reflex_name or "working approach"
+    message = (f"{first}\n{snapshot.action} · {label} · {success} · "
                f"budget {snapshot.budget_used:.0%}")
     if snapshot.next_best_strategy and snapshot.action in {"pivot", "stop"}:
         message += f" · next {snapshot.next_best_strategy}"
@@ -233,3 +237,31 @@ def render_trace(snapshots: list[DecisionSnapshot]) -> str:
             detail += f" · {snapshot.event}"
         lines.append(f"{minute:02d}:{second:02d} {label:<9} {detail}")
     return "\n".join(lines)
+
+
+def render_paths(execution: Execution, task: Task, paths: list[CandidatePath]) -> str:
+    best = min(paths, key=lambda p: (p.dominated_by is not None, not p.within_limits, -p.score))
+    chosen = next((p for p in paths if p.id == execution.chosen_path_id), None)
+    recommended = next((p for p in paths if p.id == execution.recommended_path_id), None)
+    lines = ["OPENREFLEX / PATHS", "",
+             f"Task           {task.task_class} - {task.description}",
+             f"Recommended    {recommended.strategy if recommended else 'n/a'}"]
+    if chosen is not None:
+        lines.append(f"Followed       {chosen.strategy} "
+                      f"({'inferred from tool calls' if execution.chosen_inferred else 'explicit'})")
+    else:
+        lines.append("Followed       not yet determined" +
+                      (" (execution still running)" if execution.ended_at is None
+                       else " (no strategy could be inferred from tool-call evidence)"))
+    lines += ["", "CANDIDATES"]
+    for path in paths:
+        tags = ", ".join(tag for tag in (("recommended" if path is recommended else None),
+                                          ("followed" if path is chosen else None)) if tag)
+        note = (f"dominated by {path.dominated_by}" if path.dominated_by else
+                "over your limit" if not path.within_limits else
+                (f"{path.score:+.2f} vs {best.score:+.2f}" if path is not best else ""))
+        suffix = " ".join(part for part in (f"[{tags}]" if tags else "", f"({note})" if note else "") if part)
+        lines.append(f"  {path.strategy:<14} score {path.score:+.2f}  success {path.success_probability:.0%}  "
+                      f"~{path.tool_calls:.0f} calls  ~{path.time_seconds / 60:.0f} min  risk {path.risk:.2f} "
+                      f"{suffix}".rstrip())
+    return "\n".join(lines)