opencode-resolve 0.2.0 → 0.3.0

package/README.ko.md

@@ -197,6 +197,33 @@ irm https://raw.githubusercontent.com/jshsakura/awesome-opencode-skills/main/ins
 | `language` | `auto` / `en` / `ko` | `auto` | 프롬프트 언어 선호. |
 | `maxParallelSubagents` | positive integer | 미설정 | 동시 coder 디스패치에 대한 선택적 프롬프트 수준 soft limit. |
 | `singleAgentMode` | boolean | `false` | `true`면 resolver가 `coder` 서브에이전트를 디스패치하지 않고 모든 편집을 직접 수행합니다. 단순 작업에서 지연과 토큰 비용을 절약합니다. 정보/진단용 서브에이전트(explorer/debugger)는 여전히 사용 가능합니다. |
+| `permissions` | object | `{}` | 옵트인 롤백 권한. 아래 참조. |
+
+### 롤백 권한
+
+`git reset --hard` 와 `git clean -f` 는 기본적으로 차단됩니다. 커밋하지 않은 작업을 보호하지만, 동시에 디버깅 도중 작업트리가 꼬인 에이전트가 깨끗한 상태로 되돌아갈 방법이 없다는 뜻이기도 합니다 — 그대로 고립됩니다. 두 개의 옵트인 플래그가 이를 풀어주며, resolve 에이전트에만 적용됩니다.
+
+```json
+{
+  "permissions": {
+    "allowGitReset": true,
+    "allowGitClean": true
+  }
+}
+```
+
+두 명령이 실행되기 전에, 플러그인은 **작업트리 전체** — 추적 중인 수정과 추적되지 않은 파일 모두 — 를 `refs/resolve-checkpoint/<timestamp>-<reset|clean>` 이라는 git ref 로 스냅샷합니다. 스냅샷은 임시 인덱스를 통해 기록되므로 실제 인덱스, 작업트리, 브랜치, `HEAD` 는 전혀 건드리지 않습니다. 스테이징도 커밋도 일어나지 않습니다. 스냅샷을 남기지 못하면 파괴적 명령은 무방비로 실행되는 대신 차단됩니다.
+
+되돌린 것을 후회할 때 복구하려면:
+
+```sh
+git for-each-ref refs/resolve-checkpoint    # 체크포인트 목록
+git restore --source=<ref> -- .             # 전부 복원
+```
+
+`git clean -x` 와 `-X` 는 이 플래그와 무관하게 계속 차단됩니다. gitignore 대상 파일을 삭제하는데, 체크포인트는 `.gitignore` 를 존중하는 `git add -A` 로 스냅샷하기 때문입니다 — 즉 `-x` clean 은 체크포인트가 되살릴 수 없는 파일(`.env`, 로컬 시크릿)을 파괴합니다.
+
+체크포인트는 resolve 에이전트가 해당 명령을 실행할 때마다 생성됩니다 — 두 플래그를 `false` 로 둔 채 권한 프롬프트에서 직접 승인한 경우에도 마찬가지입니다. OpenCode 기본 에이전트(`build`/`plan`/chat)는 무조건 차단이 유지되며 이 플래그의 영향을 받지 않습니다.
 
 ### 에이전트 override
 
@@ -273,6 +300,8 @@ resolve 에이전트의 bash는 기본적으로 `ask`입니다. 플러그인의
 
 `autoApprove`는 오래된 설정과의 호환을 위해 허용되지만, 현재 동작은 명시적 에이전트 권한과 명령 분류기가 제어합니다.
 
