multi-forge 0.4.0__tar.gz → 0.6.0__tar.gz

{multi_forge-0.4.0 → multi_forge-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.4.0
+Version: 0.6.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,15 +56,18 @@ 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 today, Codex 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`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+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`, and Forge handles the rest -- routing to your chosen
+model provider, tracking state across sessions, and enforcing policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -223,12 +226,14 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.4.0 → multi_forge-0.6.0}/README.md

@@ -15,15 +15,18 @@
 **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 today, Codex 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`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+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`, and Forge handles the rest -- routing to your chosen
+model provider, tracking state across sessions, and enforcing policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -182,12 +185,14 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.4.0 → multi_forge-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.4.0"
+version = "0.6.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.4.0 → multi_forge-0.6.0}/src/forge/__init__.py

@@ -1,3 +1,3 @@
 """Multi-Forge - Multi-runtime agent toolkit."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{multi_forge-0.4.0 → multi_forge-0.6.0}/src/forge/cli/activity.py

@@ -100,7 +100,10 @@ def _render(summary: SessionActivitySummary, *, days: int | None) -> None:
         for c in summary.commands:
             errors = f"[red]{c.errors}[/red]" if c.errors else "0"
             tokens = f"{c.input_tokens}/{c.output_tokens}" if (c.input_tokens or c.output_tokens) else "-"
-            cost = f"~{_fmt_usd(c.cost_micro_usd)}" if c.cost_micro_usd is not None else "-"
+            if c.cost_micro_usd is None:
+                cost = "-"
+            else:
+                cost = f"{'~' if c.cost_estimated else ''}{_fmt_usd(c.cost_micro_usd)}"
             row = [c.command, str(c.calls)]
             if show_workers:
                 row.append(str(c.workers) if c.workers else "-")
@@ -110,17 +113,26 @@ def _render(summary: SessionActivitySummary, *, days: int | None) -> None:
 
     pol = summary.policy
     if pol and pol.has_content:
-        console.print(
-            f"\n[bold]Supervisor[/bold]: {pol.supervisor_allow} allow · "
-            f"{pol.supervisor_warn} warn · {pol.supervisor_deny} block"
-        )
+        if pol.plan_check_allow or pol.plan_check_needs_review:
+            console.print(
+                f"\n[bold]Plan check (tier-1)[/bold]: {pol.plan_check_allow} allow · "
+                f"{pol.plan_check_needs_review} needs review"
+            )
+        if pol.supervisor_allow or pol.supervisor_warn or pol.supervisor_deny or pol.total_warnings:
+            console.print(
+                f"\n[bold]Supervisor[/bold]: {pol.supervisor_allow} allow · "
+                f"{pol.supervisor_warn} warn · {pol.supervisor_deny} block"
+            )
         for warning in pol.recent_warnings:
             console.print(f"  [yellow]•[/yellow] {warning}")
 
     if summary.subagents:
         console.print(f"\n[bold]Subagents[/bold]: {summary.subagents}")
 
-    total_cost = f"~{_fmt_usd(summary.total_cost_micro_usd)}" if summary.total_cost_micro_usd is not None else "n/a"
+    if summary.total_cost_micro_usd is None:
+        total_cost = "n/a"
+    else:
+        total_cost = f"{'~' if summary.cost_estimated else ''}{_fmt_usd(summary.total_cost_micro_usd)}"
     console.print(
         f"\n[dim]Total:[/dim] {summary.total_events} events · "
         f"{summary.total_input_tokens}/{summary.total_output_tokens} tok · {total_cost}"
@@ -138,7 +150,12 @@ def _footnotes(summary: SessionActivitySummary) -> list[str]:
         notes.append("policy decision log is at capacity — older decisions may not be shown")
     if summary.session_tagging_partial:
         notes.append("some calls (e.g. the action tagger) are not session-attributed")
-    notes.append("cost is reported-or-estimated, best-effort; 'forge proxy costs show' is the authoritative spend view")
+    # "no snapshot estimates" covers both exact sources: the 4g cost-plane root-join
+    # and runtime-reported (runtime_native) self-reports. A cost-less summary keeps
+    # the generic caveat -- there is no figure to call exact.
+    exact = summary.total_cost_micro_usd is not None and not summary.cost_estimated
+    evidence = "reported (no snapshot estimates mixed in)" if exact else "reported-or-estimated"
+    notes.append(f"cost is {evidence}, best-effort; 'forge proxy costs show' is the authoritative spend view")
     return notes
 
 

{multi_forge-0.4.0 → multi_forge-0.6.0}/src/forge/cli/extensions.py

@@ -99,15 +99,18 @@ def _parse_modules(modules_str: str | None) -> set[InstallModule] | None:
     return {InstallModule(m.strip()) for m in modules_str.split(",")}
 
 
-def _count_actions(plan: InstallPlan) -> tuple[int, int]:
+def _count_actions(plan: InstallPlan) -> tuple[int, int, int]:
     """Count non-skip actions in a plan.
 
     Returns:
