@parallel-cli/parallel 0.4.9 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to Parallel are documented here.
 
+## 0.5.0 - 2026-06-25
+
+### 0.5.0 Added
+
+- Added an automatically generated, versioned project context in `.parallel/project-context.json`, shared by every new agent in the same folder.
+- Added targeted freshness tracking for files inspected by agents, including content hashes and stale-file warnings.
+- Added visible project-memory indexing, deterministic fallback, token/cost accounting, `/memory`, and `/memory refresh`.
+- Added restored-session summaries directly to new-agent bootstrap context instead of relying on historical notes.
+- Added an agent performance diagnostician and deterministic simulator for model rounds, tool churn, shell micro-commands, repeated reads, hidden compactions, and context amplification.
+- Added adaptive Quick, Standard, and Deep execution profiles with visible badges and `--quick`, `--standard`, and `--deep` overrides.
+- Added a persistent incremental lexical/symbol index under `.parallel/index/` and task-oriented retrieval before the first model call.
+- Added targeted line-range reads, bounded tool output artifacts, provider retry/cache telemetry, and runtime convergence budgets.
+
+### 0.5.0 Changed
+
+- New agents now start from shared architecture, conventions, pitfalls, entry points, and recent work instead of treating the repository as unknown.
+- Replaced generic “explore first” prompting with targeted verification of relevant, unknown, stale, or soon-to-be-modified files.
+- Kept full conversations isolated per agent; `/restore` remains the explicit path for exact conversation continuity.
+- Session snapshots now record inspected files and project-context metadata while remaining compatible with older snapshots.
+- Agent telemetry now records provider wait time, hidden compaction time/calls, and peak prompt tokens.
+- Quick and Standard agents now keep a bounded recent window plus a deterministic work ledger instead of repeatedly sending every raw tool result.
+- Project-memory enrichment now runs in the background; startup no longer waits up to 20 seconds before useful work can begin.
+- Ordinary inter-agent notes are batched for the next natural turn instead of aborting an in-flight model request.
+- Included stable Settings and Wizard list navigation/windowing fixes.
+
+### 0.5.0 Fixed
+
+- Fixed newly spawned agents ignoring all useful work, notes, and conclusions that existed before their creation.
+- Fixed loaded-session summaries being added to the blackboard and then skipped by the next agent’s note cursor.
+- Fixed repetitive generic “Explore the project” progress steps when a valid project map already exists.
+- Fixed simple investigations inheriting the same 60-turn allowance as long-running plans.
+- Fixed large command and inspection results remaining in every later prompt.
+
 ## 0.4.9 - 2026-06-24
 
 ### 0.4.9 Added

package/README.md

@@ -32,6 +32,7 @@ Parallel lets several AI coding agents co-edit the same repository at the same t
 - Keep shell execution controlled with `ask`, `auto-safe`, or `yolo` approvals.
 - Get prompted for npm updates at startup, with an explicit skip path.
 - Save and restore project sessions.
+- Reuse a persistent, automatically synthesized project map across new agents in the same folder.
 - Run headless multi-agent jobs for CI or scripts.
 
 ## Install
@@ -138,6 +139,14 @@ The reviewer is ask-only: it does not edit, does not gate the session globally,
 
 Task and plan agents maintain a small Cursor-style checklist with one active step at a time. The runtime also encourages batched inspection through `read_many` and `inspect_project` so agents avoid slow chains of tiny read-only shell commands.
 
+Every agent also receives an execution profile:
+
+- `quick`: targeted questions, diagnostics, and small changes; six model turns by default.
+- `standard`: bounded multi-file work; sixteen model turns by default.
+- `deep`: plans, migrations, and long-running refactors; up to the configured global limit.
+
+Parallel selects the profile locally without spending a model call. Override it when needed with `--quick`, `--standard`, or `--deep`, for example `/task --quick fix the sound toggle`. A profile only escalates automatically when the agent discovers concrete cross-file complexity; repeated exploration does not earn more budget.
+
 Aliases:
 
 - `/a` -> `/ask`
