zames_pro 2.58.0 → 2.60.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.60.0]
+
+### Added
+
+- PreToolUse / PostToolUse hooks (see `src/hooks.ts`): a project policy can
+  attach an external script to every tool call via `.zames/hooks.json`
+  (`{ "PreToolUse": [{matcher, command}], "PostToolUse": [...] }`). A
+  PreToolUse hook that exits non-zero BLOCKS the call (its output becomes the
+  tool result); a PostToolUse hook's stdout is appended to the result.
+  Hooks are best-effort: a missing/malformed config, a crash or a 10s timeout
+  never fails the agent loop.
+
+## [2.59.0]
+
+### Added
+
+- `/improve [id]` — a backlog-driven self-improvement loop. It picks the
+  next open item from `BACKLOG.md` (highest priority, or an explicit id),
+  runs the standard task loop on it (implement, typecheck/lint/test, mark
+  the item done, add a CHANGELOG entry) and leaves the changes uncommitted
+  for review. This is the reproducible hand-off path for a fresh agent.
+
 ## [2.58.0]
 
 ### Added
@@ -198,7 +220,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Session banner warns when no saved DeepSeek session exists.
 - `--no-color` flag (explicit `NO_COLOR`).
 
-[Unreleased]: https://github.com/Viqto0r/zames_pro/compare/v2.58.0...HEAD
+[Unreleased]: https://github.com/Viqto0r/zames_pro/compare/v2.60.0...HEAD
+[2.60.0]: https://github.com/Viqto0r/zames_pro/compare/v2.59.0...v2.60.0
+[2.59.0]: https://github.com/Viqto0r/zames_pro/compare/v2.58.0...v2.59.0
 [2.58.0]: https://github.com/Viqto0r/zames_pro/compare/v2.57.1...v2.58.0
 [2.57.1]: https://github.com/Viqto0r/zames_pro/compare/v2.57.0...v2.57.1
 [2.57.0]: https://github.com/Viqto0r/zames_pro/compare/v2.56.0...v2.57.0

package/README.md

@@ -247,6 +247,10 @@ Codex CLI:
   instead of the whole list.
 - /review [focus] [--staged] — ask the agent to review uncommitted changes
   and report findings (no code changes).
+- /improve [id] — self-improvement loop: take the next open item from
+  `BACKLOG.md` (or a specific id, e.g. `/improve B3`), implement it, run the
+  typecheck/lint/tests, mark it done and add a CHANGELOG entry. Nothing is
+  committed — the changes stay in the working tree for review.
 - /plan [on|off] — plan (read-only) mode. While it is on, the mutating tools
   (Write/Edit/MultiEdit/ApplyPatch/Bash, GitAdd/GitCommit/GitPush) are removed
   from the tool set, so the agent can investigate without touching the tree.

package/dist/agent-loop.js

@@ -5,7 +5,13 @@ import { parseXmlToolCalls } from './xml-toolcall.js';
 import { translate } from './i18n.js';
 import { substituteAttachmentMarkers } from './commands.js';
 import { normText } from './browser.js';
