zames_pro 2.59.0 → 2.60.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
@@ -208,7 +220,8 @@ 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.59.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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.59.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": {