Repository navigation
Codex/hook governance v1 - #89
Merged
Merged
Conversation
Introduce HookDecision, HookEnvelope, and HookResult as the minimal governance contract for hook dispatch decisions.\n\nUpdate hook exports and extension point typing so follow-up governance orchestration can consume structured outcomes without breaking existing phase definitions.
Add a per-phase schema registry that defines required payload fields for every HookPhase value.\n\nThis creates a deterministic contract surface for governance validation and future migration checks while preserving existing hook phase semantics.
Add selector helpers for stable ordering, filtering, and deduplication of hook specs using governance precedence rules.\n\nWire HookExtensionPoint callback dispatch through deterministic spec ordering so runtime hook execution is reproducible across registrations.
Introduce a policy runner that wraps hook invocation with timeout control, retry behavior for idempotent hooks, and normalized execution outcomes.\n\nMap runtime failures to stable HOOK_* error codes so governance orchestration can handle hook execution faults deterministically.
Implement governance decision arbitration with explicit precedence (block > ask > allow).\n\nAdd patch merge validation that rejects non-allowlisted fields and conflicting mutations using HOOK_CONTRACT_ERROR semantics for deterministic policy enforcement.
Refactor HookExtensionPoint emit flow to run callbacks/hooks through policy execution, aggregate decisions, arbitrate outcomes, and validate merged patches.\n\nUpdate kernel typing so extension point emission returns a structured HookResult, enabling governed before-phase control and deterministic error downgrade handling.
Bridge governed hook dispatch into execute, tool, and verify runtime paths so before_* decisions can actively control behavior.\n\nAdd support for before_model model_input patching, before_context_assemble metadata patching, and before_tool blocking to prevent denied invocations from reaching the tool gateway.
Introduce HooksConfig in the core Config model with version/defaults/entries parsing and round-trip serialization.\n\nWire DareAgentBuilder hook resolution to deterministic source ordering (system, config, code) and config-driven per-hook priority, ensuring stable hook ordering across registration sources.
Add LegacyHookAdapter so pre-existing hook implementations can participate in V1 dispatch while defaulting to allow decisions.\n\nIntroduce shadow mode on HookExtensionPoint to record block/error outcomes without enforcing runtime denial, enabling safer phased rollout of governance policy.
… suite Add unit and integration coverage for governance runtime behavior, including block/ask/legacy compatibility flows and hook overhead telemetry assertions.\n\nEmit hook.overhead_ratio from observability tracing and update hook module docs with v1 governance contract, rollout modes, and runtime bridge behavior.
Fix the remaining pytest regressions by restoring expected prompt content, enforcing package facade constraints, and adding compatibility behavior for file tools.\n\nKey changes:\n- Add the Runtime Environment section to the built-in base system prompt so loader assertions match expected contract.\n- Move checkpoint factory construction out of package __init__ and keep __init__ files facade-only (docstring + imports/exports).\n- Rework tool internal exports to facade + lazy export module, preventing circular imports while preserving existing import surface.\n- Remove a type-level model/context circular import by switching Prompt import in context kernel to TYPE_CHECKING.\n- Extend RunCommandTool/ReadFileTool/WriteFileTool to accept both keyword-style execute(...) and legacy execute(input, context) calls.\n- Add run_command INVALID_CWD signaling and output truncation metadata to satisfy v4 tool boundary expectations.\n\nRationale:\nThese changes preserve runtime behavior while restoring compatibility with the current test contracts and package architecture rules, eliminating the 7 previously failing tests without broad refactors.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scope (One PR One Thing)
Changed Files (required)
List all touched files and why each file changed.
If this PR is a large diff (>300 changed lines), explain why split PRs are not possible and provide a split follow-up plan.
Acceptance Criteria
Test Evidence (required)
.........If this PR changes high-risk runtime paths (auth/concurrency/execution control), include
risk-matrixevidence.Risk and Rollback
Dependency and Lockfile Changes
requirements.txt/pyproject.toml/package.json): [ ] Yes [ ] No [ ] N/AAgent Rules Checklist (required)
Reference:
docs/agent_rules.mdskip/only/excludeusage is explained and reviewed