-export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 0, freshChat = false, sendSystemPrompt = false, transcript = null, attachments = [], onThinking = () => { }, onSendPause = () => { }, onSendState = () => { }, onNotice = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, onWarning = () => { }, debugLog = false, locale = 'ru', askDeadlineMs = 240_000, maxAfterToolRetries = 6, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, }) {
+import { loadHooks, runPreToolUse, runPostToolUse, } from './hooks.js';
+export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 0, freshChat = false, sendSystemPrompt = false, transcript = null, attachments = [], onThinking = () => { }, onSendPause = () => { }, onSendState = () => { }, onNotice = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, onWarning = () => { }, debugLog = false, locale = 'ru', askDeadlineMs = 240_000, maxAfterToolRetries = 6, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, hooks = undefined, }) {
+    // Resolve the hook config ONCE per task: a read per tool call would be
+    // wasteful, and a mid-task edit of hooks.json is not something to chase.
+    // `undefined` means "read .zames/hooks.json"; an explicit null disables
+    // hooks entirely.
+    const hookConfig = hooks === undefined ? loadHooks(workdir) : (hooks ?? {});
     // UI callbacks must NEVER break the agent loop. A rendering error (a huge
     // tool result, a broken markdown frame, a closed terminal) used to throw
     // out of the loop right after a tool call — the session looked "stopped
@@ -705,6 +711,21 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             syncToolAbort();
             safeToolCall(call.tool, call.args);
             transcript?.log('tool_call', { tool: call.tool, args: call.args });
+            // PreToolUse hooks run BEFORE the tool. A non-zero exit BLOCKS the call:
+            // its output becomes the tool result and the tool itself never runs.
+            // Best-effort by design — hooks must not be able to kill the loop.
+            const denial = await runPreToolUse(hookConfig, call.tool, call.args, workdir);
+            if (denial !== null) {
+                const blocked = `Blocked by PreToolUse hook: ${denial}`;
+                transcript?.log('hook_pre_deny', { tool: call.tool, reason: denial });
+                safeToolResult(blocked);
+                transcript?.log('tool_result', {
+                    tool: call.tool,
+                    result: blocked,
+                });
+                results.push({ tool: call.tool, result: blocked });
+                continue;
+            }
             let result;
             // While the tool runs, poll for an Esc/Ctrl+C: the abort flag is a plain
             // boolean set by stopGeneration(), so the only way to turn it into a
@@ -722,6 +743,17 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             finally {
                 clearInterval(poll);
             }
+            // PostToolUse hooks run AFTER the tool; their stdout is appended to the
+            // result (e.g. `prettier` output) before it is fed back to the model.
+            // Best-effort: a hook failure is ignored, the tool result still stands.
+            const post = await runPostToolUse(hookConfig, call.tool, call.args, String(result), workdir);
+            if (post) {
+                transcript?.log('hook_post_output', { tool: call.tool, output: post });
+                result = `${String(result)}
+
+[PostToolUse hook]
+${post}`;
+            }
             safeToolResult(result);
             transcript?.log('tool_result', {
                 tool: call.tool,

package/dist/commands.js

@@ -707,6 +707,79 @@ export function mergeMessages(msgs) {
     const text = header + NL + NL + parts.join(NL + NL + '---' + NL + NL);
     return { text, attachments };
 }
+// Parse BACKLOG.md into actionable items. Recognizes headings of the form
+// `### A1. ...`, `### D7. ...` and marks an item done when its heading carries
+// a `[x]` marker. Pure; unit-tested. We deliberately do NOT parse the whole
+// markdown structure — only the headings the file contract promises.
+export function parseBacklogItems(text) {
+    const out = [];
+    let priority = '';
+    for (const raw of String(text ?? '').split(NL)) {
+        const line = raw.trimEnd();
+        const p = /^##\s+(P[0-3])\b/.exec(line);
+        if (p) {
+            priority = p[1];
+            continue;
+        }
+        const m = /^###\s+([A-Z]\d+)\.\s+(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const id = m[1];
+        const rest = m[2];
+        // The `[x]` rewrite in BACKLOG keeps the ORIGINAL heading under a
+        // <details> block wrapped in `~~`. That archived copy must not be counted
+        // as a second, open item — skip a heading whose text starts with `~~`.
+        if (rest.trim().startsWith('~~'))
+            continue;
+        const done = /^\[x\]/i.test(rest.trim());
+        // The title is the heading text with the [x] marker and the `~~` strike
+        // wrappers removed, so a done item still has a clean label.
+        const title = rest
+            .replace(/^\[x\]\s*/i, '')
+            .replace(/~~/g, '')
+            .trim();
+        out.push({ id, title, status: done ? 'done' : 'open', priority });
+    }
+    return out;
+}
+// The next item to work on: the highest-priority OPEN item, in file order.
+// P0 first, then P1..P3. An explicit id overrides the priority search.
+export function nextBacklogItem(items, wanted) {
+    const open = items.filter((i) => i.status === 'open');
+    if (wanted) {
+        const w = wanted.trim().toUpperCase();
+        return items.find((i) => i.id.toUpperCase() === w) || null;
+    }
+    if (!open.length)
+        return null;
+    const rank = (p) => {
+        const m = /P(\d)/.exec(p || '');
+        return m ? Number(m[1]) : 9;
+    };
+    return open.slice().sort((a, b) => rank(a.priority) - rank(b.priority))[0];
+}
+// The task text sent to the agent for a chosen item. Agent-facing English,
+// like the rest of the loop. Keeps the working rules explicit so a fresh agent
+// does not need any external context.
+export function buildImprovePrompt(item) {
+    return ('Implement BACKLOG item ' +
+        item.id +
+        ' (priority ' +
+        (item.priority || '?') +
+        '): ' +
+        item.title +
+        NL +
+        NL +
+        'Read the full item text in BACKLOG.md for the details and the rationale. ' +
+        'Then: (1) implement it with the smallest reasonable change; ' +
+        '(2) run `npm run typecheck`, `npm run lint`, `npm run format:check` and ' +
+        '`npm test` and fix any failure; (3) mark the item done in BACKLOG.md by ' +
+        'prefixing its heading with `[x]` and wrapping the original heading text ' +
+        'in `~~ ~~`; (4) add a CHANGELOG entry if the change is user-visible; ' +
+        '(5) do NOT commit or push — leave the changes staged in the working tree ' +
+        'for the operator to review. When done, call respond with a short report ' +
+        '(files changed, tests run, whether BACKLOG/CHANGELOG were updated).');
+}
 // ---------- /review ----------
 export function buildReviewPrompt(focus, hasStaged = false) {
     const scope = hasStaged ? 'staged' : 'uncommitted';

package/dist/hooks.js

@@ -0,0 +1,154 @@
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+// A hook is a helper, not a task: if it has not finished in ten seconds the
+// tool call must not be held hostage by it.
+const HOOK_TIMEOUT_MS = 10_000;
+const HOOK_MAX_BUFFER = 1024 * 1024;
+export function hooksConfigPath(workdir) {
+    return path.join(workdir, '.zames', 'hooks.json');
+}
+/**
+ * Reads `.zames/hooks.json`. A missing, unreadable or malformed file yields an
+ * empty config: a broken hooks file must not stop the agent from starting.
+ */
+export function loadHooks(workdir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(hooksConfigPath(workdir), 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!data || typeof data !== 'object')
+        return {};
+    const obj = data;
+    return {
+        PreToolUse: normalizeEntries(obj['PreToolUse']),
+        PostToolUse: normalizeEntries(obj['PostToolUse']),
+    };
+}
+function normalizeEntries(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const entry = item;
+        const command = entry['command'];
+        if (typeof command !== 'string' || command.trim() === '')
+            continue;
+        const matcher = entry['matcher'];
+        out.push({
+            command,
+            matcher: typeof matcher === 'string' ? matcher : undefined,
+        });
+    }
+    return out.length ? out : undefined;
+}
+/** True when the entry applies to the tool. A bad regex matches nothing. */
+export function matchesHook(entry, tool) {
+    if (!entry.matcher)
+        return true;
+    try {
+        return new RegExp(entry.matcher).test(tool);
+    }
+    catch {
+        return false;
+    }
+}
+function runHook(entry, event, tool, args, workdir, result) {
+    return new Promise((resolve) => {
+        const payload = {
+            event,
+            tool,
+            args: args ?? {},
+            ...(result === undefined ? {} : { result }),
+        };
+        const env = {
+            ...process.env,
+            ZAMES_HOOK_EVENT: event,
+            ZAMES_TOOL_NAME: tool,
+            ZAMES_TOOL_ARGS: JSON.stringify(args ?? {}),
+            ...(result === undefined ? {} : { ZAMES_TOOL_RESULT: result }),
+        };
+        let child;
+        try {
+            child = exec(entry.command, {
+                cwd: workdir,
+                timeout: HOOK_TIMEOUT_MS,
+                maxBuffer: HOOK_MAX_BUFFER,
+                windowsHide: true,
+                env,
+                shell: process.platform === 'win32'
+                    ? process.env.ComSpec || 'C:\\Windows\\System32\\cmd.exe'
+                    : '/bin/sh',
+            }, (err, stdout, stderr) => {
+                let code = 0;
+                if (err) {
+                    const c = err.code;
+                    code = typeof c === 'number' ? c : 1;
+                }
+                resolve({
+                    code,
+                    stdout: (stdout || '').toString(),
+                    stderr: (stderr || '').toString(),
+                });
+            });
+        }
+        catch {
+            // Spawning the shell itself failed — treat it as a hook error, not a
+            // loop error.
+            resolve({ code: 1, stdout: '', stderr: 'hook could not be started' });
+            return;
+        }
+        // The call is also fed on stdin so a hook can parse the full JSON without
+        // depending on env size limits. A hook that ignores stdin is fine.
+        if (child.stdin) {
+            child.stdin.on('error', () => { });
+            child.stdin.end(JSON.stringify(payload) + String.fromCharCode(10));
+        }
+    });
+}
+/**
+ * Runs every matching PreToolUse hook in order. Returns a denial reason when a
+ * hook exits non-zero (its stderr/stdout becomes the tool result and the tool
+ * itself does NOT run), or null to allow the call.
+ */
+export async function runPreToolUse(hooks, tool, args, workdir) {
+    for (const entry of hooks?.PreToolUse ?? []) {
+        if (!matchesHook(entry, tool))
+            continue;
+        const r = await runHook(entry, 'PreToolUse', tool, args, workdir);
+        if (r.code !== 0) {
+            const reason = (r.stderr || r.stdout).trim();
+            return reason || `hook exited with code ${r.code}`;
+        }
+    }
+    return null;
+}
+/**
+ * Runs every matching PostToolUse hook and returns their stdout, ready to be
+ * appended to the tool result. Errors are ignored: the tool already ran, and
+ * its result must be reported.
+ */
+export async function runPostToolUse(hooks, tool, args, result, workdir) {
+    const parts = [];
+    for (const entry of hooks?.PostToolUse ?? []) {
+        if (!matchesHook(entry, tool))
+            continue;
+        const r = await runHook(entry, 'PostToolUse', tool, args, workdir, result);
+        const out = r.stdout.trim();
+        if (out)
+            parts.push(out);
+    }
+    return parts.join(String.fromCharCode(10));
+}

package/dist/i18n.js

@@ -239,6 +239,26 @@ export const CATALOG = {
         ru: '/review [focus] ревью незакоммиченных изменений',
         en: '/review [focus] review uncommitted changes',
     },
+    'help.cmd.improve': {
+        ru: '/improve [id] взять следующий пункт BACKLOG и довести до тестов',
+        en: '/improve [id] take the next BACKLOG item and drive it to green tests',
+    },
+    'improve.no_backlog': {
+        ru: 'BACKLOG.md не найден в рабочей директории.',
+        en: 'BACKLOG.md was not found in the working directory.',
+    },
+    'improve.all_done': {
+        ru: 'Открытых пунктов в BACKLOG нет.',
+        en: 'There are no open BACKLOG items.',
+    },
+    'improve.not_found': {
+        ru: 'Пункт {v} не найден в BACKLOG.',
+        en: 'Item {v} was not found in BACKLOG.',
+    },
+    'improve.start': {
+        ru: 'Улучшение {id}: {title}',
+        en: 'Improving {id}: {title}',
+    },
     'help.cmd.compact': {
         ru: '/compact сжать историю и открыть новый чат с резюме',
         en: '/compact compact the history and open a new chat with the summary',

package/dist/index.js

@@ -18,7 +18,7 @@ import { translate, normalizeLocale, localeDisplayName, isLocale, } from './i18n
 import { Transcript } from './transcript.js';
 import { UndoStore } from './undo.js';
 import { selfReview, selfDiff, selfApply, selfList } from './self-review.js';
-import { formatDiff, formatDiffStat, formatContextSources, diffGitArgs, parseTranscript, summarizeTranscript, renderCost, formatExport, defaultExportPath, renderDoctor, resolveExtraDir, buildReviewPrompt, formatDuration, formatRelativeTime, trimRestoredMessages, RESTORED_HISTORY_LIMIT, mergeMessages, hasQueuedJob, isSlashCommand, parseQueueCommand, parseLiveToggle, parseGoalCommand, isLiveConfigCommand, withGoal, formatQueueList, ctrlCEscalation, } from './commands.js';
+import { formatDiff, formatDiffStat, formatContextSources, diffGitArgs, parseTranscript, summarizeTranscript, renderCost, formatExport, defaultExportPath, renderDoctor, resolveExtraDir, buildReviewPrompt, parseBacklogItems, nextBacklogItem, buildImprovePrompt, formatDuration, formatRelativeTime, trimRestoredMessages, RESTORED_HISTORY_LIMIT, mergeMessages, hasQueuedJob, isSlashCommand, parseQueueCommand, parseLiveToggle, parseGoalCommand, isLiveConfigCommand, withGoal, formatQueueList, ctrlCEscalation, } from './commands.js';
 import { performCompact } from './compact.js';
 import { Scheduler, parseInterval, formatInterval, formatJobLine, parseCron, } from './scheduler.js';
 import { renderMarkdown, setAnswerWidth } from './markdown.js';
@@ -388,6 +388,7 @@ ${theme.bold(t('help.sec.files'))}
   ${t('help.cmd.doctor')}
   ${t('help.cmd.add_dir')}
   ${t('help.cmd.review')}
+  ${t('help.cmd.improve')}
   ${t('help.cmd.debug_dom')}
   ${t('help.cmd.help')}
   ${t('help.cmd.exit')}
@@ -448,6 +449,7 @@ const SLASH_COMMANDS = [
     { name: '/doctor', key: 'help.cmd.doctor' },
     { name: '/add-dir', key: 'help.cmd.add_dir' },
     { name: '/review', key: 'help.cmd.review' },
+    { name: '/improve', key: 'help.cmd.improve' },
     { name: '/goal', key: 'help.cmd.goal' },
     { name: '/loop', key: 'help.cmd.loop' },
     { name: '/cron', key: 'help.cmd.cron' },
@@ -3336,6 +3338,58 @@ async function main() {
             }
             continue;
         }
+        if (lower === '/improve' || lower.startsWith('/improve ')) {
+            // Backlog-driven self-improvement: pick the next open BACKLOG item (or a
+            // specific id) and run the standard task loop on it. The agent reads
+            // BACKLOG.md itself for the details, so a FRESH agent needs no external
+            // context — this is the reproducible hand-off path.
+            const arg = trimmed.slice('/improve'.length).trim();
+            let backlogText;
+            try {
+                backlogText = await fs.readFile(path.join(currentWorkdir, 'BACKLOG.md'), 'utf-8');
+            }
+            catch {
+                console.error(theme.warn(t('improve.no_backlog')));
+                continue;
+            }
+            const items = parseBacklogItems(backlogText);
+            const item = nextBacklogItem(items, arg || undefined);
+            if (!item) {
+                console.log(theme.dim(arg ? t('improve.not_found', { v: arg }) : t('improve.all_done')));
+                continue;
+            }
+            console.log(theme.system(t('improve.start', { id: item.id, title: item.title })));
+            const improveTools = mod.createTools(currentWorkdir, {
+                undo,
+                todos: todoStore,
+                readOnly: planMode,
+            });
+            if (mcpPool)
+                improveTools.push(...mcpPool.tools);
+            if (editor)
+                editor.busy = true;
+            try {
+                await runTask(browser, improveTools, buildImprovePrompt(item), currentWorkdir, {
+                    transcript,
+                    freshChat: false,
+                    sendSystemPrompt: false,
+                    queue: pendingQueue,
+                    ui: editor || null,
+                    onChatReady: (chatId) => {
+                        if (chatId) {
+                            currentChatId = chatId;
+                            saveLastChat(chatId, currentWorkdir);
+                        }
+                    },
+                    getTokenUsage: () => browser.getLastTokenUsage(),
+                });
+            }
+            finally {
+                if (editor)
+                    editor.busy = false;
+            }
+            continue;
+        }
         if (lower === '/review' || lower.startsWith('/review ')) {
             const rest = trimmed.slice('/review'.length).trim();
             const staged = rest.indexOf('--staged') !== -1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.58.0",
+  "version": "2.60.0",
   "description": "Terminal coding agent that drives chat.deepseek.com through Playwright: reads and edits files, runs commands, commits to git.",
   "type": "module",
   "bin": {