Skip to content

Enforce Closes #N injection via two-hook guard (PostToolUse state bridge + PreToolUse deny) #2248

Closed

Description

@Trecek

Problem

When the LLM orchestrator processes the compose_pr recipe step, issue_number is passed as a with: key alongside skill_command — but run_skill's Python function does not accept issue_number as a parameter. A note: field instructs the LLM to "append it as the 5th positional argument for Closes #N injection." When the LLM fails to follow this instruction, compose-pr receives only 4 positional arguments, silently omits Closes #N, and the PR body has no issue reference.

Meanwhile, release_issue_success still applies the staged label after PR merge (based solely on target_branch != promotion_target at tools_issue_lifecycle.py:546), creating an invariant violation: the system asserts "implementation has landed" without ensuring the issue will auto-close on promotion.

This caused 6 staged issues (#2201, #2198, #2189, #2185, #2179, #2166) to remain open after promotion PR #2213 merged — all 6 implementation PRs had zero Closes #N references in their bodies. The carry-forward chain (compose-pr → open-integration-pr → promote-to-main) works correctly but is garbage-in/garbage-out.

Solution: Two-Hook Guard Architecture

Implement a two-hook solution within the existing session — no orchestrator changes, no extra sessions required.

Hook 1: PostToolUse on claim_and_resolve_issue — State Bridge

  • Matcher: mcp__.*autoskillit.*__claim_and_resolve_issue.*
  • Event: PostToolUse
  • Behavior: When claim_and_resolve_issue succeeds (parse tool_response for success: true), extract issue_number from the response JSON and persist it to .autoskillit/temp/.issue_context.json (e.g., {"issue_number": 2201}). When the tool fails or the issue_url was absent (step skipped → no hook fires), no state file is written.
  • Pattern precedent: review_gate_post_hook.py already does exactly this — PostToolUse writes review_gate_state.json for downstream PreToolUse consumption.
  • Cleanup: The state file should be removed by close_kitchen (alongside hook_config.json cleanup) or at session end.

Hook 2: PreToolUse on run_skill — Compose-PR Issue Guard

  • Matcher: mcp__.*autoskillit.*__run_skill.* (add to existing HookDef or create new entry)
  • Event: PreToolUse
  • Script: guards/compose_pr_issue_guard.py
  • Behavior:
    1. Parse tool_input.skill_command from stdin JSON
    2. Check if skill_command targets compose-pr or prepare-pr
    3. If neither, exit 0 (pass-through)
    4. Read .autoskillit/temp/.issue_context.json — if absent, exit 0 (no issue expected, pass-through)
    5. Extract issue_number from state file
    6. For compose-pr: check if issue number appears as 5th positional argument. For prepare-pr: check 4th positional argument.
    7. If missing: deny with permissionDecision: "deny" and a reason like: "compose-pr requires issue number #{N} as the 5th positional argument. Re-invoke run_skill with the issue number appended to skill_command."
    8. If present: exit 0 (approve)
  • Session scope: headless_only — only fire in headless recipe sessions, not interactive invocations
  • Fail mode: fail-open on malformed JSON (matches all existing guard conventions)

Hook Registry Changes

In hook_registry.py:

  1. New PostToolUse HookDef for claim_and_resolve_issue:

    • matcher: mcp__.*autoskillit.*__claim_and_resolve_issue.*
    • event_type: PostToolUse
    • scripts: ["issue_context_post_hook.py"]
    • session_scope: headless_only
  2. Add guards/compose_pr_issue_guard.py to the existing run_skill PreToolUse HookDef scripts list (the one with matcher mcp__.*autoskillit.*__run_skill.* that already runs skill_cmd_guard.py, quota_guard.py, skill_command_guard.py)

Key Design Constraints

  • Both hooks MUST be stdlib-only (no autoskillit imports) — matches all existing hook conventions
  • The state file is written by Python code (PostToolUse hook reading the mechanical tool response), NOT by the LLM — this is the critical architectural difference from the current note:-based approach
  • The deny reason must be specific and actionable (include the exact issue number and expected skill_command format) so the LLM can retry correctly
  • The guard should NOT fire for interactive sessions or ad-hoc compose-pr invocations

Files to Create/Modify

  • Create: src/autoskillit/hooks/issue_context_post_hook.py — PostToolUse state bridge
  • Create: src/autoskillit/hooks/guards/compose_pr_issue_guard.py — PreToolUse deny guard
  • Modify: src/autoskillit/hook_registry.py — add new HookDef entries + update existing run_skill scripts list
  • Modify: src/autoskillit/server/tools/tools_kitchen.py — cleanup .issue_context.json in close_kitchen
  • Tests: Add tests for both hooks (stdin JSON → stdout decision), state file lifecycle, and the deny → retry scenario

Requirements

HOOK — Hook Infrastructure

REQ-HOOK-001: The system must persist the issue_number from a successful claim_and_resolve_issue tool response to a state file at .autoskillit/temp/.issue_context.json via a PostToolUse hook.

REQ-HOOK-002: The PostToolUse hook must only write the state file when the claim_and_resolve_issue response contains success: true and a non-empty issue_number.

REQ-HOOK-003: The state file must be removed during close_kitchen cleanup alongside the existing hook_config.json removal.

REQ-HOOK-004: A PreToolUse guard on run_skill must deny calls where skill_command targets compose-pr and the expected issue number (read from .issue_context.json) is absent from the 5th positional argument.

REQ-HOOK-005: The same PreToolUse guard must deny calls where skill_command targets prepare-pr and the expected issue number is absent from the 4th positional argument.

REQ-HOOK-006: The PreToolUse guard must pass through (exit 0) when .issue_context.json does not exist, indicating no issue is expected for this session.

REQ-HOOK-007: The PreToolUse guard must pass through (exit 0) when skill_command does not target compose-pr or prepare-pr.

REQ-HOOK-008: The deny reason must include the exact expected issue number and the corrected skill_command format so the LLM can retry with corrected parameters.

SCOPE — Session Scope and Fail Mode

REQ-SCOPE-001: Both hooks must have session_scope: headless_only to avoid interfering with interactive sessions or ad-hoc skill invocations.

REQ-SCOPE-002: Both hooks must be stdlib-only (no autoskillit.* imports) to match the existing hook subprocess contract.

REQ-SCOPE-003: Both hooks must fail-open on malformed JSON input (JSON decode failure = sys.exit(0) = approve), matching the established guard fail-mode convention.

REG — Hook Registry Integration

REQ-REG-001: A new PostToolUse HookDef entry must be added to HOOK_REGISTRY with matcher mcp__.*autoskillit.*__claim_and_resolve_issue.* and event type PostToolUse.

REQ-REG-002: The PreToolUse guard script must be added to the existing run_skill PreToolUse HookDef scripts list (matcher mcp__.*autoskillit.*__run_skill.*).

REQ-REG-003: New hook scripts must be registered in HOOK_REGISTRY and must not reuse any basename from RETIRED_SCRIPT_BASENAMES.

TEST — Testing

REQ-TEST-001: Tests must verify the PostToolUse hook writes .issue_context.json with correct content when claim_and_resolve_issue succeeds.

REQ-TEST-002: Tests must verify the PostToolUse hook does not write a state file when claim_and_resolve_issue fails.

REQ-TEST-003: Tests must verify the PreToolUse guard denies compose-pr calls missing the issue number when .issue_context.json exists.

REQ-TEST-004: Tests must verify the PreToolUse guard approves compose-pr calls that include the correct issue number.

REQ-TEST-005: Tests must verify the PreToolUse guard passes through when .issue_context.json is absent.

REQ-TEST-006: Tests must verify the PreToolUse guard passes through for non-compose-pr/prepare-pr skill commands.

Activity

  1. Trecek commented on May 31, 2026

    @Trecek
    CollaboratorAuthor

    Superseded by #3421 — updated design with broader architectural context, PreToolUse-on-Bash interception (prevents bad PR creation), and implementation flexibility for the hook pattern.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions