logo1
GSD Skill Creator
HALT & CLEAR Safety Systems

Documentation > Specialized Systems > HALT & CLEAR Safety Systems

Guide IDSS-2
AudienceSysAdmins, Security engineers
PrerequisitesGS-3: How It Works, UG-4: Configuration
Time15 minutes
DifficultyIntermediate

HALT & CLEAR Safety Systems

Skill-creator is a self-modifying system -- it observes patterns, proposes refinements, and evolves skills over time. Without safety constraints, this learning loop could drift arbitrarily far from the user's intent. The HALT and CLEAR systems are the guardrails that keep bounded learning bounded. HALT stops automatic refinements when safety thresholds are breached. CLEAR resets loaded context for a clean restart. Together with the bounded learning parameters and hook security layer, they ensure that skill-creator always operates under human control.

HALT System

HALT is the emergency stop mechanism for skill refinement. It activates automatically when any of three conditions are detected:

  • Cumulative drift exceeds 60% -- The DriftTracker in src/learning/drift-tracker.ts measures how far a skill has changed from its original version using word-level diffing. When cumulative changes exceed 60% of the original content, the tracker throws a DriftThresholdError that halts all automatic refinements for that skill. This prevents gradual semantic shift where a skill's meaning transforms beyond recognition through many small updates.
  • Contradictory feedback detected -- The ContradictionDetector in src/learning/contradiction-detector.ts analyzes pairs of feedback corrections for reversal patterns. If correction B reverses correction A (changing text back to what A originally said), that is classified as a conflict. Partial reversals where corrections overlap in opposing directions produce warnings. When conflicts are found, automatic refinement pauses until a human reviews the contradictory signals.
  • Token budget overflow -- When loaded skills would exceed the configured token budget (2-5% of the context window), the skill loading pipeline refuses to proceed. This prevents context window exhaustion that would degrade Claude's performance across all tasks, not just skill-related work.

When HALT activates, all pending auto-refinements are suspended. The system logs the trigger condition and requires explicit human intervention to resume. Recovery involves reviewing the pending changes, approving or rolling back individual refinements, and resetting the halt state.

CLEAR Protocol

CLEAR is the context cleanup mechanism for fresh starts. Where HALT stops the learning loop, CLEAR resets the runtime state that feeds it:

  • When to CLEAR -- Context rot (quality degradation as conversation history fills), conflicting state from interrupted operations, or session recovery after an error.
  • What CLEAR does -- Resets all loaded skills from the active context, clears cached activation scores and pipeline state, and forces the next operation to reload skills from disk through the full 6-stage pipeline (Score, Resolve, ModelFilter, CacheOrder, Budget, Load). On-disk state -- skill files, feedback logs, audit records -- is preserved.
  • CLEAR vs restart -- CLEAR preserves everything on disk and merely resets the in-memory session. A full restart discards all runtime state and re-initializes from the persistent store. Use CLEAR for mid-session recovery; use restart only when disk state itself may be corrupted.

Bounded Learning Guardrails

Six parameters define the non-negotiable constraints on skill refinement. These are enforced by the RefinementEngine in src/learning/refinement-engine.ts:

ParameterValuePurpose
Min corrections3Require consistent feedback before suggesting changes
Max change20%Prevent drastic alterations in a single refinement
Cooldown7 daysAllow observation of changes before next refinement
User confirmAlwaysHuman in the loop for every change
Max cumulative drift60%HALT auto-refinements when skill has drifted too far
Contradiction detectionAutoFlag contradictory feedback before applying

The refinement workflow enforces these constraints in order: first check that at least 3 corrections exist for the target skill (via FeedbackStore), then check for contradictions, then verify that the proposed changes stay within the 20% single-change limit, then verify cumulative drift is below 60%, then check that the 7-day cooldown since the last refinement has elapsed (via OperationCooldown in src/safety/operation-cooldown.ts), and finally present the changes for user confirmation. No step can be skipped.

Hook Safety

Hooks extend skill-creator's behavior at session boundaries and lifecycle events. The src/hooks/ directory implements two safety layers:

The HookValidator (src/hooks/hook-validator.ts) performs static analysis of hook source code at registration time. It scans for forbidden patterns and rejects any hook that attempts to modify process.env, call process.exit, use eval() or the Function constructor, or modify global or globalThis state. All violations are collected and reported -- the validator does not stop at the first match.

The HookErrorBoundary (src/hooks/hook-error-boundary.ts) wraps hook execution with error catching and timeout enforcement. If a hook throws synchronously, rejects asynchronously, or exceeds the 10-second timeout, the error is caught and logged to stderr, and the session continues uninterrupted. The original error is never re-thrown -- a misbehaving hook cannot crash a Claude Code session.

Integrity Monitoring

The IntegrityMonitor (src/safety/integrity-monitor.ts) provides snapshot-based change detection for skill and agent directories. It takes SHA-256 hashes of all files in monitored directories (.claude/skills, .claude/agents), saves snapshots to disk, and detects unexpected modifications by cross-referencing changes against the AuditLogger. Changes that match an audit entry (create, update, refine, migrate, rollback, delete) are classified as "expected"; changes with no matching audit entry are flagged as "unexpected" -- potential tampering or data poisoning.

The AuditLogger (src/safety/audit-logger.ts) maintains an append-only JSONL log of every skill and agent mutation. Each entry records a timestamp, operation type, file path, and source identification. Writes are serialized to prevent interleaving. Entries are validated via Zod schema on read, with malformed lines skipped gracefully rather than causing read failures.

Security Considerations

  • Path traversal -- Skill names must be sanitized before use in file paths. A skill named ../../etc/passwd must not resolve outside the skills directory.
  • YAML deserialization -- Use safe parsing only. Never load arbitrary YAML that could trigger code execution through language-specific constructors.
  • Data poisoning -- The append-only JSONL files (.audit-log.jsonl, sessions.jsonl) could be manipulated by external processes. Validate entries on read via Zod schemas and treat missing or malformed entries as recoverable errors.
  • Permission skipping -- Never bypass user confirmation for skill application, even in automated or YOLO workflows. The user confirm guardrail has no override.
  • Cross-project leakage -- User-level skills in ~/.claude/commands/ must not expose project-specific patterns to other projects.
  • Observation privacy -- The .planning/patterns/ directory should be in .gitignore for shared repositories to prevent leaking session observation data.

What's Next