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

tellonce_codex/codex_posttooluse_block.py

View on GitHub
#!/usr/bin/env python3
"""Codex PostToolUse adapter for deterministic_block.

Codex doesn't have a Stop hook. PostToolUse fires after every tool call. This
adapter:

  1. Reads codex hook stdin JSON (tool_name, tool_input, tool_response, cwd).
  2. Reconstructs a "response_text" from tool_input + tool_response.output so
     CC's evaluate_rules() can scan it for violations (active /tmp/ in code,
     etc.).
  3. Runs CC's evaluate_rules() and emits the codex hook output protocol:
       - exit 2 + JSON {decision: "block", reason: ...} when mode == 'blocking'
       - exit 0 + advisory log when mode == 'audit_only' or 'wrapper'
  4. Always logs the decision to <state>/runtime/posttooluse_log.jsonl.

The hook intentionally scans tool_input first — agent-submitted text (e.g. a
Write tool's content) is the most common source of rule violations we can
detect at this surface. tool_response.output is scanned secondarily but
filtered (build error lines often contain "stub" / "/tmp" legitimately).

Defensive: any failure -> exit 0 with empty stdout (never block codex turns).
"""
from __future__ import annotations

import json
import os
import sys
import time
from pathlib import Path


def _load_stdin() -> dict:
    try:
        return json.load(sys.stdin)
    except Exception:
        return {}


def _env_flag(*names: str) -> bool:
    for n in names:
        if os.environ.get(n, '').lower() in ('1', 'true', 'yes'):
            return True
    return False


def _streak_threshold() -> int:
    for n in ('PT_STREAK_BYPASS', 'B5_STREAK_BYPASS'):
        v = os.environ.get(n, '')
        if v:
            try:
                return int(v)
            except ValueError:
                pass
    return 3


def _apply_streak_bypass(state_root: Path, session_id, violations: list) -> list:
    """Safety valve (parity with CC deterministic_block main): once the same
    rule_id fires >= threshold times in a row within a session, auto-bypass it
    for the rest of the session (warn instead of block). Prevents an
    unsatisfiable rule from blocking every tool call. Counter lives in the
    codex state dir; any failure -> no bypass (fail toward original behavior).
    """
    try:
        threshold = _streak_threshold()
        sid = str(session_id or 'unknown').replace('/', '_')
        path = state_root / 'runtime' / 'streak_bypass.json'
        data = {}
        if path.is_file():
            try:
                data = json.loads(path.read_text(encoding='utf-8')) or {}
            except Exception:
                data = {}
        counts = data.get(sid, {})
        kept = []
        for v in violations:
            rid = str(v.get('rule_id', '?'))
            # Compare BEFORE incrementing (parity with CC deterministic_block:
            # block `threshold` times, bypass from the next firing on).
            if counts.get(rid, 0) >= threshold:
                sys.stderr.write(
                    f"[tellonce] streak bypass: rule {rid} already fired "
                    f"{counts[rid]}x in this session (threshold {threshold}) — "
                    "no longer blocking it this session\n")
            else:
                kept.append(v)
            counts[rid] = counts.get(rid, 0) + 1
        data = {sid: counts}  # keep only the current session (bounded file)
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(data, ensure_ascii=False), encoding='utf-8')
        return kept
    except Exception:
        return violations


def _extract_agent_text(payload: dict) -> str:
    """Pull agent-authored text content out of a codex PostToolUse payload.

    Priority order:
      1. tool_input.content (Write/Edit-style tools) — what the agent wrote
      2. tool_input.command (Bash/Shell) — the command itself
      3. tool_input.* string fields concatenated — fallback
      4. tool_input as JSON — last-resort fallback so SECRET / /tmp inside any
         field still scannable

    NOTE: We avoid scanning tool_response.output because that's environment
    output (build logs, command stdout) — not agent-authored. False positives
    there are common (e.g. "build using stub for X" is informational).
    """
    tool_input = payload.get("tool_input") or {}
    if not isinstance(tool_input, dict):
        return ""
    if isinstance(tool_input.get("content"), str):
        return tool_input["content"]
    if isinstance(tool_input.get("new_string"), str) and isinstance(tool_input.get("old_string"), str):
        # Edit-style: agent's new content
        return tool_input["new_string"]
    if isinstance(tool_input.get("command"), str):
        return tool_input["command"]
    parts = [
        v for v in tool_input.values()
        if isinstance(v, str) and len(v) < 100_000
    ]
    if parts:
        return "\n".join(parts)
    if not tool_input:
        return ""
    try:
        return json.dumps(tool_input, ensure_ascii=False)
    except Exception:
        return ""


def _resolve_state_root(payload: dict) -> Path | None:
    """Find the project's codex tellonce state root.

    Prefer `cwd` from payload, fall back to env CODEX_PROJECT_ROOT, else PWD.
    """
    cwd = payload.get("cwd") or os.environ.get("CODEX_PROJECT_ROOT") or os.getcwd()
    candidate = Path(cwd) / ".codex" / "tellonce"
    if (candidate / "registration.json").is_file() or (candidate / "mode.json").is_file():
        return candidate
    # Also try home-fallback layout (tellonce_codex.paths.fallback_state_root)
    try:
        from tellonce_codex.paths import project_id_for, fallback_state_root
        fb = fallback_state_root(Path(cwd))
        if (fb / "registration.json").is_file():
            return fb
    except Exception:
        pass
    return None


