A scope correction needs evidence the agent actually did unrequested work

[EdbertChan]

Summary

The scope lock protects work after a user says the agent went off task.

Previously, correction wording alone could trigger that lock, including ordinary status questions.

The detector now checks the prior agent turn for a mutating tool call before recording a correction.

Read-only, missing, unreadable, or unparseable transcript evidence does not count as mutating work.

Review Claim

Approve requiring evidence of unrequested mutating work before correction wording can trigger the scope lock.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

When correction wording follows real mutating work, the same correction is recorded at the same stage with the same message. Expansion wording remains excluded, and enforcement and release behavior are unchanged.

Slice Rationale

This is one behavior slice: the correction decision now requires transcript evidence already available to the hook. Tests and documentation describe that same decision.

Non-goals

• No change to enforcement, blocked-tool stages, contract wording, or hard-stop release conditions.
• No change to correction phrases or addition of a new hook.
• No comparison against a stated scope; this slice only establishes whether mutating work occurred.

Architecture

Before

graph TD
    A["Current user wording"] --> B["Correction phrase matcher"]
    B --> C["Record scope correction"]

Loading

After

graph TD
    A["Current user wording"] --> B["Correction phrase matcher"]
    D["Prior user turn transcript"] --> E["Mutating-work evidence"]
    B --> F["Correction decision"]
    E --> F
    F --> C["Record scope correction"]

Loading

Test Plan

Test Plan

• python3 engine/hooks/scope-lock/tests/test_hooks.py — Ran 58 tests in 0.072s; OK.
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main — ok preflight passed; hook coverage OK (1 hook(s) checked).
• bash scripts/scrub-handoff-artifacts.sh — scrub-handoff-artifacts-ok.
• python3 scripts/check_no_new_comments.py --base main — ok no new comments.

Revert Plan

Revert Plan

• Safe to revert? Yes.
• Revert command: git revert <merge-commit-sha>.
• Post-revert steps: Run python3 engine/hooks/scope-lock/tests/test_hooks.py.
• Data migration? No.

---

Note

Medium Risk
Changes when the scope-lock state machine arms, which directly affects tool blocking in live harness sessions; behavior is intentionally more conservative when transcript evidence is missing.

Overview
Scope corrections no longer lock the session from wording alone. correction_class now needs mutating_work is True, supplied by scanning the session transcript for a non–read-only tool call in the agent turn after the previous user message.

mutating_work_after_previous_user parses the JSONL transcript (including nested response_item shapes), aggregates tool names per user turn, and treats read-only tools like Read/Grep as non-corroborating. Missing, unreadable, or bad transcript data returns None (unknown), which does not record a correction—so the hook fails open when evidence cannot be verified. Pure read-only prior turns return False, so status-style questions after inspection no longer trip the lock.

Contract gates, hard-stop rules, and pretool allowlists are unchanged aside from sharing _is_local_read_only_tool for normalization. Docs and tests cover the new corroboration rule and the tradeoff that drift stated only in a plan, before any mutating call, is no longer caught.

^{Reviewed by Cursor Bugbot for commit 3a579a1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_63794f85-cbf0-41e3-abcb-23ab4cfad486)