@thegitai/cli 1.0.0-preview.1 → 1.0.0-preview.10

package/dist/src/project-orientation.js

@@ -0,0 +1,99 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, } from 'node:fs';
+import path from 'node:path';
+import { shouldIgnoreArtifactPath } from './artifact-policy.js';
+const MAX_TOP_LEVEL_ENTRIES = 80;
+const MAX_DECLARED_TASKS = 40;
+const MAX_NAME_CHARS = 120;
+const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+function normalizeName(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_NAME_CHARS);
+    return normalized || null;
+}
+function normalizeNames(value, limit) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    const seen = new Set();
+    for (const item of value) {
+        const name = normalizeName(item);
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        names.push(name);
+        if (names.length >= limit)
+            break;
+    }
+    return names;
+}
+function readPackageTasks(rootDir) {
+    const packagePath = path.join(rootDir, 'package.json');
+    let fd = null;
+    try {
+        const pathStat = lstatSync(packagePath);
+        if (pathStat.isSymbolicLink() ||
+            !pathStat.isFile() ||
+            pathStat.nlink > 1 ||
+            pathStat.size > MAX_PACKAGE_JSON_BYTES) {
+            return [];
+        }
+        const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+        fd = openSync(packagePath, constants.O_RDONLY | noFollow);
+        const fileStat = fstatSync(fd);
+        if (!fileStat.isFile() ||
+            fileStat.nlink > 1 ||
+            fileStat.size > MAX_PACKAGE_JSON_BYTES ||
+            fileStat.dev !== pathStat.dev ||
+            fileStat.ino !== pathStat.ino) {
+            return [];
+        }
+        const parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        if (!parsed?.scripts || typeof parsed.scripts !== 'object')
+            return [];
+        return normalizeNames(Object.keys(parsed.scripts), MAX_DECLARED_TASKS);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+export function normalizeProjectOrientation(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    const topLevelEntries = normalizeNames(record.topLevelEntries, MAX_TOP_LEVEL_ENTRIES);
+    const packageScripts = normalizeNames(record.packageScripts, MAX_DECLARED_TASKS);
+    if (topLevelEntries.length === 0 && packageScripts.length === 0)
+        return null;
+    return {
+        topLevelEntries,
+        packageScripts,
+        truncated: record.truncated === true,
+    };
+}
+export function collectProjectOrientation(rootDir) {
+    try {
+        const entries = readdirSync(rootDir, { withFileTypes: true })
+            .filter((entry) => !shouldIgnoreArtifactPath(entry.name))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const topLevelEntries = entries
+            .slice(0, MAX_TOP_LEVEL_ENTRIES)
+            .map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
+        return normalizeProjectOrientation({
+            topLevelEntries,
+            packageScripts: readPackageTasks(rootDir),
+            truncated: entries.length > MAX_TOP_LEVEL_ENTRIES,
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/scratch-dir.js

@@ -1,57 +1,75 @@
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync } from 'node:fs';
+import { chmodSync, lstatSync, mkdtempSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-let cachedScratchDir = null;
+const scratchDirs = new Map();
+let activeSessionId = 'default';
+export function setScratchSession(sessionId) {
+    activeSessionId = String(sessionId ?? '').trim() || 'default';
+}
+function allocateSessionScratchDir() {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'thegitai-'));
+    scratchDirs.set(activeSessionId, dir);
+    return dir;
+}
 export function sessionScratchDir() {
-    if (!cachedScratchDir) {
-        cachedScratchDir = path.join(os.tmpdir(), `thegitai-${process.pid}`);
-    }
-    return cachedScratchDir;
+    return scratchDirs.get(activeSessionId) ?? allocateSessionScratchDir();
 }
-function isSquattedScratchRoot(dir) {
+function isOwnedDirectory(dir) {
     try {
         const st = lstatSync(dir);
         if (st.isSymbolicLink() || !st.isDirectory())
-            return true;
+            return false;
         if (process.platform !== 'win32' &&
             typeof process.getuid === 'function' &&
             st.uid !== process.getuid()) {
-            return true;
+            return false;
         }
-        return false;
+        return true;
     }
     catch {
         return false;
     }
 }
 export function ensureSessionScratchDir() {
-    const dir = sessionScratchDir();
-    try {
-        if (isSquattedScratchRoot(dir)) {
-            cachedScratchDir = mkdtempSync(path.join(os.tmpdir(), 'thegitai-'));
-            return cachedScratchDir;
+    let dir = sessionScratchDir();
+    if (!isOwnedDirectory(dir)) {
+        dir = allocateSessionScratchDir();
+    }
+    if (process.platform !== 'win32') {
+        chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+function hasUnsafeScratchComponent(root, relativePath) {
+    let current = root;
+    for (const segment of relativePath.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = lstatSync(current);
+            if (stat.isSymbolicLink())
+                return true;
+            if (stat.isDirectory())
+                continue;
+            if (!stat.isFile() || stat.nlink > 1)
+                return true;
         }
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-        if (process.platform !== 'win32') {
-            chmodSync(dir, 0o700);
+        catch (error) {
+            return error?.code !== 'ENOENT';
         }
     }
-    catch {
-    }
-    return sessionScratchDir();
+    return false;
+}
+export function isWithinSessionScratchDir(absPath) {
+    const root = path.resolve(ensureSessionScratchDir());
+    const resolved = path.resolve(absPath);
+    const relative = path.relative(root, resolved);
+    return !relative.startsWith('..') && !path.isAbsolute(relative);
 }
 export function isInsideTheGitAiScratch(absPath) {
-    const tempRoot = path.resolve(os.tmpdir());
-    const relPath = path.relative(tempRoot, path.resolve(absPath));
-    if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
-        return false;
-    }
-    const first = relPath.split(/[\\/]/, 1)[0] ?? '';
-    if (!/^thegitai(?:$|[-.])/i.test(first)) {
-        return false;
-    }
-    if (/[*?[\]{}]/.test(first)) {
+    const root = path.resolve(ensureSessionScratchDir());
+    const resolved = path.resolve(absPath);
+    const relative = path.relative(root, resolved);
+    if (!isWithinSessionScratchDir(resolved))
         return false;
-    }
-    return !isSquattedScratchRoot(path.join(tempRoot, first));
+    return !hasUnsafeScratchComponent(root, relative);
 }

package/dist/src/session-store.js

@@ -1,12 +1,13 @@
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { getClientStateDir } from './client-state.js';
 import { normalizeAssistantEditJournal } from './edit-journal.js';
 import { cloneSessionSafetyState, createSessionSafetyState, mergeLocalSessionSafetyState, normalizeSessionSafetyState, } from './session-safety.js';
-import { truncate } from './utils.js';
+import { singleLinePreview } from './utils.js';
 const SESSION_STORE_VERSION = 1;
-const MAX_RECENT_SESSIONS = 5;
+export const MAX_RECENT_SESSIONS = 10;
 function cloneJson(value) {
     return JSON.parse(JSON.stringify(value ?? null));
 }
@@ -77,6 +78,12 @@ function listSessionFiles(rootDir, env = process.env) {
         .filter((name) => name.endsWith('.json'))
         .map((name) => path.join(dir, name));
 }
+function normalizeBranch(value) {
+    const text = String(value ?? '')
+        .replace(/[\r\n\t]/g, ' ')
+        .trim();
+    return text ? text.slice(0, 120) : null;
+}
 function normalizeHistory(value) {
     if (!Array.isArray(value))
         return [];
@@ -107,6 +114,7 @@ function normalizeSnapshot(raw, rootDir) {
         createdAt: normalizeIsoDate(raw.createdAt),
         updatedAt: normalizeIsoDate(raw.updatedAt),
         modelId,
+        branch: normalizeBranch(raw.branch),
         history: cloneJson(normalizeHistory(raw.history)),
         clientState: sanitizeClientState(raw.clientState),
         serverState: sanitizeOpaqueState(raw.serverState),
@@ -154,6 +162,21 @@ export function pruneSavedSessions(rootDir, env = process.env) {
         }
     }
 }
+export function readGitBranch(rootDir) {
+    try {
+        const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: rootDir,
+            encoding: 'utf8',
+            timeout: 1500,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const branch = result.status === 0 ? String(result.stdout ?? '').trim() : '';
+        return branch && branch !== 'HEAD' ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function snapshotFromSession(session) {
     const now = new Date().toISOString();
     const createdAt = normalizeIsoDate(session.sessionCreatedAt ?? now);
@@ -168,6 +191,7 @@ export function snapshotFromSession(session) {
         createdAt,
         updatedAt: now,
         modelId: session.modelId,
+        branch: readGitBranch(session.rootDir),
         history: cloneJson(session.history),
         clientState: {
             editCounter: session.clientState.editCounter,
@@ -210,6 +234,9 @@ export function applySessionSnapshot(session, snapshot, options = {}) {
         safety: mergeLocalSessionSafetyState(session.clientState.safety, snapshot.clientState.safety),
     };
 }
+export function sessionHasUserMessage(session) {
+    return session.history.some((entry) => Boolean(userPromptText(entry)));
+}
 function extractMarkedSection(text, marker) {
     const index = text.indexOf(marker);
     if (index === -1)
@@ -218,23 +245,27 @@ function extractMarkedSection(text, marker) {
     const end = after.indexOf('\n\n');
     return (end === -1 ? after : after.slice(0, end)).trim();
 }
-function extractLastUserMessage(history) {
-    for (let i = history.length - 1; i >= 0; i--) {
-        const entry = history[i];
-        if (!entry || entry.role !== 'user')
-            continue;
-        const text = (entry.parts ?? [])
-            .map((part) => (typeof part?.text === 'string' ? part.text : ''))
-            .filter(Boolean)
-            .join('\n')
-            .trim();
-        if (!text)
-            continue;
-        const request = extractMarkedSection(text, 'Current user request:') ||
-            extractMarkedSection(text, 'User request:');
-        const message = extractMarkedSection(text, 'Current user message:') ||
-            extractMarkedSection(text, 'User message:');
-        return truncate(request || message || text, 120);
+export function userPromptText(entry) {
+    if (!entry || entry.role !== 'user' || entry.kind !== 'turnStart')
+        return '';
+    const text = (entry.parts ?? [])
+        .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+    if (!text)
+        return '';
+    const request = extractMarkedSection(text, 'Current user request:') ||
+        extractMarkedSection(text, 'User request:');
+    const message = extractMarkedSection(text, 'Current user message:') ||
+        extractMarkedSection(text, 'User message:');
+    return (request || message || text).trim();
+}
+function extractFirstUserPrompt(history) {
+    for (const entry of history) {
+        const text = userPromptText(entry);
+        if (text)
+            return singleLinePreview(text, 120);
     }
     return '';
 }
@@ -247,8 +278,9 @@ function metadataFromSnapshot(snapshot) {
         updatedAt: snapshot.updatedAt,
         modelId: snapshot.modelId,
         messageCount: snapshot.history.length,
-        lastUserMessage: extractLastUserMessage(snapshot.history),
+        lastUserMessage: extractFirstUserPrompt(snapshot.history),
         summaryPreview: '',
+        branch: snapshot.branch ?? null,
     };
 }
 export function listSessionMetadata(rootDir, env = process.env) {

package/dist/src/session.js

@@ -69,6 +69,14 @@ export function createSession({ rootDir, autoYes = false, agentMode, modelId, ma
         serverState: cloneOpaqueState(serverState),
     };
 }
+export function startNewConversation(session) {
+    clearConversation(session);
+    const createdAt = new Date().toISOString();
+    session.sessionId = createSessionId();
+    session.sessionName = null;
+    session.sessionCreatedAt = createdAt;
+    session.sessionUpdatedAt = createdAt;
+}
 export function clearConversation(session) {
     session.history = [];
     session.serverState = preserveProviderSelection(session.serverState);

package/dist/src/tool-executor.js

@@ -2,6 +2,7 @@ import { drainBackgroundJobNotifications, getBackgroundJob, } from './background
 import { canStoreEditSnapshot, isEditToolName, isGitWorkTree, MAX_EDIT_JOURNAL_RECORDS, operationFromSnapshots, readFileEditSnapshot, } from './edit-journal.js';
 import { clearEditFailure, collectCommandMutations, captureMutationBaseline, ensureActiveCheckpoint, recordEditFailure, recordSessionEdit, rememberCheckpointFiles, } from './session-safety.js';
 import { buildAgentModeToolBlockedResult, } from './agent-mode.js';
+import { classifyProjectPath } from './patcher.js';
 import { dispatchTool } from './tools/index.js';
 import { syncIndexFromDisk } from './project-index.js';
 import { PATH_REPAIRING_EDIT_TOOLS, repairFilePath } from './tools/path-suggest.js';
@@ -84,9 +85,38 @@ async function collectTrackedCommandMutations({ session, projectIndex, result, t
     invalidateShellDiagnosticsCache(session.rootDir);
     rememberCheckpointFiles(session.clientState.safety, session.rootDir, records.map((record) => record.filePath), turnId);
     const priorSync = result.repoSync;
-    if (!(priorSync &&
-        (priorSync.added || priorSync.modified || priorSync.removed))) {
-        result.repoSync = await syncIndexFromDisk(projectIndex);
+    if (!(priorSync && (priorSync.added || priorSync.modified || priorSync.removed))) {
+        const mutationCounts = {
+            added: records.filter((record) => record.operation === 'create').length,
+            modified: records.filter((record) => record.operation === 'update').length,
+            removed: records.filter((record) => record.operation === 'delete').length,
+            indexedChunks: 0,
+            retrievalTokensUsed: 0,
+        };
+        if (priorSync?.error) {
+            result.repoSync = {
+                ...mutationCounts,
+                indexSyncError: priorSync.error,
+                skipped: true,
+                reason: 'local index sync failed after command execution',
+            };
+        }
+        else {
+            try {
+                const repoSync = await syncIndexFromDisk(projectIndex);
+                result.repoSync = {
+                    ...repoSync,
+                    added: Math.max(repoSync.added, mutationCounts.added),
+                    modified: Math.max(repoSync.modified, mutationCounts.modified),
+                    removed: Math.max(repoSync.removed, mutationCounts.removed),
+                };
+            }
+            catch (error) {
+                const indexSyncError = error instanceof Error ? error.message : String(error);
+                result.repoSync = { ...mutationCounts, indexSyncError };
+                session.onStatus(`Repository changes were recorded, but local index sync failed: ${indexSyncError}`);
+            }
+        }
     }
     result.sessionEdits = records.map((record) => ({
         id: record.id,
@@ -150,7 +180,7 @@ export async function collectBackgroundJobUiOutputMutations({ session, projectIn
     }
 }
 function recordAssistantEdit(session, call, result, before) {
-    if (!before || !isEditToolName(call.name))
+    if (!before || !isEditToolName(call.name) || result?.scratch === true)
         return;
     if (!result || typeof result !== 'object' || result.ok !== true) {
         const filePath = getEditToolFilePath(call);
@@ -231,10 +261,12 @@ export async function executeLocalToolCall(toolContext, session, call) {
             !editToolWritesSeparateOutput(call)
             ? repairFilePath(session.rootDir, rawEditFilePath)
             : rawEditFilePath;
-        if (filePathBeforeEdit) {
+        const tracksRepositoryEdit = filePathBeforeEdit &&
+            classifyProjectPath(session.rootDir, filePathBeforeEdit) === 'project';
+        if (tracksRepositoryEdit) {
             rememberCheckpointFiles(session.clientState.safety, session.rootDir, [filePathBeforeEdit], session.turnState.id);
         }
-        const beforeEditSnapshot = filePathBeforeEdit
+        const beforeEditSnapshot = tracksRepositoryEdit
             ? readFileEditSnapshot(session.rootDir, filePathBeforeEdit)
             : null;
         const commandTracker = call.name === 'run_command' || call.name === 'run_node_script'

package/dist/src/tools/delete-file.js

@@ -1,5 +1,5 @@
 import chalk from '../colors.js';
-import { deleteProjectFile } from '../patcher.js';
+import { classifyProjectPath, deleteProjectFile } from '../patcher.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { removeIndexFile } from '../project-index.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
@@ -9,10 +9,27 @@ export async function deleteFile(context, args) {
     if (!filePath) {
         return { ok: false, error: 'filePath is required' };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to delete outside the project root: ${filePath}. Deletable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'delete_file',
+                action: 'Delete files inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR).',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     const result = deleteProjectFile(rootDir, filePath);
     if (result.deleted) {
-        await removeIndexFile(projectIndex, filePath);
-        invalidateShellDiagnosticsCache(rootDir, filePath);
+        if (!scratchPath) {
+            await removeIndexFile(projectIndex, filePath);
+            invalidateShellDiagnosticsCache(rootDir, filePath);
+        }
         if (!isTuiMode())
             console.log(chalk.red(`  🗑️  Deleted: ${filePath}`));
     }
@@ -21,7 +38,8 @@ export async function deleteFile(context, args) {
         filePath,
         changed: result.deleted,
         deleted: result.deleted,
+        ...(scratchPath ? { scratch: true } : {}),
         content: result.content,
-        diagnostics: result.deleted ? runShellDiagnostics(rootDir) : undefined,
+        diagnostics: result.deleted && !scratchPath ? runShellDiagnostics(rootDir) : undefined,
     };
 }

package/dist/src/tools/patch-file.js

@@ -1,7 +1,7 @@
 import chalk from '../colors.js';
 import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
-import { applyUnifiedPatch, readProjectFile, renderDiffPreview, writeProjectFile, } from '../patcher.js';
+import { applyUnifiedPatch, classifyProjectPath, readProjectFile, renderDiffPreview, writeProjectFile, } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { repairFilePath } from './path-suggest.js';
 import { isTuiMode } from '../runtime-mode.js';
@@ -29,6 +29,21 @@ export async function patchFile(context, args) {
             failureCategory: 'invalid_argument',
         };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to edit outside the project root: ${filePath}. Editable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'patch_file',
+                action: 'Edit files inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR) for temporary files.',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);
@@ -68,20 +83,29 @@ export async function patchFile(context, args) {
                 ok: false,
                 skipped: true,
                 filePath,
-                error: 'User declined patch',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'patch_file',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent edit; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed patch. Nothing was changed; this was not a tool failure or an automated system skip.',
             };
         }
     }
     const { changed } = writeProjectFile(rootDir, filePath, patchedContent);
     let indexedChunks = 0;
     let retrievalTokensUsed = 0;
-    if (changed) {
+    if (changed && !scratchPath) {
         const indexResult = await upsertIndexFile(projectIndex, filePath);
         indexedChunks = indexResult.indexedChunks;
         retrievalTokensUsed = indexResult.retrievalTokensUsed ?? 0;
     }
-    invalidateShellDiagnosticsCache(rootDir, filePath);
-    const diagnostics = runShellDiagnostics(rootDir, filePath);
+    let diagnostics;
+    if (!scratchPath) {
+        invalidateShellDiagnosticsCache(rootDir, filePath);
+        diagnostics = runShellDiagnostics(rootDir, filePath);
+    }
     const originalLines = originalContent.split('\n').length;
     const patchedLines = patchedContent.split('\n').length;
     if (!isTuiMode()) {
@@ -94,6 +118,7 @@ export async function patchFile(context, args) {
         filePath,
         changed,
         operation: 'patch',
+        ...(scratchPath ? { scratch: true } : {}),
         indexedChunks,
         retrievalTokensUsed,
         bytesWritten: Buffer.byteLength(patchedContent, 'utf-8'),

package/dist/src/tools/read-file.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { normalizeProjectRelativePath, shouldIgnoreArtifactPath, } from '../artifact-policy.js';
 import { buildSecretFilePreview, isDotenvLikePath, looksLikeEditableDotenv, shouldUseSecretFilePreview, } from '../secret-preview.js';
 import { readProjectFile } from '../patcher.js';
+import { isWithinSessionScratchDir } from '../scratch-dir.js';
 import { repairFilePath } from './path-suggest.js';
 import { dotenvFitsRedactionBudget, getCurrentFileHash, recordReadCoverage, redactContentWithStableTokens, redactDotenvWithStableTokens, } from '../session-safety.js';
 import { readFileRange, truncate } from '../utils.js';
@@ -16,6 +17,7 @@ export async function readFile(context, args) {
         return { ok: false, error: 'filePath is required' };
     }
     const projectPath = normalizeProjectRelativePath(rootDir, filePath);
+    const scratchPath = path.isAbsolute(filePath) && isWithinSessionScratchDir(filePath);
     if (!projectPath && !path.isAbsolute(filePath)) {
         return {
             ok: false,
@@ -37,7 +39,7 @@ export async function readFile(context, args) {
         };
     }
     let content;
-    if (projectPath) {
+    if (projectPath || scratchPath) {
         try {
             content = readProjectFile(rootDir, filePath);
         }

package/dist/src/tools/replace-document-text.js

@@ -188,7 +188,13 @@ export async function replaceDocumentText(context, args) {
                 ok: false,
                 skipped: true,
                 filePath: targetPath,
-                error: 'User declined replace_document_text',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'replace_document_text',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent edit; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed document edit. Nothing was changed; this was not a tool failure or an automated system skip.',
             };
         }
     }