@kylecheng3146/agent-ops 0.2.1 → 0.2.2

package/dist/runtime/src/adapters/claude/output.js

@@ -53,6 +53,15 @@ export function claudeHookOutput(event, result) {
     if (result.action === "continue" && result.status === "PASS") {
         return { exitCode: 0, stdout: "", stderr: "" };
     }
+    // An advisory PreToolUse result carries nothing the user can act on: the
+    // command runs either way. Saying so on every unparsed command — a heredoc,
+    // a substitution — trains the reader to ignore the hook that also refuses
+    // stops. A result with a remedy still speaks.
+    if (event === "PreToolUse" &&
+        result.action === "continue" &&
+        result.remedy === undefined) {
+        return { exitCode: 0, stdout: "", stderr: "" };
+    }
     if (event === "PreToolUse" && result.action === "block") {
         return json({
             hookSpecificOutput: {

package/dist/runtime/src/hooks/completion-gate.js

@@ -3,7 +3,7 @@ import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "../task/completion.js";
-import { collectChangeSurface } from "../verify/change-surface.js";
+import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-surface.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
 const SESSION = /^[^\0\r\n]{1,256}$/u;
@@ -76,6 +76,38 @@ export class CompletionGateService {
         const surface = await collectChangeSurface(this.#options.gitRunner);
         return await calculateSourceFingerprint(this.#options.root, { mode: "worktree", changedFiles: surface.paths }, this.#options.gitRunner);
     }
+    /**
+     * The fingerprint the task's evidence should carry. Committed work leaves an
+     * empty worktree surface: there is nothing left to measure there, and the
+     * evidence names the `--base` range `task complete` was given instead. That
+     * range is recomputed here rather than trusted, so evidence for a range that
+     * no longer ends at HEAD still fails.
+     */
+    async #evidenceFingerprint(completionBase) {
+        const worktree = await this.#fingerprint();
+        if (completionBase === null) {
+            return worktree;
+        }
+        const surface = await collectChangeSurface(this.#options.gitRunner);
+        if (surface.paths.length > 0) {
+            return worktree;
+        }
+        try {
+            const changedFiles = await collectBaseChangePaths(this.#options.gitRunner, completionBase);
+            if (changedFiles.length === 0) {
+                return worktree;
+            }
+            return await calculateSourceFingerprint(this.#options.root, {
+                mode: "base",
+                baseRef: completionBase,
+                resolvedBase: completionBase,
+                changedFiles
+            }, this.#options.gitRunner);
+        }
+        catch {
+            return worktree;
+        }
+    }
     async initialize(sessionId) {
         const fingerprint = await this.#fingerprint();
         const state = await this.#store.mutate(sessionId, (current) => current ?? {
@@ -103,7 +135,7 @@ export class CompletionGateService {
             event.event === "command-batch" ? event.commands : [];
         return commands.some(({ command, args }) => [command, ...args].includes("allow-stop"));
     }
-    async #validateTask(sessionId, sourceFingerprint) {
+    async #validateTask(sessionId) {
         let stored;
         try {
             stored = await this.#options.taskService.status({ sessionId });
@@ -120,7 +152,11 @@ export class CompletionGateService {
         if (unfinished !== undefined) {
             return gateResult("block", "FAIL", "COMPLETION_GATE_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent.`);
         }
-        const problem = await checkTaskCompletionEvidence(stored, { ...this.#options, sourceFingerprint });
+        const sourceFingerprint = await this.#evidenceFingerprint(stored.completionBase);
+        const problem = await checkTaskCompletionEvidence(stored, {
+            ...this.#options,
+            sourceFingerprint
+        });
         if (problem !== null) {
             return gateResult("block", problem.status, `COMPLETION_GATE_${problem.code}`, problem.remedy);
         }
@@ -154,7 +190,7 @@ export class CompletionGateService {
             return gateResult("block", "UNKNOWN", "COMPLETION_GATE_NOT_INITIALIZED", "The session baseline is unavailable; continue once so PreInvocation can initialize it.");
         }
         if (state.baselineFingerprint !== fingerprint && state.permitFingerprint !== fingerprint) {
-            const failure = await this.#validateTask(sessionId, fingerprint);
+            const failure = await this.#validateTask(sessionId);
             if (failure !== null)
                 return failure;
         }

package/dist/runtime/src/hooks/shell.js

@@ -2,19 +2,179 @@ import { normalizeHookEvent } from "./normalize.js";
 const MAX_COMMAND_LENGTH = 16 * 1024;
 const MAX_COMMANDS = 64;
 const MAX_WORDS = 256;
-function parseShellWords(input) {
-    if (input.length === 0 || input.length > MAX_COMMAND_LENGTH) {
-        return null;
+/** Substitutions nest; a deeper stack is pathological input, not a script. */
+const MAX_SUBSTITUTION_DEPTH = 8;
+/** Stands in for a substitution's value in the word that contained it. */
+const SUBSTITUTION_PLACEHOLDER = "_";
+/**
+ * Walks from the opening parenthesis of a `$(...)` to the one that closes it,
+ * honouring quotes on the way. A quoted `)` is text, not structure: counting it
+ * as structure loses the whole command, and a lost command is one the policy
+ * never sees.
+ */
+function scanParenthesis(input, open) {
+    let depth = 0;
+    let index = open;
+    while (index < input.length) {
+        const character = input[index];
+        if (character === "\\") {
+            index += 2;
+            continue;
+        }
+        if (character === "'") {
+            const end = input.indexOf("'", index + 1);
+            if (end < 0)
+                return null;
+            index = end + 1;
+            continue;
+        }
+        if (character === "\"") {
+            const end = scanDoubleQuote(input, index + 1);
+            if (end === null)
+                return null;
+            index = end + 1;
+            continue;
+        }
+        if (character === "`") {
+            const end = scanBacktick(input, index + 1);
+            if (end === null)
+                return null;
+            index = end + 1;
+            continue;
+        }
+        if (character === "(") {
+            depth += 1;
+        }
+        else if (character === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+        index += 1;
+    }
+    return null;
+}
+/** Index of the `"` that closes the one already consumed. */
+function scanDoubleQuote(input, start) {
+    let index = start;
+    while (index < input.length) {
+        const character = input[index];
+        if (character === "\\") {
+            index += 2;
+            continue;
+        }
+        if (character === "`") {
+            const end = scanBacktick(input, index + 1);
+            if (end === null)
+                return null;
+            index = end + 1;
+            continue;
+        }
+        if (character === "$" && input[index + 1] === "(") {
+            const end = scanParenthesis(input, index + 1);
+            if (end === null)
+                return null;
+            index = end + 1;
+            continue;
+        }
+        if (character === "\"")
+            return index;
+        index += 1;
+    }
+    return null;
+}
+function scanBacktick(input, start) {
+    let index = start;
+    while (index < input.length) {
+        if (input[index] === "\\") {
+            index += 2;
+            continue;
+        }
+        if (input[index] === "`")
+            return index;
+        index += 1;
+    }
+    return null;
+}
+/**
+ * The substitutions in text the shell expands but does not tokenize as a
+ * command line — the body of an unquoted heredoc. Quotes there are literal
+ * characters; only `$(...)` and backticks run anything.
+ */
+function collectExpansions(input) {
+    const found = [];
+    let index = 0;
+    while (index < input.length) {
+        const character = input[index];
+        if (character === "\\") {
+            index += 2;
+            continue;
+        }
+        if (character === "$" && input[index + 1] === "(") {
+            const end = scanParenthesis(input, index + 1);
+            if (end === null)
+                return null;
+            found.push(input.slice(index + 2, end));
+            index = end + 1;
+            continue;
+        }
+        if (character === "`") {
+            const end = scanBacktick(input, index + 1);
+            if (end === null)
+                return null;
+            found.push(input.slice(index + 1, end));
+            index = end + 1;
+            continue;
+        }
+        index += 1;
+    }
+    return found;
+}
+/** Reads the `<<WORD`, `<<-WORD`, `<<'WORD'` that follows a `<<`. */
+function readHeredocHeader(input, start) {
+    let index = start;
+    if (input[index] === "-")
+        index += 1;
+    while (input[index] === " " || input[index] === "\t")
+        index += 1;
+    const quote = input[index];
+    if (quote === "'" || quote === "\"") {
+        const end = input.indexOf(quote, index + 1);
+        if (end < 0)
+            return null;
+        const delimiter = input.slice(index + 1, end);
+        return delimiter.length === 0
+            ? null
+            : { marker: { delimiter, expands: false }, end: end + 1 };
+    }
+    let delimiter = "";
+    while (index < input.length && /[A-Za-z0-9_.-]/u.test(input[index] ?? "")) {
+        delimiter += input[index];
+        index += 1;
     }
+    return delimiter.length === 0
+        ? null
+        : { marker: { delimiter, expands: true }, end: index };
+}
+/**
+ * One quote-aware pass over a command line. Everything that decides whether a
+ * character is structure or text — quotes, escapes, heredocs, substitutions —
+ * is decided here, once, so no later pass can disagree with this one about
+ * where a quote begins.
+ */
+function parseLine(input) {
     const commands = [];
+    const substitutions = [];
+    const pending = [];
     let words = [];
     let word = "";
-    let quote = null;
-    let escaped = false;
+    let started = false;
+    let index = 0;
     const finishWord = () => {
-        if (word.length > 0) {
+        if (started) {
             words.push(word);
             word = "";
+            started = false;
         }
     };
     const finishCommand = () => {
@@ -24,66 +184,154 @@ function parseShellWords(input) {
             words = [];
         }
     };
-    for (let index = 0; index < input.length; index += 1) {
+    const addText = (text) => {
+        word += text;
+        started = true;
+    };
+    while (index < input.length) {
         const character = input[index];
-        if (character === undefined) {
+        if (character === undefined || character === "\0") {
             return null;
         }
-        if (escaped) {
-            word += character;
-            escaped = false;
+        if (word.length > MAX_COMMAND_LENGTH) {
+            return null;
+        }
+        if (character === "\\") {
+            const next = input[index + 1];
+            if (next === undefined)
+                return null;
+            if (next !== "\n")
+                addText(next);
+            index += 2;
             continue;
         }
-        if (character === "\\" && quote !== "'") {
-            escaped = true;
+        if (character === "'") {
+            const end = input.indexOf("'", index + 1);
+            if (end < 0)
+                return null;
+            addText(input.slice(index + 1, end));
+            index = end + 1;
             continue;
         }
-        if (quote !== "'" &&
-            (character === "$" || character === "`")) {
-            return null;
+        if (character === "\"") {
+            const end = scanDoubleQuote(input, index + 1);
+            if (end === null)
+                return null;
+            const quoted = input.slice(index + 1, end);
+            const expansions = collectExpansions(quoted);
+            if (expansions === null)
+                return null;
+            substitutions.push(...expansions);
+            addText(quoted);
+            index = end + 1;
+            continue;
         }
-        if (quote !== null) {
-            if (character === quote) {
-                quote = null;
-            }
-            else {
-                word += character;
-            }
+        if (character === "$" && input[index + 1] === "(") {
+            const end = scanParenthesis(input, index + 1);
+            if (end === null)
+                return null;
+            substitutions.push(input.slice(index + 2, end));
+            addText(SUBSTITUTION_PLACEHOLDER);
+            index = end + 1;
             continue;
         }
-        if (character === "'" || character === "\"") {
-            quote = character;
+        if (character === "`") {
+            const end = scanBacktick(input, index + 1);
+            if (end === null)
+                return null;
+            substitutions.push(input.slice(index + 1, end));
+            addText(SUBSTITUTION_PLACEHOLDER);
+            index = end + 1;
             continue;
         }
-        if (/\s/.test(character)) {
-            finishWord();
-            if (character === "\n") {
-                finishCommand();
+        if (character === "<" && input[index + 1] === "<") {
+            const header = readHeredocHeader(input, index + 2);
+            if (header === null) {
+                // `<<` with no delimiter is a here-string or an unfinished line; either
+                // way there is no body to skip.
+                addText("<<");
+                index += 2;
+                continue;
             }
+            pending.push(header.marker);
+            addText(input.slice(index, header.end));
+            index = header.end;
             continue;
         }
-        if (character === ";" || character === "|" || character === "&") {
+        if (character === "\n") {
             finishCommand();
-            const next = input[index + 1];
-            if (next === character) {
-                index += 1;
+            index += 1;
+            while (pending.length > 0) {
+                const marker = pending.shift();
+                if (marker === undefined)
+                    break;
+                const body = [];
+                let closed = false;
+                while (index <= input.length) {
+                    const lineEnd = input.indexOf("\n", index);
+                    const line = lineEnd < 0 ? input.slice(index) : input.slice(index, lineEnd);
+                    index = lineEnd < 0 ? input.length : lineEnd + 1;
+                    if (line.trim() === marker.delimiter) {
+                        closed = true;
+                        break;
+                    }
+                    body.push(line);
+                    if (lineEnd < 0)
+                        break;
+                }
+                // An unterminated heredoc means the command is still being written.
+                if (!closed)
+                    return null;
+                if (marker.expands) {
+                    const expansions = collectExpansions(body.join("\n"));
+                    if (expansions === null)
+                        return null;
+                    substitutions.push(...expansions);
+                }
             }
             continue;
         }
-        if (character === "(" ||
-            character === ")" ||
-            character === "\0") {
-            return null;
+        if (/\s/u.test(character)) {
+            finishWord();
+            index += 1;
+            continue;
         }
-        word += character;
-        if (word.length > MAX_COMMAND_LENGTH) {
-            return null;
+        if (character === ";" || character === "|" || character === "&") {
+            finishCommand();
+            index += input[index + 1] === character ? 2 : 1;
+            continue;
+        }
+        // Grouping and subshells separate commands; their contents are commands.
+        if (character === "(" || character === ")") {
+            finishCommand();
+            index += 1;
+            continue;
         }
+        addText(character);
+        index += 1;
     }
-    if (escaped || quote !== null) {
+    finishCommand();
+    return pending.length > 0 ? null : { commands, substitutions };
+}
+function parseShellWords(input, depth = 0) {
+    if (input.length === 0 ||
+        input.length > MAX_COMMAND_LENGTH ||
+        depth > MAX_SUBSTITUTION_DEPTH) {
         return null;
     }
-    finishCommand();
+    const parsed = parseLine(input);
+    if (parsed === null) {
+        return null;
+    }
+    const commands = [...parsed.commands];
+    for (const substitution of parsed.substitutions) {
+        if (substitution.trim().length === 0)
+            continue;
+        const nested = parseShellWords(substitution, depth + 1);
+        if (nested === null)
+            return null;
+        commands.push(...nested);
+    }
     if (commands.length === 0 ||
         commands.length > MAX_COMMANDS ||
         commands.some((command) => command.length > MAX_WORDS)) {

package/dist/runtime/src/task/service.js

@@ -124,7 +124,8 @@ export class TaskService {
                 completedAt: null,
                 archivedAt: null,
                 failureFingerprint: null,
-                policyConfigHash: input.policyConfigHash ?? null
+                policyConfigHash: input.policyConfigHash ?? null,
+                completionBase: null
             };
             state.tasks.push(record);
             if (input.sessionId !== undefined) {
@@ -235,10 +236,14 @@ export class TaskService {
                 }
             }
         }
+        let completionBase = null;
         const fingerprint = async () => {
             try {
                 const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
                     ...(completion.base === undefined ? {} : { base: completion.base }) });
+                // Recorded so the completion gate can recompute this exact range once
+                // the work is committed and the worktree has nothing left to measure.
+                completionBase = scope.mode === "base" ? scope.resolvedBase : null;
                 return await calculateSourceFingerprint(completion.root, scope, completion.gitRunner);
             }
             catch (error) {
@@ -282,7 +287,8 @@ export class TaskService {
                 status: "complete",
                 evidence,
                 updatedAt: now,
-                completedAt: now
+                completedAt: now,
+                completionBase
             };
             replaceTask(state, completed);
             return cloneRecord(completed);

package/dist/runtime/src/task/store.js

@@ -64,12 +64,13 @@ function parseTaskRecord(value) {
         "task",
         "updatedAt"
     ];
-    const allowedKeys = new Set([
-        baseKeys.join("\0"),
-        [...baseKeys, "failureFingerprint"].sort().join("\0"),
-        [...baseKeys, "policyConfigHash"].sort().join("\0"),
-        [...baseKeys, "failureFingerprint", "policyConfigHash"].sort().join("\0")
-    ]);
+    // Every record written before an optional field existed must still parse, so
+    // the accepted shapes are every combination of them.
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash"];
+    const allowedKeys = new Set(Array.from({ length: 1 << optionalKeys.length }, (_unused, mask) => [
+        ...baseKeys,
+        ...optionalKeys.filter((_key, position) => (mask & (1 << position)) !== 0)
+    ].sort().join("\0")));
     if (!isRecord(value) || !allowedKeys.has(Object.keys(value).sort().join("\0"))) {
         return invalidState("Task state contains an invalid task record.");
     }
@@ -138,6 +139,13 @@ function parseTaskRecord(value) {
         (typeof policyConfigHash !== "string" || !/^[a-f0-9]{64}$/u.test(policyConfigHash))) {
         return invalidState("Task state contains an invalid policy config hash.");
     }
+    const completionBase = value.completionBase === undefined
+        ? null
+        : value.completionBase;
+    if (completionBase !== null &&
+        (typeof completionBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(completionBase))) {
+        return invalidState("Task state contains an invalid completion base.");
+    }
     return {
         task: task.value,
         status,
@@ -147,7 +155,8 @@ function parseTaskRecord(value) {
         completedAt: value.completedAt,
         archivedAt: value.archivedAt,
         failureFingerprint,
-        policyConfigHash
+        policyConfigHash,
+        completionBase
     };
 }
 function parseSession(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",