GPT tool-protocol compatibility: ApplyPatch and Code Mode

## Status

Accepted on 2026-07-28.

ApplyPatch and Code Mode will ship as independent capabilities over one effective per-run tool surface. Code Mode will execute JavaScript in a short-lived Node child process outside the Maka process. Node's permission model is defense in depth; the child must also run under the current session's existing OS sandbox or a stricter equivalent.

The current tool surface remains the default until the capability-specific validation gates pass.

## Problem

Maka currently gives GPT models a mostly generic direct-tool surface, even when their coding-agent training favors different protocols. In one controlled GPT-5.6 Sol DeepSWE pair, both runs passed, while Maka used 30.2 minutes, 5.36M tokens, and 133 environment actions versus Codex CLI's 18.2 minutes, 2.80M tokens, and 38 actions; a second pair showed the same time direction.

The sample is too small to assign causality, but it is sufficient to test two independent variables:

1. whether a GPT-compatible ApplyPatch editing surface outperforms Edit/Write; and
2. whether `exec` / `wait` orchestration outperforms direct-only tool calling.

## Decision

Extend the effective per-run tool surface from #1493 with one tool-protocol compatibility profile:

| Axis | Values |
|---|---|
| Editing | Current Edit/Write, ApplyPatch |
| Orchestration | Direct, CodeMode, CodeModeOnly |

The profile is a projection over the same effective `MakaTool[]`, deferred activation state, and `ToolRuntime`. It is not a second registry, tool catalog, permission path, or execution runtime.

Every axis has an explicit per-run override. Model-specific defaults may change only after the corresponding validation gate passes.

Candidate defaults:

| Model profile | Editing | Orchestration |
|---|---|---|
| GPT-5 profiles validated for patch training | ApplyPatch | Direct |
| GPT-5.6 Sol/Terra | ApplyPatch | CodeModeOnly |
| Other models | Current surface | Direct |

These are rollout candidates, not active defaults.

## Delivery

- [ ] #1552 — add the GPT-compatible ApplyPatch editing projection and validate it against Edit/Write.
- [ ] #1553 — add brokered `exec` / `wait` in CodeMode while retaining direct ordinary tools.

CodeModeOnly is an accepted follow-up boundary, but its issue will be opened only after CodeMode lands so its PR can start flat from the latest `main`.

#1493 is a prerequisite for both current slices and the later CodeModeOnly delivery. Each delivery must extend its effective-surface result rather than create a parallel name list or binding path.

ApplyPatch and Code Mode remain independently selectable and independently revertible. ExploreAgent removal is not part of these deliveries; open separate work only when a concrete cleanup requirement exists.

## Shared invariants

### Tool authority

- The effective per-run tool surface from #1493 remains authoritative.
- Every nested tool call re-enters the existing `ToolRuntime`; Code Mode must not call `MakaTool.impl` directly.
- Existing validation, deferred gating, permission checks, sandbox policy, abort, limits, durable T1/T2 facts, telemetry, artifacts, and UI activity remain in force.
- Provider history contains only the `exec` / `wait` calls issued by the model. Nested calls are durable runtime facts linked to their parent `exec`, but are never replayed as provider function calls or results.

### Code Mode process boundary

- Each `exec` cell runs in a short-lived Node child process, not Maka's main process and not a persistent sidecar.
- A cell receives no direct filesystem, process, module, worker, or network authority.
- Node `--permission` restrictions provide defense in depth. The OS sandbox remains the authority ceiling; if Maka cannot enforce that ceiling, Code Mode fails closed.
- A cell that completes within the initial yield window returns directly. Otherwise `exec` returns an opaque `cell_id`, and top-level `wait` collects more output or terminates it.
- Cells do not persist across turns or application restarts and do not provide REPL state.

### Projection

| Mode | Provider top level | Inside `exec` |
|---|---|---|
| Direct | Active ordinary tools | Unavailable |
| CodeMode | Active ordinary tools plus `exec` / `wait` | Active nestable tools |
| CodeModeOnly | `exec` / `wait` plus direct-only exceptions | Active nestable tools |

`AskUserQuestion`, Agent/Team tools, `exec`, and `wait` are direct-only. Ordinary product and supplemental tools are nestable by default. `load_tools` is nestable; inside a cell it updates the existing activation state and exposes newly loaded tools to that same cell.

## Validation and rollout gate

- ApplyPatch A/B holds model, prompt, task, executor, and orchestration mode constant.
- Code Mode A/B holds the editing surface constant and compares Direct, CodeMode, and CodeModeOnly.
- Contract tests cover editing replacement, the projection matrix, top-level and nested admission, same-cell `load_tools`, nested-call durability without provider transcript pollution, cell ownership/lifecycle, and the sandbox authority ceiling.
- No model default changes unless correctness does not regress and provider steps, context use, or wall time improve consistently.
- Every enabled default retains an explicit rollback to the previous surface.

## Non-goals

- Shipping ApplyPatch and Code Mode in one implementation PR.
- Removing ExploreAgent.
- Adding provider-hosted tools.
- Building a general-purpose scripting platform or persistent REPL.
- Requiring provider-native programmatic calling for V1.

Start with prerequisite #1493 and delivery issues #1552 and #1553; review how the effective MakaTool[] and ToolRuntime are projected across the stated modes. Done means the independent ApplyPatch and Code Mode slices satisfy the listed contract tests, sandbox authority, durability, and validation gates.

Written by the indexing model from the issue text.