@lannguyensi/harness 0.56.0 → 0.58.0

package/dist/policy-packs/builtin/understanding-before-execution/stay-in-scope-config.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+/**
+ * The optional reminder integration's one shared strict input schema.
+ * Runtime consumers deliberately parse this schema again: a previously
+ * generated hook must turn into a no-op when an operator disables or breaks
+ * the current manifest after apply.
+ */
+export declare const StayInScopeConfigSchema: 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;
+}>;
+export interface StayInScopeConfig {
+    tools: readonly string[];
+    labelMarkers: readonly string[];
+    descriptionMarkers: readonly string[];
+    descriptionWindow: {
+        marker: string;
+        contains: string;
+        maxChars: number;
+    } | null;
+    parentReferencePattern: string | null;
+    parentUrlPattern: string | null;
+    messages: {
+        reminder: string;
+        secondOrder: string;
+    };
+}
+/** Returns null for absent, disabled, or invalid configuration. */
+export declare function resolveStayInScopeConfig(raw: unknown): StayInScopeConfig | null;
+export type StayInScopeMatchedRule = "label" | "hintergrund-marker" | "explicit-marker" | "none";
+export interface StayInScopeMatchEvaluation {
+    matched: boolean;
+    matchedRule: StayInScopeMatchedRule;
+    secondOrder: boolean;
+    parentReference: string | null;
+}
+export declare function evaluateStayInScopeMatch(config: StayInScopeConfig, labels: readonly string[], description: string): StayInScopeMatchEvaluation;
+export declare function extractConfiguredParentUrl(config: StayInScopeConfig, description: string, parentReference: string | null): string | null;

package/dist/policy-packs/builtin/understanding-before-execution/stay-in-scope-config.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+const NonblankString = z.string().min(1).refine((value) => value.trim().length > 0, {
+    message: "must not be blank",
+});
+// Codex expands only a bare pipe-list of simple names. Keeping the same
+// restricted grammar here means a configured name cannot change matcher
+// syntax or introduce a regular-expression fragment.
+const SimpleToolName = z.string().min(1).regex(/^[A-Za-z0-9_.:-]+$/, {
+    message: "must be a simple tool name without matcher metacharacters",
+}).refine((value) => value.trim().length > 0, { message: "must not be blank" });
+const DescriptionWindowSchema = z
+    .object({
+    marker: NonblankString,
+    contains: NonblankString,
+    max_chars: z.number().int().positive(),
+})
+    .strict();
+const ParentReferencePattern = z.string().nullable().superRefine((value, ctx) => {
+    if (value === null)
+        return;
+    try {
+        new RegExp(value, "i");
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must be valid regular-expression source" });
+    }
+});
+const ParentUrlPattern = z.string().nullable().superRefine((value, ctx) => {
+    if (value === null)
+        return;
+    try {
+        new RegExp(value);
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must be valid regular-expression source" });
+    }
+});
+/**
+ * The optional reminder integration's one shared strict input schema.
+ * Runtime consumers deliberately parse this schema again: a previously
+ * generated hook must turn into a no-op when an operator disables or breaks
+ * the current manifest after apply.
+ */
+export const StayInScopeConfigSchema = z
+    .object({
+    enabled: z.boolean(),
+    tools: z.array(SimpleToolName).min(1).optional(),
+    label_markers: z.array(NonblankString).optional(),
+    description_markers: z.array(NonblankString).optional(),
+    description_window: DescriptionWindowSchema.nullable().optional(),
+    parent_reference_pattern: ParentReferencePattern.optional(),
+    parent_url_pattern: ParentUrlPattern.optional(),
+    messages: z
+        .object({ reminder: NonblankString, second_order: NonblankString })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (!value.enabled)
+        return;
+    for (const key of [
+        "tools",
+        "label_markers",
+        "description_markers",
+        "description_window",
+        "parent_reference_pattern",
+        "parent_url_pattern",
+        "messages",
+    ]) {
+        if (value[key] === undefined) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: "is required when enabled:true" });
+        }
+    }
+    if ((value.label_markers?.length ?? 0) === 0 &&
+        (value.description_markers?.length ?? 0) === 0 &&
+        value.description_window === null) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "enabled:true requires at least one label, description, or window detector",
+        });
+    }
+});
+/** Returns null for absent, disabled, or invalid configuration. */
+export function resolveStayInScopeConfig(raw) {
+    const parsed = StayInScopeConfigSchema.safeParse(raw);
+    if (!parsed.success || !parsed.data.enabled)
+        return null;
+    const value = parsed.data;
+    // superRefine establishes these fields for enabled:true. The narrow casts
+    // keep the public resolver free of a second, diverging validation path.
+    if (value.tools === undefined ||
+        value.label_markers === undefined ||
+        value.description_markers === undefined ||
+        value.description_window === undefined ||
+        value.parent_reference_pattern === undefined ||
+        value.parent_url_pattern === undefined ||
+        value.messages === undefined) {
+        return null;
+    }
+    return {
+        tools: value.tools,
+        labelMarkers: value.label_markers,
+        descriptionMarkers: value.description_markers,
+        descriptionWindow: value.description_window === null
+            ? null
+            : {
+                marker: value.description_window.marker,
+                contains: value.description_window.contains,
+                maxChars: value.description_window.max_chars,
+            },
+        parentReferencePattern: value.parent_reference_pattern,
+        parentUrlPattern: value.parent_url_pattern,
+        messages: {
+            reminder: value.messages.reminder,
+            secondOrder: value.messages.second_order,
+        },
+    };
+}
+function firstParentReference(description, pattern) {
+    if (pattern === null)
+        return null;
+    const match = description.match(new RegExp(pattern, "i"));
+    const capture = match?.[1];
+    return typeof capture === "string" && /^[0-9]+$/.test(capture) ? capture : null;
+}
+export function evaluateStayInScopeMatch(config, labels, description) {
+    const labelMatch = labels.some((label) => config.labelMarkers.some((marker) => label.toLowerCase().includes(marker.toLowerCase())));
+    const explicitMarker = config.descriptionMarkers.some((marker) => description.includes(marker));
+    const window = config.descriptionWindow;
+    const windowMatch = !explicitMarker &&
+        window !== null &&
+        (() => {
+            const index = description.indexOf(window.marker);
+            return index !== -1 && description.slice(index, index + window.maxChars).toLowerCase().includes(window.contains.toLowerCase());
+        })();
+    const matchedRule = labelMatch
+        ? "label"
+        : explicitMarker
+            ? "explicit-marker"
+            : windowMatch
+                ? "hintergrund-marker"
+                : "none";
+    const parentReference = firstParentReference(description, config.parentReferencePattern);
+    return {
+        matched: matchedRule !== "none",
+        matchedRule,
+        secondOrder: labelMatch && parentReference !== null,
+        parentReference,
+    };
+}
+export function extractConfiguredParentUrl(config, description, parentReference) {
+    if (config.parentUrlPattern !== null) {
+        const pattern = new RegExp(config.parentUrlPattern, "g");
+        let match;
+        while ((match = pattern.exec(description)) !== null) {
+            if (match[0].length > 0)
+                return match[0];
+            if (pattern.lastIndex >= description.length)
+                break;
+            pattern.lastIndex += 1;
+        }
+    }
+    return parentReference === null ? null : `#${parentReference}`;
+}
+//# sourceMappingURL=stay-in-scope-config.js.map

package/dist/policy-packs/builtin/understanding-before-execution/stay-in-scope-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stay-in-scope-config.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/stay-in-scope-config.ts"],"names":[],"mappings":"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"}

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

@@ -202,6 +202,101 @@ export declare const configSchema: z.ZodObject<{
         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;
@@ -238,6 +333,23 @@ export declare const configSchema: z.ZodObject<{
             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;
@@ -274,6 +386,23 @@ export declare const configSchema: z.ZodObject<{
             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 {
     /**

package/dist/policy-packs/builtin/understanding-before-execution.js

@@ -27,6 +27,8 @@ import { AUTO_APPROVE_HARNESS_VALUES, REPORTS_DIR_ENV, } from "./understanding-b
 // which this file only names in comments and so does not import.
 import { parseReportScanMaxWait } from "./understanding-before-execution/index.js";
 import { SHELL_ALIASES } from "../../runtime/tool-name-aliases.js";
+import { ACTIVE_CLAIM_TOOL_NAMES, DEFAULT_BOUNDARY_TOOL_NAMES, } from "../../runtime/task-providers/agent-tasks.js";
+import { resolveStayInScopeConfig, StayInScopeConfigSchema, } from "./understanding-before-execution/stay-in-scope-config.js";
 // Env var the npm-backed `understanding-gate-claude-hook` bin reads to find
 // the harness pause sentinel (`src/runtime/pause-sentinel.ts`,
 // SENTINEL_BASENAME = ".harness-paused"). The bin runs OUTSIDE harness's
@@ -303,6 +305,7 @@ export const configSchema = z
     // policy-layer `ux:` / `producers:` keys.
     ux: PolicyUxSchema.optional(),
     producers: z.array(ProducerSchema).min(1).optional(),
+    stay_in_scope: StayInScopeConfigSchema.optional(),
 })
     .strict();
 /**
@@ -406,16 +409,7 @@ export function toPackageMode(mode) {
 // other task systems override the list in their manifest. Kept here so
 // the PostToolUse hook always emits a sensible match pattern even when
 // the operator hasn't set the config explicitly.
-const DEFAULT_EXPIRE_ON_TOOL_MATCH = [
-    "mcp__agent-tasks__task_finish",
-    "mcp__agent-tasks__task_abandon",
-    "mcp__agent-tasks__pull_requests_merge",
-    // Legacy v1 verb; the post-tool-use hook applies a status filter so only
-    // `tool_input.status === "done"` actually clears the marker (PR #200,
-    // agent-tasks 9e06175f). Listed here so settings.json fires the hook
-    // at all; the status refinement happens in TypeScript.
-    "mcp__agent-tasks__tasks_transition",
-];
+const DEFAULT_EXPIRE_ON_TOOL_MATCH = DEFAULT_BOUNDARY_TOOL_NAMES;
 const POST_TOOL_USE_COMMAND_CLAUDE = "harness pack hook post-tool-use";
 // Slice 2 of the subagent-gate work (docs/decisions/2026-08-27-ug-auto-
 // mode-approval.md "TTL, cwd, and subagents"): Claude-only for now (an
@@ -441,7 +435,7 @@ const TRACK_ACTIVE_CLAIM_COMMAND = "harness pack hook track-active-claim";
 // Agent-tasks specific; operators on other tasking systems can ignore
 // this hook (the matcher won't fire for their tools). A config-driven
 // extension can land later if a second tasking system asks for it.
-const TRACK_ACTIVE_CLAIM_MATCH = "^(?:mcp__agent-tasks__task_start|mcp__agent-tasks__task_finish|mcp__agent-tasks__task_abandon|mcp__agent-tasks__tasks_transition)$";
+const TRACK_ACTIVE_CLAIM_MATCH = `^(?:${ACTIVE_CLAIM_TOOL_NAMES.join("|")})$`;
 // Codex sibling of TRACK_ACTIVE_CLAIM_MATCH above (task cf4cdc93): a
 // bare, unescaped `|`-joined list, NOT the anchored `^(?:...)$` form —
 // same rationale as `codexPostToolUseMatchPattern`'s own doc comment
@@ -454,17 +448,11 @@ const TRACK_ACTIVE_CLAIM_MATCH = "^(?:mcp__agent-tasks__task_start|mcp__agent-ta
 // even reach the hook. This bare form lets the emitted `config.toml`
 // matcher — and therefore Codex's own dispatcher — recognize those
 // variants, exactly like `PRE_TOOL_USE_MATCH_CODEX` already does.
-const TRACK_ACTIVE_CLAIM_MATCH_CODEX = "mcp__agent-tasks__task_start|mcp__agent-tasks__task_finish|mcp__agent-tasks__task_abandon|mcp__agent-tasks__tasks_transition";
-// Hardcoded matcher for the stay-in-scope reminder (harness/2ba06030).
-// Fires on the three task-mutation verbs that can carry labels and
-// description fields. tasks_update is included so a label added
-// post-hoc (e.g. `tasks_update { labels: ["from-review"] }`) still
-// surfaces the reminder.
-const STAY_IN_SCOPE_MATCH = "^(?:mcp__agent-tasks__task_create|mcp__agent-tasks__tasks_create|mcp__agent-tasks__tasks_update)$";
-// Codex sibling of STAY_IN_SCOPE_MATCH above (task cf4cdc93), same
-// bare-unanchored-list rationale as TRACK_ACTIVE_CLAIM_MATCH_CODEX.
-const STAY_IN_SCOPE_MATCH_CODEX = "mcp__agent-tasks__task_create|mcp__agent-tasks__tasks_create|mcp__agent-tasks__tasks_update";
+const TRACK_ACTIVE_CLAIM_MATCH_CODEX = ACTIVE_CLAIM_TOOL_NAMES.join("|");
 const STAY_IN_SCOPE_COMMAND = "harness pack hook stay-in-scope";
+function escapeMatcherLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 // Bash tool name used to widen the PostToolUse matcher when
 // `expire_on_bash_match` is configured (task bea04a03). Matches the
 // single entry of `DEFAULT_BASH_TOOL_NAMES` in
@@ -758,20 +746,22 @@ function buildHooks(runtime, pack, mode, opts = {}) {
                 command: TRACK_ACTIVE_CLAIM_COMMAND,
                 blocking: false,
                 budget_ms: 2000,
-                description: "Codex adapter: track the active agent-tasks claim by writing/clearing <generatedDir>/active-claim on task_start / task_finish / task_abandon. Lets `harness approve understanding` auto-resolve the task id (harness/494fd1e5, Codex parity task cf4cdc93).",
-            },
-            // Stay-in-scope reminder (harness/2ba06030), Codex parity task
-            // cf4cdc93 (parity-gaps doc gap #3). Same always-on / soft-only
-            // semantics as the Claude sibling below.
-            {
-                name: `${HOOK_NAME_PREFIX}:codex:stay-in-scope`,
-                event: "PostToolUse",
-                match: STAY_IN_SCOPE_MATCH_CODEX,
-                command: STAY_IN_SCOPE_COMMAND,
-                blocking: false,
-                budget_ms: 2000,
-                description: "Codex adapter: emit a soft reminder + audit row when a review-derived follow-up task gets created. Surfaces user-memory feedback_reviewer_findings_stay_in_scope. Disable: STAY_IN_SCOPE_DISABLED=1 (harness/2ba06030, Codex parity task cf4cdc93).",
+                description: "Codex adapter: track the active agent-tasks claim by writing/clearing <generatedDir>/active-claim on task_start / task_finish / task_abandon / task_merge. Lets `harness approve understanding` auto-resolve the task id (harness/494fd1e5, Codex parity task cf4cdc93).",
             },
+            ...(() => {
+                const stayInScope = resolveStayInScopeConfig(pack.config["stay_in_scope"]);
+                if (stayInScope === null)
+                    return [];
+                return [{
+                        name: `${HOOK_NAME_PREFIX}:codex:stay-in-scope`,
+                        event: "PostToolUse",
+                        match: stayInScope.tools.join("|"),
+                        command: STAY_IN_SCOPE_COMMAND,
+                        blocking: false,
+                        budget_ms: 2000,
+                        description: "Codex adapter: emit the configured soft stay-in-scope reminder and audit row.",
+                    }];
+            })(),
         ];
     }
     // `min_version` floor on the npm-backed bins: 0.4.0 ships the
@@ -895,9 +885,11 @@ function buildHooks(runtime, pack, mode, opts = {}) {
             return [hook];
         })(),
         // Active-claim tracker (harness/494fd1e5). PostToolUse hook on
-        // agent-tasks task_start / task_finish / task_abandon. Maintains a
-        // small file at <generatedDir>/active-claim so `harness approve
-        // understanding` can auto-resolve the task id when --task is
+        // agent-tasks task_start / task_finish / task_abandon / task_merge
+        // (task_merge added by task c86e3c4a: previously untracked here, so
+        // a real task_merge tool call never dispatched to the hook at all).
+        // Maintains a small file at <generatedDir>/active-claim so `harness
+        // approve understanding` can auto-resolve the task id when --task is
         // absent. Always emitted alongside the pack — operators on other
         // tasking systems are unaffected (the matcher won't fire for
         // their tools), the file simply never appears.
@@ -908,27 +900,22 @@ function buildHooks(runtime, pack, mode, opts = {}) {
             command: TRACK_ACTIVE_CLAIM_COMMAND,
             blocking: false,
             budget_ms: 2000,
-            description: "Track the active agent-tasks claim by writing/clearing <generatedDir>/active-claim on task_start / task_finish / task_abandon. Lets `harness approve understanding` auto-resolve the task id (harness/494fd1e5).",
-        },
-        // Stay-in-scope reminder (harness/2ba06030). PostToolUse hook on
-        // agent-tasks task_create / tasks_create / tasks_update. Emits a
-        // one-line stderr reminder + JSONL audit row when the new task's
-        // labels or description suggest it was carved out of a review
-        // finding that may have been inline-fixable. Soft (no block);
-        // enforces user-memory feedback_reviewer_findings_stay_in_scope.
-        // Bundled with this pack for operational convenience — operators
-        // on non-agent-tasks tasking systems are unaffected (matcher
-        // won't fire). Disable via STAY_IN_SCOPE_DISABLED=1 in the hook's
-        // env; override audit log path via STAY_IN_SCOPE_LOG.
-        {
-            name: `${HOOK_NAME_PREFIX}:stay-in-scope`,
-            event: "PostToolUse",
-            match: STAY_IN_SCOPE_MATCH,
-            command: STAY_IN_SCOPE_COMMAND,
-            blocking: false,
-            budget_ms: 2000,
-            description: "Emit a soft reminder + audit row when a review-derived follow-up task gets created. Surfaces user-memory feedback_reviewer_findings_stay_in_scope. Disable: STAY_IN_SCOPE_DISABLED=1.",
+            description: "Track the active agent-tasks claim by writing/clearing <generatedDir>/active-claim on task_start / task_finish / task_abandon / task_merge. Lets `harness approve understanding` auto-resolve the task id (harness/494fd1e5).",
         },
+        ...(() => {
+            const stayInScope = resolveStayInScopeConfig(pack.config["stay_in_scope"]);
+            if (stayInScope === null)
+                return [];
+            return [{
+                    name: `${HOOK_NAME_PREFIX}:stay-in-scope`,
+                    event: "PostToolUse",
+                    match: `^(?:${stayInScope.tools.map(escapeMatcherLiteral).join("|")})$`,
+                    command: STAY_IN_SCOPE_COMMAND,
+                    blocking: false,
+                    budget_ms: 2000,
+                    description: "Emit the configured soft stay-in-scope reminder and audit row.",
+                }];
+        })(),
     ];
 }
 function modeFriction(mode) {