mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/036-tool-output-truncation.rispec.md

@@ -0,0 +1,138 @@
+# RISE-036: Tool Output Truncation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/036-tool-output-truncation.rispec.md
+
+## Creative Intent
+
+mia-code automatically truncates tool outputs that exceed configurable size limits, preventing context window overflow while preserving the most useful information. When a tool produces output larger than the threshold, the system saves the full output to a reference file and inserts a truncated version — first lines, last lines, and a pointer to the full content — into the conversation. The agent retains enough signal to reason about the output and can read the full file if deeper inspection is needed. This turns unbounded tool output from a context-destroying hazard into a managed, referential resource.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Tool outputs flow directly into the conversation context with no size management
+- A single `grep` across a large codebase can produce megabytes of output, consuming the entire context window
+- Once the context window overflows, the agent loses coherence — earlier messages are silently dropped
+- There is no mechanism to save large outputs for later reference
+- The developer must manually truncate commands (adding `| head -50`) to prevent context overflow
+- Different output types (JSON, logs, code) are all truncated identically — no structural awareness
+
+**Desired State:**
+- Tool outputs exceeding a configurable limit (default: 20KB) are automatically truncated
+- Full output is saved to `.mia-code/outputs/{hash}.txt` for later reference
+- Truncated output shows: first N lines, `... truncated ({original_size}) ...`, last M lines, and a file reference
+- Per-tool configurable limits allow fine-tuning (e.g., search results get 10KB, file reads get 30KB)
+- Smart truncation adapts to content type: JSON arrays truncate inner elements, logs keep first/last sections, code preserves structure
+- Truncation metadata (original size, truncated size, output file path) is attached to the result
+
+## Desired Outcome Definition
+
+The agent runs a grep that matches 2,000 lines across 150 files. Instead of injecting 180KB into the context, the truncation system saves the full output to `.mia-code/outputs/a7f3c2.txt`, injects the first 30 lines and last 20 lines with a reference note, and the agent reasons over the visible subset. If the agent needs line 847, it reads the output file directly.
+
+## Natural Language Functional Description
+
+### Truncation Pipeline
+
+When a tool returns its result, the output passes through the truncation pipeline before entering the conversation:
+
+1. **Size check** — measure the output in bytes (UTF-8 encoded)
+2. **Threshold comparison** — compare against the tool's configured limit or the global default (20KB)
+3. **If under limit** — pass through unchanged
+4. **If over limit** — save full output to file, generate truncated version, attach metadata
+
+### Output File Storage
+
+Full outputs are saved to `.mia-code/outputs/` with content-hash filenames:
+
+```
+.mia-code/outputs/a7f3c2e9.txt    # hash of content for deduplication
+```
+
+Files are named by a truncated SHA-256 hash of the content, ensuring identical outputs share the same file. An index file `.mia-code/outputs/index.json` maps hashes to metadata:
+
+```json
+{
+  "a7f3c2e9": {
+    "tool": "bash",
+    "sessionId": "sess_abc123",
+    "timestamp": "2026-03-01T14:30:00Z",
+    "originalSize": 184320,
+    "lineCount": 2047
+  }
+}
+```
+
+### Truncated Output Format
+
+The truncated output preserves the most informative parts:
+
+```
+[first 30 lines of output]
+
+... truncated (180KB, 2047 lines) — full output: .mia-code/outputs/a7f3c2e9.txt ...
+
+[last 20 lines of output]
+```
+
+The first/last line counts are configurable. Defaults: 30 lines from the top, 20 from the bottom.
+
+### Smart Truncation by Content Type
+
+The truncation engine detects content type and applies type-appropriate strategies:
+
+- **JSON** — parse the JSON, truncate large arrays by keeping first 5 and last 5 elements with a count note, re-serialize. Object keys are never truncated — only array values.
+- **Log output** — keep first section (often headers and initial entries) and last section (most recent entries). Middle section replaced with line count.
+- **Code / source files** — preserve the file's opening declarations (imports, class definitions) and closing sections. Middle body truncated with line range note.
+- **Tabular data** — keep header row plus first N and last M data rows. Column alignment preserved.
+- **Plain text** — simple first/last line truncation with byte count.
+
+Content type is inferred from the tool ID and output content heuristics (leading `{` or `[` for JSON, timestamp patterns for logs, etc.).
+
+### Per-Tool Configuration
+
+Each tool can specify its own truncation limit:
+
+```typescript
+{
+  id: "file_read",
+  truncation: { maxBytes: 30720, firstLines: 50, lastLines: 30 }
+}
+```
+
+Tools that produce inherently large output (like search) can have lower limits, while tools that produce high-value output (like file reads) can have higher ones.
+
+### Truncation Metadata
+
+Every truncated result includes metadata attached via `context.metadata()` (RISE-035):
+
+```typescript
+{
+  truncated: true,
+  originalSize: 184320,
+  truncatedSize: 4096,
+  outputFile: ".mia-code/outputs/a7f3c2e9.txt",
+  lineCount: { original: 2047, kept: 50 }
+}
+```
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** applies truncation after tool execution and before result injection
+- **Tool Context Injection (RISE-035)** provides `metadata()` for attaching truncation info
+- **Managed Config Directory (RISE-070)** hosts the `.mia-code/outputs/` directory
+- **File Read/Write Tools (RISE-048)** allow the agent to read full output files when needed
+- **Multi-Level Config (RISE-064)** allows per-project truncation limit overrides
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Grep Safety Net:**
+The agent runs `grep -r "TODO" .` on a large project. The result is 3,400 lines. Truncation saves the full output, injects the first 30 and last 20 lines, and notes "3,400 lines total." The agent sees enough to identify patterns and tells the user: "Found TODOs across 89 files — the most frequent are in src/legacy/. Full results saved to .mia-code/outputs/b4e1f2.txt."
+
+**Scenario 2 — JSON Array Truncation:**
+A tool returns a 500-element JSON array of test results. Smart truncation keeps the array structure but reduces it to the first 5 and last 5 elements with `"... 490 more items ..."`. The agent can still see the schema of each element and the total count without consuming 200KB of context.
+
+**Scenario 3 — Agent Self-Service:**
+After seeing truncated search results, the agent decides it needs line 200-250 specifically. It reads the output file with `file_read` using a line range, getting exactly the data it needs. The truncation system enabled a two-step retrieval pattern: overview first, detail on demand.
+
+**Scenario 4 — Configurable Limits:**
+A project with huge generated files sets `.mia-code/config.json` to increase `file_read` truncation to 50KB. Another project with tight context budgets sets the global default to 10KB. Both projects get appropriate behavior without code changes.

package/rispecs/borrowed_from_opencode/037-batch-tool.rispec.md

@@ -0,0 +1,129 @@
+# RISE-037: Batch File Operations Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/037-batch-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a batch tool that executes multiple file operations — create, edit, delete — as a single atomic transaction. All operations succeed together or all roll back, eliminating the partial-failure state that plagues multi-file refactoring. The agent describes all intended changes in one tool call, the batch tool validates them, takes a snapshot, executes them, and reports results. When a rename touches an import in 12 files, either all 12 are updated or none are — the codebase is never left in an inconsistent state.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code performs file operations one at a time through the underlying CLI's tools
+- A refactoring that touches 8 files requires 8 separate tool calls — if the 5th fails, the first 4 are already committed
+- There is no rollback mechanism — partial failures leave the codebase in an inconsistent state
+- The agent must reason about operation ordering to avoid conflicts (e.g., don't delete a file before copying its content)
+- Validation happens at execution time — an invalid path in operation 7 is discovered only after operations 1-6 have completed
+- The LLM's context is consumed by 8 separate tool call/result cycles instead of one
+
+**Desired State:**
+- A single `batch` tool call accepts an array of file operations
+- All operations are validated before any execute — invalid paths, missing files, and conflicts detected upfront
+- A filesystem snapshot is taken before execution for rollback capability
+- Operations execute in order; if any fails, all previous operations are rolled back from the snapshot
+- A dry-run mode validates and reports what would happen without executing
+- One tool call, one result — reduced context consumption for multi-file changes
+
+## Desired Outcome Definition
+
+The agent needs to rename a React component from `UserList` to `TeamMembers` across 6 files. It issues a single batch tool call with 6 edit operations. The batch tool validates all 6, snapshots the affected files, executes them sequentially, and returns a summary: "6/6 operations succeeded." If the 4th edit fails (target string not found), operations 1-3 are rolled back and the error identifies exactly which operation failed and why.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface BatchInput {
+  operations: BatchOperation[];
+  dryRun?: boolean;
+}
+
+type BatchOperation =
+  | { type: "create"; path: string; content: string }
+  | { type: "edit"; path: string; old: string; new: string }
+  | { type: "delete"; path: string };
+```
+
+### Execution Pipeline
+
+1. **Parse** — validate the input structure against the Zod schema
+2. **Pre-validate** — for each operation:
+   - `create`: verify file does not already exist, verify parent directory exists or can be created
+   - `edit`: verify file exists, verify `old` string appears exactly once in the file
+   - `delete`: verify file exists
+3. **Snapshot** — copy affected files to a temporary snapshot directory (RISE-076)
+4. **Execute** — apply operations in order:
+   - `create`: write file with content, creating parent directories as needed
+   - `edit`: replace `old` with `new` in the file content
+   - `delete`: remove the file
+5. **Rollback on failure** — if any operation fails during execution, restore all files from snapshot
+6. **Report** — return a summary of all operations with their status
+
+### Dry-Run Mode
+
+When `dryRun: true`, the tool runs steps 1-2 (parse and validate) but skips steps 3-5 (snapshot and execute). The output reports what would happen:
+
+```json
+{
+  "dryRun": true,
+  "valid": true,
+  "operations": [
+    {"type": "create", "path": "src/TeamMembers.tsx", "status": "would_create"},
+    {"type": "edit", "path": "src/App.tsx", "status": "would_edit", "matchFound": true},
+    {"type": "delete", "path": "src/UserList.tsx", "status": "would_delete"}
+  ]
+}
+```
+
+### Conflict Detection
+
+The validation phase detects conflicts between operations:
+
+- Two `create` operations targeting the same path
+- An `edit` followed by a `delete` of the same file (the edit is wasted)
+- A `delete` followed by a `create` of the same path (flag as intentional replace or error)
+- An `edit` targeting a file that a previous `create` just made (allowed — the edit applies to the new content)
+
+Conflicts are reported with explanations before any execution begins.
+
+### Output Format
+
+```json
+{
+  "success": true,
+  "operationsCount": 6,
+  "operations": [
+    {"type": "edit", "path": "src/App.tsx", "status": "completed"},
+    {"type": "edit", "path": "src/routes.tsx", "status": "completed"},
+    {"type": "create", "path": "src/TeamMembers.tsx", "status": "completed"},
+    {"type": "delete", "path": "src/UserList.tsx", "status": "completed"}
+  ],
+  "snapshotId": "snap_20260301_143022"
+}
+```
+
+On failure, the output includes the failing operation, the error, and confirmation that rollback was performed.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the batch tool with id `batch`
+- **Tool Context Injection (RISE-035)** provides session context and abort signal for cancellation
+- **File Snapshot System (RISE-076)** handles pre-execution snapshots for rollback
+- **Zod Schema Validation (RISE-005)** validates the operations array structure
+- **Agent Permission Rulesets (RISE-011)** enforces per-operation permission checks (create/edit/delete)
+- **Named Error System (RISE-006)** provides BatchValidationError, BatchRollbackError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Safe Refactoring:**
+The agent renames a function across 12 files. A single batch call validates all 12 edits upfront — discovering that file 9 has been modified since the agent last read it and the old string no longer matches. The entire batch is rejected before any changes are made. The agent re-reads file 9, adjusts the edit, and retries the full batch successfully.
+
+**Scenario 2 — Component Migration:**
+The developer asks to move a component from `components/old/` to `components/new/` with updated imports. The agent issues one batch: create the new file, edit 4 import statements, delete the old file. All 6 operations execute atomically. If the import in `routes.tsx` fails, everything rolls back — the old component is never deleted without its imports being updated first.
+
+**Scenario 3 — Dry-Run Preview:**
+Before a large refactoring, the agent runs the batch with `dryRun: true`. It reports: "Would edit 8 files, create 2 files, delete 3 files. All operations valid." The developer reviews, confirms, and the agent reruns without dry-run. Confidence before commitment.
+
+**Scenario 4 — Context Efficiency:**
+Instead of 15 separate tool calls consuming 15 context round-trips, the agent makes 1 batch call. The result is a single compact summary. The saved context budget allows the agent to reason about the next steps without hitting context limits.

package/rispecs/borrowed_from_opencode/038-multi-edit-tool.rispec.md

@@ -0,0 +1,167 @@
+# RISE-038: Multi-Edit Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/038-multi-edit-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a multi-edit tool that applies multiple find-and-replace edits across one or more files in a single tool invocation. Where the batch tool (RISE-037) handles mixed operation types (create, edit, delete), the multi-edit tool specializes in surgical text replacements — the most common operation an agent performs. Each edit specifies a file path, an exact string to find, and its replacement. Edits are validated collectively, applied in order, and reported with before/after context. The result is fewer tool calls, consistent multi-file refactoring, and clear visibility into every change made.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Each file edit requires a separate tool call — renaming a variable in 5 files means 5 tool calls
+- Sequential editing consumes context rapidly: each call adds input and output to the conversation
+- If the agent's reasoning drifts between tool calls, later edits may be inconsistent with earlier ones
+- There is no way to validate all edits before committing the first one
+- Failed edits provide no context about which specific replacement failed or why
+
+**Desired State:**
+- A single `multi_edit` tool call accepts an array of `{path, old_string, new_string}` edits
+- All edits are validated before any are applied — each `old_string` must match exactly once in its target file
+- Edits are applied in order within each file, accounting for offset shifts from earlier edits
+- The output shows each edit with before/after context lines for verification
+- Failed edits report the specific edit index, file, and failure reason
+- Optional regex support for pattern-based replacements
+
+## Desired Outcome Definition
+
+The agent renames a type from `UserID` to `AccountID` across 7 files. It issues one `multi_edit` call with 11 edits (some files have multiple occurrences). Each edit is validated — the tool confirms all 11 `old_string` values match exactly once. The edits apply in order, and the result shows 11 successful replacements with 2 lines of context around each change.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface MultiEditInput {
+  edits: EditOperation[];
+  regex?: boolean;
+}
+
+interface EditOperation {
+  path: string;
+  old_string: string;
+  new_string: string;
+}
+```
+
+### Validation Rules
+
+Before any edit is applied, all edits are validated:
+
+1. Each `path` must refer to an existing file within the project root
+2. Each `old_string` must appear exactly once in the target file's current content
+3. When multiple edits target the same file, validation accounts for earlier edits' effects — edit 2's `old_string` is searched in the file as modified by edit 1
+4. Empty `old_string` is rejected — use the file write tool for full-file operations
+5. If `regex: true`, each `old_string` is compiled as a regular expression and must match exactly once
+
+If any edit fails validation, the entire operation is rejected with a detailed error listing every invalid edit.
+
+### Application Order
+
+Edits are grouped by file and applied sequentially within each file:
+
+1. Group edits by target file path
+2. For each file, read the current content
+3. Apply edits in the order they appear in the input array
+4. After each edit, update the working content for subsequent edits in the same file
+5. After all edits for a file are applied, write the final content back
+
+This ordering means later edits can depend on earlier edits' changes within the same file.
+
+### Output Format
+
+```json
+{
+  "success": true,
+  "editCount": 11,
+  "filesModified": 7,
+  "edits": [
+    {
+      "path": "src/types.ts",
+      "status": "applied",
+      "context": {
+        "before": "export type UserID = string;",
+        "after": "export type AccountID = string;"
+      }
+    },
+    {
+      "path": "src/api.ts",
+      "status": "applied",
+      "context": {
+        "before": "function getUser(id: UserID): Promise<User>",
+        "after": "function getUser(id: AccountID): Promise<User>"
+      }
+    }
+  ]
+}
+```
+
+Each edit result includes the before and after text with surrounding context lines, enabling the developer to verify correctness at a glance.
+
+### Error Reporting
+
+When validation fails, the error identifies every problematic edit:
+
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "editIndex": 3,
+      "path": "src/utils.ts",
+      "old_string": "UserID",
+      "error": "Found 3 matches — expected exactly 1. Include more context to disambiguate."
+    },
+    {
+      "editIndex": 7,
+      "path": "src/deleted.ts",
+      "error": "File does not exist."
+    }
+  ]
+}
+```
+
+The error message for multiple matches suggests including more surrounding context in `old_string` to make the match unique.
+
+### Regex Mode
+
+When `regex: true`, `old_string` values are interpreted as regular expressions:
+
+```json
+{
+  "edits": [
+    {
+      "path": "src/config.ts",
+      "old_string": "version:\\s*\"\\d+\\.\\d+\\.\\d+\"",
+      "new_string": "version: \"2.0.0\""
+    }
+  ],
+  "regex": true
+}
+```
+
+Regex mode supports capture groups in `new_string` via `$1`, `$2` syntax. The same uniqueness constraint applies — the regex must match exactly once per file.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the multi-edit tool with id `multi_edit`
+- **Tool Context Injection (RISE-035)** provides session context and abort signal
+- **Zod Schema Validation (RISE-005)** validates the edits array structure
+- **File Snapshot System (RISE-076)** takes pre-edit snapshots for undo capability
+- **Agent Permission Rulesets (RISE-011)** enforces write permissions on each target file path
+- **Tool Output Truncation (RISE-036)** truncates output when many edits produce verbose results
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Variable Rename:**
+The developer asks to rename `userEmail` to `contactEmail` everywhere. The agent finds 14 occurrences across 6 files, constructs 14 edits each with enough surrounding context for unique matching, and submits one `multi_edit` call. All 14 apply cleanly. The developer sees a compact summary with before/after for each change.
+
+**Scenario 2 — Disambiguation Feedback:**
+The agent tries to replace `id` in a file but the `multi_edit` tool rejects it: "Found 12 matches — include more context." The agent retries with `old_string: "const id = user.id"` — now unique. The tool's error message guided the agent to a successful edit without developer intervention.
+
+**Scenario 3 — Import Path Migration:**
+A team moves from `@/lib/` to `@/utils/` import paths. The agent constructs 30 edits across 20 files, all in one `multi_edit` call. The operation completes in one round-trip. Without multi-edit, this would be 30 separate tool calls consuming 30x the context.
+
+**Scenario 4 — Regex Version Bump:**
+Using regex mode, the agent updates all version strings matching `"version": "\d+\.\d+\.\d+"` across package.json files in a monorepo. One call, one regex pattern, consistent updates everywhere.

package/rispecs/borrowed_from_opencode/039-apply-patch-tool.rispec.md

@@ -0,0 +1,161 @@
+# RISE-039: Apply Patch Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/039-apply-patch-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a tool that applies unified diff patches directly to files — the same format produced by `git diff`. The agent can express complex, multi-hunk, multi-file changes as a single patch and apply them in one operation. This bridges the gap between human-readable diffs (which LLMs generate naturally) and actual file modifications. When an AI produces a diff showing exactly what to change, mia-code can apply it directly rather than decomposing it into individual find-and-replace operations.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code can only modify files through individual find-and-replace edits via the CLI's built-in tools
+- LLMs naturally produce unified diffs when describing changes, but these cannot be applied directly
+- The agent must translate a conceptual diff into multiple `edit` tool calls — losing fidelity and consuming context
+- External patches (from code reviews, PRs, or other AI tools) cannot be applied within a mia-code session
+- There is no support for hunk-level context matching, which unified diffs rely on for precise positioning
+- Applying a 200-line diff requires decomposing it into dozens of individual edits — error-prone and slow
+
+**Desired State:**
+- A single `apply_patch` tool accepts unified diff text and applies all hunks to target files
+- Both `---/+++` standard format and git extended diff format are supported
+- Context lines in hunks enable fuzzy matching when exact line numbers have shifted
+- The tool handles file creation (new file patches), file deletion, and multi-hunk modifications
+- Fuzz factor is configurable — allowing context lines to match with small offsets
+- Failed hunks report exactly which hunk didn't match and show the expected vs actual context
+
+## Desired Outcome Definition
+
+The agent generates a unified diff with 4 hunks across 2 files. It passes this diff text to the `apply_patch` tool. The tool parses the patch, matches each hunk's context against the target files (with up to 3 lines of fuzz), applies the changes, and reports: "Applied 4 hunks to 2 files (2 hunks applied with offset)."
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface ApplyPatchInput {
+  patch: string;          // unified diff text
+  fuzzFactor?: number;    // context matching tolerance (default: 3 lines)
+  dryRun?: boolean;       // validate without applying
+  stripPrefix?: number;   // strip N leading path components (like patch -p)
+}
+```
+
+### Patch Parsing
+
+The tool parses standard unified diff format:
+
+```diff
+--- a/src/auth.ts
++++ b/src/auth.ts
+@@ -15,7 +15,8 @@ import { hash } from './crypto';
+ export async function authenticate(
+   username: string,
+   password: string,
++  mfaToken?: string,
+ ): Promise<AuthResult> {
+-  const user = await findUser(username);
++  const user = await findUserByName(username);
+   if (!user) throw new AuthError('not_found');
+```
+
+The parser extracts:
+- File paths from `---` and `+++` headers
+- Hunk ranges from `@@` markers
+- Context lines (space-prefixed), removed lines (`-` prefixed), added lines (`+` prefixed)
+
+### Hunk Application with Fuzz
+
+Each hunk is applied by matching its context lines against the target file:
+
+1. Start at the line number specified in the hunk header
+2. If context lines match exactly at that position, apply the hunk
+3. If not, search within `fuzzFactor` lines above and below the specified position
+4. If a match is found at an offset, apply the hunk and note the offset in the result
+5. If no match is found within the fuzz range, the hunk fails
+
+Fuzz matching uses the context lines (unchanged lines in the diff) as anchors. All context lines must match for the hunk to apply — only the position can vary.
+
+### File Operations
+
+The patch tool handles three file operation types:
+
+- **Modification** — standard `---/+++` with existing file paths, applies hunks to modify content
+- **Creation** — `--- /dev/null` with `+++ b/new-file.ts`, creates the file with the added content
+- **Deletion** — `--- a/old-file.ts` with `+++ /dev/null`, deletes the file after verifying current content matches
+
+### Git Extended Format
+
+The tool also supports git's extended diff headers:
+
+```diff
+diff --git a/src/auth.ts b/src/auth.ts
+index 1a2b3c4..5e6f7g8 100644
+--- a/src/auth.ts
++++ b/src/auth.ts
+```
+
+The `diff --git` header, `index` line, and file mode are parsed for metadata but not required for hunk application.
+
+### Output Format
+
+```json
+{
+  "success": true,
+  "filesModified": 2,
+  "filesCreated": 1,
+  "filesDeleted": 0,
+  "hunks": [
+    {"file": "src/auth.ts", "hunk": 1, "status": "applied", "offset": 0},
+    {"file": "src/auth.ts", "hunk": 2, "status": "applied", "offset": 3},
+    {"file": "src/routes.ts", "hunk": 1, "status": "applied", "offset": 0},
+    {"file": "src/mfa.ts", "hunk": 1, "status": "created"}
+  ]
+}
+```
+
+### Error Handling
+
+When a hunk fails to apply:
+
+```json
+{
+  "success": false,
+  "error": "Hunk 2 of src/auth.ts failed to apply",
+  "detail": {
+    "file": "src/auth.ts",
+    "hunk": 2,
+    "expectedContext": ["  const user = await findUser(username);"],
+    "actualContent": ["  const user = await lookupUser(username);"],
+    "searchRange": "lines 18-24"
+  },
+  "appliedBefore": ["hunk 1 of src/auth.ts"],
+  "rolledBack": true
+}
+```
+
+When any hunk fails, previously applied hunks within the same file are rolled back. Cross-file rollback is managed by the snapshot system.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the apply_patch tool with id `apply_patch`
+- **Tool Context Injection (RISE-035)** provides session context and cancellation
+- **File Snapshot System (RISE-076)** enables rollback when hunks fail
+- **Zod Schema Validation (RISE-005)** validates the patch input structure
+- **Agent Permission Rulesets (RISE-011)** enforces write permissions on target file paths
+- **Batch Tool (RISE-037)** provides complementary file operations for non-diff changes
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — AI-Generated Diff Application:**
+The agent produces a 150-line diff describing a refactoring. Instead of decomposing it into 20 individual edits, it passes the entire diff to `apply_patch`. One tool call, one result, and the refactoring is complete. The LLM's natural diff-generation ability is leveraged directly.
+
+**Scenario 2 — External Patch Replay:**
+A developer pastes a patch from a code review comment: "Apply this fix." The agent passes the patch text directly to the tool. The fuzz factor handles the fact that the developer's version has 2 extra lines compared to the patch's context — the hunk applies at offset +2. Seamless integration with external workflows.
+
+**Scenario 3 — Dry-Run Validation:**
+Before applying a large patch from an untrusted source, the agent runs `dryRun: true`. The tool reports: "4 of 5 hunks would apply. Hunk 3 fails: context mismatch at line 42." The agent adjusts hunk 3 manually and retries. Safety before commitment.
+
+**Scenario 4 — New File Creation via Patch:**
+The agent generates a diff creating a new test file (`--- /dev/null`, `+++ b/tests/auth.test.ts`). The `apply_patch` tool creates the file with the specified content. This is more natural for the LLM than using a separate create tool — the diff is a unified representation of all changes.