Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

shared_lib/deterministic_block.py

View on GitHub
#!/usr/bin/env python3
"""Deterministic hard-block Stop hook (extension point).

This Stop hook calls evaluate_rules() to decide whether to block (exit 2 +
decision='block') or allow. By default evaluate_rules() ships NO built-in rules,
so the hook allows everything — it is an extension point for projects that want
to register their own deterministic violation classes.

Behavior:
  - Verdict output is JSON.
  - `PT_TEST_FORCE_VIOLATION` drives a synthetic violation for the test path.
  - Enforcement is gated by path_config.enforcement_enabled(); when disabled the
    hook is observational only.
  - `B5_DETERMINISTIC_DISABLED=1` env opt-out.
"""
import json
import os
import re
import sys
from datetime import datetime, timezone

LIB_DIR = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, LIB_DIR)
import path_config  # central path config
import transcript_adapter  # cross-runtime stdin + transcript parsing (Copilot/Claude)

B5_DETERMINISTIC_DISABLED = path_config.pt_env('DETERMINISTIC_DISABLED', '').lower() in ('1', 'true', 'yes')

# Safety valve: once the same atomic_id fires >= STREAK_BYPASS times in a row
# within a session, that atomic_id is auto-bypassed for the rest of the session
# (logs a warning but does not block). Prevents cascading transcript disasters.
STREAK_BYPASS = path_config.pt_env_int('STREAK_BYPASS', 3)


def _extract_response_and_transcript_lines(stdin_data):
    """From Stop hook stdin JSON, extract (response_text, transcript_lines).

    Delegates to transcript_adapter so both Copilot (transcriptPath +
    assistant.message/data.content) and Claude (transcript_path +
    assistant/message.content) schemas work. Kept for backward-compat /
    existing tests; main() uses the richer adapter call directly.

    Returns (response_text, transcript_lines) or ('', []).
    """
    response, _last_user, _tools, lines = transcript_adapter.read_transcript(stdin_data)
    return response, lines


def evaluate_rules(response, transcript_lines=None, last_user='', tool_commands=None):
    """Return deterministic-rule violations for a response. Ships empty (no
    built-in rules); see the body. Each violation: {rule_id, reason, evidence_excerpt}.

    Args:
      response: last assistant natural-language text.
      transcript_lines: raw transcript lines (legacy).
      last_user: last user prompt text (from transcript_adapter).
      tool_commands: shell/tool command strings from the latest assistant turn.
    """
    violations = []
    if not response and not tool_commands:
        return violations

    # The public release ships with NO built-in deterministic rules: preference-
    # tracker must not hard-block anyone on a maintainer's personal preferences.
    # Deterministic enforcement is opt-in and driven by the user's own recorded
    # rules / the shadow judge. This function is the extension point where rules
    # would be evaluated; by default it adds nothing.
    #
    # Test affordance: PT_TEST_FORCE_VIOLATION=1 emits one synthetic violation so
    # the block / exit-code mechanism stays testable without shipping a real rule.
    if os.environ.get('PT_TEST_FORCE_VIOLATION'):
        violations.append({
            'rule_id': 'test-synthetic',
            'reason': 'forced violation for mechanism testing',
            'evidence_excerpt': (response or '')[:120],
        })

    return violations


def build_block_reason(violations):
    """Build the block-reason text shown to the agent: list the triggered rules
    and their fix direction. No personal writing-style dictation."""
    if not violations:
        return ''
    triggered_lines = []
    for v in violations:
        rid = v.get('rule_id', 'rule')
        hint = v.get('fix') or v.get('reason') or ''
        triggered_lines.append(
            f"  • [{rid}] {str(v.get('evidence_excerpt', ''))[:120]}\n"
            f"    → {hint}"
        )
    triggered = '\n'.join(triggered_lines)

    reason = (
        f"⛔ {', '.join(v.get('rule_id', 'rule') for v in violations)} triggered\n\n"
        f"{triggered}\n\n"
        f"Override: env `B5_DETERMINISTIC_DISABLED=1` disables all; `B5_STREAK_BYPASS=N` "
        f"sets the consecutive-violation bypass threshold (default 3)."
    )
    return reason


def _streak_path(session_id):
    """Per-session streak counter file path."""
    sid = re.sub(r'[^a-zA-Z0-9_-]', '_', session_id or 'unknown')[:64]
    return os.path.join(path_config.get_streak_dir(), f'{sid}.json')


def _load_streak(session_id):
    """Load {atomic_id: count} for current session."""
    path = _streak_path(session_id)
    if not os.path.exists(path):
        return {}
    try:
        with open(path) as f:
            return json.load(f)
    except Exception:
        return {}


def _bump_streak(session_id, rule_ids):
    """Increment streak counter for given rule_ids. Returns updated dict."""
    os.makedirs(path_config.get_streak_dir(), exist_ok=True)
    streak = _load_streak(session_id)
    for rid in rule_ids:
        streak[rid] = streak.get(rid, 0) + 1
    try:
        with open(_streak_path(session_id), 'w') as f:
            json.dump(streak, f)
    except Exception:
        pass
    return streak


def _filter_bypass_streaked(violations, streak):
    """Safety valve: same atomic_id streak >= STREAK_BYPASS → bypass that rule (drop from violations).
    Returns (filtered_violations, bypassed_rule_ids).
    """
    filtered = []
    bypassed = []
    for v in violations:
        rid = v['rule_id']
        if streak.get(rid, 0) >= STREAK_BYPASS:
            bypassed.append(rid)
        else:
            filtered.append(v)
    return filtered, bypassed


def log_check(session_id, status, violations, latency_ms):
    """Append b5_check entry to compliance_log.jsonl."""
    entry = {
        'timestamp': datetime.now(timezone.utc).isoformat(),
        'session_id': session_id,
        'event': 'Stop',
        'check_source': 'deterministic_block',
        'b5_check': {
            'deterministic_status': status,  # 'pass' | 'block' | 'disabled'
            'deterministic_violations': [v['rule_id'] for v in violations],
            'deterministic_latency_ms': round(latency_ms, 2),
        },
    }
    try:
        log_path = path_config.get_compliance_log_path()
        os.makedirs(os.path.dirname(log_path), exist_ok=True)
        with open(log_path, 'a', encoding='utf-8') as f:
            f.write(json.dumps(entry, ensure_ascii=False) + '\n')
        # Log carries violation evidence; restrict to user-only.
        path_config.chmod_or_warn(log_path, 0o600)
    except Exception:
        pass


def main():
    """Stop hook entrypoint. Read stdin JSON, evaluate rules, exit 2 + JSON if block."""
    import time
    t0 = time.time()
    try:
        data = json.load(sys.stdin)
    except Exception:
        # Malformed stdin: don't block
        sys.exit(0)

    session_id = transcript_adapter.get_session_id(data)

    if path_config.is_child_session():
        sys.exit(0)

    # Infinite-loop guard (Claude Code Stop contract): the streak bypass is
    # the primary bound, but it needs a writable streak dir — on a read-only
    # FS a firing rule would otherwise block the Stop forever.
    if data.get('stop_hook_active') is True:
        sys.exit(0)

    if B5_DETERMINISTIC_DISABLED or not path_config.enforcement_enabled():
        log_check(session_id, 'disabled', [], (time.time() - t0) * 1000)
        sys.exit(0)

    response, last_user, tool_commands, transcript_lines = transcript_adapter.read_transcript(data)
    if not response and not tool_commands:
        log_check(session_id, 'pass', [], (time.time() - t0) * 1000)
        sys.exit(0)

    violations = evaluate_rules(response, transcript_lines, last_user=last_user, tool_commands=tool_commands)

    # Safety valve: bypass a rule after it fires STREAK_BYPASS times in a row
    if violations:
        streak = _load_streak(session_id)
        violations, bypassed = _filter_bypass_streaked(violations, streak)
        if bypassed:
            # log the bypassed rules (don't block, but record the disaster-escape event)
            log_check(session_id, 'streak_bypass', [{'rule_id': r, 'reason': 'streak >= bypass threshold', 'evidence_excerpt': f'streak={streak.get(r, 0)}'} for r in bypassed], (time.time() - t0) * 1000)

    latency_ms = (time.time() - t0) * 1000

    if violations:
        # bump streak only for rules that actually fired this turn (not bypassed)
        _bump_streak(session_id, [v['rule_id'] for v in violations])
        log_check(session_id, 'block', violations, latency_ms)
        decision = {
            'decision': 'block',
            'reason': build_block_reason(violations),
        }
        print(json.dumps(decision, ensure_ascii=False))
        # Belt-and-braces (mirrors check-observation-log.sh): per the hooks
        # contract stdout JSON is parsed on exit 0, while on a non-zero exit
        # stderr is what reaches the model — emit the reason on both channels
        # so the block guidance arrives either way.
        try:
            sys.stderr.write(decision['reason'] + '\n')
        except Exception:
            pass
        sys.exit(path_config.stop_block_exit_code())

    log_check(session_id, 'pass', [], latency_ms)
    sys.exit(0)


if __name__ == '__main__':
    try:
        main()
    except SystemExit:
        raise
    except Exception:
        # Defensive: never block on internal errors
        sys.exit(0)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall