Imported from vladolaru/claude-code-plugins (plugins/yoloing-safe/AGENTS.md). Install upstream with npx skills add vladolaru/claude-code-plugins --skill yoloing-safe. Copyright stays with the author.

yoloing-safe — Agent Instructions

You maintain a dual-host PreToolUse safety hook for Claude Code's YOLO mode (--dangerously-skip-permissions) and Codex. The hook evaluates tool calls in this order:

1. allowlist
2. block-tier rules
3. ask-tier rules
4. allow

The runtime entrypoint stays at scripts/pre-tool-use-safety.py, but that file is now a compatibility shim. The assembled rule registry in scripts/yoloing_safe/rules/__init__.py is the canonical rule order and metadata source. Claude Code receives ask-tier confirmation output. Codex payloads include turn_id; because Codex PreToolUse does not support ask, the runtime converts those outcomes into explicit blocks. Codex also emits apply_patch plus a patch command instead of Write/Edit plus file_path; paths.extract_apply_patch_paths() and paths.resolve_tool_path() adapt every patch target to the canonical Write rules.

Key Files

Critical Constraints

• test-cases.json is generated. Edit test-fixtures.json or rule examples, then run make generate.
• Block-tier rules must stay before ask-tier rules in scripts/yoloing_safe/rules/__init__.py.
• Preserve the public compatibility surface exposed by scripts/pre-tool-use-safety.py unless you intentionally update tests, docs, and e2e tooling together.

Public Testing Contract

The shim (scripts/pre-tool-use-safety.py) re-exports RULES, RULES_BY_TOOL, ALLOWLIST_PATTERNS, DEFAULTS, NON_DISABLEABLE_RULES, normalize_command, load_config, is_allowlisted, and strip_writer_heredocs for the test suites, the e2e generator, the benchmark, and the runtime. TestShimCompatContract in tests/test_meta.py is the authority on that list and fails before downstream tooling breaks silently. The e2e generator imports RULES from the package (from yoloing_safe.rules import RULES), so it depends only on the canonical registry.

Rule Structure

Each assembled RULES entry has:

For declarative rules, registry.py compiles patterns and generates the legacy _detect callable. For custom rules, registry.py wraps the internal detector so tests still see the legacy (detected, message) interface via hook.RULES[rule_id]["_detect"].

Rule Types

Use a declarative rule when the behavior is fully expressible as regex match plus require/exclude conditions. Use the ask_rule() or block_rule() builders from registry.py:

("git_force_push", ask_rule(
    tools={"Bash"},
    patterns=[r"^git push\b"],
    require=[r"(--force\b|-f\b)"],
    exclude=[r"--force-with-lease", r"--force-if-includes"],
    message="Force push rewrites remote history. Use --force-with-lease instead.",
    examples=["git push --force origin hotfix/fix-arena"],
)),

Use a custom rule when you need config lookups, tool-specific path handling, chain-aware logic, or anything procedural. Custom detectors take an EvalContext object:

def detect_my_rule(ctx):
    # ctx.command, ctx.tool_name, ctx.tool_input, ctx.config
    # ctx.whole_command (cached), ctx.segments (cached)
    return bool(_RE_MY_PATTERN.search(ctx.command))

("my_rule", block_rule(
    tools={"Bash"},
    detect=detect_my_rule,
    message="Guidance message.",
    examples=["dangerous-command --flag"],
)),

Domain Modules

Each domain module exports an ordered RULE_SPECS list of (rule_id, spec) tuples and an ALLOWLIST_PATTERNS list. The aggregator in rules/__init__.py concatenates them with block-tier first, ask-tier second.

Testing

CWD matters: Always run pytest from the repo root, not from inside plugins/yoloing-safe/. Integration and scenario tests spawn the hook as a subprocess that inherits CWD. If CWD is inside the plugin directory, relative paths in test commands (e.g., chmod 777 file) resolve under _PLUGIN_ROOT and self-protection blocks them — causing spurious failures. After running make generate (which cds into tests/e2e/), return to the repo root before running pytest.

Fast suites:

pytest plugins/yoloing-safe/tests/ -v
pytest plugins/yoloing-safe/tests/test_meta.py -v
pytest plugins/yoloing-safe/tests/benchmark_hook.py -v

E2E suite (must be run manually by the user — requires interactive TTY for make auth and a Docker daemon):

cd plugins/yoloing-safe/tests/e2e
make generate   # regenerate test-cases.json from RULES + test-fixtures.json
make build      # build Docker image with latest hook code and fixtures
make auth       # interactive — authenticates Claude CLI inside the container
make run        # executes all e2e tests (model calls, slow)
# Return to repo root before running pytest
cd /path/to/repo

Agents cannot run make auth or make run — they require an interactive terminal and a valid Claude API session. When e2e-relevant changes are made (new rules, allowlist patterns, test fixtures, Dockerfile), agents should run make generate and make build, then tell the user to run make auth + make run manually.

Which Tests to Run

tests/TESTING.md § Which Tests to Run After Changes maps each kind of change to its suites. Any change under scripts/ runs the whole suite plus benchmark_hook.py; a rule or allowlist change also runs make generate in tests/e2e/ (see After Any Rule Change below).

Rule Workflows

Adding a New Rule

1. Choose the domain module in scripts/yoloing_safe/rules/.
2. Add regex constants and helpers in that module if needed.
3. For custom rules: write a detect_my_rule(ctx) function.
4. Add the rule to the module's RULE_SPECS using block_rule() or ask_rule().
5. If the rule needs a safe variant, add it to that module's ALLOWLIST_PATTERNS.
6. Add a Test{PascalCaseRuleId} class to the matching split suite (test_rules_*.py).
7. Add scenarios:
   • block rule: scenarios/blocked.json and at least one scenarios/evasion.json entry
   • ask rule: scenarios/asked.json
   • both: safe variant in scenarios/allowed.json
8. Run the After Any Rule Change steps.

Removing a Rule

1. Remove it from the domain module's RULE_SPECS.
2. Remove any allowlist entries for that rule.
3. Remove scenarios from blocked.json, asked.json, allowed.json, and evasion.json.
4. Remove the unit test class from the matching split suite.
5. Remove any tests/e2e/test-fixtures.json override.
6. Run the After Any Rule Change steps.

Renaming a Rule

Rename it in all of these places:

1. Domain module RULE_SPECS key and detector function name if applicable
2. Module ALLOWLIST_PATTERNS
3. blocked.json, asked.json, allowed.json, evasion.json
4. tests/e2e/test-fixtures.json
5. Test class and any explicit references in tests
6. Run the After Any Rule Change steps

Changing a Rule's Tier

1. Change the builder from block_rule() to ask_rule() or vice versa.
2. Move scenario entries between blocked.json and asked.json.
3. If promoting to block, add evasion scenarios.
4. Update the message tone to match the new tier.
5. Run the After Any Rule Change steps.

After Any Rule Change

1. pytest plugins/yoloing-safe/tests/test_meta.py -v
2. pytest plugins/yoloing-safe/tests/ -v
3. pytest plugins/yoloing-safe/tests/benchmark_hook.py -v
4. cd plugins/yoloing-safe/tests/e2e && make generate
5. Update CHANGELOG.md and bump .claude-plugin/marketplace.json per the repo versioning rules