@@ -340,6 +349,8 @@ If the update succeeds, restart Parallel to run the new version. Use `parallel -
 - `/diff`: live diff history.
 - `/cost`: token and cost breakdown.
 - `/status`: session model, approval mode, agents, and cost snapshot.
+- `/memory`: show shared project-memory freshness, model, tokens, and cost.
+- `/memory refresh`: force a visible regeneration of the shared project map.
 - `/skills`: available skills.
 - `/specialists`: available specialists.
 - `/save [name]`: save the current session.
@@ -347,12 +358,16 @@ If the update succeeds, restart Parallel to run the new version. Use `parallel -
 - `/session <n|latest>`: load a saved session snapshot. If active agents are running, use `/session <n|latest> --force` after saving/stopping what you need.
 - `/restore <agent>`: relaunch a restored agent by name, alias, or saved id when its conversation history is still available.
 
-Session memory has two layers:
+Project and session memory have three distinct layers:
 
 - Live memory: active agents see statuses, notes, claims, work-map warnings, file activity, and recent diffs before every model action.
-- Durable memory: `/save` and autosave persist notes, claims, recent diff excerpts, file activity, work-map warnings, agent aliases, model/provider metadata, context usage, and conversation paths for restore.
+- Project memory: `.parallel/project-context.json` stores a model-generated architecture map, entry points, conventions, pitfalls, file hashes, and recent completed work. It loads automatically for every new agent in the same folder.
+- Local index: `.parallel/index/manifest.json` incrementally records text files, symbols, imports, hashes, and searchable terms. Before the first model call, Parallel uses it to rank the files relevant to the current task.
+- Session/conversation memory: `/save` and autosave persist coordination state and per-agent conversation paths for explicit `/restore`.
 
-Restore is best effort and explicit. `/session` reloads coordination memory into the blackboard; `/restore <agent>` relaunches an agent only when the saved conversation file still exists. Restored agents keep their prior task, mode, model, specialist, and conversation when available.
+Parallel prewarms project memory when a project opens, but the first agent never waits for an LLM-generated synthesis. It immediately uses the persisted map, deterministic fallback, and local task-oriented index while enrichment continues in the background. `/memory` reports both map and index freshness.
+
+Agents trust the project map for orientation, but re-read files that are relevant, unknown, stale, or about to be modified. Full conversations are never copied into unrelated new agents. Restore remains best effort and explicit: `/session` reloads coordination memory, while `/restore <agent>` relaunches the selected agent with its prior conversation when available.
 
 ### Settings And Exit
 
@@ -365,7 +380,7 @@ Restore is best effort and explicit. `/session` reloads coordination memory into
 - `/folder [folder]`: alias for `/project`.
 - `/wizard`: relaunch the setup wizard. If agents are active, use `/wizard --force` after saving/stopping what you need.
 - `/setup`: alias for `/wizard`.
-- `/doctor`: run local readiness diagnostics for provider, key, model, endpoint, attach socket, and Git tooling.
+- `/doctor`: run local readiness diagnostics for provider, key, model, endpoint, project memory, attach socket, and Git tooling.
 - `/help`: full command reference.
 - `/quit`: save the session and exit.
 
@@ -392,7 +407,7 @@ Parallel separates agent modes from shell approval behavior.
 Parallel stores credentials and session state with owner-only permissions where supported:
 
 - `~/.parallel/config.json` and `~/.parallel/update.json` are written privately and atomically.
-- Project runtime files under `.parallel/` use private directories for sessions, conversations, memory, socket state, and attach tokens.
+- Project runtime files under `.parallel/` use private directories for sessions, conversations, project context, memory, socket state, and attach tokens.
 - Attached terminals authenticate to the running session with a per-session token; local clients without the token cannot steer agents or answer approvals.
 - `/doctor` reports local permission warnings alongside provider, model, endpoint, attach socket, `git`, and `gh` checks.
 - Command output shown in logs is sanitized to strip terminal escape/control sequences.
@@ -402,7 +417,9 @@ Shell safety is still a shared responsibility. `auto-safe` uses conservative heu
 
 ## Sessions, Skills, And Specialists
 
