agentlint 2.2.1__tar.gz → 2.3.1__tar.gz

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

@@ -1,5 +1,60 @@
 # 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
+keeps CI adoption safe by preserving INFO-as-non-blocking behavior while
+reducing repeated output and avoiding framework-convention false positives.
+
+### Changed
+
+- `no-unnecessary-async` is now FastAPI-aware and skips route handlers such as
+  `@router.get(...)` and `@app.post(...)` by default.
+- `agentlint ci --format text` now groups repeated findings by file, rule, and
+  severity while leaving JSON output unchanged.
+- Added per-rule `ignore_paths` as an accepted-pattern alias for documented
+  local conventions.
+- Documented `ignore_fastapi_routes`, per-rule `ignore_paths`, and `reason`
+  examples in the sample config and README.
+
+### Compatibility
+
+- INFO findings still do not fail CI by default.
+- Teams that want strict async-route checks can set
+  `rules.no-unnecessary-async.ignore_fastapi_routes: false`.
+- Existing `allow_paths` behavior is unchanged.
+
+---
+
 ## v2.2.1 (2026-05-10) — Install Experience Polish
 
 This release removes the last extra-step surprise from AgentChute setup.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlint
-Version: 2.2.1
+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.2.1 highlights:** Install experience polish with `agentlint --version` and AgentChute sync support from the default `pip install agentlint` package. Previous: 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 |
 |------|----------|-------------|
@@ -116,7 +116,7 @@ AgentLint ships with 76 rules across 8 packs and normalizes tool events across s
 | `no-unsafe-shell` | ERROR | Blocks unsafe shell execution via subprocess or os module |
 | `no-dangerous-migration` | WARNING | Warns on risky Alembic migration operations |
 | `no-wildcard-import` | WARNING | Prevents `from module import *` |
-| `no-unnecessary-async` | INFO | Flags async functions that never use `await` |
+| `no-unnecessary-async` | INFO | Flags async functions that never use `await`; skips FastAPI route handlers by default |
 | `no-sql-injection` | ERROR | Blocks SQL via string interpolation (f-strings, `.format()`) |
 
 </details>
@@ -194,6 +194,16 @@ rules:
 
 </details>
 
+Per-rule accepted patterns can be documented locally:
+
+```yaml
+rules:
+  no-unnecessary-async:
+    ignore_paths:
+      - "app/api/*_routes.py"
+    reason: "FastAPI route consistency"
+```
+
 <details>
 <summary><strong>Autopilot pack</strong> (18 rules) — ⚠️ experimental, opt-in</summary>
 