def _read_mode(state_root: Path | None) -> str:
    if not state_root:
        return "audit_only"
    p = state_root / "mode.json"
    if not p.is_file():
        return "audit_only"
    try:
        return (json.loads(p.read_text(encoding="utf-8")) or {}).get("mode", "audit_only")
    except Exception:
        return "audit_only"


def _log_decision(state_root: Path | None, record: dict) -> None:
    if not state_root:
        return
    log_dir = state_root / "runtime"
    try:
        log_dir.mkdir(parents=True, exist_ok=True)
        log_path = log_dir / "posttooluse_log.jsonl"
        # POSIX: a single line write to an O_APPEND fd is atomic up to PIPE_BUF
        # (typically 4096 bytes). Our records are well under that, so flock is
        # belt-and-suspenders here, but it ALSO blocks tmp races between
        # concurrent codex sessions on the same project.
        try:
            import fcntl
            with log_path.open("a", encoding="utf-8") as f:
                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
                try:
                    f.write(json.dumps(record, ensure_ascii=False) + "\n")
                finally:
                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
        except (ImportError, OSError):
            # No fcntl (Windows) — fall back to bare append; record may
            # interleave on rare contention but won't corrupt single lines.
            with log_path.open("a", encoding="utf-8") as f:
                f.write(json.dumps(record, ensure_ascii=False) + "\n")
        try:
            os.chmod(log_path, 0o600)
        except OSError:
            pass
    except Exception:
        pass


def main() -> int:
    payload = _load_stdin()
    if not payload:
        return 0

    # Kill-switch: the block reason advertises PT_/B5_DETERMINISTIC_DISABLED as
    # an override, and the CC variant honors it in deterministic_block.main().
    # This adapter calls evaluate_rules() directly, so honor it here too.
    if _env_flag('PT_DETERMINISTIC_DISABLED', 'B5_DETERMINISTIC_DISABLED'):
        return 0

    state_root = _resolve_state_root(payload)
    mode = _read_mode(state_root)

    # Lazy import shared CC lib. Try multiple layouts:
    #   1. ~/.codex/skills/tellonce/shared_lib/ (installed layout)
    #   2. <repo>/lib/ (development layout when running from repo)
    candidates = [
        Path(__file__).parent.parent / "shared_lib",            # installed
        Path(__file__).parent.parent.parent / "lib",            # repo dev
    ]
    for cand in candidates:
        if cand.is_dir() and str(cand) not in sys.path:
            sys.path.insert(0, str(cand))
            break
    try:
        import deterministic_block as db  # type: ignore
    except Exception:
        return 0

    text = _extract_agent_text(payload)

    # The public release ships NO built-in personal rules (including the
    # maintainer's BibTeX/citation workflow). This just runs the shared
    # deterministic rules — empty by default. Tool input (file content / shell
    # command) is not a user-facing reply, so language rules never apply here.
    #
    # CX-B2 fix: only skip genuinely empty/whitespace input. The previous
    # `len(text) < 30` floor silently dropped short-but-dangerous tool inputs
    # (e.g. `rm -rf /tmp/x`), so they were never scanned at all.
    if not text or not text.strip():
        return 0
    try:
        violations = db.evaluate_rules(text, [])
    except Exception:
        violations = []
    violations = [v for v in violations if not str(v.get('rule_id', '')).startswith('lang-')]

    record = {
        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
        "session_id": payload.get("session_id"),
        "turn_id": payload.get("turn_id"),
        "tool_name": payload.get("tool_name"),
        "mode": mode,
        "violations": [v.get("rule_id") for v in violations],
    }
    _log_decision(state_root, record)

    if not violations:
        return 0

    if mode != "blocking":
        # Advisory only — print to stderr (codex shows it to user/agent without
        # blocking the tool call).
        sys.stderr.write(
            "[tellonce advisory] "
            + ", ".join(v.get("rule_id", "?") for v in violations)
            + "\n"
        )
        return 0

    # Streak bypass safety valve (parity with the CC variant — advertised in
    # the block reason text, so it must actually work here).
    violations = _apply_streak_bypass(state_root, payload.get("session_id"), violations)
    if not violations:
        return 0

    # Build feedback text using CC's helper if available.
    try:
        reason = db.build_block_reason(violations)
    except Exception:
        reason = "tellonce: deterministic violations: " + ", ".join(
            v.get("rule_id", "?") for v in violations
        )

    # Blocking mode: emit codex PostToolUse-block JSON + exit 2.
    # If JSON serialization fails (shouldn't happen, but defensive), don't
    # exit 2 — codex would log "invalid JSON output" and the user wouldn't
    # see the reason. Better: fail open (advisory only, exit 0).
    out = {
        "hookSpecificOutput": {
            "hookEventName": "PostToolUse",
            "additionalContext": reason,
        },
        "decision": "block",
        "reason": reason,
    }
    try:
        sys.stdout.write(json.dumps(out, ensure_ascii=False))
    except Exception:
        sys.stderr.write("[tellonce] JSON serialize failed; demoting to advisory\n")
        sys.stderr.write(reason + "\n")
        return 0
    sys.stderr.write(reason + "\n")
    return 2


if __name__ == "__main__":
    sys.exit(main())
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