cext-review-toolkit

Comprehensive C extension analysis using specialized agents. Use when the user asks to analyze, audit, or review a C extension, find bugs in C extension code, run all checks on an extension, or do a full extension review. Covers refcount safety, error handling, NULL safety, GIL discipline, module state, type slots, ABI compliance, version compatibility, PyErr_Clear auditing, resource lifecycle, and C/Python parity.

Quick health dashboard scoring a C extension across all dimensions. Use when the user asks for a quick overview, health check, status, score, or summary of a C extension's quality.

Find the worst functions to fix first by combining refcount issues, error handling bugs, and complexity scoring. Use when the user asks where to focus review effort, which functions are most dangerous, what to fix first, or wants a prioritized list of hotspots in a C extension.

Extension modernization assessment covering multi-phase init migration, stable ABI adoption, version compatibility, and free-threading readiness. Use when the user asks to modernize an extension, prepare for subinterpreters, migrate to stable ABI, clean up deprecated APIs, or assess migration effort for a C extension.

Use this agent to measure and analyze C code complexity in extension modules, identifying hotspots and suggesting simplifications. <example> User: What are the most complex functions in this extension? Agent: I will run the complexity measurement script, identify hotspots with score >= 5.0, assess inherent vs reducible complexity, correlate with safety findings, and suggest concrete simplifications. </example>

Use this agent to audit error handling correctness in C extension code that calls the Python/C API. <example> User: Check the error handling in my C extension. Agent: I will run the error path scanner, prioritize missing NULL checks and return-without-exception findings, and review extension-specific error patterns like PyErr_Clear misuse and exception clobbering. </example>

Use this agent to audit GIL (Global Interpreter Lock) management in C extension code, including foreign C library interaction and free-threaded Python readiness. <example> User: Check GIL handling in my C extension that wraps a foreign library. Agent: I will run the GIL usage scanner, verify matched Py_BEGIN/END_ALLOW_THREADS pairs, check for Python API calls without the GIL, audit foreign library callback patterns, and assess free-threaded Python readiness. </example>

Use this agent for temporal analysis of a C extension codebase -- finding similar bugs via git history and prioritizing review by churn patterns. <example> User: We just fixed a NULL check bug -- did we miss any similar bugs elsewhere? Agent: I will run the history analyzer, examine recent fix commits for bug patterns, search the entire codebase for structurally similar code, and produce a churn-risk matrix. </example>

Use this agent to audit module initialization and state management in C extension code, including single-phase vs multi-phase init and global state migration. <example> User: Review the module state management in my C extension. Agent: I will run the module state scanner, assess the init style, catalog global PyObject state, check for missing traverse/clear slots, and produce a migration assessment with difficulty rating. </example>

Use this agent to audit NULL pointer safety in C extension code. <example> User: Check for NULL pointer dereference risks in my C extension. Agent: I will run the NULL safety scanner, verify each unchecked allocation and dereference-before-check finding, and review extension-specific NULL patterns like PyDict_GetItem returning NULL for missing keys. </example>

Use this agent to find behavioral differences between C and Python implementations of the same functionality in extensions that ship dual implementations. <example> User: Check if the C and Python parsers in my extension behave the same. Agent: I will identify dual C/Python implementations, compare validation logic, error handling, and edge case behavior to find security-relevant parity gaps. </example>

Use this agent to audit PyErr_Clear() usage in C extension code, finding calls that silently swallow exceptions like MemoryError and KeyboardInterrupt. <example> User: Check for dangerous PyErr_Clear usage in my extension. Agent: I will run the PyErr_Clear scanner, triage each unguarded clear call, and assess whether exceptions are being silently swallowed. </example>

Use this agent to audit reference counting correctness in C extension code that calls the Python/C API. <example> User: Review the reference counting in my C extension module. Agent: I will run the refcount scanner, triage each finding, and perform deep analysis of potential leaks, borrowed-ref-across-call hazards, and stolen-ref misuse. </example>

Use this agent to audit non-PyObject resource lifecycle in C extension code -- malloc/free pairing, HDF5 handle leaks, buffer protocol, and file descriptor management. <example> User: Check for resource leaks in my C extension. Agent: I will run the resource lifecycle scanner, triage each finding for true leaks on error paths, and verify that all allocated resources (memory, file handles, HDF5 objects, buffers) are freed on all exit paths. </example>

Use this agent to audit Python stable ABI and limited API compliance in C extension code. <example> User: Check if my C extension is compatible with the stable ABI. Agent: I will determine whether the extension claims limited API compliance, verify that claim against the stable ABI surface, check for private API usage and direct struct access, and assess migration feasibility if not currently using the limited API. </example>

Use this agent to audit Python type definitions (PyTypeObject, PyType_Spec) in C extension code for correctness of slots, dealloc, traverse, and GC integration. <example> User: Check the type definitions in my C extension. Agent: I will run the type slot scanner, verify dealloc/traverse/GC flag consistency, check richcompare and type spec correctness, and review heap type lifecycle management. </example>

Use this agent to audit Python version compatibility in C extension code, including deprecated API usage, version-guarded code, and pythoncapi-compat opportunities. <example> User: Check Python version compatibility in my C extension. Agent: I will determine the target Python versions, check for unguarded version-specific API usage, identify dead compatibility code, flag deprecated APIs, and recommend pythoncapi-compat adoption where appropriate. </example>