From 335a960c988cb323a38ef00d38c266d9814fdb33 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 21:24:23 -0400 Subject: [PATCH 1/7] docs: document run modes for the runs API and the MCP start tool --- content/docs/mcp/tools.mdx | 4 ++++ content/docs/reference/api.mdx | 14 +++++++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/content/docs/mcp/tools.mdx b/content/docs/mcp/tools.mdx index 7c33768..efaba1f 100644 --- a/content/docs/mcp/tools.mdx +++ b/content/docs/mcp/tools.mdx @@ -24,6 +24,10 @@ A run prompt can invoke a skill without fetching it: write `$handle` in the `prompt` of `mogplex_start_agent_run`. See [Using Skills](/web/agents/using-skills). +`mogplex_start_agent_run` also takes `mode` (`SAFE`, `AUTO`, or `YOLO`) for +Codex and Claude Code runs. See [Start a run](/reference/api#start-a-run) for +what each mode allows, including the MCP tools that stay callable in `SAFE`. + `mogplex_create_sandbox` consumes the existing launch event stream and returns when the launch succeeds or fails. It does not create a separate status-polling loop. diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 9e40a8b..3479da3 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -748,13 +748,25 @@ type StartRunRequest = { rootDirectory?: string | null; conversationId?: string; workspaceSessionId?: string; - mode?: string; + mode?: "SAFE" | "AUTO" | "YOLO"; // Case-insensitive. Default: AUTO. }; ``` The response is `202 Accepted` with `MogplexApiRunDetail & { replayed: boolean }` inside `data`. +`mode` sets what the harness may do in its sandbox: + +- `SAFE`: the harness doesn't change the checkout. Claude Code plans instead + of editing, and Codex runs read-only. MCP tools are not screened, so a + connection or Mogplex tool that writes (a GitHub issue, a memory, a stdio + server with filesystem access) can still make changes. +- `AUTO`: the harness edits files and runs commands in the sandbox. +- `YOLO`: the harness skips every permission check. + +Any other value returns `400 BAD_REQUEST`. `mode` isn't accepted for runs that +use the Mogplex harness. + When `createBranch` is true and `workingBranch` is omitted, Mogplex creates a deterministic branch name from the idempotency key and request. If supplied, the working branch must differ from the base branch. From a54ca6aa1700792918ae1257b6453aa2c7c9a8da Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 22:17:27 -0400 Subject: [PATCH 2/7] docs(api): show mode on the run detail --- content/docs/reference/api.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 3479da3..331a159 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -717,6 +717,7 @@ type MogplexApiRunDetail = { createBranch: boolean; }; rootDirectory: string | null; + mode: string | null; // The mode the run started with, upper-cased. null: AUTO. eventsUrl: string; cancelUrl: string; createdAt: string; From 9ff363883761f28d0aa30033bcbd407af14f7826 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 22:30:25 -0400 Subject: [PATCH 3/7] docs(api): say what YOLO still blocks on Claude Code --- content/docs/reference/api.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 331a159..3a01a3c 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -763,7 +763,9 @@ The response is `202 Accepted` with connection or Mogplex tool that writes (a GitHub issue, a memory, a stdio server with filesystem access) can still make changes. - `AUTO`: the harness edits files and runs commands in the sandbox. -- `YOLO`: the harness skips every permission check. +- `YOLO`: the harness runs without approval prompts. Claude Code still blocks + its deny-listed tools and commands, such as `curl`, `ssh`, and reading `.env` + files. Any other value returns `400 BAD_REQUEST`. `mode` isn't accepted for runs that use the Mogplex harness. From fb08e6cb767edc73bb54aded787cdb869710824e Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 23:38:40 -0400 Subject: [PATCH 4/7] docs(api): document the mogplex harness and fix the MCP tool count --- content/docs/reference/api.mdx | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 3a01a3c..2054322 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -709,7 +709,7 @@ type MogplexApiRunDetail = { sandboxRecordId: string | null; sandboxId: string | null; repoId: string; - harness: "codex" | "claude-code"; + harness: "codex" | "claude-code" | "mogplex"; status: MogplexApiRunStatus; branch: { base: string; @@ -717,7 +717,10 @@ type MogplexApiRunDetail = { createBranch: boolean; }; rootDirectory: string | null; - mode: string | null; // The mode the run started with, upper-cased. null: AUTO. + // The mode the run started with, upper-cased. null: the default, AUTO, or a + // Mogplex-harness run, which takes no mode. Typed as a string because runs + // started by older Mogplex CLIs can carry other values. + mode: string | null; eventsUrl: string; cancelUrl: string; createdAt: string; @@ -742,7 +745,7 @@ Request body: type StartRunRequest = { repoId: string; prompt: string; // At most 100,000 characters. - harness?: "codex" | "claude-code"; // Default: codex. + harness?: "codex" | "claude-code" | "mogplex"; // Default: codex. baseBranch?: string; workingBranch?: string; createBranch?: boolean; @@ -767,8 +770,12 @@ The response is `202 Accepted` with its deny-listed tools and commands, such as `curl`, `ssh`, and reading `.env` files. -Any other value returns `400 BAD_REQUEST`. `mode` isn't accepted for runs that -use the Mogplex harness. +Any other value returns `400 BAD_REQUEST`. + +`harness: "mogplex"` runs Mogplex's own agent instead of a CLI. It takes no +`mode` (sending one returns `400`), always works on its own branch (it creates +one unless `workingBranch` names a branch other than the base), and reports +`mode: null`. When `createBranch` is true and `workingBranch` is omitted, Mogplex creates a deterministic branch name from the idempotency key and request. If supplied, @@ -887,7 +894,7 @@ https://mogplex.com/api/v1/mogplex/mcp ``` Use [Install Mogplex MCP](/mcp/install) for client setup and OAuth. Use -[MCP tools](/mcp/tools) for all 23 tool argument schemas. +[MCP tools](/mcp/tools) for all 29 tool argument schemas. Request envelope: From 31eaca700fe864b6c20010e2396e95366f08d6a1 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 23:44:12 -0400 Subject: [PATCH 5/7] docs: name the Mogplex harness in the run indexes; clarify null mode --- content/docs/mcp/tools.mdx | 4 ++-- content/docs/reference/api.mdx | 10 ++++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/content/docs/mcp/tools.mdx b/content/docs/mcp/tools.mdx index efaba1f..fc04551 100644 --- a/content/docs/mcp/tools.mdx +++ b/content/docs/mcp/tools.mdx @@ -26,7 +26,7 @@ A run prompt can invoke a skill without fetching it: write `$handle` in the `mogplex_start_agent_run` also takes `mode` (`SAFE`, `AUTO`, or `YOLO`) for Codex and Claude Code runs. See [Start a run](/reference/api#start-a-run) for -what each mode allows, including the MCP tools that stay callable in `SAFE`. +what each mode allows. MCP tools aren't screened in `SAFE` and stay callable. `mogplex_create_sandbox` consumes the existing launch event stream and returns when the launch succeeds or fails. It does not create a separate status-polling @@ -86,7 +86,7 @@ published graph. | Tool | Scope | What it does | | --- | --- | --- | -| `mogplex_start_agent_run` | `write` | Start a Codex or Claude Code run in a repo sandbox. | +| `mogplex_start_agent_run` | `write` | Start a Codex, Claude Code, or Mogplex agent run in a repo sandbox. | | `mogplex_get_run` | `read` | Read current run state and metadata. | | `mogplex_get_run_events` | `read` | Read append-only run events. | | `mogplex_cancel_run` | `write` | Request cancellation of a one-off agent run, not a Flow job. | diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 2054322..7a8804e 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -157,7 +157,7 @@ type MogplexApiError = { | `GET` | [`/automations/{automationId}/runs`](#list-automation-runs) | `read` | List recent automation runs. | | `GET` | [`/automations/{automationId}/runs/{runId}`](#read-automation-run-logs) | `read` | Read detailed automation run logs. | | `POST` | [`/pr-reviews/rerun`](#rerun-a-pr-review) | `write` | Queue a fresh Mogplex PR review. | -| `POST` | [`/runs`](#start-a-run) | `write` | Start a Codex or Claude Code run. | +| `POST` | [`/runs`](#start-a-run) | `write` | Start a Codex, Claude Code, or Mogplex agent run. | | `GET` | [`/runs/{runId}`](#get-a-run) | `read` | Read run state. | | `GET` | [`/runs/{runId}/events`](#list-run-events) | `read` | Read structured run events. | | `POST` | [`/runs/{runId}/cancel`](#cancel-a-run) | `write` | Cancel an active run. | @@ -717,9 +717,11 @@ type MogplexApiRunDetail = { createBranch: boolean; }; rootDirectory: string | null; - // The mode the run started with, upper-cased. null: the default, AUTO, or a - // Mogplex-harness run, which takes no mode. Typed as a string because runs - // started by older Mogplex CLIs can carry other values. + // The mode the request named, upper-cased: an explicit "AUTO" reports + // "AUTO". null when the request omitted mode (AUTO applies) and for a + // Mogplex-harness run, which takes no mode. Typed as a string because the + // Mogplex CLI's cloud runs report the CLI's own run mode (such as "single"), + // which runs as AUTO. mode: string | null; eventsUrl: string; cancelUrl: string; From 9f07b66804388ebf33f9cd90396470b2bff8a1c7 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 28 Sep 2026 23:59:23 -0400 Subject: [PATCH 6/7] docs(api): note the CLI run modes the API still accepts --- content/docs/reference/api.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 7a8804e..55f27f1 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -772,7 +772,10 @@ The response is `202 Accepted` with its deny-listed tools and commands, such as `curl`, `ssh`, and reading `.env` files. -Any other value returns `400 BAD_REQUEST`. +Any other value returns `400 BAD_REQUEST`, except the run modes released +Mogplex CLIs send for their cloud runs (such as `single`). Those are accepted +for compatibility, stored as sent, and run as `AUTO`. New callers should send +one of the three values above. `harness: "mogplex"` runs Mogplex's own agent instead of a CLI. It takes no `mode` (sending one returns `400`), always works on its own branch (it creates From 89898bb28c381340f4b7cacf739926471aa9bbff Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 29 Sep 2026 00:12:43 -0400 Subject: [PATCH 7/7] docs(api): say how legacy CLI modes are reported and which harness sends them --- content/docs/reference/api.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/docs/reference/api.mdx b/content/docs/reference/api.mdx index 55f27f1..40e8a81 100644 --- a/content/docs/reference/api.mdx +++ b/content/docs/reference/api.mdx @@ -717,11 +717,11 @@ type MogplexApiRunDetail = { createBranch: boolean; }; rootDirectory: string | null; - // The mode the request named, upper-cased: an explicit "AUTO" reports - // "AUTO". null when the request omitted mode (AUTO applies) and for a - // Mogplex-harness run, which takes no mode. Typed as a string because the - // Mogplex CLI's cloud runs report the CLI's own run mode (such as "single"), - // which runs as AUTO. + // The mode the request named. SAFE, AUTO, and YOLO are reported upper-cased + // (a request with "auto" reports "AUTO"). null when the request omitted mode + // (AUTO applies) and for a Mogplex-harness run, which takes no mode. Typed + // as a string because the Mogplex CLI's Codex cloud runs report the CLI's + // own run mode as sent (such as "single"), which runs as AUTO. mode: string | null; eventsUrl: string; cancelUrl: string; @@ -773,9 +773,9 @@ The response is `202 Accepted` with files. Any other value returns `400 BAD_REQUEST`, except the run modes released -Mogplex CLIs send for their cloud runs (such as `single`). Those are accepted -for compatibility, stored as sent, and run as `AUTO`. New callers should send -one of the three values above. +Mogplex CLIs send for their cloud runs (such as `single`). Those runs use the +`codex` harness, and those modes are accepted for compatibility, stored as sent, +and run as `AUTO`. New callers should send one of the three values above. `harness: "mogplex"` runs Mogplex's own agent instead of a CLI. It takes no `mode` (sending one returns `400`), always works on its own branch (it creates