@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/policy-packs/builtin/understanding-before-execution.d.ts

@@ -1,526 +0,0 @@
-import { z } from "zod";
-import type { PolicyPack, PolicyUx, Producer } from "../../schema/index.js";
-import { type Runtime } from "../runtime.js";
-import type { PackContribution } from "../types.js";
-export declare const PAUSE_FILE_ENV = "UNDERSTANDING_GATE_PAUSE_FILE";
-export declare const PACK_NAME = "understanding-before-execution";
-export declare const VERSION_COMMAND: readonly [string, string];
-export type Mode = "fast_confirm" | "grill_me" | "strict";
-export declare const DEFAULT_MODE: Mode;
-/**
- * Env var carrying an operator-set mode override. Also the exact name
- * `@lannguyensi/understanding-gate` reads on its own (package
- * `src/mode.ts`: "ENV wins because operators set it consciously").
- *
- * Two DIFFERENT resolution contracts read this name, deliberately (task
- * 5d73d78d, review HIGH-3 fix-round):
- *
- *   - The GENERATION path — {@link resolve}/`buildHooks`, and
- *     `resolveBuiltinDefaultConfig` in `../registry.ts` (consumed by
- *     `harness doctor`'s UX-drift comparison and `harness pack reseed`) —
- *     resolves mode via {@link resolveModeFromConfig}, which reads ONLY
- *     `pack.config.mode`. It never consults this env var. Generation runs
- *     at `harness apply` / `harness doctor` / `harness pack reseed` time,
- *     writing artefacts (settings.json hook commands, instructions.md,
- *     reseeded config) that persist until the NEXT apply; if that write
- *     depended on whatever happened to be exported in the operator's
- *     shell at that moment, the artefact would silently drift from
- *     `config.mode` the instant the shell's env changed — exactly the
- *     class of bug this task closes for the OTHER resolver (see below),
- *     re-opened one layer up. `buildHooks` DOES still bake this env var
- *     into the two npm-backed Claude bin commands it emits (`wrapMode`)
- *     — but the value baked in is the GENERATION-time config-resolved
- *     mode, frozen at apply time, not a live env read.
- *   - LIVE runtime consumers — {@link resolveMode} (used by
- *     `approve/understanding.ts`'s stdin-report gap-fill, and by the
- *     Codex `UserPromptSubmit` injector,
- *     `src/cli/pack/hook-codex-user-prompt-submit.ts`) — resolve mode at
- *     INVOCATION time, with the live process environment actually
- *     available, so Env > `config.mode` > {@link DEFAULT_MODE} is the
- *     correct priority there: this is what makes a one-off
- *     `UNDERSTANDING_GATE_MODE=fast_confirm harness approve understanding`
- *     override work without editing harness.yaml, mirroring the npm
- *     package's own env-wins rule for the exact same reason.
- *
- * Before task 5d73d78d, NEITHER resolver read `config.mode` for
- * enforcement at all — the package-owned Claude bins were invoked bare
- * (no env var), and `persistStdinReport`'s gap-fill default was a
- * hardcoded `"fast_confirm"` literal — so a host with `config.mode:
- * grill_me` was silently enforced as `fast_confirm` regardless. See
- * `docs/policy-packs/understanding-before-execution.md`'s "Mode
- * resolution and enforcement" section for the full narrative.
- */
-export declare const MODE_ENV = "UNDERSTANDING_GATE_MODE";
-/**
- * The agent-facing `required:` phrase for the understanding-gate deny
- * envelope, derived from the configured mode. Only `strict` forces
- * `requiresHumanApproval` (see {@link modeFriction}); in `fast_confirm`
- * and `grill_me` the agent self-attests and a structural validator
- * checks the report, so naming it "human-approved" there would overstate
- * what the gate actually enforces. Generation surfaces (the Custom
- * composer, the init templates) call this so the wording can never drift
- * from the mode it is paired with.
- */
-export declare function understandingApprovalRequirement(mode: Mode): string;
-/**
- * Shipped default `config.producers` for this pack (agent-tasks/25bced52).
- * Canonical source for the "golden path" recovery command: both `harness
- * init` generation surfaces (Solo/Team/Full templates, the Custom
- * composer) and `harness pack reseed` (task 68b9ad9c) read from here, so
- * a future wording change to the producer descriptions only has to land
- * in one place to reach every manifest-generating surface plus the
- * reseed path used to backfill already-installed manifests.
- */
-export declare function defaultProducers(): Producer[];
-/**
- * Shipped default `config.ux` for this pack, parameterised on the
- * resolved mode (only the `required` line varies across modes — see
- * `understandingApprovalRequirement` above). Canonical source consumed
- * by the same generation surfaces as `defaultProducers()`, plus
- * `harness doctor`'s divergence warning and `harness pack reseed` (task
- * 68b9ad9c): the dogfood motivating that task found that a deny-message
- * wording fix (e.g. the heredoc submission form, agent-tasks/e48e3b45)
- * only reached NEW `harness init` manifests, because nothing propagated
- * the improved text into an already-installed operator manifest whose
- * `config.ux` still taught the old wording. Reading from one function
- * here means a future wording fix is available to `pack reseed`
- * automatically, with no separate update needed.
- */
-export declare function defaultUx(mode: Mode): PolicyUx;
-export declare function isMode(value: unknown): value is Mode;
-/**
- * Zod schema for this pack's `config:` block. Surfaced via
- * `resolveBuiltinConfigSchema()` and consumed by `harness validate` /
- * `harness doctor` so typo'd keys (e.g. `permision_profile`) or values
- * (e.g. `mode: fastConfirm`) fail loud at lint time instead of falling
- * through to the runtime fallback. Each shape mirrors what the pack's
- * own resolvers (`resolveMode`, `resolveExpireOnToolMatch`,
- * `resolvePermissionProfile`) accept — the schema is a typo guard, not
- * a replacement parser; the resolvers still own defaults + warnings for
- * borderline cases the schema lets through.
- *
- * `.strict()` is intentional: this pack already documents every
- * supported key, and an unknown key in the operator's manifest is far
- * more likely to be a typo than forward-compat. New keys added in a
- * future harness version land in this schema first, then in the pack.
- */
-export declare const configSchema: z.ZodObject<{
-    mode: z.ZodOptional<z.ZodEnum<[Mode, ...Mode[]]>>;
-    permission_profile: z.ZodOptional<z.ZodEnum<[string, ...string[]]>>;
-    approval_lifecycle: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodLiteral<"session">>;
-        expire_on_tool_match: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        expire_on_bash_match: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        max_age: z.ZodOptional<z.ZodString>;
-    }, "strict", z.ZodTypeAny, {
-        mode?: "session" | undefined;
-        max_age?: string | undefined;
-        expire_on_tool_match?: string[] | undefined;
-        expire_on_bash_match?: string[] | undefined;
-    }, {
-        mode?: "session" | undefined;
-        max_age?: string | undefined;
-        expire_on_tool_match?: string[] | undefined;
-        expire_on_bash_match?: string[] | undefined;
-    }>>;
-    auto_approve: z.ZodOptional<z.ZodObject<{
-        when: z.ZodArray<z.ZodString, "many">;
-        harnesses: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["claude-code", "codex"]>, "many">, ("claude-code" | "codex")[], ("claude-code" | "codex")[]>>;
-        report_scan: z.ZodOptional<z.ZodObject<{
-            max_wait: z.ZodEffects<z.ZodString, string, string>;
-        }, "strict", z.ZodTypeAny, {
-            max_wait: string;
-        }, {
-            max_wait: string;
-        }>>;
-        require_report: z.ZodLiteral<true>;
-    }, "strict", z.ZodTypeAny, {
-        when: string[];
-        require_report: true;
-        harnesses?: ("claude-code" | "codex")[] | undefined;
-        report_scan?: {
-            max_wait: string;
-        } | undefined;
-    }, {
-        when: string[];
-        require_report: true;
-        harnesses?: ("claude-code" | "codex")[] | undefined;
-        report_scan?: {
-            max_wait: string;
-        } | undefined;
-    }>>;
-    ux: z.ZodOptional<z.ZodObject<{
-        cannot: z.ZodString;
-        required: z.ZodArray<z.ZodString, "many">;
-        run: z.ZodArray<z.ZodString, "many">;
-    }, "strict", z.ZodTypeAny, {
-        cannot: string;
-        required: string[];
-        run: string[];
-    }, {
-        cannot: string;
-        required: string[];
-        run: string[];
-    }>>;
-    producers: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
-        kind: z.ZodLiteral<"bash">;
-        command: z.ZodString;
-        description: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        command: string;
-        description: string;
-        kind: "bash";
-    }, {
-        command: string;
-        description: string;
-        kind: "bash";
-    }>, z.ZodObject<{
-        kind: z.ZodLiteral<"mcp">;
-        verb: z.ZodString;
-        example: z.ZodString;
-        description: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        description: string;
-        kind: "mcp";
-        verb: string;
-        example: string;
-    }, {
-        description: string;
-        kind: "mcp";
-        verb: string;
-        example: string;
-    }>, z.ZodObject<{
-        kind: z.ZodLiteral<"ask">;
-        command: z.ZodString;
-        description: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        command: string;
-        description: string;
-        kind: "ask";
-    }, {
-        command: string;
-        description: string;
-        kind: "ask";
-    }>]>, "many">>;
-    stay_in_scope: z.ZodOptional<z.ZodEffects<z.ZodObject<{
-        enabled: z.ZodBoolean;
-        tools: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-        label_markers: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-        description_markers: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-        description_window: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-            marker: z.ZodEffects<z.ZodString, string, string>;
-            contains: z.ZodEffects<z.ZodString, string, string>;
-            max_chars: z.ZodNumber;
-        }, "strict", z.ZodTypeAny, {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        }, {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        }>>>;
-        parent_reference_pattern: z.ZodOptional<z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, string | null>>;
-        parent_url_pattern: z.ZodOptional<z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, string | null>>;
-        messages: z.ZodOptional<z.ZodObject<{
-            reminder: z.ZodEffects<z.ZodString, string, string>;
-            second_order: z.ZodEffects<z.ZodString, string, string>;
-        }, "strict", z.ZodTypeAny, {
-            reminder: string;
-            second_order: string;
-        }, {
-            reminder: string;
-            second_order: string;
-        }>>;
-    }, "strict", z.ZodTypeAny, {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    }, {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    }>, {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    }, {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    }>>;
-}, "strict", z.ZodTypeAny, {
-    producers?: ({
-        command: string;
-        description: string;
-        kind: "bash";
-    } | {
-        description: string;
-        kind: "mcp";
-        verb: string;
-        example: string;
-    } | {
-        command: string;
-        description: string;
-        kind: "ask";
-    })[] | undefined;
-    ux?: {
-        cannot: string;
-        required: string[];
-        run: string[];
-    } | undefined;
-    mode?: Mode | undefined;
-    approval_lifecycle?: {
-        mode?: "session" | undefined;
-        max_age?: string | undefined;
-        expire_on_tool_match?: string[] | undefined;
-        expire_on_bash_match?: string[] | undefined;
-    } | undefined;
-    permission_profile?: string | undefined;
-    auto_approve?: {
-        when: string[];
-        require_report: true;
-        harnesses?: ("claude-code" | "codex")[] | undefined;
-        report_scan?: {
-            max_wait: string;
-        } | undefined;
-    } | undefined;
-    stay_in_scope?: {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    } | undefined;
-}, {
-    producers?: ({
-        command: string;
-        description: string;
-        kind: "bash";
-    } | {
-        description: string;
-        kind: "mcp";
-        verb: string;
-        example: string;
-    } | {
-        command: string;
-        description: string;
-        kind: "ask";
-    })[] | undefined;
-    ux?: {
-        cannot: string;
-        required: string[];
-        run: string[];
-    } | undefined;
-    mode?: Mode | undefined;
-    approval_lifecycle?: {
-        mode?: "session" | undefined;
-        max_age?: string | undefined;
-        expire_on_tool_match?: string[] | undefined;
-        expire_on_bash_match?: string[] | undefined;
-    } | undefined;
-    permission_profile?: string | undefined;
-    auto_approve?: {
-        when: string[];
-        require_report: true;
-        harnesses?: ("claude-code" | "codex")[] | undefined;
-        report_scan?: {
-            max_wait: string;
-        } | undefined;
-    } | undefined;
-    stay_in_scope?: {
-        enabled: boolean;
-        tools?: string[] | undefined;
-        label_markers?: string[] | undefined;
-        description_markers?: string[] | undefined;
-        description_window?: {
-            marker: string;
-            contains: string;
-            max_chars: number;
-        } | null | undefined;
-        parent_reference_pattern?: string | null | undefined;
-        parent_url_pattern?: string | null | undefined;
-        messages?: {
-            reminder: string;
-            second_order: string;
-        } | undefined;
-    } | undefined;
-}>;
-export interface ResolvePackOptions {
-    /**
-     * Absolute path to the persisted-report directory the pack's hooks
-     * should write/read. When provided, the pack prefixes each hook
-     * command that touches the persisted report (writes, reads or expires
-     * it) with `UNDERSTANDING_GATE_REPORT_DIR=<path>` so the
-     * Stop hook (writes the report), the PreToolUse blocker (reads it),
-     * and `harness approve understanding` (flips it) all resolve the same
-     * directory regardless of each process's cwd. Apply sets this to a
-     * manifest-anchored absolute path; in test/legacy paths it may be
-     * omitted, in which case the commands are emitted unchanged and the
-     * runtime `defaultReportsDir()` falls back to the env-var-or-cwd
-     * precedence.
-     */
-    reportsDir?: string;
-    /**
-     * Path to the solution-verdict directory the solution-acceptance
-     * completion-gate hook should read; should be absolute (a relative value is
-     * flagged by `harness validate` because it resolves against each process's
-     * cwd and cannot be reconciled). When provided, the pack prefixes each
-     * contributed hook command with `SOLUTION_VERDICT_DIR=<path>` so the
-     * hook (consumer) and the grounding-mcp server (producer) resolve the same
-     * directory regardless of each process's cwd. Apply sets this to the value
-     * declared in `tools.mcp[grounding-mcp].env.SOLUTION_VERDICT_DIR` when
-     * present; when absent the env var is not injected and the runtime
-     * `verdictDir()` falls back to the env-var-or-XDG precedence.
-     */
-    solutionVerdictDir?: string;
-    /**
-     * Absolute path to the harness pause sentinel file (`sentinelPath(generatedDir)`
-     * from `src/runtime/pause-sentinel.ts`). When provided, the pack prefixes
-     * ONLY the Claude UserPromptSubmit hook command with
-     * `UNDERSTANDING_GATE_PAUSE_FILE=<path>` so the npm-backed
-     * `understanding-gate-claude-hook` bin — which runs outside harness's own
-     * runtime and cannot resolve `generatedDir` itself — can read the same
-     * sentinel harness's own hooks already consult. Apply sets this to
-     * `sentinelPath(generatedDir)`; in test/legacy paths it may be omitted,
-     * in which case the command is emitted unchanged (agent-tasks 63fefe3a).
-     */
-    pauseFile?: string;
-}
-/**
- * POSIX single-quote-escape for an arbitrary path. Safe inside the
- * `VAR=<value>` prefix of a `sh -c` command line. Always quotes — paths
- * derived from `path.dirname()` may contain spaces or other shell
- * metacharacters, and a plain `VAR=$path` would split on whitespace.
- */
-export declare function shellQuoteSingle(s: string): string;
-/**
- * Minimal shape the mode resolvers below need: they only ever read
- * `pack.config` (and `pack.name`, for the warning text) — never
- * `source`/`enabled`/`description`/`min_version`. Narrowed from the full
- * {@link PolicyPack} (task 5d73d78d review LOW-10) so a caller that has
- * to SYNTHESISE a fallback pack object (an undeclared or disabled pack —
- * see `approve/understanding.ts`'s `declaredPack`) is not forced to also
- * invent values for fields the resolvers never look at.
- */
-export type ModeConfigSource = Pick<PolicyPack, "name" | "config">;
-/**
- * Resolve the pack's effective mode from `pack.config.mode` alone —
- * `pack.config.mode` (harness.yaml) > {@link DEFAULT_MODE}. Never reads
- * {@link MODE_ENV}. This is the GENERATION-path resolver: see
- * {@link MODE_ENV}'s doc comment for why the artefacts this function's
- * callers write (hook commands, instructions.md, reseeded config) must
- * not depend on the live process environment. Used by {@link resolve} /
- * `buildHooks` below, and by `resolveBuiltinDefaultConfig` in
- * `../registry.ts`.
- */
-export declare function resolveModeFromConfig(pack: ModeConfigSource): {
-    mode: Mode;
-    warning: string | null;
-};
-/**
- * Resolve the pack's effective mode for a LIVE runtime consumer. Priority:
- * {@link MODE_ENV} (env) > `pack.config.mode` (harness.yaml) >
- * {@link DEFAULT_MODE} — see {@link MODE_ENV}'s doc comment for which
- * callers this is (and is not) correct for. An invalid value at either
- * the env or the config layer is skipped (with a warning) rather than
- * short-circuiting straight to the default, so a typo'd env var does not
- * also stomp on an otherwise-valid YAML setting. The config layer is
- * VALIDATED (and its warning surfaced) even when a valid env value
- * already resolved `mode` (task 5d73d78d review LOW-8): otherwise a
- * config.mode typo would go unreported for as long as an operator happens
- * to have a valid env override exported, resurfacing silently the moment
- * they unset it. Env wins over YAML deliberately: it is the same
- * precedence `@lannguyensi/understanding-gate` gives its own
- * env-vs-marker resolution, and it is how an operator (or CI) does a
- * one-off override without editing harness.yaml.
- *
- * The env value is trimmed and lower-cased before matching (task 5d73d78d
- * review LOW-9), aligned with the npm package's own normalisation of the
- * same env var (`pickMode`, package `src/mode.ts`:
- * `env.UNDERSTANDING_GATE_MODE?.trim().toLowerCase()`) — so
- * `UNDERSTANDING_GATE_MODE=' Grill_Me '` resolves the same way on both
- * sides of the interop boundary instead of harness rejecting a value the
- * package would have accepted.
- */
-export declare function resolveMode(pack: ModeConfigSource): {
-    mode: Mode;
-    warning: string | null;
-};
-/**
- * Map harness's {@link Mode} (which includes `strict`) onto the two-value
- * mode `@lannguyensi/understanding-gate` itself understands
- * (`fast_confirm` | `grill_me`; package `src/schema/types.ts`). The
- * package has no `strict` variant of its own; `grill_me` is the closest
- * available approximation (full Report, Prior Art enforced) — passing
- * `strict` through unmapped would mean the package silently ignores the
- * env override (it only recognises its own two literals) and falls back
- * to its own default, `fast_confirm`, i.e. the exact drift this task
- * closes for `grill_me`, just unfixed for `strict`. This does not change
- * what `strict` means inside harness (modeFriction/
- * understandingApprovalRequirement are untouched); it only picks what to
- * tell the external package, which cannot represent `strict` at all.
- */
-export declare function toPackageMode(mode: Mode): "fast_confirm" | "grill_me";
-export declare function resolve(pack: PolicyPack, runtime?: Runtime, opts?: ResolvePackOptions): {
-    contribution: PackContribution;
-    warnings: string[];
-};