-        Tuple of (file_actions, settings_actions) that are not skips.
+        Tuple of (file_actions, settings_actions, codex_actions) that
+        actually change something. A codex install/update counts as an
+        action so a codex-only change never renders "Already up to date.".
     """
     file_actions = sum(1 for f in plan.files if f.action != "skip")
     settings_actions = sum(1 for s in plan.settings if s.action != "skip")
-    return file_actions, settings_actions
+    codex_actions = 1 if plan.codex is not None and plan.codex.action in ("install", "update") else 0
+    return file_actions, settings_actions, codex_actions
 
 
 # Modules that are intentionally empty in the source tree (only .gitkeep).
@@ -165,8 +168,8 @@ def _print_completion_message(
     tracking: TrackingStore,
 ) -> None:
     """Print appropriate completion message based on what was done."""
-    file_actions, settings_actions = _count_actions(plan)
-    total_actions = file_actions + settings_actions
+    file_actions, settings_actions, codex_actions = _count_actions(plan)
+    total_actions = file_actions + settings_actions + codex_actions
 
     _warn_if_modules_have_no_files(plan, scope, project_root, tracking)
 
@@ -178,6 +181,8 @@ def _print_completion_message(
             parts.append(f"{file_actions} file{'s' if file_actions != 1 else ''}")
         if settings_actions > 0:
             parts.append(f"{settings_actions} setting{'s' if settings_actions != 1 else ''}")
+        if codex_actions > 0:
+            parts.append("Codex hooks")
         console.print(f"\n[green]Extensions enabled.[/green] ({', '.join(parts)} updated)")
 
     print_tip(
@@ -200,6 +205,30 @@ def _print_completion_message(
         required = gated[0][1].value
         print_tip(f"Additional skills available with --profile {required}: {skill_list}", console=console)
 
+    _print_codex_completion(plan, scope)
+
+
+def _print_codex_completion(plan: InstallPlan, scope: InstallScope) -> None:
+    """Print the trust-ceremony guidance (or skip notice) for the codex plan.
+
+    Registration alone is inert: Codex hooks fire only after the user's
+    one-time interactive trust ceremony, which Forge can neither perform nor
+    verify -- so a fresh registration always names the ceremony explicitly.
+    """
+    codex = plan.codex
+    if codex is None:
+        return
+    if codex.action in ("install", "update"):
+        where = "in any project" if scope == InstallScope.USER else "in this project"
+        config = display_path(codex.config_path) if codex.config_path else "config.toml"
+        console.print("\n[dim]Next steps (Codex hooks):[/dim]")
+        console.print(f"  - Forge hooks are registered in {config} but stay inert until trusted.")
+        console.print(f"  - Run 'codex' interactively {where} and grant trust when prompted (one-time).")
+    elif codex.action == "conflict":
+        console.print(f"\n[yellow]Warning:[/yellow] Codex hook registration skipped: {codex.reason}")
+    elif codex.action == "unavailable":
+        console.print(f"\n[dim]Codex hooks skipped: {codex.reason}.[/dim]")
+
 
 def _validate_anchor(anchor: Path) -> None:
     """Reject anchors that point inside a ``.claude/`` directory.
@@ -324,6 +353,23 @@ def _print_plan(plan: InstallPlan, dry_run: bool = False) -> None:
 
         console.print(table)
 
+    if plan.codex is not None:
+        console.print(f"\n{prefix}[bold]Codex hooks (config.toml):[/bold]")
+        table = Table(show_header=True, header_style="bold", box=None)
+        table.add_column("ACTION", style="dim")
+        table.add_column("TARGET")
+        table.add_column("REASON", style="dim")
+        style = {
+            "install": "green",
+            "update": "yellow",
+            "skip": "dim",
+            "conflict": "yellow",  # best-effort: degrades to skip, never blocks
+            "unavailable": "dim",
+        }.get(plan.codex.action, "")
+        target = display_path(plan.codex.config_path) if plan.codex.config_path else ""
+        table.add_row(plan.codex.action, target, plan.codex.reason or "", style=style)
+        console.print(table)
+
     if plan.has_conflicts:
         console.print(f"\n{prefix}[bold red]Conflicts detected:[/bold red]")
         for c in plan.conflicts:
@@ -467,7 +513,7 @@ def extensions() -> None:
     "--with",
     "-w",
     "with_modules",
-    help="Add modules (comma-separated: commands,agents,skills,hooks,status-line,permissions)",
+    help="Add modules (comma-separated: commands,agents,skills,hooks,status-line,permissions,codex-hooks)",
 )
 @click.option(
     "--without",
@@ -672,8 +718,8 @@ def sync_cmd(scope: str | None, force: bool) -> None:
             console.print("\n[red]Sync failed due to conflicts.[/red]")
             sys.exit(1)
         else:
-            file_actions, settings_actions = _count_actions(plan)
-            total_actions = file_actions + settings_actions
+            file_actions, settings_actions, codex_actions = _count_actions(plan)
+            total_actions = file_actions + settings_actions + codex_actions
             if total_actions == 0:
                 console.print("\n[dim]Already up to date.[/dim]")
             else:
@@ -682,8 +728,15 @@ def sync_cmd(scope: str | None, force: bool) -> None:
                     parts.append(f"{file_actions} file{'s' if file_actions != 1 else ''}")
                 if settings_actions > 0:
                     parts.append(f"{settings_actions} setting{'s' if settings_actions != 1 else ''}")
+                if codex_actions > 0:
+                    parts.append("Codex hooks")
                 console.print(f"\n[green]Sync complete.[/green] ({', '.join(parts)} updated)")
 
+            # A synced block can carry NEW entries whose trust is not yet
+            # granted (per-entry trusted_hash) -- the ceremony guidance
+            # matters most exactly here.
+            _print_codex_completion(plan, install_scope)
+
     except NoForgeInstallationError as e:
         console.print(f"[red]Error:[/red] {e}")
         sys.exit(1)
@@ -788,6 +841,10 @@ def disable_cmd(scope: str | None, uninstall_all: bool, yes: bool) -> None:
             console.print("[bold]Settings:[/bold]")
             console.print(table)
 
+        if existing.codex_config_path:
+            console.print("\n[bold]Codex hooks:[/bold]")
+            console.print(f"  [red]remove[/red] managed block in {display_path(existing.codex_config_path)}")
+
         if not yes:
             if not click.confirm("\nProceed with disable?"):
                 console.print("[dim]Cancelled.[/dim]")
@@ -926,6 +983,8 @@ def status_cmd(scope: str | None, path: str | None, show_all: bool, as_json: boo
                     "modules": list(inst.modules_enabled),
                     "files_count": len(inst.files),
                     "settings_count": len(inst.settings_entries),
+                    "codex_config_path": inst.codex_config_path,
+                    "codex_commands": list(inst.codex_commands),
                     "installed_at": inst.installed_at,
                     "updated_at": inst.updated_at,
                 }
@@ -966,6 +1025,8 @@ def status_cmd(scope: str | None, path: str | None, show_all: bool, as_json: boo
         console.print(f"  Modules:   {', '.join(installation.modules_enabled)}")
         console.print(f"  Files:     {len(installation.files)}")
         console.print(f"  Settings:  {len(installation.settings_entries)} entries")
+        if installation.codex_config_path:
+            console.print(f"  Codex:     hooks registered in {display_path(installation.codex_config_path)}")
         console.print(f"  Installed: {installation.installed_at}")
         console.print(f"  Updated:   {installation.updated_at}")
 

{multi_forge-0.4.0 → multi_forge-0.6.0}/src/forge/cli/gc.py

@@ -16,9 +16,9 @@ from forge.core.ops.gc import CleanError, CleanReport, collect_clean_report, run
 @click.command("clean")
 @click.option(
     "--scope",
-    type=click.Choice(["repo", "project", "all"]),
-    default="repo",
-    help="Scope: repo (default), project, or all",
+    type=click.Choice(["workspace", "project", "all"]),
+    default="workspace",
+    help="Scope: workspace (default), project, or all",
 )
 @click.option("--yes", "-y", is_flag=True, help="Actually delete (default is dry-run)")
 @click.option("--verbose", "-v", is_flag=True, help="Show individual items")
@@ -31,7 +31,7 @@ def clean_cmd(scope: str, yes: bool, verbose: bool, as_json: bool) -> None:
     Examples:
 
     \b
-        forge clean                       # Dry-run (scope: repo)
+        forge clean                       # Dry-run (scope: workspace)
         forge clean --yes                 # Actually clean
         forge clean --scope all --yes     # Clean globally
         forge clean --scope project       # Current Forge project only

{multi_forge-0.4.0 → multi_forge-0.6.0}/src/forge/cli/hooks/_group.py

@@ -8,11 +8,12 @@ import click
 @click.group(name="hook", hidden=True)
 @click.pass_context
 def hooks(ctx: click.Context) -> None:
-    """Hook handlers invoked by Claude Code.
+    """Hook handlers invoked by agent runtimes.
 
-    Most subcommands are invoked automatically by Claude Code hooks
-    configured in .claude/settings.local.json. The 'enable' and
-    'disable' subcommands are user-facing.
+    Most subcommands are invoked automatically by runtime hooks: Claude Code's
+    are configured in .claude/settings.local.json; Codex's (codex-policy-check)
+    are registered in a Codex config and require trust enrollment. The 'enable'
+    and 'disable' subcommands are user-facing.
     """
     from forge.core.logging import configure_debug_logging
 

multi_forge-0.6.0/src/forge/cli/hooks/codex_patch.py

@@ -0,0 +1,129 @@
+"""Parser for Codex's apply_patch envelope (PreToolUse ``tool_input.command``).
+
+System boundary: the patch text arrives in a Codex hook payload (external data),
+so the parser is strict but the caller fails open -- ``None`` means "not a patch
+Forge can reason about", and the hook allows the action rather than guessing.
+Codex's own apply_patch rejects input outside this grammar, so failing open on
+malformed text converges with native behavior.
+
+Grammar (codex-cli 0.138.0; witness fixture in ``tests/fixtures/codex/hooks/``)::
+
+    *** Begin Patch
+    *** Add File: <path> | *** Update File: <path> | *** Delete File: <path>
+    *** Move to: <path>        (only immediately after an Update header)
+    <body lines prefixed +, -, space, or @@; blank lines are context>
+    *** End of File            (tolerated inside add/update sections)
+    *** End Patch
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from forge.policy.types import extract_added_lines
+
+PatchOpKind = Literal["add", "update", "delete"]
+
+_BEGIN = "*** Begin Patch"
+_END = "*** End Patch"
+_EOF_MARKER = "*** End of File"
+_MOVE_TO = "*** Move to: "
+_HEADERS: tuple[tuple[str, PatchOpKind], ...] = (
+    ("*** Add File: ", "add"),
+    ("*** Update File: ", "update"),
+    ("*** Delete File: ", "delete"),
+)
+
+
+@dataclass(frozen=True)
+class PatchFileOp:
+    """One file operation parsed from an apply_patch envelope.
+
+    ``path`` is the post-op path (the "Move to" target when present) -- policies
+    judge where content lands, not where it came from. The pre-move path is
+    recoverable from ``raw_section``.
+    """
+
+    kind: PatchOpKind
+    path: str
+    move_to: str | None
+    added_content: str  # introduced lines ("" for delete)
+    raw_section: str  # verbatim header + body (raw_diff source)
+
+
+@dataclass
+class _Section:
+    kind: PatchOpKind
+    path: str
+    move_to: str | None = None
+    header_lines: list[str] = field(default_factory=list)
+    body: list[str] = field(default_factory=list)
+
+    def finalize(self) -> PatchFileOp:
+        body = "\n".join(self.body)
+        return PatchFileOp(
+            kind=self.kind,
+            path=self.move_to or self.path,
+            move_to=self.move_to,
+            added_content="" if self.kind == "delete" else extract_added_lines(body),
+            raw_section="\n".join(self.header_lines + self.body),
+        )
+
+
+def parse_apply_patch(command: str) -> list[PatchFileOp] | None:
+    """Parse an apply_patch envelope into per-file operations.
+
+    Returns None for anything outside the known grammar (caller fails open);
+    an empty envelope (Begin + End only) returns [].
+    """
+    lines = [line.rstrip("\r") for line in command.split("\n")]
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    while lines and not lines[-1].strip():
+        lines.pop()
+    if not lines or lines[0] != _BEGIN or lines[-1] != _END or len(lines) < 2:
+        return None
+
+    ops: list[PatchFileOp] = []
+    current: _Section | None = None
+
+    for line in lines[1:-1]:
+        header = _match_header(line)
+        if header is not None:
+            kind, path = header
+            if not path:
+                return None
+            if current is not None:
+                ops.append(current.finalize())
+            current = _Section(kind=kind, path=path, header_lines=[line])
+        elif line.startswith(_MOVE_TO):
+            # Only valid immediately after an Update header (no body yet, one move max).
+            target = line[len(_MOVE_TO) :].strip()
+            if current is None or current.kind != "update" or current.body or current.move_to or not target:
+                return None
+            current.move_to = target
+            current.header_lines.append(line)
+        elif line == _EOF_MARKER:
+            if current is None or current.kind == "delete":
+                return None
+            current.body.append(line)  # kept verbatim in raw_section; extract_added_lines ignores it
+        elif current is None:
+            return None  # body line before any section header
+        elif current.kind == "delete":
+            return None  # Delete sections are bodyless in the grammar
+        elif line == "" or line.startswith(("+", "-", " ", "@@")):
+            current.body.append(line)
+        else:
+            return None
+
+    if current is not None:
+        ops.append(current.finalize())
+    return ops
+
+
+def _match_header(line: str) -> tuple[PatchOpKind, str] | None:
+    for prefix, kind in _HEADERS:
+        if line.startswith(prefix):
+            return kind, line[len(prefix) :].strip()
+    return None