@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/pack/hook-post-tool-use.js

@@ -1,137 +0,0 @@
-// `harness pack hook post-tool-use [--pack <name>]` — task-boundary marker expiry.
-//
-// PostToolUse hook for the understanding-before-execution pack. Receives
-// the Claude Code event JSON on stdin and, when the just-completed tool
-// matches the pack's `config.approval_lifecycle.expire_on_tool_match`
-// list, deletes the per-session approval marker so the next Edit /
-// Write / Bash forces a fresh Understanding Report.
-//
-// Why a PostToolUse hook and not a PreToolUse one: the marker is the
-// canonical "operator approved this interpretation" signal. Expiring it
-// AFTER the boundary-marker tool (task_finish / pull_requests_merge /
-// task_abandon) is semantically right — the agent has just declared the
-// current task done, so the next tool call belongs to a new task and
-// deserves a fresh re-interpretation. PostToolUse fires only when the
-// tool actually ran (a PreToolUse-blocked call does NOT fire PostToolUse),
-// so we never expire a marker for a tool the agent merely attempted.
-//
-// Exception, aligned with the active-claim marker (task 5018c0c4): a
-// task_finish whose result lands the task in `review` keeps the work
-// claim, so it keeps the approval too. That decision is not made here:
-// `matchPostToolUseBoundary` asks `claimEffectForAgentTasksTool` with
-// the event's `tool_response`, and an unreadable result still expires.
-//
-// Failure mode: every error path resolves to no-op + stderr log. The
-// gate is opt-in; turning a buggy hook into a session-wide "everything
-// is unapproved now" surface would be hostile. Worst case the marker
-// persists past the intended boundary; the session marker still counts
-// only while the active claim names the task it was granted for
-// (task 5018c0c4; this hook is not emitted under `mode: session`, the
-// one mode where that binding is not applied), so it degrades to a
-// per-task approval, not to the legacy per-session contract.
-import { applyPostToolUseExpiry, defaultReportsDir, describePostToolUseExpiry, describePostToolUseTrigger, matchPostToolUseBoundary, parseApprovalLifecycle, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
-import { resolveGeneratedDir } from "../../runtime/pending-approval.js";
-import { checkHookPause, loadManifestOrInjected, readStdin, } from "./hook-bootstrap.js";
-const PACK_NAME = "understanding-before-execution";
-function noop(diagnostic, stderr) {
-    stderr.write(`${diagnostic}\n`);
-    return {
-        exitCode: 0,
-        matchedExpiry: false,
-        markerCleared: false,
-        taskMarkerCleared: false,
-        persistedReportExpired: false,
-        diagnostic,
-    };
-}
-export async function runPackHookPostToolUseCli(opts = {}) {
-    const stdin = opts.stdin ?? process.stdin;
-    const stderr = opts.stderr ?? process.stderr;
-    const packName = opts.pack ?? PACK_NAME;
-    const raw = await readStdin(stdin);
-    let event = {};
-    try {
-        event = JSON.parse(raw.trim() || "{}");
-    }
-    catch {
-        return noop("harness pack hook post-tool-use: malformed event JSON, skipping marker expiry", stderr);
-    }
-    // Pause sentinel — skip marker expiry while paused so a debug A/B-test
-    // doesn't silently invalidate the operator's approval state.
-    if (checkHookPause("post-tool-use", stderr, opts, opts.generatedDir).paused) {
-        return noop("harness paused; post-tool-use skipping marker expiry without evaluating.", stderr);
-    }
-    const sessionId = (typeof event.session_id === "string" ? event.session_id : undefined) ??
-        process.env.CLAUDE_CODE_SESSION_ID ??
-        process.env.CLAUDE_SESSION_ID ??
-        "";
-    const toolName = typeof event.tool_name === "string" ? event.tool_name : "";
-    if (sessionId === "" || toolName === "") {
-        return noop(`harness pack hook post-tool-use: missing session_id (${sessionId === "" ? "absent" : "ok"}) or tool_name (${toolName === "" ? "absent" : "ok"}), skipping`, stderr);
-    }
-    let manifest;
-    let manifestPath;
-    try {
-        ({ manifest, manifestPath } = loadManifestOrInjected(opts, opts.manifest));
-    }
-    catch (err) {
-        return noop(`harness pack hook post-tool-use: manifest load failed (${err.message}), skipping`, stderr);
-    }
-    const declared = manifest.policy_packs.find((p) => p.name === packName);
-    if (!declared) {
-        return noop(`harness pack hook post-tool-use: pack "${packName}" not declared in manifest, skipping`, stderr);
-    }
-    if (!declared.enabled) {
-        return noop(`harness pack hook post-tool-use: pack "${packName}" is enabled:false, skipping`, stderr);
-    }
-    const lifecycle = parseApprovalLifecycle(declared.config["approval_lifecycle"], stderr);
-    if (lifecycle.legacyMode) {
-        return noop(`harness pack hook post-tool-use: legacy-session mode, skipping`, stderr);
-    }
-    const noBoundariesConfigured = lifecycle.expireOnToolMatch.length === 0 && lifecycle.expireOnBashMatch.length === 0;
-    if (noBoundariesConfigured) {
-        return noop(`harness pack hook post-tool-use: no expire_on_tool_match or expire_on_bash_match configured, skipping`, stderr);
-    }
-    // tool-name / bash-command boundary match (shared with the Codex
-    // sibling hook via matchPostToolUseBoundary, task a1348c89). Bash
-    // check only runs when the event is actually a Bash call; an MCP tool
-    // whose name happens to match a regex is not a Bash boundary.
-    // `tool_response` feeds the active-claim decider so a task_finish that
-    // lands in `review` (claim kept) does not expire the approval
-    // (task 5018c0c4).
-    const boundary = matchPostToolUseBoundary(toolName, event.tool_input, lifecycle, undefined, event.tool_response);
-    if (!boundary.matched) {
-        const detail = !boundary.rawToolNameMatched
-            ? toolName === "Bash"
-                ? `Bash command did not match any expire_on_bash_match regex`
-                : `tool ${toolName} not in expire_on_tool_match`
-            : `${toolName} keeps the work claim per the active-claim decider`;
-        return noop(`harness pack hook post-tool-use: ${detail}, skipping`, stderr);
-    }
-    const generatedDir = opts.generatedDir ??
-        (manifestPath !== undefined
-            ? resolveGeneratedDir({
-                ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
-                manifestPath,
-            })
-            : undefined);
-    if (generatedDir === undefined) {
-        return noop("harness pack hook post-tool-use: generatedDir unresolvable, skipping marker expiry", stderr);
-    }
-    // Clear the session marker, the task-scoped marker (when applicable),
-    // and expire the persisted report — same side effects the Codex
-    // sibling hook applies via the shared `applyPostToolUseExpiry`.
-    const reportsDir = opts.reportsDir ?? defaultReportsDir();
-    const expiry = applyPostToolUseExpiry(generatedDir, sessionId, event.tool_input, boundary.toolNameMatched, reportsDir, opts.now, describePostToolUseTrigger(toolName, boundary));
-    const diagnostic = describePostToolUseExpiry("harness pack hook post-tool-use", sessionId, toolName, boundary.bashRegex, expiry);
-    stderr.write(`${diagnostic}\n`);
-    return {
-        exitCode: 0,
-        matchedExpiry: true,
-        markerCleared: expiry.wasMarkerPresent,
-        taskMarkerCleared: expiry.taskMarkerCleared,
-        persistedReportExpired: expiry.persistedReportExpired,
-        diagnostic,
-    };
-}
-//# sourceMappingURL=hook-post-tool-use.js.map

package/dist/cli/pack/hook-post-tool-use.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hook-post-tool-use.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-post-tool-use.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/hook-pre-tool-use.d.ts

@@ -1,92 +0,0 @@
-import { type LedgerEntry } from "../../policies/index.js";
-import { type ApprovalCheckResult } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
-import { type LedgerWriteFn } from "../../runtime/ledger-writer.js";
-import { type Manifest } from "../../schema/index.js";
-import { type LoaderOptions } from "../loader.js";
-export interface PackHookPreToolUseOptions extends LoaderOptions {
-    /** Pack name to evaluate. Defaults to understanding-before-execution. */
-    pack?: string;
-    /** Override report directory (test injection). */
-    reportsDir?: string;
-    /** Override the harness.generated/ directory (test injection). */
-    generatedDir?: string;
-    /** Override timeout per ledger call. */
-    ledgerTimeoutMs?: number;
-    /** Defaults to process.stdin. */
-    stdin?: NodeJS.ReadableStream;
-    /** Defaults to process.stdout. */
-    stdout?: NodeJS.WritableStream;
-    /** Defaults to process.stderr. */
-    stderr?: NodeJS.WritableStream;
-    /** Inject an alternate manifest (test). */
-    manifest?: Manifest;
-    /** Inject a fake ledger query (test). */
-    ledgerQuery?: (sessionId: string) => Promise<LedgerEntry[] | {
-        degraded: string;
-    }>;
-    /**
-     * Inject the ledger WRITER used for the auto-approval path's audit-only
-     * `understanding-auto-approved:<sid>` fact (test). Mirrors
-     * `hook-post-merge-gate-record.ts`'s injection point. When omitted the
-     * writer is resolved from the manifest's `grounding-mcp` entry, exactly
-     * as every other Trusted-Writer producer does; when that resolution
-     * fails the auto path logs one line and continues (audit only, never a
-     * gate input).
-     */
-    writeLedger?: LedgerWriteFn;
-    /**
-     * Override "now" for the pause-sentinel expiry check (test injection).
-     * The lower layers (`checkPauseFromLoader`, `maybeAnnouncePause`,
-     * `readSentinel`) already accept a `now`; this threads it through so a
-     * test can drive pause auto-expiry off an injected clock instead of a
-     * real-time sleep.
-     */
-    now?: Date;
-    /**
-     * Clock / sleep / interval injection for the slice-3 transcript scan
-     * (test). The scan is a bounded POLL, so without this a suite covering
-     * its timeout would have to sleep for real time. Production leaves it
-     * unset and the scan uses `Date.now` and a real `setTimeout`.
-     */
-    reportScanClock?: {
-        now?: () => number;
-        sleep?: (ms: number) => Promise<void>;
-        pollMs?: number;
-    };
-}
-export interface PackHookPreToolUseResult {
-    exitCode: number;
-    blocked: boolean;
-    /**
-     * True when the hook deferred to the operator's interactive permission
-     * prompt (`permissionDecision: "ask"`) instead of hard-denying. Used for
-     * the `harness approve` / `harness gate` escape commands so the operator's
-     * go on the prompt IS the approval. Mutually exclusive with `blocked`.
-     */
-    asked?: boolean;
-    approvalCheck: ApprovalCheckResult;
-    /** Diagnostic line emitted to stderr (always; even on allow). */
-    diagnostic: string;
-}
-/**
- * The sentence appended to the standard block reason when a valid
- * delegation was present but the child's own report had not reached the
- * transcript within `auto_approve.report_scan.max_wait` (ADR "Report
- * capture under `-p`": past the bound the hook blocks with an instruction
- * that asks for REPEATED retries, because a text asking for a single
- * retry was measured to leave the outcome to run-to-run variation).
- *
- * Deliberately does NOT pin a heading level. The same block envelope
- * already carries `renderReportSchemaHint`'s "any heading level (#, ##,
- * ###)" rule, and naming one level here would give the agent two
- * different heading rules in one deny text.
- */
-export declare const DELEGATION_REPORT_RETRY_INSTRUCTION = "Emit or re-emit your Understanding Report as an `Understanding Report` section (any heading level), then retry this command; if it is denied again, retry again.";
-/**
- * `harness pack hook pre-tool-use`. A stdin read that times out (the idle
- * bound fired before stdin closed) is refused here instead of being handed to
- * the gate as an empty or truncated event it would allow: the event never
- * finished arriving, so the gate cannot judge the tool call (task 7dfdcaaf).
- * The operator pause still wins; every other input runs the gate unchanged.
- */
-export declare function runPackHookPreToolUseCli(opts?: PackHookPreToolUseOptions): Promise<PackHookPreToolUseResult>;