feat: add apply_patch tool (exec-gated)

docs/tools/apply-patch.md

@@ -0,0 +1,49 @@
+---
+summary: "Apply multi-file patches with the apply_patch tool"
+read_when:
+  - You need structured file edits across multiple files
+  - You want to document or debug patch-based edits
+---
+
+# apply_patch tool
+
+Apply file changes using a structured patch format. This is ideal for multi-file
+or multi-hunk edits where a single `edit` call would be brittle.
+
+The tool accepts a single `input` string that wraps one or more file operations:
+
+```
+*** Begin Patch
+*** Add File: path/to/file.txt
++line 1
++line 2
+*** Update File: src/app.ts
+@@
+-old line
++new line
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+## Parameters
+
+- `input` (required): Full patch contents including `*** Begin Patch` and `*** End Patch`.
+
+## Notes
+
+- Paths are resolved relative to the workspace root.
+- Use `*** Move to:` within an `*** Update File:` hunk to rename files.
+- `*** End of File` marks an EOF-only insert when needed.
+- Experimental and disabled by default. Enable with `tools.exec.applyPatch.enabled`.
+- OpenAI-only (including OpenAI Codex). Optionally gate by model via
+  `tools.exec.applyPatch.allowModels`.
+- Config is only under `tools.exec` (no `tools.bash` alias).
+
+## Example
+
+```json
+{
+  "tool": "apply_patch",
+  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
+}
+```

docs/tools/exec.md

@@ -33,3 +33,23 @@ Background + poll:
 {"tool":"exec","command":"npm run build","yieldMs":1000}
 {"tool":"process","action":"poll","sessionId":"<id>"}
 ```
+
+## apply_patch (experimental)
+
+`apply_patch` is a subtool of `exec` for structured multi-file edits.
+Enable it explicitly:
+
+```json5
+{
+  tools: {
+    exec: {
+      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] }
+    }
+  }
+}
+```
+
+Notes:
+- Only available for OpenAI/OpenAI Codex models.
+- Tool policy still applies; `allow: ["exec"]` implicitly allows `apply_patch`.
+- Config lives under `tools.exec.applyPatch` (no `tools.bash` alias).

docs/tools/index.md

@@ -31,6 +31,10 @@ alongside tools (for example, the voice-call plugin).
 
 ## Tool inventory
 
+### `apply_patch`
+Apply structured patches across one or more files. Use for multi-hunk edits.
+Experimental: enable via `tools.exec.applyPatch.enabled` (OpenAI models only).
+
 ### `exec`
 Run shell commands in the workspace.