Method pruneMessages

src/agent/loop.ts:2575–2657

Drop oldest turn groups when context exceeds budget. Preserves tool_call/tool_result coupling.

(messages: Message[], maxTokens: number)

          this.planGateSatisfied = true; // good — the model is planning; let it through
        } else if (tc.function.name.startsWith('artifact_')) {
          // Artifact tools produce a standalone deliverable (a page/component the user keeps),
          // not a refactor of the project codebase — the architecture-plan discipline doesn't
          // apply, and gating them just derails the create→preview→review flow. Let them through.
        } else if (!this.planGateSatisfied && !this.planGateFired) {
          this.planGateFired = true; // fire at most once per run
          logger.info('Pre-flight gate: requiring a plan before the first build action', { tool: tc.function.name });
          uiEvents.push({ type: 'progress', message: '🧭 Architecture gate: plan first, then build' } as any);
          return { content: PREFLIGHT_MESSAGE, isError: true, uiEvents };
        }
      }

      // ─── Read-before-write gate (stateful tool gating) ───
      // The system prompt's "Read before write" rule, enforced in code instead of prose.
      // A mutating filesystem tool on an EXISTING file is refused unless the file was
      // successfully read this session — and refused if it changed on disk since the
      // last read (stale knowledge). The refusal is a normal tool-result observation,
      // so the model self-corrects by calling read_file. New-file creation always passes.
      // Off-switch: discipline.readBeforeWrite: false
      if (isGatedMutationTool(tc.function.name) &&
          (this.config as any)?.discipline?.readBeforeWrite !== false) {
        for (const p of extractMutationPaths(tc.function.name, args)) {
          const absP = path.isAbsolute(p) ? p : path.resolve(this.effectiveCwd ?? this.cwd, p);
          let st: fsSync.Stats | null = null;
          try { st = fsSync.statSync(absP); } catch { st = null; }
          if (!st || !st.isFile()) continue; // new file (or non-file): creation is allowed
          const verdict = this.readLedger.check(absP, st.mtimeMs);
          if (!verdict.ok) {
            const rel = path.relative(this.effectiveCwd ?? this.cwd, absP) || p;
            logger.info('Read-before-write gate refused mutation', {
              tool: tc.function.name, path: rel, kind: verdict.kind,
            });
            uiEvents.push({
              type: 'progress',
              message: `🔒 Read-before-write: ${rel} ${verdict.kind === 'unread' ? 'not read yet' : 'changed since last read'} — asking model to read it first`,
            } as any);
            return { content: buildGateMessage(rel, verdict.kind), isError: true, uiEvents };
          }
        }
      }

      // ─── Auto-snapshot: take ONE snapshot per turn, before the first mutating tool ───
      // Why per-turn instead of per-tool: a single user request often triggers many
      // edits (read → edit_text × 3 → bash test → edit_text × 2). One snapshot at
      // the start of the work captures the pre-change state. /undo rolls back the
      // whole turn — exactly what the user wants if "make the change" went sideways.
      //
      // This is the safety net Hamed asked for: every mutation has a back button.
      if (this.snapshotService && !this.turnSnapshotTaken) {
        const isMutating = tool && !tool.isReadOnly;
        if (isMutating) {
          try {
            const rec = this.snapshotService.takeSnapshot(
              `turn-${this.currentTurn}: before ${tc.function.name}`,
              this.currentTurn,
            );
            if (rec) {
              this.turnSnapshotTaken = true;
              logger.info('Auto-snapshot taken before mutating tool', {