-Parallel stores project state under `.parallel/` in the selected project directory. That includes saved sessions, memory, skills, specialists, and session socket state.
+Parallel stores project state under `.parallel/` in the selected project directory. That includes saved sessions, the generated project context, durable facts, skills, specialists, and session socket state.
+
+`.parallel/state.json` remains a best-effort diagnostic snapshot. It is not loaded as conversation history; use project memory for shared understanding and `/restore` for exact agent continuity.
 
 Skills are markdown instruction files agents can load with the `load_skill` tool or that you can force-load with `#skill-name` in a task:
 

package/dist/agents/agent.js

@@ -1,12 +1,14 @@
+import path from 'node:path';
 import * as Diff from 'diff';
 import { ToolExecutor, TOOL_DEFINITIONS } from './tools.js';
 import { costOf } from '../pricing.js';
 import { skillsCatalog } from '../skills.js';
 import { getLang, LANG_NAME_EN, t } from '../i18n.js';
-import { appendFilePrivate, sanitizeForPersistence } from '../security.js';
+import { appendFilePrivate, sanitizeForPersistence, writeFileAtomicPrivate } from '../security.js';
+import { EXECUTION_BUDGETS, nextExecutionProfile, shouldEscalateExecution, } from './execution-policy.js';
 // Agent-facing prompts stay in English (canonical for models). Only notes
 // addressed to the user follow the configured UI language.
-const SYSTEM_PROMPT = (name, task, mode, userLang, skillsList, specialist, projectMemory) => `You are agent "${name}", an autonomous software engineer inside PARALLEL, an environment where SEVERAL agents work at the same time on the SAME project, each on its own task given by the user.
+const SYSTEM_PROMPT = (name, task, mode, userLang, skillsList, specialist, projectMemory, projectContext, profile = 'standard') => `You are agent "${name}", an autonomous software engineer inside PARALLEL, an environment where SEVERAL agents work at the same time on the SAME project, each on its own task given by the user.
 ${specialist
     ? `
 YOUR ROLE — you are the "${specialist.name}" specialist:
@@ -19,6 +21,19 @@ ${task}
 </user_task>
 
 AGENT MODE: ${mode}
+EXECUTION PROFILE: ${profile}
+${profile === 'quick'
+    ? `QUICK PROFILE:
+- This task must converge in a few model turns.
+- Do not create a progress checklist unless the task unexpectedly becomes multi-file.
+- Use the task-oriented local index first, batch the smallest relevant inspection, then conclude.
+- Do not spend a turn only updating status or steps.`
+    : profile === 'standard'
+        ? `STANDARD PROFILE:
+- Keep inspection bounded and use a checklist only when there are multiple distinct outcomes.
+- Escalation is justified by discovered cross-file complexity, not by repeated exploration.`
+        : `DEEP PROFILE:
+- Multi-step planning and broader validation are allowed, but every turn must make concrete progress.`}
 ${mode === 'ask'
     ? `ASK MODE:
 - You are advisory only. Do not modify files.
@@ -28,8 +43,8 @@ ${mode === 'ask'
 - Finish with task_complete using this user-facing structure in ${userLang}: "Réponse courte", "Recommandation", "Pourquoi", "Prochaines étapes".`
     : mode === 'plan'
         ? `PLAN MODE:
-- Explore first with read-only tools.
-- Batch independent reads/searches with read_many or inspect_project. Keep exploration broad enough to be correct but bounded.
+- Start from the shared project context. Inspect only the task-relevant files that are unknown, stale, or needed as evidence.
+- Batch independent targeted reads/searches with read_many or inspect_project.
 - Before modifying any file or running mutating commands, call ask_user with a concrete implementation plan.
 - The plan must include steps, files you expect to touch, risks, and validation.
 - Use options ["Approve", "Revise"], recommended "Revise" so timeout never approves changes.
@@ -37,7 +52,7 @@ ${mode === 'ask'
 - Finish with task_complete using this user-facing structure in ${userLang}: "Plan appliqué", "Ce que j’ai modifié", "Validation", "Risques restants".`
         : `TASK MODE:
 - Execute the user's objective end-to-end.
-- Use this loop: create visible steps, batch inspect, act, batch validate, summarize.
+- Use this loop: create outcome-oriented visible steps, verify the relevant context, act, batch validate, summarize.
 - If the task is a verification/audit and the correct outcome is no file changes, that is valid task work. Say explicitly in task_complete that no modification was necessary and why.
 - Ask the user only when blocked or when a risky product decision cannot be inferred.
 - Finish with task_complete using this user-facing structure in ${userLang}: "Ce que j’ai fait", "Ce que j’ai vérifié", "Résultat", "Détails techniques".`}
@@ -53,6 +68,13 @@ PROJECT MEMORY — durable facts recorded by previous agents on this project. Tr
 <project_memory>
 ${projectMemory}
 </project_memory>
+`
+    : ''}${projectContext
+    ? `
+SHARED PROJECT CONTEXT — automatically maintained across agents in this folder:
+<project_context>
+${projectContext}
+</project_context>
 `
     : ''}
 
@@ -73,7 +95,9 @@ PARALLEL'S PHILOSOPHY — REAL-TIME CO-EDITING, NEVER ANY BLOCKING:
 
 WORK METHOD:
 - For non-trivial work, call update_steps early with 3-6 concrete steps. Keep exactly one step active and mark steps done as you complete them.
-- Explore first before modifying. Decide all independent reads/searches you need, then batch them with read_many or inspect_project instead of calling tools one by one.
+- Do not create a generic "explore the project" step when shared project context already describes the codebase. Steps must state task-specific outcomes.
+- Use shared project context first. Re-read only files directly relevant to the task, files marked stale/unknown, and every file immediately before modifying it.
+- If the shared context is absent or insufficient for the task area, perform a bounded inspection and record durable discoveries.
 - Use run_command for builds/tests/validation and genuinely useful shell scripts. Do NOT spend many turns running grep/head/tail/wc/awk cascades; batch independent shell checks into one labelled command or use inspect_project.
 - Declare your work area with claim_files when you start (and when it changes): it prevents collisions without ever locking anything.
 - If you discover a durable, non-obvious fact about the project (convention, decision, pitfall), save it with remember(fact) for future agents.
@@ -98,6 +122,12 @@ const EMPTY_PERF = {
     shellCommands: 0,
     shellMs: 0,
     readOnlyShellCommands: 0,
+    llmMs: 0,
+    compactionTurns: 0,
+    compactionMs: 0,
+    maxPromptTokens: 0,
+    retries: 0,
+    cachedTokens: 0,
 };
 function noChangeTaskLine() {
     switch (getLang()) {
@@ -124,20 +154,26 @@ export class Agent {
     llm;
     board;
     maxSteps;
+    budget;
     abort = new AbortController();
     paused = false;
     stopped = false;
     lastNoteId = 0;
     lastChangeId = 0;
     readOnlyShellStreak = 0;
+    artifactSeq = 0;
+    convergenceWarned = new Set();
     constructor(opts) {
         this.opts = opts;
         this.id = opts.id;
         this.name = opts.name;
         this.llm = opts.llm;
         this.board = opts.board;
-        this.maxSteps = opts.maxSteps;
-        this.executor = new ToolExecutor(opts.board, opts.id, opts.name, opts.projectRoot, opts.requestApproval, opts.requestQuestion, opts.skills, opts.mode);
+        const profile = opts.profile ?? (opts.mode === 'plan' ? 'deep' : opts.mode === 'ask' ? 'quick' : 'standard');
+        const budget = opts.budget ?? EXECUTION_BUDGETS[profile];
+        this.maxSteps = Math.min(opts.maxSteps, budget.maxRounds);
+        this.budget = budget;
+        this.executor = new ToolExecutor(opts.board, opts.id, opts.name, opts.projectRoot, opts.requestApproval, opts.requestQuestion, opts.skills, opts.mode, opts.onInspect, profile, budget.maxResultChars);
         const info = {
             id: opts.id,
             name: opts.name,
@@ -145,6 +181,7 @@ export class Agent {
             color: opts.color,
             task: opts.task,
             mode: opts.mode,
+            profile,
             model: opts.model,
             state: 'idle',
             currentAction: '',
@@ -273,13 +310,66 @@ export class Agent {
         const current = this.board.agents.get(this.id)?.perf ?? EMPTY_PERF;
         this.board.updateAgent(this.id, {
             perf: {
-                modelTurns: current.modelTurns + (delta.modelTurns ?? 0),
-                toolCalls: current.toolCalls + (delta.toolCalls ?? 0),
-                shellCommands: current.shellCommands + (delta.shellCommands ?? 0),
-                shellMs: current.shellMs + (delta.shellMs ?? 0),
-                readOnlyShellCommands: current.readOnlyShellCommands + (delta.readOnlyShellCommands ?? 0),
+                modelTurns: (current.modelTurns ?? 0) + (delta.modelTurns ?? 0),
+                toolCalls: (current.toolCalls ?? 0) + (delta.toolCalls ?? 0),
+                shellCommands: (current.shellCommands ?? 0) + (delta.shellCommands ?? 0),
+                shellMs: (current.shellMs ?? 0) + (delta.shellMs ?? 0),
+                readOnlyShellCommands: (current.readOnlyShellCommands ?? 0) + (delta.readOnlyShellCommands ?? 0),
+                llmMs: (current.llmMs ?? 0) + (delta.llmMs ?? 0),
+                compactionTurns: (current.compactionTurns ?? 0) + (delta.compactionTurns ?? 0),
+                compactionMs: (current.compactionMs ?? 0) + (delta.compactionMs ?? 0),
+                maxPromptTokens: Math.max(current.maxPromptTokens ?? 0, delta.maxPromptTokens ?? 0),
+                retries: (current.retries ?? 0) + (delta.retries ?? 0),
+                cachedTokens: (current.cachedTokens ?? 0) + (delta.cachedTokens ?? 0),
+            },
+        });
+    }
+    boundedHistory() {
+        const limit = this.budget.maxRecentMessages;
+        if (this.history.length <= limit)
+            return this.history;
+        let cut = Math.max(1, this.history.length - limit);
+        while (cut < this.history.length && this.history[cut].role === 'tool')
+            cut++;
+        const removed = this.history.slice(1, cut);
+        const actions = [];
+        for (const message of removed) {
+            if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
+                for (const call of message.tool_calls) {
+                    actions.push(`${call.function?.name ?? 'tool'}(${String(call.function?.arguments ?? '').slice(0, 100)})`);
+                }
+            }
+            else if (message.role === 'tool') {
+                actions.push(`result: ${String(message.content ?? '').replace(/\s+/g, ' ').slice(0, 140)}`);
+            }
+            if (actions.length >= 24)
+                break;
+        }
+        return [
+            this.history[0],
+            {
+                role: 'user',
+                content: `[DETERMINISTIC WORK LEDGER — older raw outputs omitted]\n${actions.map((item) => `- ${item}`).join('\n') || '- Earlier context omitted.'}`,
             },
+            ...this.history.slice(cut),
+        ];
+    }
+    maybeEscalate() {
+        const next = nextExecutionProfile(this.budget.profile);
+        if (!next)
+            return false;
+        const info = this.board.agents.get(this.id);
+        const changedFiles = new Set(this.board.changes.filter((change) => change.agentId === this.id).map((change) => change.path)).size;
+        if (!shouldEscalateExecution(this.opts.task, info?.inspectedFiles?.length ?? 0, changedFiles))
+            return false;
+        this.budget = EXECUTION_BUDGETS[next];
+        this.maxSteps = Math.min(this.opts.maxSteps, this.budget.maxRounds);
+        this.board.updateAgent(this.id, { profile: next, currentAction: `budget escalated to ${next}` });
+        this.record({
+            role: 'user',
+            content: `[EXECUTION PROFILE ESCALATED TO ${next.toUpperCase()}] Concrete task complexity justified more budget. Continue with targeted work; repeated exploration is not justification for another escalation.`,
         });
+        return true;
     }
     /**
      * Build the live context injected before EVERY model call:
@@ -287,6 +377,9 @@ export class Agent {
      * Returns { text, hasNews } — hasNews drives the 'listening' state.
      */
     liveContext() {
+        if (this.board.agents.size <= 1) {
+            return { text: '[REAL TIME] No other active agent context. Continue with the smallest useful next action.', hasNews: false };
+        }
         let hasNews = false;
         const parts = ['[REAL TIME]', this.board.snapshotFor(this.id)];
         const notes = this.board.notesFor(this.name, this.lastNoteId);
@@ -324,6 +417,14 @@ export class Agent {
         return { text: parts.join('\n'), hasNews };
     }
     async run() {
+        this.board.setAgentState(this.id, 'working', 'loading project memory');
+        let sharedProjectContext = '';
+        try {
+            sharedProjectContext = (await this.opts.projectContext) ?? '';
+        }
+        catch {
+            sharedProjectContext = '';
+        }
         this.board.setAgentState(this.id, 'working', 'starting');
         if (this.opts.initialHistory && this.opts.initialHistory.length > 0) {
             // Resume a previous conversation (/restore): re-record everything into
@@ -333,13 +434,15 @@ export class Agent {
                 this.record(m);
             this.record({
                 role: 'user',
-                content: '[SESSION RESTORED] This conversation was saved and has just been restored. Time has passed: files may have changed on disk. Re-read the files you rely on before editing them, then continue your task from where you left off.',
+                content: `[SESSION RESTORED] This conversation was saved and has just been restored. Continue from where you left off. Use the shared project context below to identify what changed, and re-read only task-relevant files marked stale or files you are about to modify.
+
+${sharedProjectContext}`,
             });
         }
         else {
             this.record({
                 role: 'system',
-                content: SYSTEM_PROMPT(this.name, this.opts.task, this.opts.mode, LANG_NAME_EN[getLang()], skillsCatalog(this.opts.skills), this.opts.specialist, this.opts.projectMemory),
+                content: SYSTEM_PROMPT(this.name, this.opts.task, this.opts.mode, LANG_NAME_EN[getLang()], skillsCatalog(this.opts.skills), this.opts.specialist, this.opts.projectMemory, sharedProjectContext, this.budget.profile),
             });
             // Pasted images (multimodal models): attached to the very first user turn.
             if (this.opts.images && this.opts.images.length > 0) {
@@ -360,9 +463,24 @@ export class Agent {
      */
     async loop() {
         let steps = 0;
+        let closingTurnGranted = false;
         try {
             this.finished = false;
-            while (!this.stopped && steps < this.maxSteps) {
+            while (!this.stopped) {
+                if (steps >= this.maxSteps) {
+                    if (this.maybeEscalate())
+                        continue;
+                    if (!closingTurnGranted) {
+                        closingTurnGranted = true;
+                        this.maxSteps++;
+                        this.record({
+                            role: 'user',
+                            content: '[FINAL BUDGET TURN] Do not inspect further. Call task_complete now with the strongest conclusion supported by current evidence, explicitly stating any remaining uncertainty.',
+                        });
+                        continue;
+                    }
+                    break;
+                }
                 await this.waitWhilePaused();
                 if (this.stopped)
                     break;
@@ -380,13 +498,12 @@ export class Agent {
                 if (live.hasNews) {
                     // Visible (and audible via state event) cue: the agent is listening to the others.
                     this.board.setAgentState(this.id, 'listening', 'reading the other agents’ work…');
-                    await new Promise((r) => setTimeout(r, 600));
                     if (this.stopped)
                         break;
                 }
                 this.repairToolCallHistory();
                 const messages = [
-                    ...this.history,
+                    ...this.boundedHistory(),
                     { role: 'user', content: live.text },
                 ];
                 this.board.setAgentState(this.id, 'thinking');
@@ -396,8 +513,12 @@ export class Agent {
                 const onStop = () => this.llmAbort?.abort();
                 this.abort.signal.addEventListener('abort', onStop, { once: true });
                 let res;
+                const llmStartedAt = Date.now();
                 try {
-                    res = await this.llm.chat(messages, TOOL_DEFINITIONS, this.llmAbort.signal);
+                    res = await this.llm.chat(messages, TOOL_DEFINITIONS, this.llmAbort.signal, {
+                        maxTokens: this.budget.profile === 'quick' ? 2_048 : 4_096,
+                        timeoutMs: this.budget.profile === 'quick' ? 45_000 : this.budget.profile === 'standard' ? 90_000 : 180_000,
+                    });
                 }
                 catch (err) {
                     if (!this.stopped && this.steered) {
@@ -415,7 +536,13 @@ export class Agent {
                     this.llmAbort = null;
                 }
                 this.steered = false;
-                this.updatePerf({ modelTurns: 1 });
+                this.updatePerf({
+                    modelTurns: 1,
+                    llmMs: Date.now() - llmStartedAt,
+                    maxPromptTokens: res.tokensIn,
+                    retries: res.retries,
+                    cachedTokens: res.cachedTokens,
+                });
                 const a = this.board.agents.get(this.id);
                 if (a) {
                     // Real-time financial view: accrue the cost of this round immediately.
@@ -429,6 +556,15 @@ export class Agent {
                         ctxPct: Math.min(100, Math.round((res.tokensIn / CONTEXT_WINDOW) * 100)),
                     });
                 }
+                const currentPerf = this.board.agents.get(this.id)?.perf;
+                const budgetRatio = Math.max(steps / this.budget.maxRounds, (this.board.agents.get(this.id)?.tokensIn ?? 0) / this.budget.maxInputTokens, (currentPerf?.toolCalls ?? 0) / this.budget.maxToolCalls);
+                if (budgetRatio >= this.budget.convergenceAt && !this.convergenceWarned.has(this.budget.profile)) {
+                    this.convergenceWarned.add(this.budget.profile);
+                    this.record({
+                        role: 'user',
+                        content: '[BUDGET CONVERGENCE] You are approaching this execution profile budget. Stop broad exploration. Use the evidence already collected, perform at most one targeted verification, then call task_complete.',
+                    });
+                }
                 const msg = res.message;
                 if (msg.content && msg.content.trim()) {
                     // "✻" marks thinking/commentary steps — visually distinct from tool lines.
@@ -486,11 +622,34 @@ export class Agent {
                     this.board.updateAgent(this.id, { currentAction: label.slice(0, 80) });
                     const shellStartedAt = tc.function.name === 'run_command' ? Date.now() : 0;
                     let result;
-                    try {
-                        result = await this.executor.execute(tc.function.name, args);
+                    const perfBefore = this.board.agents.get(this.id)?.perf;
+                    if ((perfBefore?.toolCalls ?? 0) >= this.budget.maxToolCalls) {
+                        result = 'BUDGET: tool-call limit reached. Conclude with the evidence already collected.';
+                    }
+                    else if (tc.function.name === 'run_command' && (perfBefore?.shellCommands ?? 0) >= this.budget.maxShellCommands) {
+                        result = 'BUDGET: shell-command limit reached. Use existing evidence or a non-shell targeted tool, then conclude.';
+                    }
+                    else {
+                        try {
+                            result = await this.executor.execute(tc.function.name, args);
+                        }
+                        catch (err) {
+                            result = `ERROR: ${err?.message ?? String(err)}`;
+                        }
                     }
-                    catch (err) {
-                        result = `ERROR: ${err?.message ?? String(err)}`;
+                    if (result.length > this.budget.maxResultChars) {
+                        const artifactId = `artifact-${++this.artifactSeq}.txt`;
+                        const artifactFile = path.join(this.opts.projectRoot, '.parallel', 'runs', this.id, 'artifacts', artifactId);
+                        try {
+                            writeFileAtomicPrivate(artifactFile, result);
+                            result =
+                                `${result.slice(0, this.budget.maxResultChars)}\n` +
+                                    `... (${result.length.toLocaleString()} characters total; full output stored as ${artifactId}. ` +
+                                    `Use read_artifact with this id and a targeted line range if more evidence is required.)`;
+                        }
+                        catch {
+                            result = `${result.slice(0, this.budget.maxResultChars)}\n... (truncated by execution budget)`;
+                        }
                     }
                     const shellMs = shellStartedAt ? Date.now() - shellStartedAt : 0;
                     const readOnlyShell = tc.function.name === 'run_command' && isReadOnlyShell(String(args.command ?? ''));
@@ -524,6 +683,7 @@ export class Agent {
                             lastResult: `${noChangePrefix}${summary}`,
                             progressSteps: (this.board.agents.get(this.id)?.progressSteps ?? []).map((s) => ({ ...s, status: 'done' })),
                         });
+                        this.opts.onComplete?.(this.id, summary);
                         // ONE short headline note (the full summary lives in lastResult and
                         // is rendered as the agent's recap) — no duplicated walls of text.
                         const headline = summary.split('\n').find((l) => l.trim())?.trim() ?? 'Task complete.';
@@ -547,7 +707,8 @@ export class Agent {
                     this.board.setAgentState(this.id, 'done', 'done ✅');
                     return;
                 }
-                await this.compactHistory();
+                if (this.budget.profile === 'deep')
+                    await this.compactHistory();
             }
             if (!this.stopped) {
                 this.board.setAgentState(this.id, 'error', `step limit of ${this.maxSteps} reached`);
@@ -572,6 +733,8 @@ export class Agent {
                 return `📖 read ${args.path}`;
             case 'read_many':
                 return `📚 read ${Array.isArray(args.paths) ? args.paths.slice(0, 3).join(', ') : 'files'}`;
+            case 'read_artifact':
+                return `📖 artifact ${args.id}`;
             case 'write_file':
                 return `✏ write ${args.path}`;
             case 'edit_file':
@@ -662,6 +825,7 @@ export class Agent {
             }
             this.board.updateAgent(this.id, { currentAction: t('agent.compactingShort') });
             this.board.log(this.id, 'memory', t('agent.compactingStart'));
+            const compactStartedAt = Date.now();
             const res = await this.llm.chat([
                 {
                     role: 'system',
@@ -669,6 +833,11 @@ export class Agent {
                 },
                 { role: 'user', content: lines.join('\n') },
             ], undefined, this.abort.signal);
+            this.updatePerf({
+                compactionTurns: 1,
+                compactionMs: Date.now() - compactStartedAt,
+                maxPromptTokens: res.tokensIn,
+            });
             const a = this.board.agents.get(this.id);
             if (a) {
                 const price = this.opts.price;

package/dist/agents/execution-policy.js

@@ -0,0 +1,58 @@
+export const EXECUTION_BUDGETS = {
+    quick: {
+        profile: 'quick',
+        maxRounds: 6,
+        maxToolCalls: 12,
+        maxShellCommands: 2,
+        maxInputTokens: 150_000,
+        maxResultChars: 8_000,
+        maxRecentMessages: 24,
+        convergenceAt: 0.7,
+    },
+    standard: {
+        profile: 'standard',
+        maxRounds: 16,
+        maxToolCalls: 32,
+        maxShellCommands: 6,
+        maxInputTokens: 600_000,
+        maxResultChars: 16_000,
+        maxRecentMessages: 42,
+        convergenceAt: 0.75,
+    },
+    deep: {
+        profile: 'deep',
+        maxRounds: 60,
+        maxToolCalls: 120,
+        maxShellCommands: 30,
+        maxInputTokens: 3_000_000,
+        maxResultChars: 32_000,
+        maxRecentMessages: 80,
+        convergenceAt: 0.82,
+    },
+};
+const COMPLEX = /\b(migrat|refactor|architecture|redesign|rewrite|exhaustive|end[- ]to[- ]end|across|monorepo|multi[- ]service|security audit|performance audit|release|deploy)\b/i;
+const SIMPLE = /\b(explain|find|locate|where|why|diagnos|inspect|verify|check|typo|rename|toggle|small|simple)\b/i;
+export function classifyExecutionProfile(task, mode, forced) {
+    if (forced)
+        return forced;
+    if (mode === 'plan')
+        return 'deep';
+    if (mode === 'ask')
+        return COMPLEX.test(task) || task.length > 1_200 ? 'standard' : 'quick';
+    const pathMentions = task.match(/\b[\w./-]+\.(?:ts|tsx|js|mjs|json|md|py|rs|go|java)\b/g)?.length ?? 0;
+    if (COMPLEX.test(task) || pathMentions > 3 || task.length > 1_600)
+        return 'standard';
+    if (SIMPLE.test(task) || pathMentions <= 1 || task.length < 500)
+        return 'quick';
+    return 'standard';
+}
+export function nextExecutionProfile(profile) {
+    if (profile === 'quick')
+        return 'standard';
+    if (profile === 'standard')
+        return 'deep';
+    return null;
+}
+export function shouldEscalateExecution(task, inspectedFiles, changedFiles) {
+    return COMPLEX.test(task) || inspectedFiles > 3 || changedFiles > 3;
+}