chore(dev): add standalone pre-commit check script

Merge #6084

## Summary

Adds `scripts/run_precommit_checks.py` to run the `.pre-commit-config.yaml` checks **without** the `pre-commit` framework, which requires a git repository and so cannot run in environments such as a piper checkout that has no `.git`.

- Parses `.pre-commit-config.yaml` so the file lists, global/per-hook `exclude` and `files` patterns, and `args` all come from the config — only the hook-id → CLI command mapping (and each hook's implicit file-type/text filter) is maintained in the script.
- Defaults to fixing in place; pass `--check` to verify only (CI behavior).
- Limits the walk to `src`/`tests`/`contributing`/`pyproject.toml` and never follows symlinks, so `.venv`, build artifacts, and out-of-repo code (e.g. a symlinked `a2a`) are never touched.
- Skips binary files for text fixers, and batches arguments to stay under the OS arg limit.
- `scripts/run_precommit.sh` is a thin wrapper that prefers an already-synced interpreter (`.venv` / active venv) before falling back to `uv run`.
- Adds the standalone lint tools to the `dev` extra (capped at the next major) so `uv sync --extra dev` provides everything the script needs.

## Test plan

- [ ] `scripts/run_precommit.sh --check` passes on a clean tree
- [ ] `scripts/run_precommit.sh` (default fix mode) does not modify binaries (images/PDFs) or `.venv`
- [ ] Runs from any directory; PATH args are repo-root-relative
- [ ] `addlicense` / `check-new-py-prefix` degrade gracefully when unavailable / git-only

Co-authored-by: Wei Sun (Jack) <weisun@google.com>
COPYBARA_INTEGRATE_REVIEW=#6084 from google:chore/dev-precommit-script fa38633
PiperOrigin-RevId: 930799785

Author: Jacksunwei

.agents/skills/adk-unit-guide/SKILL.md

@@ -8,7 +8,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.5.0
+    rev: v2.24.0
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/PyCQA/isort

.pre-commit-config.yaml

@@ -1,14 +1,12 @@
 [build-system]
 build-backend = "flit_core.buildapi"
-
 # Build system specify which backend is used to build/install the project (flit,
 # poetry, setuptools,...). All backends are supported by `pip install`
 requires = [ "flit-core>=3.8,<4" ]
 
 [project]
 # Project metadata. Available keys are documented at:
 # https://packaging.python.org/en/latest/specifications/declaring-project-metadata
-
 name = "google-adk"
 description = "Agent Development Kit"
 readme = "README.md"
@@ -26,12 +24,12 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Libraries :: Python Modules",
   # List of https://pypi.org/classifiers/
   "Typing :: Typed",
 ]
 dynamic = [ "version" ]
