agentlint 2.3.0__tar.gz → 2.3.1__tar.gz

{agentlint-2.3.0 → agentlint-2.3.1}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v2.3.1 (2026-05-15) — AgentChute Onboarding Polish
+
+This release applies first-run AgentChute setup feedback from local Codex
+dogfooding. It makes the install path less ambiguous and keeps diagnostics from
+mutating or crashing on the local sync queue.
+
+### Changed
+
+- `agentlint init --team-key ...` now prints `AGENTCHUTE_API_URL` alongside the
+  license key and enable flag, so local AgentChute tests keep targeting the
+  local API instead of silently falling back to production defaults.
+- `agentlint setup codex` now enables `codex_hooks = true` under `[features]` in
+  `~/.codex/config.toml`, and repairs stale root or nested `codex_hooks` keys
+  that can make Codex fail to load its config.
+- Codex, Claude Code, and Cursor setup docs now include AgentChute local testing
+  env vars and restart/reload guidance.
+- `agentlint sync --dry-run` now counts queued events without acquiring the
+  flush lock or advancing the delivery cursor.
+- AgentChute queue flushing now treats lock acquisition failures as a locked
+  queue instead of crashing.
+
+### Compatibility
+
+- Existing hook files and AgentLint configs remain valid.
+- Codex users must still restart Codex after enabling hooks; Codex loads hooks
+  when the session starts.
+
+---
+
 ## v2.3.0 (2026-05-14) — CI Signal Polish
 
 This release applies real-world Codex and AgentLint dogfooding feedback. It