{agentlint-2.2.1 → 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.2.1 highlights:** Install experience polish with `agentlint --version` and AgentChute sync support from the default `pip install agentlint` package. Previous: 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 |
 |------|----------|-------------|
@@ -80,7 +80,7 @@ AgentLint ships with 76 rules across 8 packs and normalizes tool events across s
 | `no-unsafe-shell` | ERROR | Blocks unsafe shell execution via subprocess or os module |
 | `no-dangerous-migration` | WARNING | Warns on risky Alembic migration operations |
 | `no-wildcard-import` | WARNING | Prevents `from module import *` |
-| `no-unnecessary-async` | INFO | Flags async functions that never use `await` |
+| `no-unnecessary-async` | INFO | Flags async functions that never use `await`; skips FastAPI route handlers by default |
 | `no-sql-injection` | ERROR | Blocks SQL via string interpolation (f-strings, `.format()`) |
 
 </details>
@@ -158,6 +158,16 @@ rules:
 
 </details>
 
+Per-rule accepted patterns can be documented locally:
+
+```yaml
+rules:
+  no-unnecessary-async:
+    ignore_paths:
+      - "app/api/*_routes.py"
+    reason: "FastAPI route consistency"
+```
+
 <details>
 <summary><strong>Autopilot pack</strong> (18 rules) — ⚠️ experimental, opt-in</summary>
 

{agentlint-2.2.1 → agentlint-2.3.1}/agentlint.yml.example

@@ -51,6 +51,11 @@ rules:
   # ── PostToolUse (warnings after the action) ─────────────
   # max-file-size:
   #   limit: 500                # Warn if file exceeds this many lines
+  # no-unnecessary-async:
+  #   ignore_fastapi_routes: true  # Default: don't flag FastAPI route handlers
+  #   ignore_paths:
+  #     - "app/api/*_routes.py"
+  #   reason: "FastAPI route consistency"
   # drift-detector:
   #   threshold: 10             # Warn after this many edits without tests
 

{agentlint-2.2.1 → 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.2.1 → 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.2.1 → 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.2.1 → agentlint-2.3.1}/pyproject.toml

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

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

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

{agentlint-2.2.1 → 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.2.1 → 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.
 
@@ -488,12 +573,27 @@ def ci(diff: str | None, project_dir: str | None, output_format: str):
         if not all_violations:
             click.echo(f"Clean — {len(changed_files)} files scanned, {total_evaluated} rules evaluated.")
         else:
-            for v in all_violations:
-                sev = v.severity.value.upper()
-                loc = f"{v.file_path}" if v.file_path else "?"
-                click.echo(f"{loc}  [{v.rule_id}] {sev}  {v.message}")
-                if v.suggestion:
-                    click.echo(f"  → {v.suggestion}")
+            for group in _group_ci_violations(all_violations):
+                if len(group) == 1:
+                    v = group[0]
+                    sev = v.severity.value.upper()
+                    loc = f"{v.file_path}" if v.file_path else "?"
+                    click.echo(f"{loc}  [{v.rule_id}] {sev}  {v.message}")
+                    if v.suggestion:
+                        click.echo(f"  → {v.suggestion}")
+                    click.echo()
+                    continue
+
+                first = group[0]
+                sev = first.severity.value.upper()
+                loc = f"{first.file_path}" if first.file_path else "?"
+                click.echo(f"{loc}  [{first.rule_id}] {sev}  {len(group)} findings")
+                for v in group:
+                    line = f"line {v.line}: " if v.line is not None else ""
+                    click.echo(f"  - {line}{v.message}")
+                suggestions = sorted({v.suggestion for v in group if v.suggestion})
+                if len(suggestions) == 1:
+                    click.echo(f"  → {suggestions[0]}")
                 click.echo()
             click.echo(
                 f"{len(all_violations)} violation(s) "
@@ -504,6 +604,19 @@ def ci(diff: str | None, project_dir: str | None, output_format: str):
     sys.exit(1 if has_errors else 0)
 
 
+def _group_ci_violations(violations: list) -> list[list]:
+    """Group repeated text CI findings by file, rule, and severity."""
+    grouped: list[list] = []
+    index: dict[tuple, list] = {}
+    for violation in violations:
+        key = (violation.file_path, violation.rule_id, violation.severity.value)
+        if key not in index:
+            index[key] = []
+            grouped.append(index[key])
+        index[key].append(violation)
+    return grouped
+
+
 @main.command()
 @click.option("--project-dir", default=None, help="Project directory")
 @click.option(
@@ -557,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")
 
@@ -686,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.2.1 → agentlint-2.3.1}/src/agentlint/engine.py

@@ -59,6 +59,15 @@ class Engine:
                     if any(fnmatch(context.file_path, p) or fnmatch(basename, p) for p in rule_allow):
                         continue
 
+                # Per-rule ignore_paths — accepted-pattern alias for allow_paths.
+                # Useful when teams want to document why a rule does not apply
+                # to a local convention without disabling the rule globally.
+                rule_ignore = get_rule_setting(context.config, rule.id, "ignore_paths", [])
+                if isinstance(rule_ignore, list) and rule_ignore:
+                    basename = os.path.basename(context.file_path)
+                    if any(fnmatch(context.file_path, p) or fnmatch(basename, p) for p in rule_ignore):
+                        continue
+
             result.rules_evaluated += 1
 
             try:

{agentlint-2.2.1 → agentlint-2.3.1}/src/agentlint/packs/python/no_unnecessary_async.py

@@ -9,6 +9,7 @@ _WRITE_TOOLS = {"Write", "Edit"}
 
 _ASYNC_DEF_RE = re.compile(r"^(\s*)async\s+def\s+(\w+)\s*\(", re.MULTILINE)
 _AWAIT_RE = re.compile(r"\bawait\b")
+_FASTAPI_ROUTE_METHODS = {"get", "post", "put", "patch", "delete", "options", "head", "trace", "websocket"}
 _SKIP_DECORATORS = {"property", "override", "abstractmethod"}
 _SKIP_BODIES = {"pass", "...", "raise NotImplementedError"}
 
@@ -45,6 +46,7 @@ class NoUnnecessaryAsync(Rule):
 
         ignore_decorators = set(context.config.get("ignore_decorators", []))
         all_skip_decorators = _SKIP_DECORATORS | ignore_decorators
+        ignore_fastapi_routes = context.config.get("ignore_fastapi_routes", True)
 
         violations: list[Violation] = []
         lines = content.splitlines()
@@ -57,9 +59,11 @@ class NoUnnecessaryAsync(Rule):
             # Check decorators above
             decorator_line = func_line - 1
             skip = False
+            decorators: list[str] = []
             while decorator_line >= 0:
                 dline = lines[decorator_line].strip()
                 if dline.startswith("@"):
+                    decorators.append(dline)
                     dec_name = dline[1:].split("(")[0].split(".")[-1]
                     if dec_name in all_skip_decorators:
                         skip = True
@@ -72,6 +76,8 @@ class NoUnnecessaryAsync(Rule):
 
             if skip:
                 continue
+            if ignore_fastapi_routes and _has_fastapi_route_decorator(decorators):
+                continue
 
             # Extract body lines
             body_lines = []
@@ -104,3 +110,20 @@ class NoUnnecessaryAsync(Rule):
                 )
 
         return violations
+
+
+def _has_fastapi_route_decorator(decorators: list[str]) -> bool:
+    """Return True for common FastAPI route decorators.
+
+    Async FastAPI handlers are a framework convention even when a handler
+    currently has no direct await; dependencies, middleware, or later
+    instrumentation often remain async.
+    """
+    for decorator in decorators:
+        target = decorator[1:].split("(", 1)[0]
+        parts = target.split(".")
+        if len(parts) >= 2 and parts[-1] in _FASTAPI_ROUTE_METHODS:
+            receiver = parts[-2].lower()
+            if receiver == "app" or receiver.endswith("router"):
+                return True
+    return False

{agentlint-2.2.1 → agentlint-2.3.1}/tests/packs/test_python_pre.py

@@ -8,6 +8,7 @@ from agentlint.packs.python.no_sql_injection import NoSqlInjection
 from agentlint.packs.python.no_bare_except import NoBareExcept
 from agentlint.packs.python.no_unsafe_shell import NoUnsafeShell
 from agentlint.packs.python.no_dangerous_migration import NoDangerousMigration
+from agentlint.packs.python.no_unnecessary_async import NoUnnecessaryAsync
 from agentlint.packs.python.no_wildcard_import import NoWildcardImport
 
 
@@ -612,6 +613,48 @@ class TestNoWildcardImport:
         assert len(violations) == 0
 
 
+# ---------------------------------------------------------------------------
+# NoUnnecessaryAsync
+# ---------------------------------------------------------------------------
+
+
+class TestNoUnnecessaryAsync:
+    rule = NoUnnecessaryAsync()
+
+    def test_detects_plain_async_without_await(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/service.py",
+            "content": "async def compute():\n    return 1\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert len(violations) == 1
+        assert violations[0].severity == Severity.INFO
+
+    def test_skips_fastapi_route_by_default(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/api/routes.py",
+            "content": "@router.get('/health')\nasync def health():\n    return {'ok': True}\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert violations == []
+
+    def test_skips_fastapi_app_route_by_default(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/main.py",
+            "content": "@app.post('/items')\nasync def create_item():\n    return {'ok': True}\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert violations == []
+
+    def test_fastapi_route_can_be_checked_when_configured(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/api/routes.py",
+            "content": "@router.get('/health')\nasync def health():\n    return {'ok': True}\n",
+        }, config={"ignore_fastapi_routes": False})
+        violations = self.rule.evaluate(ctx)
+        assert len(violations) == 1
+
+
 # ---------------------------------------------------------------------------
 # Pack loader
 # ---------------------------------------------------------------------------