-
 dependencies = [
   "aiosqlite>=0.21",
   "authlib>=1.6.6,<2",
@@ -58,7 +56,6 @@ dependencies = [
   "watchdog>=6,<7",
   "websockets>=15.0.1,<16",
 ]
-
 optional-dependencies.a2a = [
   "a2a-sdk>=0.3.4,<0.4",
 ]
@@ -94,31 +91,35 @@ optional-dependencies.all = [
   "sqlalchemy>=2,<3",
   "sqlalchemy-spanner>=1.14",
 ]
-
 optional-dependencies.antigravity = [
   "google-antigravity>=0.1,<0.2",
   "protobuf>=6",
 ]
-
 optional-dependencies.community = [
   "google-adk-community",
 ]
-
 optional-dependencies.db = [
   "sqlalchemy>=2,<3",
   "sqlalchemy-spanner>=1.14",
 ]
-
 optional-dependencies.dev = [
   "flit>=3.10",
+  # Lint tools used by scripts/run_precommit_checks.sh (which runs them directly,
+  # without the pre-commit framework). Formatters that rewrite files are pinned
+  # to the exact versions in .pre-commit-config.yaml so local runs produce
+  # byte-identical output to CI.
+  "isort==8.0.1",
+  "mdformat==0.7.22",
+  "mdformat-gfm",
   "mypy>=1.15",
   "pre-commit>=4",
-  "pyink>=25.12",
+  "pre-commit-hooks==4.6",
+  "pyink==25.12",
   "pylint>=2.6",
+  "pyproject-fmt==2.24",
   "tox>=4.23.2",
   "tox-uv>=1.33.2",
 ]
-
 optional-dependencies.docs = [
   "autodoc-pydantic",
   "furo",
@@ -128,7 +129,6 @@ optional-dependencies.docs = [
   "sphinx-click",
   "sphinx-rtd-theme",
 ]
-
 optional-dependencies.e2b = [
   "e2b>=2,<3", # For E2BEnvironment remote sandbox.
 ]
@@ -140,7 +140,6 @@ optional-dependencies.eval = [
   "rouge-score>=0.1.2",
   "tabulate>=0.9",
 ]
-
 optional-dependencies.extensions = [
   "anthropic>=0.78",                                                 # For anthropic model support; 0.78 introduced ThinkingConfigAdaptiveParam (required for Claude Opus 4.7).
   "beautifulsoup4>=3.2.2",                                           # For load_web_page tool.
@@ -157,7 +156,6 @@ optional-dependencies.extensions = [
   "pypika>=0.50",
   "toolbox-adk>=1,<2",
 ]
-
 optional-dependencies.gcp = [
   "google-cloud-aiplatform[agent-engines]>=1.148.1,<2",
   "google-cloud-bigquery>=2.2",
@@ -180,12 +178,10 @@ optional-dependencies.gcp = [
   "pyarrow>=14",
   "python-dateutil>=2.9.0.post0,<3",
 ]
-
 optional-dependencies.mcp = [
   "anyio>=4.9,<5",
   "mcp>=1.24,<2",
 ]
-
 optional-dependencies.otel-gcp = [
   "opentelemetry-instrumentation-google-genai>=0.6b0,<1",
   "opentelemetry-instrumentation-grpc>=0.43b0,<1",
@@ -248,45 +244,40 @@ optional-dependencies.test = [
   "tabulate>=0.9",
   "tomli>=2,<3; python_version<'3.11'",
 ]
-
 optional-dependencies.toolbox = [ "toolbox-adk>=1,<2" ]
-
 optional-dependencies.tools = [
   "google-api-python-client>=2.157,<3",
 ]
-
 urls.changelog = "https://github.com/google/adk-python/blob/main/CHANGELOG.md"
 urls.documentation = "https://google.github.io/adk-docs/"
 urls.homepage = "https://google.github.io/adk-docs/"
 urls.repository = "https://github.com/google/adk-python"
 scripts.adk = "google.adk.cli:main"
 
-[tool.flit.sdist]
-include = [ 'src/**/*', 'README.md', 'pyproject.toml', 'LICENSE' ]
-exclude = [ 'src/**/*.sh', 'src/**/README.md' ]
-
-[tool.flit.module]
-name = "google.adk"
-include = [ "py.typed" ]
+[tool.flit]
+module.name = "google.adk"
+module.include = [ "py.typed" ]
+sdist.include = [ "src/**/*", "README.md", "pyproject.toml", "LICENSE" ]
+sdist.exclude = [ "src/**/*.sh", "src/**/README.md" ]
 
 [tool.isort]
 profile = "google"
-single_line_exclusions = [  ]
 line_length = 200
-known_third_party = [ "google.adk", "a2a" ]
-
-[tool.pytest.ini_options]
-testpaths = [ "tests" ]
-asyncio_default_fixture_loop_scope = "function"
-asyncio_mode = "auto"
+single_line_exclusions = []
+known_third_party = [ "a2a", "google.adk" ]
 
 [tool.mypy]
+exclude = [ "contributing/samples/", "tests/" ]
+follow_imports = "skip"
 python_version = "3.11"
-exclude = [ "tests/", "contributing/samples/" ]
-plugins = [ "pydantic.mypy" ]
-strict = true
 disable_error_code = [ "import-not-found", "import-untyped", "unused-ignore" ]
-follow_imports = "skip"
+strict = true
+plugins = [ "pydantic.mypy" ]
+
+[tool.pytest]
+ini_options.testpaths = [ "tests" ]
+ini_options.asyncio_default_fixture_loop_scope = "function"
+ini_options.asyncio_mode = "auto"
 
 [tool.pyink]
 line-length = 80

pyproject.toml

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Convenience wrapper for scripts/run_precommit_checks.py.
+#
+#   scripts/run_precommit.sh            # auto-fix everything (default)
+#   scripts/run_precommit.sh --check    # verify only, no changes (like CI)
+#   scripts/run_precommit.sh src tests  # auto-fix specific paths
+#
+# Picks an interpreter that already has the dev tools installed, in order:
+#   1. the repo's .venv (created by `uv sync --extra dev`)
+#   2. an active virtualenv ($VIRTUAL_ENV)
+#   3. `uv run --extra dev` (resolves/syncs on the fly; slower)
+#   4. plain python3
+# This avoids re-running `uv run` (which re-resolves the environment) when a
+# synced interpreter is already available.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+checker="${repo_root}/scripts/run_precommit_checks.py"
+
+if [[ -x "${repo_root}/.venv/bin/python" ]]; then
+  exec "${repo_root}/.venv/bin/python" "${checker}" "$@"
+elif [[ -n "${VIRTUAL_ENV:-}" && -x "${VIRTUAL_ENV}/bin/python" ]]; then
+  exec "${VIRTUAL_ENV}/bin/python" "${checker}" "$@"
+elif command -v uv >/dev/null 2>&1; then
+  exec uv run --extra dev python "${checker}" "$@"
+else
+  exec python3 "${checker}" "$@"
+fi