multi-forge 0.7.0__tar.gz → 0.8.0__tar.gz

{multi_forge-0.7.0 → multi_forge-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.7.0
+Version: 0.8.0
 Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
 Project-URL: Homepage, https://github.com/hapa1i/multi-forge
 Project-URL: Repository, https://github.com/hapa1i/multi-forge
@@ -56,10 +56,10 @@ Description-Content-Type: text/markdown
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
-next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
-verification. You run `forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks
-state across sessions, and enforces configured policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime), adding
+persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
+`forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks state across
+sessions, and enforces configured policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
@@ -128,6 +128,8 @@ tracking, hooks, and all Forge features except multi-model routing. Use `--proxy
 
 - **Platform**: macOS or Linux
 - **Python**: 3.11–3.13 (3.14 blocked on upstream `uvloop` wheels — see #1)
+- **Installer**: [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/) for the recommended global
+  install
 - **Claude Code**: installed and on PATH
 - **Provider auth**: Claude Code login is enough for direct interactive sessions. Proxies and headless workflows need a
   supported API or gateway credential such as `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
@@ -136,14 +138,27 @@ tracking, hooks, and all Forge features except multi-model routing. Use `--proxy
 ## Quick Start
 
 ```bash
-# Install Forge
-pip install multi-forge
+# Install Forge as a global tool (recommended -- puts `forge` on your PATH)
+uv tool install multi-forge
+# or: pipx install multi-forge
 
-# Or for development (editable install from local clone):
-git clone https://github.com/hapa1i/multi-forge.git
-cd multi-forge && pip install -e .
+# Confirm how forge is installed and whether it is globally reachable
+forge extension doctor
 
-# Install extensions (hooks, skills, status line) into Claude Code
+# For development on Forge itself (editable install from a local clone):
+git clone https://github.com/hapa1i/multi-forge.git
+cd multi-forge && uv sync
+# When FORGE_DEV is unset, eligible host hooks use an executable recorded or
+# known-location launcher. Install the persistent editable launcher too:
+./scripts/setup.sh --local
+# Make uv's tool bin available in this shell and future shells:
+uv tool update-shell
+export PATH="$(uv tool dir --bin):$PATH"
+
+# Register only runtime hooks at user scope
+forge extension enable --scope user --profile minimal --with hooks,codex-hooks --without commands
+
+# Then, inside a project: install project-owned assets and settings
 forge extension enable
 
 # Launch Claude with session tracking (no proxy needed)
@@ -249,7 +264,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
 
 ```bash
 forge extension disable
-pip uninstall multi-forge
+uv tool uninstall multi-forge   # or: pipx uninstall multi-forge
 ```
 
 ## License

{multi_forge-0.7.0 → multi_forge-0.8.0}/README.md

@@ -15,10 +15,10 @@
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
-next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
-verification. You run `forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks
-state across sessions, and enforces configured policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime), adding
+persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
+`forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks state across
+sessions, and enforces configured policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
@@ -87,6 +87,8 @@ tracking, hooks, and all Forge features except multi-model routing. Use `--proxy
 
 - **Platform**: macOS or Linux
 - **Python**: 3.11–3.13 (3.14 blocked on upstream `uvloop` wheels — see #1)
+- **Installer**: [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/) for the recommended global
+  install
 - **Claude Code**: installed and on PATH
 - **Provider auth**: Claude Code login is enough for direct interactive sessions. Proxies and headless workflows need a
   supported API or gateway credential such as `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
@@ -95,14 +97,27 @@ tracking, hooks, and all Forge features except multi-model routing. Use `--proxy
 ## Quick Start
 
 ```bash
-# Install Forge
-pip install multi-forge
+# Install Forge as a global tool (recommended -- puts `forge` on your PATH)
+uv tool install multi-forge
+# or: pipx install multi-forge
 
-# Or for development (editable install from local clone):
-git clone https://github.com/hapa1i/multi-forge.git
-cd multi-forge && pip install -e .
+# Confirm how forge is installed and whether it is globally reachable
+forge extension doctor
 
-# Install extensions (hooks, skills, status line) into Claude Code
+# For development on Forge itself (editable install from a local clone):
+git clone https://github.com/hapa1i/multi-forge.git
+cd multi-forge && uv sync
+# When FORGE_DEV is unset, eligible host hooks use an executable recorded or
+# known-location launcher. Install the persistent editable launcher too:
+./scripts/setup.sh --local
+# Make uv's tool bin available in this shell and future shells:
+uv tool update-shell
+export PATH="$(uv tool dir --bin):$PATH"
+
+# Register only runtime hooks at user scope
+forge extension enable --scope user --profile minimal --with hooks,codex-hooks --without commands
+
+# Then, inside a project: install project-owned assets and settings
 forge extension enable
 
 # Launch Claude with session tracking (no proxy needed)
@@ -208,7 +223,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
 
 ```bash
 forge extension disable
-pip uninstall multi-forge
+uv tool uninstall multi-forge   # or: pipx uninstall multi-forge
 ```
 
 ## License

{multi_forge-0.7.0 → multi_forge-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.7.0"
+version = "0.8.0"
 description = "Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration"
 readme = "README.md"
 license = "Apache-2.0"

multi_forge-0.8.0/src/forge/__init__.py

@@ -0,0 +1,16 @@
+"""Multi-Forge - Multi-runtime agent toolkit."""
+
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+# Forge is both a library and a CLI. Keep library warnings from falling through
+# Python's lastResort stderr handler when CLI file logging is disabled.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+try:
+    # Single source of truth is pyproject.toml; reading installed metadata keeps
+    # ``__version__`` from drifting (a hardcoded literal once shipped 0.5.0 while
+    # the package was 0.6.0, poisoning forge_version in manifests and work items).
+    __version__ = version("multi-forge")
+except PackageNotFoundError:  # source tree without an installed dist
+    __version__ = "0.0.0+unknown"

{multi_forge-0.7.0 → multi_forge-0.8.0}/src/forge/backend/registry.py

@@ -12,11 +12,10 @@ Ownership: Forge Backend Manager (`forge model backend` CLI).
 
 from __future__ import annotations
 
-import json
 import logging
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
-from typing import Callable, Literal
+from typing import Any, Callable, Literal, NoReturn
 
 import dacite
 
@@ -26,6 +25,7 @@ from forge.core.state import (
     StateUnreadableError,
     atomic_write_json,
     file_lock_for_target,
+    read_versioned_json_object,
 )
 
 logger = logging.getLogger(__name__)
@@ -99,6 +99,16 @@ def _uses_old_backend_id_process_records(data: object) -> bool:
     return any(isinstance(entry, dict) and "backend_id" in entry for entry in entries.values())
 
 
+def _handle_registry_version_mismatch(path: Path, data: dict[str, Any], version: Any) -> NoReturn:
+    if version == 1 and _uses_old_backend_id_process_records(data):
+        raise BackendRegistryCorruptedError(str(path), OLD_BACKEND_ID_PROCESS_FIELD_TIP)
+    raise BackendRegistryCorruptedError(
+        str(path),
+        f"incompatible version {version} (this Forge expects {BACKEND_REGISTRY_VERSION}). "
+        f"Delete this file and retry.",
+    )
+
+
 class BackendRegistryStore:
     """Manage the backend registry at ~/.forge/backends/index.json.
 
@@ -121,26 +131,14 @@ class BackendRegistryStore:
         if not self.exists():
             return BackendRegistry()
 
-        try:
-            with open(self._registry_path, encoding="utf-8") as f:
-                data = json.load(f)
-        except json.JSONDecodeError as e:
-            raise BackendRegistryCorruptedError(str(self._registry_path), f"invalid JSON: {e}")
-        except OSError as e:
-            # A failed read is environmental, not corruption -- forge clean must not delete it.
-            raise BackendRegistryUnreadableError(str(self._registry_path), f"read error: {e}")
-
-        version = data.get("version")
-        if version is None:
-            raise BackendRegistryCorruptedError(str(self._registry_path), "missing version field")
-        if version != BACKEND_REGISTRY_VERSION:
-            if version == 1 and _uses_old_backend_id_process_records(data):
-                raise BackendRegistryCorruptedError(str(self._registry_path), OLD_BACKEND_ID_PROCESS_FIELD_TIP)
-            raise BackendRegistryCorruptedError(
-                str(self._registry_path),
-                f"incompatible version {version} (this Forge expects {BACKEND_REGISTRY_VERSION}). "
-                f"Delete this file and retry.",
-            )
+        data = read_versioned_json_object(
+            self._registry_path,
+            version_key="version",
+            expected_version=BACKEND_REGISTRY_VERSION,
+            corrupted_error=BackendRegistryCorruptedError,
+            unreadable_error=BackendRegistryUnreadableError,
+            on_version_mismatch=_handle_registry_version_mismatch,
+        )
 
         try:
             return dacite.from_dict(

{multi_forge-0.7.0 → multi_forge-0.8.0}/src/forge/cli/activity.py

@@ -54,7 +54,7 @@ def activity_cmd(session: str | None, as_json: bool, period: str) -> None:
 
     \b
     Examples:
-        forge telemetry activity                  # current session ($FORGE_SESSION)
+        forge telemetry activity                  # current session
         forge telemetry activity planner          # a named session (or Claude UUID)
         forge telemetry activity --period week    # this week
         forge telemetry activity --period all --json

{multi_forge-0.7.0 → multi_forge-0.8.0}/src/forge/cli/claude.py

@@ -18,6 +18,10 @@ import httpx
 from rich.console import Console
 
 from forge.cli.output import err_console, print_error, print_error_with_tip
+from forge.core.models.direct_model import (
+    apply_direct_model_env,
+    apply_proxy_context_model_defaults,
+)
 from forge.core.paths import display_path
 from forge.core.reactive.env import FORGE_PROXY_WIRE_SHAPE_VAR, resolve_proxy_wire_shape
 from forge.proxy.proxies import (
@@ -25,10 +29,6 @@ from forge.proxy.proxies import (
     ProxyResolutionError,
 )
 from forge.session.context_limit import _get_context_limit_for_proxy
-from forge.session.direct_model import (
-    apply_direct_model_env,
-    apply_proxy_context_model_defaults,
-)
 
 console = Console()
 
@@ -151,7 +151,7 @@ def start_cmd(
 ) -> None:
     """Start Claude Code with proxy routing or direct to Anthropic.
 
-    Bare launcher: no session state, no FORGE_SESSION.  Use
+    Bare launcher: no session state (not a managed session). Use
     ``forge session start`` for managed sessions with lifecycle tracking.
 
     \b
@@ -308,7 +308,7 @@ def preset_show(raw: bool = False, as_json: bool = False) -> None:
         return
 
     if raw:
-        console.print(content, end="")
+        click.echo(content, nl=False)
     else:
         console.print("[bold]Claude Code Settings Preset[/bold]")
         console.print(f"[bold]Path:[/bold] {display_path(preset_path)}")

{multi_forge-0.7.0 → multi_forge-0.8.0}/src/forge/cli/codex.py

@@ -29,6 +29,10 @@ from forge.core.paths import display_path
 from forge.core.runtime import get_runtime
 from forge.core.runtime.codex_preflight import codex_proxy_contract_blocker
 from forge.install.codex_hooks import (
+    CodexRegistrationKey,
+    codex_expected_registration_keys,
+    codex_registration_key,
+    codex_registration_keys,
     codex_registration_pairs,
     get_builtin_codex_entries,
     get_codex_config_path,
@@ -108,23 +112,24 @@ def _runtime_info() -> _RuntimeInfo:
 
 
 def _enrollment_posture(
-    expected: set[tuple[str, str]],
-    actual: set[tuple[str, str]],
-    commands_registered: tuple[str, ...],
+    expected: set[CodexRegistrationKey],
+    actual: set[CodexRegistrationKey],
 ) -> str:
     """Classify static registration as yes/no/partial/wrong-event (no probe).
 
-    `expected` is the builtin (event, command) set; `actual` is the event-aware
-    set really in the config; `commands_registered` is the event-agnostic set of
-    our commands found anywhere. A command present by name but not under its
-    expected event is `wrong-event` (not merely missing).
+    `expected` is the builtin logical (event, command identity) set; `actual`
+    is the event-aware logical set really in the config. A command identity
+    present under the wrong event is `wrong-event` (not merely missing).
     """
     if expected <= actual:
         return "yes"
-    present_cmds = set(commands_registered)
-    if not present_cmds:
+    expected_event_by_identity = {(kind, value): event for event, kind, value in expected}
+    matching_actual = [
+        (event, kind, value) for event, kind, value in actual if (kind, value) in expected_event_by_identity
+    ]
+    if not matching_actual:
         return "no"
-    wrong_event = any((ev, cmd) not in actual and cmd in present_cmds for ev, cmd in expected)
+    wrong_event = any(event != expected_event_by_identity[(kind, value)] for event, kind, value in matching_actual)
     return "wrong-event" if wrong_event else "partial"
 
 
@@ -177,9 +182,9 @@ def _scope_status(scope: InstallScope, project_root: Path | None, tracking: Trac
     config_path = get_codex_config_path(scope, project_root)
     entries = get_builtin_codex_entries()
     registration = read_codex_registration(config_path, entries)
-    actual = codex_registration_pairs(config_path)
-    expected = {(e.event, e.command) for e in entries}
-    forge_commands = {e.command for e in entries}
+    actual_pairs = codex_registration_pairs(config_path)
+    actual_keys = codex_registration_keys(config_path)
+    expected_keys = codex_expected_registration_keys(entries)
 
     tracked_path: str | None = None
     tracked_commands: list[str] = []
@@ -195,9 +200,11 @@ def _scope_status(scope: InstallScope, project_root: Path | None, tracking: Trac
         config_path=display_path(config_path),
         config_exists=config_path.exists(),
         block_present=registration.block_present,
-        registered=_enrollment_posture(expected, actual, registration.commands_registered),
+        registered=_enrollment_posture(expected_keys, actual_keys),
         # Forge footprint only: unrelated user hooks in the same config are not ours to report.
-        registered_pairs=sorted(f"{ev} -> {cmd}" for ev, cmd in actual if cmd in forge_commands),
+        registered_pairs=sorted(
+            f"{ev} -> {cmd}" for ev, cmd in actual_pairs if codex_registration_key(ev, cmd) in expected_keys
+        ),
         commands_registered=list(registration.commands_registered),
         tracked_config_path=display_path(tracked_path) if tracked_path else None,
         tracked_commands=tracked_commands,
@@ -376,7 +383,9 @@ def start_cmd(proxy: str, sandbox: str, codex_args: tuple[str, ...]) -> None:
         # wire_shape is "openai_responses_passthrough" on success (uninformative); the
         # failure path names the actual shape via the exception instead.
         default_model, _ = assert_proxy_responses_capable(
-            entry.base_url, expected_proxy_id=entry.proxy_id, expected_template=entry.template
+            entry.base_url,
+            expected_proxy_id=entry.proxy_id,
+            expected_template=entry.template,
         )
     except ProxyUnreachableError as e:
         print_error_with_tip(