{agentlint-2.3.0 → agentlint-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlint
-Version: 2.3.0
+Version: 2.3.1
 Summary: Real-time quality guardrails for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/agentlint
 Project-URL: Repository, https://github.com/mauhpr/agentlint
@@ -62,7 +62,7 @@ We don't have a mature answer to that yet. Nobody does. The **autopilot pack** i
 
 AgentLint ships with 76 rules across 8 packs and normalizes tool events across supported AI coding agents. The 23 **universal** rules and 7 **quality** rules work with any tech stack; 4 additional packs auto-activate based on your project files; the **security** pack is opt-in; and the **autopilot** pack is opt-in and experimental.
 
-**v2.3.0 highlights:** Codex dogfooding polish with FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
+**v2.3.1 highlights:** AgentChute onboarding polish with clearer local setup output, safe Codex hook enablement, safer sync dry-run diagnostics, FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
 
 | Rule | Severity | What it does |
 |------|----------|-------------|

{agentlint-2.3.0 → agentlint-2.3.1}/README.md

@@ -26,7 +26,7 @@ We don't have a mature answer to that yet. Nobody does. The **autopilot pack** i
 
 AgentLint ships with 76 rules across 8 packs and normalizes tool events across supported AI coding agents. The 23 **universal** rules and 7 **quality** rules work with any tech stack; 4 additional packs auto-activate based on your project files; the **security** pack is opt-in; and the **autopilot** pack is opt-in and experimental.
 
-**v2.3.0 highlights:** Codex dogfooding polish with FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
+**v2.3.1 highlights:** AgentChute onboarding polish with clearer local setup output, safe Codex hook enablement, safer sync dry-run diagnostics, FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
 
 | Rule | Severity | What it does |
 |------|----------|-------------|

{agentlint-2.3.0 → agentlint-2.3.1}/docs/setup-claude.md

@@ -18,6 +18,17 @@ This creates `.claude/settings.json` in your project root with hooks for:
 - `Notification` — notification-triggered rules
 - `Stop` — session summary report
 
+For AgentChute local testing, set the API URL before starting Claude Code:
+
+```bash
+export AGENTCHUTE_API_URL=http://localhost:8000/v1
+export AGENTCHUTE_LICENSE_KEY=ac_team_...
+export AGENTCHUTE_ENABLED=true
+```
+
+Restart Claude Code in the project after running `agentlint setup claude` so it
+loads the updated hook config.
+
 ## Hook Format
 
 Claude Code uses a JSON-based hook protocol:
@@ -74,6 +85,7 @@ Removes only AgentLint hooks; preserves any other custom hooks you have configur
 **Hooks not firing?**
 - Verify `.claude/settings.json` exists and contains a `"hooks"` key
 - Check that the `agentlint` binary is on PATH or that `agentlint setup` embedded an absolute path
+- Restart Claude Code after installing hooks
 - Run `agentlint doctor` to diagnose installation issues
 
 **Blocking rules not actually blocking?**

{agentlint-2.3.0 → agentlint-2.3.1}/docs/setup-codex.md

@@ -16,6 +16,33 @@ This creates `.codex/hooks.json` in your project root with hooks for:
 - `SessionStart` — session initialization
 - `Stop` — session summary report
 
+Codex also requires native hooks to be enabled globally. `agentlint setup codex`
+updates `~/.codex/config.toml` for you by adding the flag under `[features]`:
+
+```toml
+[features]
+codex_hooks = true
+```
+
+Do not append `codex_hooks = true` to the end of `config.toml` manually. TOML
+assigns bare keys to the most recent table, so appending after a section such as
+`[tui.model_availability_nux]` can make Codex fail to load its config.
+
+Restart Codex from the terminal where your AgentLint/AgentChute environment
+variables are set:
+
+```bash
+codex
+```
+
+For AgentChute local testing, set the API URL before starting Codex:
+
+```bash
+export AGENTCHUTE_API_URL=http://localhost:8000/v1
+export AGENTCHUTE_LICENSE_KEY=ac_team_...
+export AGENTCHUTE_ENABLED=true
+```
+
 ## Important: Codex Hook Coverage
 
 Codex's PreToolUse hook currently only reliably intercepts **Bash tool calls**. Coverage for `apply_patch` edits and MCP tool calls is intermittent and depends on the Codex CLI version. This is a known upstream limitation.
@@ -71,6 +98,12 @@ Removes only AgentLint hooks; preserves any other custom hooks you have configur
 - Ensure your Codex CLI is up to date; hook support is evolving rapidly
 - Bash tool calls should always trigger PreToolUse hooks
 
+**No events in AgentChute?**
+- Ensure `codex_hooks = true` is present under `[features]` in `~/.codex/config.toml`
+- Start a fresh Codex session after running `agentlint setup codex`
+- Launch Codex from the same terminal where `AGENTCHUTE_API_URL`, `AGENTCHUTE_LICENSE_KEY`, and `AGENTCHUTE_ENABLED` are exported
+- Run `agentlint agentchute status` and `agentlint sync` from the project root
+
 **Need full file-write coverage?**
 - Consider using AgentLint's MCP server alongside hooks for pre-validation
 - Run `agentlint doctor` for alternative integration suggestions

{agentlint-2.3.0 → agentlint-2.3.1}/docs/setup-cursor.md

@@ -17,6 +17,17 @@ This creates `.cursor/hooks.json` in your project root with hooks for:
 - `subagentStart` / `subagentStop` — subagent safety
 - `stop` — session summary report
 
+For AgentChute local testing, set the API URL before launching Cursor:
+
+```bash
+export AGENTCHUTE_API_URL=http://localhost:8000/v1
+export AGENTCHUTE_LICENSE_KEY=ac_team_...
+export AGENTCHUTE_ENABLED=true
+```
+
+Reload the Cursor window after running `agentlint setup cursor` so it loads the
+updated hook config.
+
 ## Hook Format
 
 Cursor hooks use a JSON-based protocol:
@@ -57,3 +68,11 @@ agentlint uninstall cursor
 | `CURSOR_SESSION_ID` | Session ID for state tracking |
 | `AGENTLINT_PROJECT_DIR` | Generic project directory (takes precedence) |
 | `AGENTLINT_SESSION_ID` | Generic session ID (takes precedence) |
+
+## Troubleshooting
+
+**No events in AgentChute?**
+- Verify `.cursor/hooks.json` exists in the project
+- Reload the Cursor window after installing hooks
+- Ensure Cursor inherits `AGENTCHUTE_API_URL`, `AGENTCHUTE_LICENSE_KEY`, and `AGENTCHUTE_ENABLED`
+- Run `agentlint agentchute status` and `agentlint sync` from the project root

{agentlint-2.3.0 → agentlint-2.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentlint"
-version = "2.3.0"
+version = "2.3.1"
 description = "Real-time quality guardrails for AI coding agents"
 readme = "README.md"
 license = "MIT"

{agentlint-2.3.0 → agentlint-2.3.1}/src/agentlint/__init__.py

@@ -1,6 +1,6 @@
 """AgentLint - Real-time quality guardrails for AI coding agents."""
 
-__version__ = "2.3.0"
+__version__ = "2.3.1"
 
 from agentlint.core.models import (
     AgentEvent,

{agentlint-2.3.0 → agentlint-2.3.1}/src/agentlint/agentchute/queue.py

@@ -140,10 +140,31 @@ def flush_queue(
     """Flush queued events to AgentChute in bounded batches."""
     result = FlushResult()
     client = AgentChuteClient.from_env()
-    if client is None:
+    if client is None and not dry_run:
         result.aborted_reason = "AGENTCHUTE_LICENSE_KEY not set"
         return result
 
+    if dry_run:
+        cursor = int(_load_json(_cursor_path(), {"offset": 0}).get("offset", 0))
+        lines = _read_lines()
+        if cursor >= len(lines):
+            return result
+        pending = lines[cursor:]
+        if max_events is not None:
+            pending = pending[:max_events]
+        for raw in pending:
+            if not raw.strip():
+                result.skipped += 1
+                continue
+            try:
+                json.loads(raw)
+            except json.JSONDecodeError:
+                result.skipped += 1
+                continue
+            result.attempted += 1
+            result.delivered += 1
+        return result
+
     if not _acquire_lock():
         result.locked = True
         return result
@@ -271,6 +292,9 @@ def _acquire_lock() -> bool:
                 return False
             return _acquire_lock()
         return False
+    except OSError:
+        logger.debug("agentlint.agentchute: could not acquire flush lock", exc_info=True)
+        return False
 
 
 def _release_lock() -> None:

{agentlint-2.3.0 → agentlint-2.3.1}/src/agentlint/cli.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 import json
 import logging
 import os
+import re
 import sys
 import time
+import tomllib
 from pathlib import Path
 from typing import Any
 
@@ -40,6 +42,10 @@ from agentlint.utils.git import get_changed_files, get_diff_files
 
 logger = logging.getLogger("agentlint")
 
+_TOML_SECTION_RE = re.compile(r"^\s*\[([^\[\]]+)\]\s*(?:#.*)?$")
+_CODEX_HOOKS_KEY_RE = re.compile(r"^(\s*)codex_hooks\s*=.*$")
+_HOOKS_KEY_RE = re.compile(r"^(\s*)hooks\s*=.*$")
+
 _SUPPORTED_ADAPTERS = (
     "claude",
     "cursor",
@@ -64,6 +70,85 @@ def _resolve_project_dir(project_dir: str | None = None) -> str:
     )
 
 
+def _codex_hooks_enabled() -> bool:
+    """Return whether Codex native hooks are enabled in ~/.codex/config.toml."""
+    config_path = Path.home() / ".codex" / "config.toml"
+    try:
+        text = config_path.read_text()
+    except OSError:
+        return False
+
+    try:
+        config = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        return False
+
+    features = config.get("features")
+    if not isinstance(features, dict):
+        return False
+    return features.get("hooks") is True or features.get("codex_hooks") is True
+
+
+def _enable_codex_hooks() -> Path:
+    """Enable Codex hooks in ~/.codex/config.toml without corrupting TOML tables."""
+    config_path = Path.home() / ".codex" / "config.toml"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        text = config_path.read_text()
+    except OSError:
+        text = ""
+
+    lines = text.splitlines()
+    output: list[str] = []
+    current_section: str | None = None
+    features_start: int | None = None
+    features_end: int | None = None
+    features_codex_hooks_index: int | None = None
+    features_hooks_index: int | None = None
+
+    for line in lines:
+        section_match = _TOML_SECTION_RE.match(line)
+        if section_match:
+            if current_section == "features" and features_end is None:
+                features_end = len(output)
+            current_section = section_match.group(1).strip()
+            if current_section == "features":
+                features_start = len(output)
+            output.append(line)
+            continue
+
+        if _CODEX_HOOKS_KEY_RE.match(line):
+            if current_section == "features":
+                features_codex_hooks_index = len(output)
+                output.append("codex_hooks = true")
+            # Drop stale root or nested codex_hooks keys. The flag is only valid
+            # under [features], and nested keys can break Codex schema loading.
+            continue
+
+        if current_section == "features" and _HOOKS_KEY_RE.match(line):
+            features_hooks_index = len(output)
+            output.append("hooks = true")
+            continue
+
+        output.append(line)
+
+    if current_section == "features" and features_end is None:
+        features_end = len(output)
+
+    if features_hooks_index is None and features_codex_hooks_index is None:
+        if features_start is None:
+            if output and output[-1].strip():
+                output.append("")
+            output.extend(["[features]", "codex_hooks = true"])
+        else:
+            insert_at = features_end if features_end is not None else len(output)
+            output.insert(insert_at, "codex_hooks = true")
+
+    config_path.write_text("\n".join(output) + "\n")
+    return config_path
+
+
 def _resolve_adapter(adapter_name: str | None = None) -> Any:
     """Resolve the agent adapter from explicit flag or environment detection.
 
@@ -585,8 +670,12 @@ agentchute:
     click.echo(f"Created {config_path}")
     click.echo(f"Detected packs: {', '.join(packs)}")
     if team_key:
+        from agentlint.agentchute.client import DEFAULT_API_URL, ENV_AGENTCHUTE_API_URL
+
+        api_url = os.environ.get(ENV_AGENTCHUTE_API_URL, DEFAULT_API_URL)
         click.echo("")
         click.echo("AgentChute enabled. Add these env vars to your shell or AI tool settings:")
+        click.echo(f"export AGENTCHUTE_API_URL={api_url}")
         click.echo(f"export AGENTCHUTE_LICENSE_KEY={team_key}")
         click.echo("export AGENTCHUTE_ENABLED=true")
 
@@ -714,6 +803,15 @@ def setup(platform: str, scope: str, project_dir: str | None, dry_run: bool):
 
     click.echo(f"Installed AgentLint hooks for {platform}")
 
+    if platform == "codex" and not dry_run:
+        if _codex_hooks_enabled():
+            click.echo("Codex hooks are enabled in ~/.codex/config.toml.")
+        else:
+            config_path = _enable_codex_hooks()
+            click.echo(f"Enabled Codex hooks in {config_path}.")
+            click.echo("Set [features].codex_hooks = true.")
+        click.echo("Restart Codex from the terminal where your AgentLint/AgentChute env vars are set.")
+
     # Also create agentlint.yml if it doesn't exist
     config_path = os.path.join(project_dir, "agentlint.yml")
     if not dry_run and not os.path.exists(config_path):

{agentlint-2.3.0 → agentlint-2.3.1}/tests/test_agentchute_policy_queue_sync.py

@@ -252,7 +252,35 @@ def test_queue_enqueue_flush_dry_run_and_status(tmp_path, monkeypatch):
 
     assert result.attempted == 1
     assert result.delivered == 1
-    assert queue.queue_status()["pending"] == 0
+    assert queue.queue_status()["pending"] == 1
+    assert not (tmp_path / "flush.lock").exists()
+
+
+def test_queue_flush_dry_run_counts_limited_poison_entries(tmp_path, monkeypatch):
+    from agentlint.agentchute import queue
+
+    monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
+    monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_x")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
+    queue._save_json(tmp_path / "cursor.json", {"offset": 1})
+    (tmp_path / "queue.jsonl").write_text(
+        "\n".join(
+            [
+                json.dumps({"event_id": "already-delivered", "event": {}}),
+                "",
+                "{not-json",
+                json.dumps({"event_id": "e1", "event": {"n": 1}}),
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    result = queue.flush_queue(max_events=3, dry_run=True)
+
+    assert result.skipped == 2
+    assert result.attempted == 1
+    assert result.delivered == 1
+    assert json.loads((tmp_path / "cursor.json").read_text())["offset"] == 1
 
 
 def test_queue_disabled_and_oversized_events_are_not_queued(tmp_path, monkeypatch):
@@ -330,6 +358,35 @@ def test_queue_flush_success_paths_and_aborts(tmp_path, monkeypatch):
     assert json.loads((tmp_path / "retry.json").read_text())["failures"] == 1
 
 
+def test_queue_flush_empty_queue_clears_retry(tmp_path, monkeypatch):
+    from agentlint.agentchute import queue
+
+    monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
+    monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_x")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
+    queue._save_json(tmp_path / "retry.json", {"failures": 2, "next_attempt_at": 123})
+
+    result = queue.flush_queue()
+
+    assert result.attempted == 0
+    assert not (tmp_path / "retry.json").exists()
+
+
+def test_queue_flush_advances_over_poison_only_batch(tmp_path, monkeypatch):
+    from agentlint.agentchute import queue
+
+    monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
+    monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_x")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
+    (tmp_path / "queue.jsonl").write_text("\n{not-json\n", encoding="utf-8")
+
+    result = queue.flush_queue(batch_size=2)
+
+    assert result.skipped == 2
+    assert result.attempted == 0
+    assert json.loads((tmp_path / "cursor.json").read_text())["offset"] == 2
+
+
 def test_queue_flush_handles_lock_and_stale_lock(tmp_path, monkeypatch):
     from agentlint.agentchute import queue
 
@@ -349,11 +406,48 @@ def test_queue_flush_handles_lock_and_stale_lock(tmp_path, monkeypatch):
     assert queue.flush_queue(dry_run=True).locked is False
 
 
+def test_queue_filesystem_failures_are_nonfatal(tmp_path, monkeypatch):
+    from agentlint.agentchute import queue
+
+    monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
+    monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_x")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
+    queue._save_json(tmp_path / "queue.jsonl", {"not": "jsonl"})
+
+    with patch("pathlib.Path.read_text", side_effect=OSError("cannot read")):
+        assert queue._read_lines() == []
+
+    with patch("builtins.open", side_effect=OSError("cannot count")):
+        assert queue._count_lines(tmp_path / "queue.jsonl") == 0
+
+    with patch("os.open", side_effect=OSError("cannot lock")):
+        assert queue.flush_queue().locked is True
+
+    lock = tmp_path / "flush.lock"
+    lock.write_text("other", encoding="utf-8")
+    old = 1
+    import os
+
+    os.utime(lock, (old, old))
+    with patch("pathlib.Path.unlink", side_effect=OSError("cannot unlink stale lock")):
+        assert queue.flush_queue().locked is True
+
+    with patch("pathlib.Path.unlink", side_effect=OSError("cannot unlink")):
+        queue._release_lock()
+        queue._clear_retry()
+
+
 def test_trigger_background_flush_respects_retry_and_spawns(tmp_path, monkeypatch):
     from agentlint.agentchute import queue
 
     monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
     monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_x")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
+    monkeypatch.setenv("AGENTCHUTE_ENABLED", "false")
+    with patch("subprocess.Popen") as popen:
+        queue.trigger_background_flush()
+    popen.assert_not_called()
+
     monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")
     queue._save_json(tmp_path / "retry.json", {"next_attempt_at": 9999999999})
     with patch("subprocess.Popen") as popen:

{agentlint-2.3.0 → agentlint-2.3.1}/tests/test_cli.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 
 import json
 import os
+import tomllib
 from unittest.mock import patch
 
 from click.testing import CliRunner
 
-from agentlint.cli import _resolve_adapter, main
+from agentlint.cli import _codex_hooks_enabled, _enable_codex_hooks, _resolve_adapter, main
 
 
 class TestMainCommand:
@@ -17,7 +18,7 @@ class TestMainCommand:
         result = runner.invoke(main, ["--version"])
 
         assert result.exit_code == 0
-        assert result.output.strip() == "agentlint 2.3.0"
+        assert result.output.strip() == "agentlint 2.3.1"
 
 
 class TestCheckCommand:
@@ -102,6 +103,7 @@ class TestInitCommand:
         assert "agentchute:" in config_text
         assert "enabled: true" in config_text
         assert "ac_team_test_secret" not in config_text
+        assert "export AGENTCHUTE_API_URL=" in result.output
         assert "export AGENTCHUTE_LICENSE_KEY=ac_team_test_secret" in result.output
 
 
@@ -2005,6 +2007,101 @@ class TestSetupPlatformSubcommands:
         assert data["version"] == 1
         assert "hooks" in data
 
+    def test_setup_codex_enables_global_hooks(self, tmp_path, monkeypatch) -> None:
+        monkeypatch.setenv("HOME", str(tmp_path / "home"))
+        runner = CliRunner()
+        result = runner.invoke(main, ["setup", "codex", "--project-dir", str(tmp_path)])
+        assert result.exit_code == 0
+        assert "Installed AgentLint hooks for codex" in result.output
+        assert "Enabled Codex hooks" in result.output
+        assert "codex_hooks = true" in result.output
+        assert "Restart Codex" in result.output
+
+        hooks_file = tmp_path / ".codex" / "hooks.json"
+        assert hooks_file.exists()
+        config_file = tmp_path / "home" / ".codex" / "config.toml"
+        config = tomllib.loads(config_file.read_text())
+        assert config["features"]["codex_hooks"] is True
+
+    def test_setup_codex_reports_existing_global_hooks(self, tmp_path, monkeypatch) -> None:
+        home = tmp_path / "home"
+        monkeypatch.setenv("HOME", str(home))
+        config_file = home / ".codex" / "config.toml"
+        config_file.parent.mkdir(parents=True)
+        config_file.write_text("[features]\ncodex_hooks = true\n", encoding="utf-8")
+
+        runner = CliRunner()
+        result = runner.invoke(main, ["setup", "codex", "--project-dir", str(tmp_path)])
+
+        assert result.exit_code == 0
+        assert "Codex hooks are enabled in ~/.codex/config.toml." in result.output
+        assert "Enabled Codex hooks" not in result.output
+
+    def test_setup_codex_repairs_orphan_codex_hooks_key(self, tmp_path, monkeypatch) -> None:
+        home = tmp_path / "home"
+        monkeypatch.setenv("HOME", str(home))
+        config_file = home / ".codex" / "config.toml"
+        config_file.parent.mkdir(parents=True)
+        config_file.write_text(
+            "\n".join(
+                [
+                    'model = "gpt-5.5"',
+                    "",
+                    "[features]",
+                    "goals = true",
+                    "",
+                    "[tui.model_availability_nux]",
+                    '"gpt-5.5" = 4',
+                    "codex_hooks = true",
+                    "",
+                ]
+            )
+        )
+
+        runner = CliRunner()
+        result = runner.invoke(main, ["setup", "codex", "--project-dir", str(tmp_path)])
+        assert result.exit_code == 0
+
+        config = tomllib.loads(config_file.read_text())
+        assert config["features"]["codex_hooks"] is True
+        assert config["tui"]["model_availability_nux"] == {"gpt-5.5": 4}
+
+    def test_codex_hooks_enabled_reads_features_only(self, tmp_path, monkeypatch) -> None:
+        home = tmp_path / "home"
+        monkeypatch.setenv("HOME", str(home))
+        config_file = home / ".codex" / "config.toml"
+        config_file.parent.mkdir(parents=True)
+
+        assert _codex_hooks_enabled() is False
+
+        config_file.write_text("[features\n", encoding="utf-8")
+        assert _codex_hooks_enabled() is False
+
+        config_file.write_text('features = "not-a-table"\n', encoding="utf-8")
+        assert _codex_hooks_enabled() is False
+
+        config_file.write_text("[features]\nhooks = true\n", encoding="utf-8")
+        assert _codex_hooks_enabled() is True
+
+    def test_enable_codex_hooks_handles_existing_feature_variants(self, tmp_path, monkeypatch) -> None:
+        home = tmp_path / "home"
+        monkeypatch.setenv("HOME", str(home))
+        config_file = home / ".codex" / "config.toml"
+        config_file.parent.mkdir(parents=True)
+
+        config_file.write_text("[features]\ncodex_hooks = false\n", encoding="utf-8")
+        _enable_codex_hooks()
+        assert tomllib.loads(config_file.read_text())["features"]["codex_hooks"] is True
+
+        config_file.write_text("[features]\nhooks = false\n", encoding="utf-8")
+        _enable_codex_hooks()
+        assert tomllib.loads(config_file.read_text())["features"]["hooks"] is True
+
+        config_file.write_text('model = "gpt-5.5"\n', encoding="utf-8")
+        _enable_codex_hooks()
+        text = config_file.read_text()
+        assert '\n\n[features]\ncodex_hooks = true\n' in text
+
     def test_setup_default_is_claude(self, tmp_path) -> None:
         """Backward compat: agentlint setup without platform defaults to claude."""
         runner = CliRunner()

{agentlint-2.3.0 → agentlint-2.3.1}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentlint"
-version = "2.3.0"
+version = "2.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },