@fml-inc/fml 0.8.10-dev.1 → 0.8.11-rc.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fml",
-  "version": "0.8.10-dev.1",
+  "version": "0.8.11-rc.1",
   "description": "FML agent tools for Claude Code",
   "mcpServers": {
     "fml": {

package/README.md

@@ -66,6 +66,117 @@ plugin-namespaced skill.
 For a coding agent operating in a sandbox, use the
 [agent installation guide](./docs/agent_installation_guide.md).
 
+### mini-swe-agent v2
+
+FML supports native v2 `DefaultAgent`/`InteractiveAgent` with `LocalEnvironment`.
+Install mini and its dependencies yourself (Python >=3.10, Pydantic >=2), activate
+that environment, and retain your native model credentials:
+
+```bash
+fml install
+mini -t "Your task" -o ./mini-run.traj.json
+```
+
+Successful Mini setup uses the shared installation summary; Mini-specific output
+is reserved for warnings.
+
+Native `mini-swe-agent` and `python -m minisweagent` entrypoints also work.
+No wrapper, `PYTHONPATH` export, or adapter flag is required. Installation probes
+package metadata without importing mini or loading its `.env`; activation needs
+writable site-packages. An absent Mini installation or unrelated executable named
+`mini` is optional, not a warning. An existing activation is retained when Mini
+is unavailable. Recognized Mini prerequisite failures and activation conflicts
+still warn without blocking general FML setup.
+
+An ASCII-only owned `.pth` loads a guarded bootstrap bound to the selected Python
+prefix, including paths with non-ASCII characters.
+Hook delivery uses owned absolute Node and hook-handler paths recorded at
+installation; it does not resolve `fml` or Node from the runtime PATH.
+Automatic capture leaves ordinary Python commands and other environments native,
+including environments inheriting that site-packages directory. Native YAML,
+`.env`, model/mode/limit/output settings, and configuration edits remain
+authoritative. `fml doctor` silently checks prerequisites, activation, and ownership
+of the managed adapter and hook-command assets. It shows a Mini-specific warning
+only when a recognized installation needs attention; missing or modified assets
+warn without changing files. Installation does not guarantee capture for custom
+configurations.
+
+Explicit `-c`/`--config` (including short-option clusters such as `-yc`) and
+`--agent-class` opt out unless they select an FML adapter. Supplying `-c` replaces
+mini's default config list: include the native base first, such as
+`-c mini.yaml -c local-overlay.yaml`. CLI class selection wins
+over YAML. To capture an explicit configuration, select
+`--agent-class fml_mini_agent.FmlInteractiveAgent` or
+`--agent-class fml_mini_agent.FmlDefaultAgent`.
+Native `-o` overrides YAML `agent.output_path`, including its default when omitted.
+Custom agents, remote environments, mini v1, and batch/SWE-bench are unsupported.
+
+The adapter preserves native confirmation, human/yolo modes, interruptions,
+completion, and exceptions. FML requests run through bash using the CLI-only
+workflow; there is no native `/fml`, `$fml`, MCP client, or `fml review` command.
+The bundled workflow is model-visible without being printed as a user message in
+the interactive terminal. Capture-only interruptions after execution preserve
+the native result or pending exception, including during observation snapshots,
+before interrupting further native work.
+Capture interruptions before native execution discard the pending execution
+record, so the final snapshot does not report a command that never ran.
+
+Each `run()` receives a UUID; interactive continuation keeps it. Native output is
+unchanged. Atomic snapshots retain the complete native trajectory plus FML
+identity, actual execution, context, cwd, and message-observation metadata under
+`<FML data directory>/mini-swe-agent/trajectories/<UUID>.traj.json`.
+Managed snapshots omit native `info.config.model.model_kwargs` and
+`info.config.environment.env`; native configuration and output retain both.
+Messages and tool output remain raw, not generally credential-redacted.
+Sync replaces the session projection as this full JSON snapshot changes, rather
+than appending JSONL. Rejected proposals are not executed bash calls, and injected
+context is not a human prompt. Usage views count reasoning/cache tokens once,
+including native OpenRouter cache-write details; unknown usage remains unknown.
+Native cumulative costs are scoped to each run.
+
+Snapshots require `fml.human_message_indices`, recorded at native input boundaries
+and tied to retained message objects. Blank interruption and mode-switch feedback
+do not create human turns; genuine comments and human commands still do, even
+when their text matches generated feedback. Projection does not infer provenance
+from message text or accept snapshots missing this metadata.
+Provenance is recorded before interruptible hook delivery, so accepted native
+input keeps its human role if capture is interrupted.
+Human-mode shell commands retain their raw whitespace, including mode-like text
+that native Mini treats as a command. Confirmation and interruption responses
+follow their native caller's input decision instead of a global trim heuristic.
+
+Capture uses the bounded, fail-open hook inbox and authenticated destination
+binding. Dynamic server context is supported, but disabled for mini by default.
+Admins can opt an organization in through the existing dynamic-context policy
+with the Convex-safe override `{"harnesses":{"miniSweAgent":true}}`; organization
+override lookup failures leave mini disabled. Other harness defaults are unchanged,
+and the public target/source remains `mini-swe-agent`.
+
+The hook's JSON transport uses explicit UTF-8 encoding, independent of Python's
+locale, so Unicode context is preserved at the native model boundary.
+
+The initial native task and actual interactive human prompts arm a `BeforeModel`
+request immediately before the next provider call. Native slash/mode controls,
+generated feedback, and tool continuations do not rearm it. Returned context is
+inserted quietly into native messages without printing a user message; snapshots
+record its position in `fml.context_message_indices`, so it is not classified as
+human input. Both requests and insertion honor pause state, including a pause
+while a request is in flight. Deferred capture interruptions are delivered before
+the next provider call or tool execution, without replacing completed native
+results or exceptions.
+
+`fml stop` pauses hooks, context, and snapshots, not native history; resuming
+publishes the complete cumulative run, including its paused interval.
+Reinstall repairs a missing owned `.pth` after environment revalidation.
+When Mini resolves to a different interpreter, reinstall moves the unchanged
+owned activation to that environment; no prior uninstall is required.
+Modified hooks and destination conflicts are preserved with a warning.
+Updates retain activation if mini is unavailable. Uninstall removes unchanged
+owned files without editing native YAML or `.env`; modified/conflicting files
+retain their dependencies with a warning. Trajectories remain unless `--purge`
+is explicit, and unrelated or modified files are preserved even during purge.
+Resolve reported ownership conflicts manually.
+
 ## Upgrading from standalone Panopticon
 
 Earlier releases shipped as a separate `@fml-inc/panopticon` package that
@@ -98,9 +209,9 @@ them into local session, message, tool-call, or scanner tables. Server-side
 scanners own parsing and projections.
 
 Discovery covers supported local stores across Claude Code, Codex, Gemini,
-Grok, Cursor, Pi, Copilot CLI, and Factory Droid, including archived Codex
-sessions. Availability depends on which harnesses have written artifacts on
-the machine.
+Grok, Cursor, Pi, mini-swe-agent, Copilot CLI, and Factory Droid, including
+archived Codex sessions and managed mini full-trajectory snapshots.
+Availability depends on which harnesses have written artifacts on the machine.
 
 Sync has one persistent setting: enabled or disabled. It defaults to enabled.
 The backend environment, login, and selected organization determine the upload

package/agent-assets/mini-swe-agent/FML_WORKFLOW.md

@@ -0,0 +1,62 @@
+<!-- fml-managed-agent-surface:v1 -->
+
+# FML workflow for mini-swe-agent
+
+Use FML only when explicitly requested. Invoke its real CLI through bash;
+mini has no native FML skill, slash command, or MCP client. With no requested
+command, give concise help rather than performing an operation.
+
+## CLI routing and safety
+
+- Select `review` before CLI discovery: it is the agent workflow below, **not**
+  a CLI command. Never execute `fml review` or delegate the review to the CLI.
+- Discover commands with `fml commands` and `fml <command> --help`. Discover
+  backend tools with `fml tools list --json` and `fml tools describe <name> --json`;
+  never guess tool names or schemas.
+- Call described tools with `fml tools call <name> --args '<json>'` or `--file <path>`
+  for nested/multiline JSON. Use the CLI for install, authentication, environments,
+  observer, sync, and read-only structured data.
+- Activity/history reads synced data in the selected organization, not a local
+  analytics database. Summarize large results unless raw output was requested.
+- Apply the user's approval rules to mutations. Explain destructive operations,
+  including `sync reset` and `uninstall --purge`, before executing them. Native
+  mini confirmation is not a substitute for approval. Do not silently mutate
+  integrations, automations, memory, or analyses.
+- Diagnose with `fml doctor`; use `fml login --device` when browser callbacks are
+  unavailable. Never print credentials or tokens. Report unavailable commands
+  and failures without inventing results or retrying indefinitely.
+
+## FML review
+
+1. Read repository instructions. Establish the branch and explicit/PR base;
+   otherwise use `refs/remotes/origin/HEAD`, then local `main` or `master`.
+   Do not fetch or mutate branches solely for review. Ask if no reliable base exists.
+2. Inspect committed and working-tree changes separately:
+
+   ```bash
+   git status --short
+   git diff --stat <base>...HEAD
+   git diff --find-renames <base>...HEAD
+   git log --oneline <base>..HEAD
+   git diff
+   git diff --cached
+   ```
+
+3. Read complete changed code and relevant callers, tests, schemas, and config.
+   State the base and whether uncommitted changes are included.
+4. Prioritize correctness, security/auth, secrets/privacy, data loss, migrations,
+   concurrency, partial failure, idempotency, public/platform contracts, packaging,
+   install/removal symmetry, and meaningful regression coverage. Trace actual
+   execution paths; report concrete triggers, impact, repair, and file/line evidence.
+   Do not report formatting preferences or speculative defects.
+5. Finish code review before consulting FML for uncertain intent. Discover and
+   describe read-only tools before use: `fml_commit_context`, `fml_path_history`,
+   `fml_pr_context`, or `search_engineering_sessions` then `get_session_timeline`.
+   CLI routes include `fml search`, `fml sessions`, and `fml timeline`; inspect help.
+   If unavailable or irrelevant, state the limit and finish from code evidence.
+   Historical intent never excuses a concrete defect.
+6. Report severity-ordered **Findings**, material **Questions / assumptions**, and
+   **Verdict**: Request changes, Approve with comments, or Approve. Use P0 for
+   catastrophic/release-blocking defects, P1 serious, P2 normal correctness, P3 minor.
+   Name meaningful evidence/test gaps even with no findings. Put FML-resolved intent
+   after the verdict in **Follow-up: FML-sourced intent** only when it was used.

package/agent-assets/mini-swe-agent/fml_mini_agent.py

@@ -0,0 +1,483 @@
+# <!-- fml-managed-agent-surface:v1 -->
+"""FML adapters for mini-swe-agent v2's native local agents.
+
+fml install activates these with an interpreter-local, native-CLI bootstrap.
+Native configuration and explicit CLI overrides remain authoritative. This
+module never launches mini; native serialization and output remain native.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from functools import wraps
+from uuid import uuid4
+
+try:
+    from minisweagent import __version__
+    if __version__.split(".")[0] != "2":
+        raise RuntimeError("FML supports mini-swe-agent v2 only; use your existing v2 installation.")
+    from minisweagent.agents.default import DefaultAgent
+    from minisweagent.agents.interactive import InteractiveAgent
+    from minisweagent.environments.local import LocalEnvironment
+    from minisweagent.exceptions import Submitted
+    from minisweagent.models.utils.content_string import get_content_string
+except ImportError as error:
+    raise RuntimeError(
+        "FML requires an existing mini-swe-agent v2 installation and its dependencies in this Python environment."
+    ) from error
+
+
+HOOK_TIMEOUT_SECONDS = 3.5
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _override(name):
+    value = os.environ.get(name, "")
+    if not value.strip():
+        return None
+    path = Path(value)
+    if not path.is_absolute():
+        raise ValueError(f"{name} must be an absolute path: {value}")
+    return path
+
+
+def _platform_base(name, fallback):
+    value = os.environ.get(name, "")
+    return Path(value) if value.strip() and Path(value).is_absolute() else fallback
+
+
+def _data_dir():
+    override = _override("FML_DATA_DIR")
+    if override is not None:
+        return override
+    home = Path.home()
+    if sys.platform == "darwin":
+        return home / "Library" / "Application Support" / "fml"
+    if sys.platform == "win32":
+        return _platform_base("APPDATA", home / "AppData" / "Roaming") / "fml"
+    return _platform_base("XDG_DATA_HOME", home / ".local" / "share") / "fml"
+
+
+def _observer_dir():
+    for name in ("FML_OBSERVER_DIR", "PANOPTICON_HOME"):
+        override = _override(name)
+        if override is not None:
+            return override
+    home = _override("FML_HOME")
+    return home / "panopticon" if home is not None else Path.home() / ".fml" / "panopticon"
+
+
+def _capture_enabled():
+    # An imported, subsequently uninstalled adapter must not resume capture.
+    if not Path(__file__).is_file():
+        return False
+    try:
+        (_observer_dir() / "hook-capture.disabled").lstat()
+    except FileNotFoundError:
+        return True
+    except (OSError, ValueError):
+        return False
+    return False
+
+
+def _hook_command():
+    try:
+        command = json.loads(Path(__file__).with_name("fml_hook_command.json").read_text(encoding="utf-8"))
+        if isinstance(command, list) and len(command) == 2 and all(
+            isinstance(part, str) and Path(part).is_absolute() for part in command
+        ):
+            return command
+    except (OSError, ValueError, TypeError):
+        pass
+    return []
+
+
+def _capture_interrupts(method):
+    """Route capture-only Ctrl-C without replacing pending native exceptions."""
+    @wraps(method)
+    def capture(self, *args, **kwargs):
+        pending_exception = sys.exc_info()[0] is not None
+        try:
+            return method(self, *args, **kwargs)
+        except KeyboardInterrupt:
+            ended = self.messages and self.messages[-1].get("role") == "exit"
+            if not (self._fml_ending or ended or pending_exception) and (
+                self._fml_in_step or not isinstance(self, InteractiveAgent)
+            ):
+                raise
+            self._fml_interrupted = True
+            return {}
+    return capture
+
+
+
+class _FmlMixin:
+    def __init__(self, model, env, **kwargs):
+        if type(env) is not LocalEnvironment:
+            raise ValueError("FML mini-swe-agent supports the native v2 LocalEnvironment only (no remote/batch environments).")
+        super().__init__(model, env, **kwargs)
+        self._fml = None
+        self._fml_hook_command = None
+        self._fml_message_observations = {}
+        self._fml_event_ordinal = 0
+        self._fml_action_message_index = None
+        self._fml_inserting_context = False
+        self._fml_quiet_context = False
+        self._fml_pending_prompt = None
+        self._fml_pending_response = None
+        self._fml_initial_task_pending = False
+        self._fml_prompt_depth = 0
+        self._fml_workflow_inserted = False
+        self._fml_in_step = False
+        self._fml_interrupted = False
+        self._fml_ending = False
+
+    def _fml_cwd(self, cwd=""):
+        return str(Path(cwd or self.env.config.cwd or os.getcwd()).resolve())
+
+    @_capture_interrupts
+    def _fml_hook(self, event_name, **fields):
+        if self._fml is None or not _capture_enabled():
+            return {}
+        ordinal = self._fml_event_ordinal
+        self._fml_event_ordinal += 1
+        payload = {
+            "event_name": event_name,
+            "session_id": self._fml["session_id"],
+            "event_id": f'{self._fml["session_id"]}:{ordinal}',
+            "timestamp": _now(),
+            "cwd": self._fml["cwd"],
+            **fields,
+        }
+        try:
+            if self._fml_hook_command is None:
+                self._fml_hook_command = _hook_command()
+            if not self._fml_hook_command:
+                return {}
+            result = subprocess.run(
+                [*self._fml_hook_command, "mini-swe-agent"],
+                input=json.dumps(payload), text=True, encoding="utf-8", stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL, timeout=HOOK_TIMEOUT_SECONDS, check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                response = json.loads(result.stdout)
+                return response if isinstance(response, dict) else {}
+        except (OSError, subprocess.SubprocessError, ValueError, TypeError):
+            pass
+        return {}
+
+    @_capture_interrupts
+    def _fml_snapshot(self):
+        if self._fml is None or not _capture_enabled():
+            return
+        temporary = None
+        try:
+            self._fml["updated_at"] = _now()
+            # Snapshot-only copies: native serialization/configuration still
+            # owns the opaque provider kwargs and environment overrides.
+            data = dict(self.serialize())
+            info = dict(data["info"])
+            config = dict(info["config"])
+            for section, field in (("model", "model_kwargs"), ("environment", "env")):
+                config[section] = {
+                    key: value for key, value in config[section].items() if key != field
+                }
+            info["config"] = config
+            data["info"] = info
+            observed = [
+                self._fml_message_observations.get(id(message))
+                for message in self.messages
+            ]
+            # Match the actual objects, not a historical ordinal: native runs
+            # reset the list, and restored messages may replace earlier rows.
+            observed_at = [
+                entry[1] if entry is not None and entry[0] is message else None
+                for message, entry in zip(self.messages, observed)
+            ]
+            self._fml["message_observed_at_ms"] = observed_at
+            self._fml["human_message_indices"] = [
+                index for index, (message, entry) in enumerate(zip(self.messages, observed))
+                if entry is not None and entry[0] is message and entry[2]
+            ]
+            self._fml["context_message_indices"] = [
+                index for index, (message, entry) in enumerate(zip(self.messages, observed))
+                if entry is not None and entry[0] is message and entry[3]
+            ]
+            data["fml"] = self._fml
+            directory = _data_dir() / "mini-swe-agent" / "trajectories"
+            directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+            destination = directory / f'{self._fml["session_id"]}.traj.json'
+            with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=directory, prefix=".snapshot-", delete=False) as stream:
+                temporary = Path(stream.name)
+                json.dump(data, stream, ensure_ascii=False)
+                stream.flush()
+                os.fsync(stream.fileno())
+            # A pause arriving during serialization must not publish new bytes.
+            if not _capture_enabled():
+                return
+            os.replace(temporary, destination)
+            temporary = None
+            if os.name == "posix":
+                descriptor = os.open(directory, os.O_RDONLY)
+                try:
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+        except Exception as error:
+            self.logger.debug("FML snapshot unavailable: %s", error)
+        finally:
+            if temporary is not None:
+                try:
+                    temporary.unlink(missing_ok=True)
+                except OSError:
+                    pass
+
+    def add_messages(self, *messages):
+        first_index = len(self.messages)
+        # Context bypasses InteractiveAgent's user-message printer, not native formatting.
+        result = DefaultAgent.add_messages(self, *messages) if self._fml_quiet_context else super().add_messages(*messages)
+        if self._fml is not None:
+            observed_at_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+            for index, message in enumerate(self.messages[first_index:], first_index):
+                context = self._fml_inserting_context
+                initial_task = self._fml_initial_task_pending and index == 1 and message.get("role") == "user"
+                extra = message.get("extra", {})
+                # Carry raw input to the native message boundary. Observations
+                # may precede that message; each caller interprets modes itself.
+                response = self._fml_pending_response
+                interrupt_type = extra.get("interrupt_type")
+                human = not context and (initial_task or (
+                    response is not None and message.get("role") == "user" and (
+                        extra.get("actions")
+                        or (interrupt_type in {"UserInterruption", "UserNewTask"}
+                            and response.strip() not in self._MODE_COMMANDS_MAPPING)
+                        or (interrupt_type == "UserRejection" and response.strip() != "/u")
+                    )
+                ))
+                self._fml_message_observations[id(message)] = (message, observed_at_ms, bool(human), context)
+                if human:
+                    if initial_task:
+                        self._fml_initial_task_pending = False
+                    else:
+                        self._fml_pending_response = None
+                        self._fml_submit_prompt(response)
+                if initial_task and not context:
+                    self._fml_submit_prompt(get_content_string(message))
+            self._fml_snapshot()
+        return result
+
+    def _fml_submit_prompt(self, prompt):
+        if self._fml is not None and isinstance(prompt, str) and prompt.strip():
+            self._fml_pending_prompt = prompt
+            self._fml_hook("UserPromptSubmit", prompt=prompt)
+
+    def _fml_add_context(self, content, *, quiet=False):
+        if not content or not isinstance(content, str):
+            return
+        self._fml_inserting_context = True
+        self._fml_quiet_context = quiet
+        try:
+            self.add_messages(self.model.format_message(role="user", content=content))
+        finally:
+            self._fml_inserting_context = False
+            self._fml_quiet_context = False
+
+    @_capture_interrupts
+    def _fml_before_model(self):
+        if not _capture_enabled():
+            return
+        if not self._fml_workflow_inserted:
+            try:
+                workflow = Path(__file__).with_name("FML_WORKFLOW.md").read_text(encoding="utf-8")
+                self._fml_add_context(workflow, quiet=True)
+                self._fml_workflow_inserted = True
+            except Exception as error:
+                self.logger.debug("FML workflow unavailable: %s", error)
+        if self._fml_pending_prompt is not None:
+            prompt = self._fml_pending_prompt
+            self._fml_pending_prompt = None
+            try:
+                response = self._fml_hook("BeforeModel", prompt=prompt)
+                if _capture_enabled():
+                    self._fml_add_context(response.get("context"), quiet=True)
+            except Exception as error:
+                self.logger.debug("FML context unavailable: %s", error)
+
+    def step(self):
+        self._fml_in_step = True
+        try:
+            return super().step()
+        finally:
+            self._fml_in_step = False
+
+    def query(self):
+        if self._fml_interrupted:
+            self._fml_interrupted = False
+            raise KeyboardInterrupt
+        return super().query()
+
+    def execute_actions(self, message):
+        previous = self._fml_action_message_index
+        self._fml_action_message_index = next(
+            (index for index in range(len(self.messages) - 1, -1, -1) if self.messages[index] is message), None
+        )
+        try:
+            return super().execute_actions(message)
+        finally:
+            self._fml_action_message_index = previous
+
+    def save(self, path, *extra_dicts):
+        try:
+            return super().save(path, *extra_dicts)
+        finally:
+            ending = self._fml_ending
+            self._fml_ending = ending or sys.exc_info()[0] is not None
+            try:
+                self._fml_snapshot()
+                self._fml_hook("Stop")
+            finally:
+                self._fml_ending = ending
+
+    def run(self, task="", **kwargs):
+        if self._fml is not None:
+            raise RuntimeError("An FML mini agent cannot run concurrently on the same instance.")
+        started = _now()
+        self._fml = {
+            "version": 1, "session_id": str(uuid4()), "started_at": started,
+            "updated_at": started, "cwd": self._fml_cwd(),
+            "executions": [], "context_message_indices": [], "human_message_indices": [],
+            "model_stats_baseline": {"instance_cost": self.cost, "api_calls": self.n_calls},
+        }
+        self._fml_event_ordinal = 0
+        self._fml_hook_command = None
+        self._fml_message_observations = {}
+        self._fml_pending_prompt = None
+        self._fml_pending_response = None
+        self._fml_initial_task_pending = True
+        self._fml_prompt_depth = 0
+        self._fml_workflow_inserted = False
+        self._fml_interrupted = False
+        self._fml_ending = False
+        original_query = self.model.query
+        original_execute = self.env.execute
+        # Preserve instance attributes exactly, not a lingering bound-method shim.
+        query_attribute = self.model.__dict__.get("query")
+        execute_attribute = self.env.__dict__.get("execute")
+        had_query = "query" in self.model.__dict__
+        had_execute = "execute" in self.env.__dict__
+
+        def query(*args, **query_kwargs):
+            self._fml_before_model()
+            if self._fml_interrupted:
+                self._fml_interrupted = False
+                raise KeyboardInterrupt
+            return original_query(*args, **query_kwargs)
+
+        def execute(action, *args, **execute_kwargs):
+            if self._fml_interrupted:
+                self._fml_interrupted = False
+                raise KeyboardInterrupt
+            cwd = execute_kwargs.get("cwd", args[0] if args else "")
+            record = {
+                "id": f'execution-{len(self._fml["executions"])}',
+                "message_index": self._fml_action_message_index, "action": action,
+                "cwd": self._fml_cwd(cwd), "started_at": _now(),
+            }
+            self._fml["executions"].append(record)
+            try:
+                self._fml_snapshot()
+            except BaseException:
+                # No native execution started. Remove this exact pending row,
+                # not another execution, and preserve the original interruption.
+                executions = self._fml["executions"]
+                for index, pending in enumerate(executions):
+                    if pending is record:
+                        executions.pop(index)
+                        break
+                raise
+            try:
+                output = original_execute(action, *args, **execute_kwargs)
+                record["output"] = output
+                return output
+            except BaseException as error:
+                record["exception"] = {"type": type(error).__name__, "message": str(error)}
+                if hasattr(error, "messages"):
+                    record["exception"]["messages"] = error.messages
+                if isinstance(error, Submitted):
+                    record["submitted"] = True
+                raise
+            finally:
+                record["completed_at"] = _now()
+                # Native execution has finished. Capture must not replace its
+                # return or pending exception; honor Ctrl-C before further work.
+                ending = self._fml_ending
+                self._fml_ending = True
+                try:
+                    self._fml_snapshot()
+                    self._fml_hook(
+                        "PostToolUse", tool_name="bash", tool_input=action,
+                        tool_result=record.get("output", {
+                            "exception": record.get("exception"), "submitted": record.get("submitted", False),
+                        }),
+                    )
+                finally:
+                    self._fml_ending = ending
+
+        self.model.query = query
+        self.env.execute = execute
+        try:
+            self._fml_hook("SessionStart")
+            return super().run(task, **kwargs)
+        finally:
+            # No next step exists: final capture must not replace native results
+            # or exceptions, including a native KeyboardInterrupt.
+            self._fml_ending = True
+            try:
+                self._fml_snapshot()
+                self._fml_hook("SessionEnd")
+            finally:
+                if had_query:
+                    self.model.query = query_attribute
+                else:
+                    del self.model.query
+                if had_execute:
+                    self.env.execute = execute_attribute
+                else:
+                    del self.env.execute
+                self._fml = None
+                self._fml_message_observations = {}
+                self._fml_pending_prompt = None
+                self._fml_pending_response = None
+                self._fml_initial_task_pending = False
+                self._fml_prompt_depth = 0
+                self._fml_interrupted = False
+                self._fml_ending = False
+
+
+class FmlDefaultAgent(_FmlMixin, DefaultAgent):
+    """DefaultAgent with bounded FML capture/context at native boundaries."""
+
+
+class FmlInteractiveAgent(_FmlMixin, InteractiveAgent):
+    """InteractiveAgent retaining native confirmation, human and interrupt flow."""
+
+    def _prompt_and_handle_slash_commands(self, prompt, *, _multiline=False):
+        # Delegate all prompting/mode/confirmation behavior to native Mini. Its
+        # recursive help/multiline prompts produce one final human response.
+        if self._fml_prompt_depth == 0:
+            self._fml_pending_response = None
+        self._fml_prompt_depth += 1
+        try:
+            response = super()._prompt_and_handle_slash_commands(prompt, _multiline=_multiline)
+        finally:
+            self._fml_prompt_depth -= 1
+        if self._fml_prompt_depth == 0 and self._fml is not None and response.strip():
+            self._fml_pending_response = response
+        return response