aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
588 lines (503 loc) • 18.4 kB
YAML
# Agent Persistence Hooks Configuration
# Integration layer for Agent Persistence Framework with agent loops
# Issue: #261
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/ralph-persistence-hooks/v1"
title: "Ralph Persistence Hooks"
description: |
Event hooks for Agent Persistence Framework integration with agent loops.
Enables laziness detection, regression monitoring, and recovery enforcement
at strategic execution points.
# Hook Definitions
hooks:
# ============================================================================
# Loop Lifecycle Hooks
# ============================================================================
loop_start:
description: "Invoked when agent loop begins execution"
trigger: "Agent loop initialization"
timing: before_first_iteration
agents_to_invoke:
- agent: progress-tracker
purpose: "Initialize baseline metrics"
required: true
inputs:
task_description: "{task}"
completion_criteria: "{completion}"
working_directory: "{cwd}"
- agent: laziness-detector
purpose: "Enable laziness pattern detection"
required: true
inputs:
detection_mode: "standard"
patterns_enabled: ["test_deletion", "feature_removal", "coverage_regression"]
actions:
- initialize_baseline_metrics
- snapshot_codebase_state
- enable_file_watchers
- log_loop_start
state_updates:
- set: "baseline_metrics"
from: "progress-tracker.baseline"
- set: "detection_enabled"
value: true
- set: "reinforcement_level"
value: "MINIMAL"
loop_complete:
description: "Invoked when agent loop completes (success or failure)"
trigger: "Loop reaches terminal state"
timing: after_final_iteration
agents_to_invoke:
- agent: progress-tracker
purpose: "Generate final progress report"
required: true
inputs:
loop_id: "{loop_id}"
final_status: "{status}"
- agent: best-output-selector
purpose: "Select highest quality iteration output"
required: true
inputs:
iteration_history: "{iterations}"
quality_metric: "overall_quality_score"
actions:
- select_best_output
- archive_iteration_history
- generate_completion_report
- disable_file_watchers
- log_loop_complete
state_updates:
- set: "selected_iteration"
from: "best-output-selector.iteration"
- set: "completion_report_path"
from: "progress-tracker.report_path"
- set: "detection_enabled"
value: false
# ============================================================================
# Iteration Lifecycle Hooks
# ============================================================================
pre_iteration:
description: "Invoked before each Ralph iteration"
trigger: "Iteration N starts"
timing: before_iteration_execution
agents_to_invoke:
- agent: prompt-reinforcement
purpose: "Inject iteration-aware anti-laziness prompts"
required: true
inputs:
iteration_number: "{iteration}"
task_context: "{task}"
error_history: "{errors}"
risk_patterns: "{detected_risks}"
actions:
- snapshot_pre_iteration_state
- calculate_reinforcement_level
- inject_reinforcement_prompts
- log_iteration_start
state_updates:
- increment: "iteration_count"
- set: "reinforcement_level"
from: "prompt-reinforcement.level"
- set: "pre_iteration_snapshot"
from: "snapshot_path"
post_iteration:
description: "Invoked after each Ralph iteration completes"
trigger: "Iteration N completes"
timing: after_iteration_execution
agents_to_invoke:
- agent: progress-tracker
purpose: "Capture iteration metrics"
required: true
inputs:
iteration: "{iteration}"
artifacts: "{modified_files}"
test_results: "{test_output}"
- agent: regression-detector
purpose: "Check for quality regression"
required: true
inputs:
baseline: "{baseline_metrics}"
current: "{current_metrics}"
iteration: "{iteration}"
- agent: best-output-tracker
purpose: "Update best iteration tracker"
required: true
inputs:
iteration: "{iteration}"
quality_score: "{quality}"
artifacts: "{iteration_artifacts}"
actions:
- capture_iteration_metrics
- check_regression
- update_best_output
- update_iteration_history
- check_completion_criteria
- log_iteration_complete
state_updates:
- append: "iteration_history"
from: "iteration_metrics"
- set: "best_iteration"
from: "best-output-tracker.best_iteration"
- set: "regression_detected"
from: "regression-detector.detected"
- set: "last_iteration_quality"
from: "quality_score"
conditional_actions:
- condition: "regression_detected == true"
action: trigger_hook
hook: regression_detected
- condition: "iteration >= 5 AND quality_delta < 0.05"
action: trigger_hook
hook: reinforcement_escalation
# ============================================================================
# Tool Call Hooks
# ============================================================================
pre_tool_call:
description: "Invoked before executing high-risk tool operations"
trigger: "Destructive tool call detected"
timing: before_tool_execution
risk_patterns:
- tool: Write
file_pattern: "**/test/**/*"
risk: "test_file_modification"
- tool: Write
file_pattern: "**/*.test.{ts,js,py}"
risk: "test_file_modification"
- tool: Bash
command_pattern: "rm -rf*"
risk: "bulk_deletion"
- tool: Bash
command_pattern: "git rm*"
risk: "version_control_deletion"
agents_to_invoke:
- agent: prompt-reinforcement
purpose: "Inject pre-action warning"
required: true
inputs:
tool: "{tool_name}"
target: "{tool_target}"
risk_level: "{risk}"
- agent: laziness-detector
purpose: "Pre-action validation"
required: false # Non-blocking
inputs:
action_type: "{tool_name}"
target_path: "{tool_target}"
actions:
- log_risky_action
- inject_warning_prompt
- create_rollback_checkpoint
state_updates:
- append: "risky_actions"
from: "action_log"
- set: "last_risky_action"
from: "action_description"
post_tool_call:
description: "Invoked after high-risk tool operations complete"
trigger: "Destructive tool call completed"
timing: after_tool_execution
agents_to_invoke:
- agent: regression-detector
purpose: "Immediate regression check"
required: true
inputs:
baseline: "{baseline_metrics}"
current: "{current_metrics}"
tool: "{tool_name}"
actions:
- capture_post_action_metrics
- compare_against_baseline
- log_action_impact
state_updates:
- append: "tool_call_history"
from: "tool_call_record"
conditional_actions:
- condition: "regression_detected == true"
action: trigger_hook
hook: regression_detected
# ============================================================================
# Error Handling Hooks
# ============================================================================
on_error:
description: "Invoked when iteration encounters error"
trigger: "Error during iteration execution"
timing: immediate_on_error
agents_to_invoke:
- agent: prompt-reinforcement
purpose: "Inject post-error guidance"
required: true
inputs:
error_type: "{error.type}"
error_message: "{error.message}"
iteration: "{iteration}"
previous_errors: "{error_history}"
actions:
- log_error
- increment_error_count
- inject_recovery_guidance
- check_for_stuck_loop
state_updates:
- append: "error_history"
from: "error_record"
- increment: "error_count"
- set: "last_error"
from: "error_record"
conditional_actions:
- condition: "error_count >= 3 AND same_error_repeated"
action: trigger_hook
hook: stuck_loop_detected
# ============================================================================
# Regression Detection Hooks
# ============================================================================
regression_detected:
description: "Invoked when regression is detected"
trigger: "Regression detector signals violation"
timing: immediate
agents_to_invoke:
- agent: recovery-orchestrator
purpose: "Enforce recovery protocol"
required: true
inputs:
regression_type: "{regression.type}"
severity: "{regression.severity}"
iteration: "{iteration}"
diff: "{regression.diff}"
actions:
- pause_execution
- log_regression_event
- invoke_recovery_protocol
- notify_human_if_critical
state_updates:
- append: "regression_events"
from: "regression_record"
- set: "recovery_in_progress"
value: true
- increment: "recovery_attempts"
recovery_protocol:
steps:
- PAUSE: "Block pending file operations"
- DIAGNOSE: "Analyze root cause"
- ADAPT: "Modify approach based on diagnosis"
- RETRY: "Re-attempt with adapted approach"
- ESCALATE: "Human gate if max retries exceeded"
escalation_conditions:
- condition: "recovery_attempts >= 3"
action: "invoke_human_gate"
- condition: "severity == 'critical'"
action: "invoke_human_gate"
- condition: "regression.type == 'test_deletion'"
action: "invoke_human_gate"
# ============================================================================
# Reinforcement Escalation Hooks
# ============================================================================
reinforcement_escalation:
description: "Invoked to escalate reinforcement intensity"
trigger: "Iteration count threshold or quality plateau"
timing: before_next_iteration
thresholds:
iteration_3: "STANDARD"
iteration_5: "AGGRESSIVE"
quality_plateau: "AGGRESSIVE" # 3 iterations with delta < 5%
agents_to_invoke:
- agent: prompt-reinforcement
purpose: "Escalate reinforcement level"
required: true
inputs:
current_level: "{reinforcement_level}"
iteration: "{iteration}"
quality_trajectory: "{quality_history}"
actions:
- escalate_reinforcement_level
- log_escalation
- inject_escalated_prompts
state_updates:
- set: "reinforcement_level"
from: "prompt-reinforcement.escalated_level"
- append: "escalation_history"
from: "escalation_record"
stuck_loop_detected:
description: "Invoked when loop appears stuck (repeated failures)"
trigger: "3+ consecutive errors or same issue repeated"
timing: immediate
agents_to_invoke:
- agent: recovery-orchestrator
purpose: "Force escalation to human"
required: true
inputs:
error_pattern: "{error_pattern}"
iteration: "{iteration}"
attempts: "{recovery_attempts}"
actions:
- pause_execution
- log_stuck_loop
- invoke_human_gate
- generate_diagnostic_report
state_updates:
- set: "stuck_loop_detected"
value: true
- set: "recovery_in_progress"
value: true
human_gate:
type: "TERMINATE"
timeout: null # Block indefinitely
message: |
🚨 STUCK LOOP DETECTED - Iteration {iteration}
The loop has encountered the same issue repeatedly:
{error_pattern}
Recovery attempts: {recovery_attempts}
Human guidance required to proceed.
options:
- id: "continue"
label: "Continue loop with modified approach"
action: "resume_with_new_strategy"
- id: "abort"
label: "Abort loop"
action: "abort_loop"
- id: "manual_fix"
label: "Manually fix and resume"
action: "pause_for_manual_intervention"
# ============================================================================
# Hook Execution Configuration
# ============================================================================
execution:
async_hooks:
description: "Hooks that can run asynchronously"
hooks:
- post_tool_call # Non-blocking validation
blocking_hooks:
description: "Hooks that must complete before proceeding"
hooks:
- pre_tool_call
- regression_detected
- stuck_loop_detected
timeout_ms:
default: 5000
pre_tool_call: 2000 # Fast pre-action check
regression_detected: 10000 # Allow time for recovery
stuck_loop_detected: null # No timeout, blocks until human
error_handling:
on_hook_failure:
default: log_and_continue
critical_hooks:
- hook: regression_detected
on_failure: abort_iteration
- hook: stuck_loop_detected
on_failure: force_pause
# ============================================================================
# State Extension Schema Reference
# ============================================================================
state_extension_schema: "@agentic/code/addons/ralph/schemas/persistence-extension.yaml"
# ============================================================================
# Integration with ConversableAgent
# ============================================================================
conversable_agent_protocol:
description: |
All agents invoked via hooks use ConversableAgent interface.
Hook → send(message) → Agent
Agent → generateReply() → Response
Response → receive() → Hook Handler
message_format:
role: "user"
content: "{hook_description}"
metadata:
hook_name: "{hook}"
loop_id: "{loop_id}"
iteration: "{iteration}"
inputs: "{hook_inputs}"
response_format:
role: "assistant"
content: "{agent_output}"
metadata:
verdict: "{verdict}" # For detection agents
recommendations: "{recommendations}"
artifacts: "{generated_paths}"
# ============================================================================
# Performance Requirements
# ============================================================================
performance:
detection_latency:
target_p95_ms: 500
target_p99_ms: 1000
measurement: "from hook trigger to completion"
integration_overhead:
max_percentage: 10
baseline: "Ralph iteration without hooks"
measurement: "total iteration time increase"
false_positive_rate:
target: "<5%"
measurement: "false detections / total detections"
# ============================================================================
# Audit Trail
# ============================================================================
audit:
log_all_hook_invocations: true
log_location: ".aiwg/ralph/loops/{loop_id}/hook-log.jsonl"
log_format:
timestamp: "ISO-8601"
hook_name: "string"
loop_id: "string"
iteration: "integer"
agents_invoked: "array"
outcomes: "array"
state_changes: "object"
retention_days: 90
# ============================================================================
# Examples
# ============================================================================
examples:
loop_start_invocation:
hook: loop_start
loop_id: "ralph-fix-tests-a1b2c3d4"
task: "Fix all TypeScript errors"
completion: "npx tsc --noEmit passes"
agents_invoked:
- progress-tracker:
baseline_metrics:
test_count: 150
coverage_percentage: 85
typescript_errors: 12
- laziness-detector:
patterns_enabled: ["test_deletion", "feature_removal"]
detection_mode: "standard"
regression_detected_invocation:
hook: regression_detected
loop_id: "ralph-fix-tests-a1b2c3d4"
iteration: 7
regression:
type: "test_deletion"
severity: "critical"
diff:
before_test_count: 150
after_test_count: 148
deleted_tests:
- "test/unit/auth/login.test.ts: should validate email format"
- "test/unit/auth/login.test.ts: should reject weak passwords"
agents_invoked:
- recovery-orchestrator:
recovery_protocol: "PDARE"
diagnosis: "Agent deleted failing tests instead of fixing code"
recommended_action: "ESCALATE to human gate"
# ============================================================================
# References
# ============================================================================
references:
requirements:
- "@.aiwg/requirements/use-cases/UC-AP-001-detect-test-deletion.md"
- "@.aiwg/requirements/use-cases/UC-AP-003-detect-coverage-regression.md"
- "@.aiwg/requirements/use-cases/UC-AP-004-enforce-recovery-protocol.md"
- "@.aiwg/requirements/use-cases/UC-AP-005-prompt-reinforcement.md"
- "@.aiwg/requirements/nfr-modules/agent-persistence-nfrs.md"
architecture:
- "@.aiwg/architecture/decisions/ADR-AP-001-detection-hook-architecture.md"
- "@.aiwg/architecture/decisions/ADR-AP-002-rule-enforcement-strategy.md"
- "@.aiwg/architecture/decisions/ADR-AP-003-prompt-injection-points.md"
schemas:
- "@agentic/code/addons/ralph/schemas/persistence-extension.yaml"
- "@agentic/code/addons/ralph/schemas/loop-state.yaml"
- "@agentic/code/addons/ralph/schemas/checkpoint.yaml"
research:
- "@.aiwg/research/findings/agentic-laziness-research.md"
rules:
- "@.claude/rules/conversable-agent-interface.md"
- "@.claude/rules/executable-feedback.md"
- "@.claude/rules/actionable-feedback.md"