+`git reset --hard` 와 `git clean -f` 는 옵트인하지 않으면 차단됩니다 — [롤백 권한](#롤백-권한) 참조. 허용된 경우 플러그인이 먼저 작업트리를 체크포인트합니다.
+
 신뢰할 수 없는 저장소에서는 샌드박스나 VM을 사용하세요.
 
 ## 병렬 서브에이전트

package/README.md

@@ -197,6 +197,33 @@ Full commented reference: [opencode-resolve.reference.jsonc](./opencode-resolve.
 | `language` | `auto` / `en` / `ko` | `auto` | Prompt language preference. |
 | `maxParallelSubagents` | positive integer | unset | Optional prompt-level soft limit for concurrent coder dispatch. |
 | `singleAgentMode` | boolean | `false` | When `true`, the resolver makes all edits directly instead of dispatching a `coder` subagent — lower latency and token cost on simple tasks. Information/diagnostic subagents (explorer/debugger) are still available. |
+| `permissions` | object | `{}` | Opt-in rollback permissions. See below. |
+
+### Rollback Permissions
+
+`git reset --hard` and `git clean -f` are denied by default. That protects your uncommitted work, but it also means an agent that tangles the worktree mid-debug cannot get back to a clean state — it stalls. Two opt-in flags un-gate them, for resolve agents only:
+
+```json
+{
+  "permissions": {
+    "allowGitReset": true,
+    "allowGitClean": true
+  }
+}
+```
+
+Before either command runs, the plugin snapshots the **entire worktree** — tracked edits *and* untracked files — into a git ref named `refs/resolve-checkpoint/<timestamp>-<reset|clean>`. The snapshot is written through a throwaway index, so your real index, working tree, branches, and `HEAD` are never touched: nothing is staged, nothing is committed. If the snapshot cannot be written, the destructive command is blocked instead of run unprotected.
+
+To recover from a rollback you regret:
+
+```sh
+git for-each-ref refs/resolve-checkpoint    # list checkpoints
+git restore --source=<ref> -- .             # bring everything back
+```
+
+`git clean -x` and `-X` stay denied regardless of these flags. They delete gitignored files, and the checkpoint snapshots via `git add -A`, which honours `.gitignore` — so a `-x` clean would destroy files (`.env`, local secrets) the checkpoint cannot bring back.
+
+Checkpoints are taken whenever one of these commands executes under a resolve agent — including when you approve it yourself at the permission prompt with both flags left `false`. Native OpenCode agents (`build`/`plan`/chat) keep the unconditional deny and are unaffected by these flags.
 
 ### Agent Overrides
 
@@ -273,6 +300,8 @@ Resolve agents keep bash at `ask` by default. The plugin's permission hook auto-
 
 `autoApprove` is accepted for compatibility with older configs, but current behavior is controlled by explicit agent permissions and the command classifier.
 
+`git reset --hard` and `git clean -f` are denied unless you opt in — see [Rollback Permissions](#rollback-permissions). When permitted, the plugin checkpoints the worktree first.
+
 Use a sandbox or VM for untrusted repositories.
 
 ## Parallel Subagents

package/dist/checkpoint.d.ts

@@ -0,0 +1,22 @@
+import type { RollbackKind } from "./types.js";
+/** Namespace for checkpoint refs. Outside refs/heads, so it never shows up as a branch. */
+export declare const CHECKPOINT_REF_NAMESPACE = "refs/resolve-checkpoint";
+export type Checkpoint = {
+    /** Full ref name, e.g. `refs/resolve-checkpoint/1730000000000-reset`. */
+    ref: string;
+    /** Copy-pasteable command that puts the worktree back the way it was. */
+    restoreCommand: string;
+};
+export declare function isGitRepository(directory: string): Promise<boolean>;
+/**
+ * Snapshot the worktree into `refs/resolve-checkpoint/<timestamp>-<kind>`.
+ * Throws with the underlying git error if the snapshot cannot be written — the
+ * caller must abort the destructive command rather than run it unprotected.
+ */
+export declare function createRollbackCheckpoint(directory: string, kind: RollbackKind): Promise<Checkpoint>;
+/**
+ * Restores every path recorded in the checkpoint, including files a later
+ * `git clean` deleted. Files created after the checkpoint are left alone —
+ * recovery is additive, never destructive.
+ */
+export declare function restoreCommandFor(ref: string): string;

package/dist/checkpoint.js

@@ -0,0 +1,72 @@
+// Rollback checkpoints.
+//
+// `git reset --hard` and `git clean -f` are the two recovery commands an agent
+// needs to escape a tangled worktree, and they are also the two that can destroy
+// uncommitted work. Before either runs, we snapshot the entire worktree —
+// tracked modifications *and* untracked files — into a git ref that nothing else
+// points at.
+//
+// The snapshot uses a throwaway index (`GIT_INDEX_FILE`) so the real index and
+// the working tree are never touched: add -A → write-tree → commit-tree →
+// update-ref. Nothing is staged, nothing is committed to any branch, no HEAD
+// move. The ref keeps the objects alive against `git gc`.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCommand } from "./utils.js";
+/** Namespace for checkpoint refs. Outside refs/heads, so it never shows up as a branch. */
+export const CHECKPOINT_REF_NAMESPACE = "refs/resolve-checkpoint";
+const GIT_TIMEOUT_MS = 15_000;
+export async function isGitRepository(directory) {
+    const { exitCode } = await runCommand("git rev-parse --is-inside-work-tree", directory, GIT_TIMEOUT_MS);
+    return exitCode === 0;
+}
+/**
+ * Snapshot the worktree into `refs/resolve-checkpoint/<timestamp>-<kind>`.
+ * Throws with the underlying git error if the snapshot cannot be written — the
+ * caller must abort the destructive command rather than run it unprotected.
+ */
+export async function createRollbackCheckpoint(directory, kind) {
+    const ref = `${CHECKPOINT_REF_NAMESPACE}/${Date.now()}-${kind}`;
+    const indexDirectory = await mkdtemp(join(tmpdir(), "opencode-resolve-ckpt-"));
+    const indexFile = join(indexDirectory, "index");
+    // One shell invocation: a failure anywhere aborts (set -e) and we surface it.
+    // `git add -A` against an empty throwaway index stages the whole worktree,
+    // honouring .gitignore. `commit-tree` parents on HEAD when a HEAD exists (a
+    // freshly-initialised repo has none).
+    const script = [
+        "set -e",
+        `export GIT_INDEX_FILE=${JSON.stringify(indexFile)}`,
+        // commit-tree refuses to run without a committer identity; a repo with no
+        // user.email configured must still be able to checkpoint.
+        "export GIT_AUTHOR_NAME=opencode-resolve GIT_AUTHOR_EMAIL=checkpoint@opencode-resolve.local",
+        "export GIT_COMMITTER_NAME=opencode-resolve GIT_COMMITTER_EMAIL=checkpoint@opencode-resolve.local",
+        "git add -A",
+        "tree=$(git write-tree)",
+        `message=${JSON.stringify(`opencode-resolve checkpoint before git ${kind}`)}`,
+        'if git rev-parse -q --verify HEAD >/dev/null 2>&1; then',
+        '  commit=$(git commit-tree "$tree" -p HEAD -m "$message")',
+        "else",
+        '  commit=$(git commit-tree "$tree" -m "$message")',
+        "fi",
+        `git update-ref ${JSON.stringify(ref)} "$commit"`,
+    ].join("\n");
+    try {
+        const { stderr, exitCode } = await runCommand(script, directory, GIT_TIMEOUT_MS);
+        if (exitCode !== 0) {
+            throw new Error(`checkpoint failed (git exit ${exitCode}): ${stderr.trim() || "no stderr"}`);
+        }
+    }
+    finally {
+        await rm(indexDirectory, { recursive: true, force: true }).catch(() => { });
+    }
+    return { ref, restoreCommand: restoreCommandFor(ref) };
+}
+/**
+ * Restores every path recorded in the checkpoint, including files a later
+ * `git clean` deleted. Files created after the checkpoint are left alone —
+ * recovery is additive, never destructive.
+ */
+export function restoreCommandFor(ref) {
+    return `git restore --source=${ref} -- .`;
+}

package/dist/config.d.ts

@@ -1,5 +1,5 @@
 import { Config } from "@opencode-ai/plugin";
-import { ResolveConfig, ProjectContext, ResolveAgentName, UnknownRecord, ResolvePluginOptions, ResolveAgentConfig, PermissionValue } from "./types.js";
+import { ResolveConfig, ProjectContext, ResolveAgentName, UnknownRecord, ResolvePluginOptions, ResolveAgentConfig, PermissionValue, ResolvePermissions } from "./types.js";
 export declare function applyResolveConfig(config: Config, resolveConfig: ResolveConfig, projectContext: ProjectContext): void;
 export declare function buildContextInjection(ctx: ProjectContext): string;
 export declare function defaultResolveConfig(): ResolveConfig;
@@ -11,6 +11,7 @@ export declare function getPluginOptions(config: Config): unknown;
 export declare function isResolvePluginEntry(entry: string): boolean;
 export declare function resolvePath(path: string, directory: string): string;
 export declare function normalizeResolveConfig(value: unknown, source: string): ResolvePluginOptions;
+export declare function normalizePermissions(value: unknown, source: string): ResolvePermissions;
 export declare function normalizeAgentConfig(value: unknown, source: string): ResolveAgentConfig;
 export declare function normalizeTools(value: unknown, source: string): Record<string, boolean>;
 export declare function normalizePermission(value: unknown, source: string): ResolveAgentConfig["permission"];
@@ -24,6 +25,7 @@ export declare function expectNumber(value: unknown, source: string): number;
 export declare function isObject(value: unknown): value is UnknownRecord;
 export declare function loadResolveConfig(directory: string, opencodeConfig: Config, options: unknown): Promise<ResolveConfig>;
 export declare const VALID_TOP_LEVEL_KEYS: Set<string>;
+export declare const VALID_PERMISSIONS_KEYS: Set<string>;
 export declare const VALID_AGENT_KEYS: Set<string>;
 export declare const VALID_MODES: Set<string>;
 export declare const VALID_PERMISSION_VALUES: Set<string>;

package/dist/config.js

@@ -94,6 +94,7 @@ export function defaultResolveConfig() {
         commands: false,
         autoApprove: true,
         autoUpdate: true,
+        permissions: {},
     };
 }
 export function mergeResolveConfig(...configs) {
@@ -110,6 +111,7 @@ export function mergeResolveConfig(...configs) {
         result.autoUpdate = config.autoUpdate ?? result.autoUpdate;
         result.language = config.language ?? result.language;
         result.singleAgentMode = config.singleAgentMode ?? result.singleAgentMode;
+        result.permissions = { ...result.permissions, ...config.permissions };
         result.models = { ...result.models, ...config.models };
         result.agents = mergeAgents(result.agents, config.agents);
     }
@@ -223,10 +225,26 @@ export function normalizeResolveConfig(value, source) {
         }
         result.maxParallelSubagents = limit;
     }
+    if (config.permissions !== undefined)
+        result.permissions = normalizePermissions(config.permissions, `${source}.permissions`);
     if (config.config !== undefined)
         result.config = expectString(config.config, `${source}.config`);
     return result;
 }
+export function normalizePermissions(value, source) {
+    const permissions = expectObject(value, source);
+    const result = {};
+    for (const key of Object.keys(permissions)) {
+        if (!VALID_PERMISSIONS_KEYS.has(key)) {
+            throw new Error(`Unknown permissions key "${key}" in ${source}. Valid: ${[...VALID_PERMISSIONS_KEYS].join(", ")}`);
+        }
+    }
+    if (permissions.allowGitReset !== undefined)
+        result.allowGitReset = expectBoolean(permissions.allowGitReset, `${source}.allowGitReset`);
+    if (permissions.allowGitClean !== undefined)
+        result.allowGitClean = expectBoolean(permissions.allowGitClean, `${source}.allowGitClean`);
+    return result;
+}
 export function normalizeAgentConfig(value, source) {
     const config = expectObject(value, source);
     for (const key of Object.keys(config)) {
@@ -359,8 +377,10 @@ export const VALID_TOP_LEVEL_KEYS = new Set([
     "autoUpdate",
     "language",
     "singleAgentMode",
+    "permissions",
     "config",
 ]);
+export const VALID_PERMISSIONS_KEYS = new Set(["allowGitReset", "allowGitClean"]);
 export const VALID_AGENT_KEYS = new Set([
     "enabled",
     "model",

package/dist/hooks/index.js

@@ -1,5 +1,6 @@
 import { DIAGNOSTICS_TTL_MS, FAILURE_PATTERN_TTL_MS, FAILURE_THRESHOLD, STRATEGY_PIVOT_THRESHOLD, EDIT_HOTSPOT_THRESHOLD, DISPATCH_STOP_THRESHOLD, DISPATCH_PIVOT_THRESHOLD } from "../state.js";
-import { classifyBashCommand, detectProjectContext } from "../utils.js";
+import { classifyBashCommand, detectRollbackCommand, formatError, detectProjectContext } from "../utils.js";
+import { createRollbackCheckpoint, isGitRepository } from "../checkpoint.js";
 import { loadResolveConfig, applyResolveConfig } from "../config.js";
 import { contextMessage, narrate, resolveLocale, t, agentDisplayName, brand, PLUGIN_BRAND } from "../messages.js";
 import { VALID_AGENT_NAMES } from "../agents.js";
@@ -37,6 +38,43 @@ function isCodeFile(filePath) {
         return true; // no extension — treat as code
     return CODE_EXTENSIONS.includes(filePath.slice(dot + 1).toLowerCase());
 }
+// Harness boilerplate — not the model's words, so rewriting them wholesale
+// costs nothing and buys a sharper instruction.
+const HARNESS_BOILERPLATE_REWRITES = [
+    ["Summarize the task tool output above and continue with your task.",
+        "Analyze the subtask result above. If it succeeded, continue. If it failed, diagnose and retry. Report completion only when verified."],
+    [/Summarize the .+ output above and continue/i,
+        "Analyze the result above. If it succeeded, continue to the next step. If it failed, diagnose root cause and retry with a fix."],
+    [/continue with your task\.$/i,
+        "continue driving toward verified completion."],
+];
+// Marker on every appended nudge. Also the idempotency key: a part that already
+// carries it is never nudged again.
+const NUDGE_MARKER = `[${PLUGIN_BRAND}] self-check:`;
+// The model's own words — uncertainty, low confidence, retry intent. Overwriting
+// these erases the reasoning trace the model needs to notice it is going in
+// circles, so the original text stays and a nudge is appended after it.
+const SELF_REVIEW_NUDGES = [
+    [/I('ve| have) (completed|finished|done) (the )?.*\.$/i,
+        "Before this counts as complete: did typecheck/lint/test actually run and pass? Verify, then report."],
+    [/I('ll| will) (try again|retry|attempt again|redo)/i,
+        "Name the ROOT CAUSE before retrying — a retry that repeats the same fix fails the same way."],
+    [/I('m| am) (not sure|unsure|uncertain) .*/i,
+        "The uncertainty is worth stating. Now settle it with evidence: read the code, check resolve-diagnostics, or search."],
+    [/this (might|should|could|may) work/i,
+        "CONFIRM it works by running verification before moving on. Do not assume."],
+    [/it (seems|appears|looks) to (be )?(working|fine|correct)/i,
+        "VERIFY with typecheck/lint/test — 'seems to work' is not evidence."],
+];
+// Edit-hotspot feedback. Repeatedly editing one file is often the *correct*
+// path through a hard bug — the failure mode is not the repetition itself but
+// re-applying the same change blind. So the nudge asks the model to inspect its
+// own diff, never to go edit some other file (that spreads the damage).
+function hotspotDiffPrompt(filePath, count) {
+    return `'${filePath}' has been edited ${count} times. Before the next edit, run \`git diff -- ${filePath}\` ` +
+        `and check whether recent edits repeat the same substitution or undo each other. ` +
+        `If the root cause is genuinely in this file, keep working here.`;
+}
 function capTemperature(current, cap) {
     return typeof current === "number" && Number.isFinite(current)
         ? Math.min(current, cap)
@@ -262,7 +300,11 @@ export function getHooks(directory, options, sessionState) {
                     : Array.isArray(input.pattern)
                         ? input.pattern.join(" ")
                         : "";
-                const action = classifyBashCommand(cmd);
+                // `permissions.allowGitReset` / `allowGitClean` only relax the policy for
+                // resolve agents — they are the ones `tool.execute.before` checkpoints.
+                // Native agents keep the universal deny.
+                const permissions = isActiveResolve() ? sessionState.storedConfig?.permissions : undefined;
+                const action = classifyBashCommand(cmd, permissions);
                 // Banned/dangerous commands are denied universally (protect everyone).
                 if (action === "deny") {
                     output.status = "deny";
@@ -344,6 +386,30 @@ export function getHooks(directory, options, sessionState) {
                 if (typeof cmd === "string" && cmd.includes("git commit") && !cmd.includes("-m")) {
                     output.args = { ...output.args, _resolve_hint: "Use 'git commit -m \"message\"' — interactive commit is blocked." };
                 }
+                // Rollback safety net: snapshot the worktree before `git reset --hard` /
+                // `git clean -f` destroys uncommitted work. Runs whenever the command is
+                // about to execute — whether it was un-gated by `permissions.allow*` or
+                // approved by the user at the prompt. If the snapshot cannot be written
+                // in a git repo, abort rather than run the command unprotected.
+                if (typeof cmd === "string") {
+                    const rollback = detectRollbackCommand(cmd);
+                    if (rollback && await isGitRepository(directory)) {
+                        let checkpoint;
+                        try {
+                            checkpoint = await createRollbackCheckpoint(directory, rollback);
+                        }
+                        catch (error) {
+                            throw new Error(`[${PLUGIN_BRAND}] refused to run '${cmd}': could not create a rollback checkpoint (${formatError(error)}). ` +
+                                `Commit or stash your work first.`);
+                        }
+                        narrate(sessionState, "narration.checkpoint");
+                        output.args = {
+                            ...output.args,
+                            _resolve_checkpoint_ref: checkpoint.ref,
+                            _resolve_checkpoint_restore: checkpoint.restoreCommand,
+                        };
+                    }
+                }
             }
             // For write: warn about overwriting existing files
             if (input.tool === "write" && output.args && typeof output.args === "object") {
@@ -406,7 +472,7 @@ export function getHooks(directory, options, sessionState) {
                     // Ralph Loop: inject loop warning into metadata
                     const hotspot = sessionState.editHotspots.get(editedPath);
                     if (hotspot && hotspot.count >= EDIT_HOTSPOT_THRESHOLD) {
-                        meta._resolve_loop_warning = `This file has been edited ${hotspot.count} times. Consider a different approach.`;
+                        meta._resolve_loop_warning = hotspotDiffPrompt(editedPath, hotspot.count);
                     }
                 }
                 output.metadata = meta;
@@ -423,7 +489,7 @@ export function getHooks(directory, options, sessionState) {
                 sessionState.loopWarnings = [];
                 for (const [file, data] of sessionState.editHotspots) {
                     if (data.count >= EDIT_HOTSPOT_THRESHOLD) {
-                        sessionState.loopWarnings.push(`File '${file}' edited ${data.count} times — consider a different approach for this file. Keep iterating.`);
+                        sessionState.loopWarnings.push(hotspotDiffPrompt(file, data.count));
                     }
                 }
             }
@@ -533,47 +599,26 @@ export function getHooks(directory, options, sessionState) {
             // Rewrite passive language only within resolve turns — native chat is verbatim.
             if (!isActiveResolve())
                 return;
-            const replacements = [
-                // Exact: default OpenCode "continue" prompt
-                ["Summarize the task tool output above and continue with your task.",
-                    "Analyze the subtask result above. If it succeeded, continue. If it failed, diagnose and retry. Report completion only when verified."],
-                // Regex: any "Summarize ... and continue" variant
-                [/Summarize the .+ output above and continue/i,
-                    "Analyze the result above. If it succeeded, continue to the next step. If it failed, diagnose root cause and retry with a fix."],
-                // Regex: generic "continue with your task" ending
-                [/continue with your task\.$/i,
-                    "continue driving toward verified completion."],
-                // Regex: "I've completed..." without verification
-                [/I('ve| have) (completed|finished|done) (the )?.*\.$/i,
-                    "Verify your changes pass typecheck/lint/test before reporting completion."],
-                // Ralph Loop: detect "I'll try again" — encourage different approach, don't stop
-                [/I('ll| will) (try again|retry|attempt again|redo)/i,
-                    "Diagnose the ROOT CAUSE of the failure, then apply a DIFFERENT fix. The Ralph Loop keeps going."],
-                // Regex: "I'm not sure" — uncertainty without action
-                [/I('m| am) (not sure|unsure|uncertain) .*/i,
-                    "Resolve uncertainty by reading the code, checking diagnostics, or using resolve-search. Keep driving."],
-                // Regex: "This might work" — low confidence
-                [/this (might|should|could|may) work/i,
-                    "CONFIRM it works by running verification. Do not assume."],
-                // Regex: "It seems to be working" — unverified claim
-                [/it (seems|appears|looks) to (be )?(working|fine|correct)/i,
-                    "VERIFY with typecheck/lint/test. 'Seems to work' is not evidence."],
-            ];
             for (const msg of output.messages) {
                 for (const part of msg.parts) {
                     if (part.type !== "text")
                         continue;
-                    // Preserve collaborative handoffs/questions — never rewrite a turn
-                    // that asks the user something. Only rewrite passive/stalled claims
-                    // ("this might work", "seems fine", unverified "completed", ...).
+                    // Preserve collaborative handoffs/questions — never touch a turn that
+                    // asks the user something.
                     if (HANDOFF_PATTERNS.some((p) => p.test(part.text.trim())))
                         continue;
-                    for (const [pattern, replacement] of replacements) {
-                        if (typeof pattern === "string" ? part.text === pattern : pattern.test(part.text)) {
-                            part.text = replacement;
-                            break; // first match wins
-                        }
+                    const boilerplate = HARNESS_BOILERPLATE_REWRITES.find(([pattern]) => typeof pattern === "string" ? part.text === pattern : pattern.test(part.text));
+                    if (boilerplate) {
+                        part.text = boilerplate[1];
+                        continue;
                     }
+                    // transform() sees the whole message list every turn, so an appended
+                    // nudge would compound. One nudge per part, ever.
+                    if (part.text.includes(NUDGE_MARKER))
+                        continue;
+                    const nudge = SELF_REVIEW_NUDGES.find(([pattern]) => pattern.test(part.text));
+                    if (nudge)
+                        part.text = `${part.text}\n\n${NUDGE_MARKER} ${nudge[1]}`;
                 }
             }
         },
@@ -631,7 +676,10 @@ export function getHooks(directory, options, sessionState) {
                 for (const w of sessionState.loopWarnings.slice(0, 3)) {
                     lines.push(`  - ${w}`);
                 }
+                // Self-observation first — reading your own diff is the cheapest way out
+                // of a hotspot, and the only one that cannot pollute an unrelated file.
                 const strategyKeys = [
+                    "strategy.reviewDiff",
                     "strategy.rereadFile",
                     "strategy.tryDifferent",
                     "strategy.useDiagnostics",

package/dist/messages.d.ts

@@ -6,7 +6,7 @@ export declare function resolveLocale(configured: string | undefined, envLang: s
 export declare function brand(agent: string | undefined): string;
 /** Friendly display name per agent (used in role-play narration). */
 export declare function agentDisplayName(agent: string | undefined, locale: Locale): string;
-export type MessageKey = "reminder.verify" | "reminder.ralphLoopText" | "system.driveResolution" | "system.projectKnowledge" | "system.contextDocs" | "system.verifyCommands" | "system.typescriptMandatory" | "system.failuresHeader" | "system.failuresFooter" | "system.strategyPivotHeader" | "system.strategyPivotBody" | "system.strategyPivotTail" | "system.ralphHeader" | "system.ralphKeepGoing" | "system.sessionStats" | "system.iterationWarning" | "system.dispatchEscalate" | "system.dispatchStop" | "system.dispatchPivot" | "system.awaitingVerify" | "compaction.contextHeader" | "tool.edit" | "tool.write" | "tool.bash" | "tool.task" | "tool.glob" | "tool.grep" | "tool.read" | "tool.webfetch" | "tool.todowrite" | "dispatch.toSubagent" | "dispatch.fromResolver" | "dispatch.coder" | "dispatch.reviewer" | "dispatch.deepReviewer" | "dispatch.explorer" | "dispatch.planner" | "dispatch.architect" | "dispatch.researcher" | "dispatch.debugger" | "dispatch.completed" | "dispatch.failed" | "narration.editing" | "narration.searching" | "narration.reading" | "narration.thinking" | "narration.bashing" | "narration.compacting" | "narration.writing" | "narration.testing" | "narration.typechecking" | "narration.linting" | "narration.git" | "narration.fetch" | "narration.todo" | "narration.diagnostics" | "narration.context" | "narration.verifyPass" | "narration.verifyFail" | "narration.idle" | "strategy.smallerPieces" | "strategy.differentFile" | "strategy.readTest" | "strategy.checkImports" | "strategy.searchSimilar" | "strategy.rereadFile" | "strategy.tryDifferent" | "strategy.useDiagnostics" | "strategy.suggestionLabel";
+export type MessageKey = "reminder.verify" | "reminder.ralphLoopText" | "system.driveResolution" | "system.projectKnowledge" | "system.contextDocs" | "system.verifyCommands" | "system.typescriptMandatory" | "system.failuresHeader" | "system.failuresFooter" | "system.strategyPivotHeader" | "system.strategyPivotBody" | "system.strategyPivotTail" | "system.ralphHeader" | "system.ralphKeepGoing" | "system.sessionStats" | "system.iterationWarning" | "system.dispatchEscalate" | "system.dispatchStop" | "system.dispatchPivot" | "system.awaitingVerify" | "compaction.contextHeader" | "tool.edit" | "tool.write" | "tool.bash" | "tool.task" | "tool.glob" | "tool.grep" | "tool.read" | "tool.webfetch" | "tool.todowrite" | "dispatch.toSubagent" | "dispatch.fromResolver" | "dispatch.coder" | "dispatch.reviewer" | "dispatch.deepReviewer" | "dispatch.explorer" | "dispatch.planner" | "dispatch.architect" | "dispatch.researcher" | "dispatch.debugger" | "dispatch.completed" | "dispatch.failed" | "narration.editing" | "narration.searching" | "narration.reading" | "narration.thinking" | "narration.bashing" | "narration.compacting" | "narration.writing" | "narration.testing" | "narration.typechecking" | "narration.linting" | "narration.git" | "narration.checkpoint" | "narration.fetch" | "narration.todo" | "narration.diagnostics" | "narration.context" | "narration.verifyPass" | "narration.verifyFail" | "narration.idle" | "strategy.smallerPieces" | "strategy.differentFile" | "strategy.readTest" | "strategy.checkImports" | "strategy.searchSimilar" | "strategy.rereadFile" | "strategy.tryDifferent" | "strategy.useDiagnostics" | "strategy.reviewDiff" | "strategy.suggestionLabel";
 type Params = Record<string, string | number>;
 /** Render a message in the requested locale. Picks a random variant if multiple are defined. */
 export declare function t(key: MessageKey, locale: Locale, params?: Params): string;

package/dist/messages.js

@@ -71,8 +71,8 @@ const MESSAGES = {
         "system.strategyPivotHeader": ({ count }) => `🔀 STRATEGY PIVOT: ${count} total failures detected.`,
         "system.strategyPivotBody": "The current approach is not working. Dispatch ARCHITECT to analyze the problem from scratch and propose a fundamentally different strategy.",
         "system.strategyPivotTail": "Then apply the new strategy. Do NOT keep retrying the same approach.",
-        "system.ralphHeader": "🔄 Ralph Loop: heavy editing detected on same file(s):",
-        "system.ralphKeepGoing": "Keep driving — the Ralph Loop should keep iterating until verified resolution.",
+        "system.ralphHeader": "🔄 Ralph Loop: heavy editing detected on same file(s). Repetition is not itself the problem — repeating the *same* edit is:",
+        "system.ralphKeepGoing": "Read the diff before the next edit. If the root cause really is in this file, stay here — moving to an unrelated file to break the count only spreads the damage. Keep driving until verified.",
         "system.sessionStats": ({ edits, calls, elapsed }) => `📊 Session stats: ${edits} edits, ${calls} tool calls, ${elapsed}s elapsed.`,
         "system.iterationWarning": "Significant iteration with failures. Consider a fundamentally different approach — but keep going.",
         "system.dispatchEscalate": ({ count, agent }) => `🔄 Ralph Loop: ${agent ?? "subagent"} dispatch failed ${count} time(s) in a row. Do NOT retry the same way. Diagnose the ROOT CAUSE first (read the error, use resolve-diagnostics), then re-dispatch with a precise fix.`,
@@ -345,6 +345,11 @@ const MESSAGES = {
             "🌳 inspecting the diff",
             "🌳 listening to git",
         ],
+        "narration.checkpoint": [
+            "🛟 snapshotting the worktree before rollback",
+            "🛟 saving a checkpoint you can restore from",
+            "🛟 stashing a safety copy first",
+        ],
         "narration.fetch": [
             "🌐 fetching from the web",
             "🌐 grabbing the docs",
@@ -402,13 +407,14 @@ const MESSAGES = {
             "🪑 brief regroup",
         ],
         "strategy.smallerPieces": "Break the problem into smaller pieces. Edit one function at a time, verify between each.",
-        "strategy.differentFile": "Check if the error is actually in a DIFFERENT file — the real issue may be upstream.",
+        "strategy.differentFile": "Follow the evidence: if diagnostics point at a different file, the real cause may be upstream. Confirm that before editing anything else.",
         "strategy.readTest": "Read the test file if it exists — the test often reveals the expected behavior.",
         "strategy.checkImports": "Check imports — missing or wrong imports are a common cause of cascading errors.",
         "strategy.searchSimilar": "Use resolve-search to find similar patterns elsewhere in the codebase.",
         "strategy.rereadFile": "Re-read the file carefully. You may be missing existing code that conflicts with your edit.",
-        "strategy.tryDifferent": "Try a completely different approach — revert your last change and try a different fix.",
+        "strategy.tryDifferent": "The fix, not the file, is what should change. Try a different fix for the same root cause.",
         "strategy.useDiagnostics": "Use resolve-diagnostics to check current LSP errors before the next edit.",
+        "strategy.reviewDiff": "Run `git diff` on the hotspot file. Look for edits that repeat the same substitution or cancel each other out.",
         "strategy.suggestionLabel": "Strategy suggestion",
     },
     ko: {
@@ -435,8 +441,8 @@ const MESSAGES = {
         "system.strategyPivotHeader": ({ count }) => `🔀 전략 전환: 총 ${count}회의 실패가 감지됐어요.`,
         "system.strategyPivotBody": "지금 접근은 통하지 않아요. ARCHITECT 를 위임해서 문제를 처음부터 분석하고 근본적으로 다른 전략을 제안받으세요.",
         "system.strategyPivotTail": "그 다음 새 전략을 적용하세요. 같은 접근을 다시 시도하지 마세요.",
-        "system.ralphHeader": "🔄 Ralph Loop: 같은 파일을 너무 자주 수정 중이에요:",
-        "system.ralphKeepGoing": "계속 진행하세요 — Ralph Loop 는 검증된 해결이 나올 때까지 반복합니다.",
+        "system.ralphHeader": "🔄 Ralph Loop: 같은 파일을 반복 수정 중이에요. 반복 자체가 문제가 아니라, *같은 수정* 을 반복하는 게 문제입니다:",
+        "system.ralphKeepGoing": "다음 편집 전에 diff 를 읽으세요. 근본 원인이 정말 이 파일에 있다면 계속 여기서 작업하세요 — 횟수를 피하려고 무관한 파일로 옮겨가면 오염만 번집니다. 검증될 때까지 계속.",
         "system.sessionStats": ({ edits, calls, elapsed }) => `📊 세션 통계: ${edits}회 편집, ${calls}회 도구 호출, ${elapsed}초 경과.`,
         "system.iterationWarning": "실패와 함께 반복이 많아졌어요. 근본적으로 다른 접근을 고려하세요 — 하지만 멈추지는 마세요.",
         "system.dispatchEscalate": ({ count, agent }) => `🔄 Ralph Loop: 서브에이전트(${agent ?? "subagent"})가 ${count}회 연속 실패했습니다. 같은 방식으로 재시도 금지. 먼저 루트 코즈를 진단하고, 정확한 수정으로 다시 위임하세요.`,
@@ -722,6 +728,11 @@ const MESSAGES = {
             "🌳 diff 점검 중",
             "🌳 git 말 듣는 중",
         ],
+        "narration.checkpoint": [
+            "🛟 롤백 전에 작업트리 스냅샷 뜨는 중",
+            "🛟 복구용 체크포인트 저장 중",
+            "🛟 만약을 위해 안전 사본 남기는 중",
+        ],
         "narration.fetch": [
             "🌐 웹에서 가져오는 중",
             "🌐 문서 끌어오는 중",
@@ -779,13 +790,14 @@ const MESSAGES = {
             "🪑 잠깐 정비",
         ],
         "strategy.smallerPieces": "문제를 더 작은 단위로 쪼개세요. 한 번에 함수 하나씩 편집하고, 각 사이에 검증하세요.",
-        "strategy.differentFile": "에러가 실제로는 다른 파일에 있는지 확인하세요 — 진짜 원인은 상류일 수 있습니다.",
+        "strategy.differentFile": "증거를 따라가세요: 진단이 다른 파일을 가리킨다면 진짜 원인은 상류일 수 있습니다. 다른 파일을 건드리기 전에 먼저 확인하세요.",
         "strategy.readTest": "테스트 파일이 있으면 먼저 읽으세요 — 기대 동작이 거기에 드러나 있을 때가 많습니다.",
         "strategy.checkImports": "import 를 확인하세요 — 누락되거나 잘못된 import 가 연쇄 에러의 흔한 원인입니다.",
         "strategy.searchSimilar": "resolve-search 로 코드베이스 내 유사 패턴을 찾으세요.",
         "strategy.rereadFile": "파일을 다시 차분히 읽으세요. 편집과 충돌하는 기존 코드를 놓쳤을 수 있습니다.",
-        "strategy.tryDifferent": "완전히 다른 접근을 시도하세요 — 마지막 변경을 되돌리고 다른 방법으로 고치세요.",
+        "strategy.tryDifferent": "바꿔야 할 건 파일이 아니라 해법입니다. 같은 근본 원인에 대해 다른 수정을 시도하세요.",
         "strategy.useDiagnostics": "다음 편집 전에 resolve-diagnostics 로 현재 LSP 에러를 확인하세요.",
+        "strategy.reviewDiff": "핫스팟 파일에 `git diff` 를 실행하세요. 같은 치환을 반복했거나 서로 상쇄되는 편집이 있는지 확인하세요.",
         "strategy.suggestionLabel": "전략 제안",
     },
 };

package/dist/tools/index.js

@@ -15,6 +15,10 @@ function readOnlyToolWriteDenied(ctx, action) {
     return `Permission denied: agent '${ctx.agent ?? "unknown"}' is read-only and cannot ${action}. Dispatch resolver/coder for workspace writes.`;
 }
 function commandExecutionDenied(command) {
+    // Deliberately called without `permissions` — this path executes directly and
+    // never reaches `tool.execute.before`, so a rollback here would run without a
+    // checkpoint. `permissions.allowGitReset`/`allowGitClean` only relax the
+    // OpenCode bash tool, which is checkpointed.
     const action = classifyBashCommand(command);
     if (action === "allow")
         return undefined;

package/dist/types.d.ts

@@ -21,6 +21,14 @@ export type ResolveAgentConfig = {
 };
 export type TierName = "bronze" | "silver" | "gold";
 export type LanguageSetting = "auto" | "en" | "ko";
+/** Opt-in relaxations of the universal bash safety policy. Off by default. */
+export type ResolvePermissions = {
+    /** Let resolve agents run `git reset --hard` (a checkpoint ref is written first). */
+    allowGitReset?: boolean;
+    /** Let resolve agents run `git clean -f...` (a checkpoint ref is written first). */
+    allowGitClean?: boolean;
+};
+export type RollbackKind = "reset" | "clean";
 export type ResolveConfig = {
     tier?: TierName;
     enabled?: ResolveAgentName[];
@@ -33,6 +41,7 @@ export type ResolveConfig = {
     autoUpdate?: boolean;
     language?: LanguageSetting;
     singleAgentMode?: boolean;
+    permissions?: ResolvePermissions;
 };
 export type ResolvePluginOptions = ResolveConfig & {
     config?: string;

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import { ProjectContext, ResolveConfig } from "./types.js";
+import { ProjectContext, ResolveConfig, ResolvePermissions, RollbackKind } from "./types.js";
 export declare const PLUGIN_VERSION: string;
 export declare function runCommand(command: string, cwd: string, timeoutMs: number): Promise<{
     stdout: string;
@@ -10,7 +10,13 @@ export declare function truncateOutput(text: string, maxLen: number): string;
 export declare function sanitizeShellArg(input: string): string;
 export declare function isMissingFileError(error: unknown): boolean;
 export declare function formatError(error: unknown): string;
-export declare function classifyBashCommand(pattern: string): "allow" | "deny" | "ask";
+/**
+ * Which rollback command, if any, this bash line runs. Both are destructive and
+ * denied by default; `permissions.allowGitReset` / `allowGitClean` un-gate them,
+ * and the caller writes a checkpoint ref before execution.
+ */
+export declare function detectRollbackCommand(pattern: string): RollbackKind | undefined;
+export declare function classifyBashCommand(pattern: string, permissions?: ResolvePermissions): "allow" | "deny" | "ask";
 export declare function existsFile(path: string): Promise<boolean>;
 export declare function existsPath(path: string): Promise<boolean>;
 export declare function existsDirectory(path: string): Promise<boolean>;
@@ -18,6 +24,9 @@ export declare function detectProjectContext(directory: string): Promise<Project
 export declare function collectContextFiles(rootDirectory: string, relativeDirectory: string, maxFiles?: number): Promise<string[]>;
 export declare function readPluginVersion(): string;
 export declare function readFirstJson(paths: string[]): Promise<ResolveConfig | undefined>;
+export declare const GIT_HARD_RESET_PATTERN: RegExp;
+export declare const GIT_FORCE_CLEAN_PATTERN: RegExp;
+export declare const GIT_CLEAN_IGNORED_PATTERN: RegExp;
 export declare const BANNED_COMMANDS: ReadonlyArray<RegExp>;
 export declare const DANGEROUS_BASH_PATTERNS: ReadonlyArray<RegExp>;
 export declare const ALWAYS_SAFE_COMMANDS: ReadonlyArray<string>;

package/dist/utils.js

@@ -45,16 +45,45 @@ export function isMissingFileError(error) {
 export function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
-export function classifyBashCommand(pattern) {
+/**
+ * Which rollback command, if any, this bash line runs. Both are destructive and
+ * denied by default; `permissions.allowGitReset` / `allowGitClean` un-gate them,
+ * and the caller writes a checkpoint ref before execution.
+ */
+export function detectRollbackCommand(pattern) {
     const cmd = pattern.trim();
+    if (GIT_HARD_RESET_PATTERN.test(cmd))
+        return "reset";
+    if (GIT_FORCE_CLEAN_PATTERN.test(cmd))
+        return "clean";
+    return undefined;
+}
+function isRollbackPermitted(kind, permissions) {
+    if (kind === "reset")
+        return permissions?.allowGitReset === true;
+    return permissions?.allowGitClean === true;
+}
+export function classifyBashCommand(pattern, permissions) {
+    const cmd = pattern.trim();
+    // A permitted rollback stops being a deny-pattern, but every *other* deny
+    // pattern in the same command line still applies — `git reset --hard && rm -rf /`
+    // must not slip through on the strength of the exemption.
+    const exempt = new Set();
+    if (permissions?.allowGitReset)
+        exempt.add(GIT_HARD_RESET_PATTERN);
+    if (permissions?.allowGitClean)
+        exempt.add(GIT_FORCE_CLEAN_PATTERN);
     for (const re of BANNED_COMMANDS) {
-        if (re.test(cmd))
+        if (!exempt.has(re) && re.test(cmd))
             return "deny";
     }
     for (const re of DANGEROUS_BASH_PATTERNS) {
-        if (re.test(cmd))
+        if (!exempt.has(re) && re.test(cmd))
             return "deny";
     }
+    const rollback = detectRollbackCommand(cmd);
+    if (rollback && isRollbackPermitted(rollback, permissions))
+        return "allow";
     const firstToken = cmd.split(/\s+/)[0];
     if (ALWAYS_SAFE_COMMANDS.includes(firstToken))
         return "allow";
@@ -235,6 +264,17 @@ export async function readFirstJson(paths) {
     }
     return undefined;
 }
+// The two destructive-but-recoverable rollback commands. Shared regex identities
+// so `classifyBashCommand` can exempt them from the deny lists by reference when
+// the matching `permissions.allow*` flag is set.
+export const GIT_HARD_RESET_PATTERN = /\bgit\s+reset\s+--hard/;
+export const GIT_FORCE_CLEAN_PATTERN = /\bgit\s+clean\s+-[a-zA-Z]*f/;
+// `git clean -x` also deletes gitignored files. Checkpoints snapshot via
+// `git add -A`, which honours .gitignore — so a `-x` clean destroys files
+// (.env, local secrets) the checkpoint cannot restore. Never exempted.
+// Matches `-x` in any flag position (`-xdf`, `-f -x`, `-Xf`), but does not
+// reach past a command separator into the next command.
+export const GIT_CLEAN_IGNORED_PATTERN = /\bgit\s+clean\b[^;&|]*\s-[a-zA-Z]*[xX]/;
 export const BANNED_COMMANDS = [
     /\b(vim?|nano|emacs|pico|ed)\b/, // interactive editors
     /\b(less|more|most|pg)\b/, // pagers
@@ -264,7 +304,7 @@ export const BANNED_COMMANDS = [
     /\bchown\s+-R\s+/, // recursive chown
     /\bsudo\s+(rm|chmod|chown|dd|mkfs)/, // sudo + destructive
     /\bgit\s+push\s+--force/, // force push
-    /\bgit\s+reset\s+--hard/, // hard reset
+    GIT_HARD_RESET_PATTERN, // hard reset (gated by permissions.allowGitReset)
     /\brm\s+(-rf?|-fr?)\s+[^.]/, // rm -rf (not dotfiles)
     /\bdd\s+if=/, // dd can destroy disks
     /\b(mkfs|format)\b/, // filesystem format
@@ -272,8 +312,9 @@ export const BANNED_COMMANDS = [
 export const DANGEROUS_BASH_PATTERNS = [
     /\brm\s+.*-[rR].*[fF].*\s+\//, // rm -rf /... (absolute path)
     /\bgit\s+push\s+.*(--force|-f\b)/, // force push
-    /\bgit\s+reset\s+--hard/, // hard reset
-    /\bgit\s+clean\s+-fd/, // clean untracked files
+    GIT_HARD_RESET_PATTERN, // hard reset (gated by permissions.allowGitReset)
+    GIT_FORCE_CLEAN_PATTERN, // clean untracked files (gated by permissions.allowGitClean)
+    GIT_CLEAN_IGNORED_PATTERN, // clean gitignored files — unrecoverable, never exempted
     /\bsudo\s+rm\b/, // sudo rm
     /\bdd\s+.*of=\/dev\//, // dd to device
     /\bchmod\s+-R\s+777\s+\//, // chmod everything

package/opencode-resolve.reference.jsonc

@@ -106,6 +106,44 @@
   // -----------------------------------------------------------------------
   // "singleAgentMode": false,
 
+  // -----------------------------------------------------------------------
+  // permissions (object)
+  // Opt-in relaxations of the universal bash safety policy. Both default to
+  // false, and both apply ONLY to opencode-resolve's own agents — native
+  // opencode agents (build/plan/chat) keep the unconditional deny.
+  //
+  //   allowGitReset — permits `git reset --hard`
+  //   allowGitClean — permits `git clean -f` (and -fd, -df, ...)
+  //
+  // `git clean -x` / `-X` stays denied no matter what: it deletes gitignored
+  // files, and the checkpoint below snapshots via `git add -A`, which honours
+  // .gitignore. A `-x` clean would destroy files (.env, local secrets) the
+  // checkpoint cannot bring back.
+  //
+  // Without these, an agent that tangles the worktree mid-debug has no way to
+  // return to a clean state and stalls. With them, the agent can recover.
+  //
+  // Before either command runs, the plugin snapshots the ENTIRE worktree —
+  // tracked edits and untracked files — into a git ref:
+  //
+  //     refs/resolve-checkpoint/<timestamp>-<reset|clean>
+  //
+  // The snapshot uses a throwaway index, so your real index, working tree,
+  // branches and HEAD are never touched. Nothing is staged or committed.
+  // If the snapshot cannot be written, the destructive command is blocked.
+  //
+  // To recover after a rollback you regret:
+  //     git for-each-ref refs/resolve-checkpoint    # list checkpoints
+  //     git restore --source=<ref> -- .             # bring everything back
+  //
+  // Checkpoints are also taken when you approve one of these commands at the
+  // permission prompt, even with both flags left false.
+  // -----------------------------------------------------------------------
+  // "permissions": {
+  //   "allowGitReset": true,
+  //   "allowGitClean": true
+  // },
+
   // -----------------------------------------------------------------------
   // models (object)
   // Alias map. Keys are either an agent name (coder, reviewer, resolver,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-resolve",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCode plugin that adds a lightweight resolver/coder harness for continuous agentic coding.",
   "type": "module",
   "homepage": "https://jshsakura.github.io/opencode-resolve/",