WS5-2

codetracer-python-recorder/README.md: 
codetracer-python-recorder/codetracer_python_recorder/cli.py: 
codetracer-python-recorder/tests/python/unit/test_auto_start.py: 
design-docs/configurable-trace-filters-implementation-plan.status.md: 
design-docs/py-api-001.md: 

Signed-off-by: Tzanko Matev <[email protected]>

Author: tzanko-matev

codetracer-python-recorder/README.md

@@ -30,7 +30,7 @@ python -m codetracer_python_recorder \
   --trace-dir ./trace-out \
   --format json \
   --activation-path app/main.py \
-  --with-diff \
+  --trace-filter config/trace-filter.toml \
   app/main.py --arg=value
 ```
 
@@ -40,9 +40,12 @@ python -m codetracer_python_recorder \
   integration with the DB backend importer.
 - `--activation-path` – optional gate that postpones tracing until the interpreter
   executes this file (defaults to the target script).
-- `--with-diff` / `--no-with-diff` – records the caller’s preference in
-  `trace_metadata.json`. The desktop Codetracer CLI is responsible for generating
-  diff artefacts; the recorder simply surfaces the flag.
+- `--trace-filter` – path to a filter file. Provide multiple times or use `//`
+  separators within a single argument to build a chain. When present, the recorder
+  prepends the project default `.codetracer/trace-filter.toml` (if found near the
+  target script) so later entries override the defaults. The
+  `CODETRACER_TRACE_FILTER` environment variable accepts the same syntax when using
+  the auto-start hook.
 
 All additional arguments are forwarded to the target script unchanged. The CLI
 reuses whichever interpreter launches it so wrappers such as `uv run`, `pipx`,

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -71,7 +71,10 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
         action="append",
         help=(
             "Path to a trace filter file. Provide multiple times to chain filters; "
-            "specify multiple paths within a single argument using '//' separators."
+            "specify multiple paths within a single argument using '//' separators. "
+            "Filters load after any project default '.codetracer/trace-filter.toml' so "
+            "later entries override earlier ones; the CODETRACER_TRACE_FILTER "
+            "environment variable accepts the same syntax for env auto-start."
         ),
     )
     parser.add_argument(

codetracer-python-recorder/tests/python/unit/test_auto_start.py

@@ -0,0 +1,66 @@
+"""Unit tests for environment-driven auto-start behaviour."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from codetracer_python_recorder import auto_start, session
+import codetracer_python_recorder.codetracer_python_recorder as backend
+
+
+@pytest.fixture(autouse=True)
+def reset_session_state() -> None:
+    """Ensure each test runs with a clean global session handle."""
+    session._active_session = None
+    yield
+    session._active_session = None
+
+
+def test_auto_start_resolves_filter_chain(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    trace_dir = tmp_path / "trace-output"
+    filter_dir = tmp_path / "filters"
+    filter_dir.mkdir()
+    default_filter = filter_dir / "default.toml"
+    default_filter.write_text("# default\n", encoding="utf-8")
+    override_filter = filter_dir / "override.toml"
+    override_filter.write_text("# override\n", encoding="utf-8")
+
+    state: dict[str, bool] = {"active": False}
+    captured_filters: list[list[str] | None] = []
+
+    def fake_start_backend(
+        path: str,
+        fmt: str,
+        activation: str | None,
+        filters: list[str] | None,
+    ) -> None:
+        state["active"] = True
+        captured_filters.append(filters)
+
+    def fake_stop_backend() -> None:
+        state["active"] = False
+
+    monkeypatch.setenv(auto_start.ENV_TRACE_PATH, str(trace_dir))
+    monkeypatch.setenv(
+        auto_start.ENV_TRACE_FILTER, f"{default_filter}//{override_filter}"
+    )
+
+    monkeypatch.setattr(session, "_start_backend", fake_start_backend)
+    monkeypatch.setattr(session, "_stop_backend", fake_stop_backend)
+    monkeypatch.setattr(session, "_flush_backend", lambda: None)
+    monkeypatch.setattr(session, "_is_tracing_backend", lambda: bool(state["active"]))
+    monkeypatch.setattr(session, "_configure_policy_from_env", lambda: None)
+    monkeypatch.setattr(backend, "configure_policy_from_env", lambda: None)
+
+    auto_start.auto_start_from_env()
+
+    assert len(captured_filters) == 1
+    assert captured_filters[0] == [
+        str(default_filter.resolve()),
+        str(override_filter.resolve()),
+    ]
+    assert session._active_session is not None
+
+    session.stop()
+    assert state["active"] is False

design-docs/configurable-trace-filters-implementation-plan.status.md

@@ -14,6 +14,7 @@
 - `codetracer-python-recorder/codetracer_python_recorder/session.py` *(WS5 python API wiring)*
 - `codetracer-python-recorder/codetracer_python_recorder/cli.py` *(WS5 CLI plumbing)*
 - `codetracer-python-recorder/codetracer_python_recorder/auto_start.py` *(WS5 env integration)*
+- `codetracer-python-recorder/tests/python/unit/test_auto_start.py` *(WS5 env regression coverage)*
 - `codetracer-python-recorder/tests/python/unit/test_session_helpers.py`
 - `codetracer-python-recorder/tests/python/unit/test_cli.py`
 - `codetracer-python-recorder/Cargo.toml`
@@ -25,7 +26,7 @@
 - ✅ **WS2 – Filter Model & Loader:** Added `trace_filter::config` with `TraceFilterConfig::from_paths`, strict schema validation, SHA256-backed `FilterSummary`, scope/value structs, and path normalisation for `file:` selectors. Dependencies `toml` and `sha2` wired via `Cargo.toml`. Unit tests cover composition, inheritance guards, unknown keys, IO validation, and literal path normalisation; exercised using `just cargo-test`.
 - ✅ **WS3 – Runtime Engine & Caching:** Implemented `trace_filter::engine` with `TraceFilterEngine::resolve` caching `ScopeResolution` entries per code id (DashMap), deriving module/object/file metadata, and compiling value policies with ordered pattern evaluation. Added `ValueKind` to align future runtime integration and unit tests proving caching, rule precedence (object > package/file), and relative path normalisation—all exercised via `just cargo-test`.
 - ✅ **WS4 – RuntimeTracer Integration:** `RuntimeTracer` now accepts an optional `Arc<TraceFilterEngine>`, caches `ScopeResolution` results per code id, and records `filter_scope_skip` when scopes are denied. Value capture helpers honour `ValuePolicy` with a reusable `<redacted>` sentinel, emit per-kind telemetry, and we persist the active filter summary plus skip/redaction counts into `trace_metadata.json`. Bootstrapping now discovers `.codetracer/trace-filter.toml`, instantiates `TraceFilterEngine`, and passes the shared `Arc` into `RuntimeTracer::new`; new `session::bootstrap` tests cover both presence/absence of the default filter and `just cargo-test` (nextest `--no-default-features`) confirms the flow end-to-end.
-- 🚧 **WS5 – Python Surface, CLI, Metadata:** In progress. Session helpers normalise chained specs, auto-start honours `CODETRACER_TRACE_FILTER`, PyO3 merges explicit/default chains, and the CLI now exposes `--trace-filter` with test coverage; documentation + env tests remain.
+- ✅ **WS5 – Python Surface, CLI, Metadata:** Session helpers normalise chained specs, auto-start honours `CODETRACER_TRACE_FILTER`, PyO3 merges explicit/default chains, CLI exposes `--trace-filter`, unit coverage exercises env auto-start filter chaining, and docs/CLI help now describe filter precedence and env wiring.
 - ⏳ **WS6 – Hardening, Benchmarks & Documentation:** Pending prior stages.
 
 ## WS5 Progress Checklist
@@ -34,6 +35,6 @@
 3. ✅ Updated CLI/env plumbing (`--trace-filter`, `CODETRACER_TRACE_FILTER`) plus unit/integration coverage exercising CLI parsing and end-to-end filter metadata.
 
 ## Next Steps
-1. Add explicit tests for `CODETRACER_TRACE_FILTER` auto-start behaviour so env-driven sessions verify filter chaining.
-2. Draft docs/CLI help updates covering the new flag, env var, and filter discovery precedence ahead of WS5 sign-off.
+1. ✅ Added explicit tests for `CODETRACER_TRACE_FILTER` auto-start behaviour so env-driven sessions verify filter chaining (`codetracer_python_recorder/tests/python/unit/test_auto_start.py`).
+2. ✅ Drafted docs/CLI help updates covering the new flag, env var, and filter discovery precedence ahead of WS5 sign-off.
 3. Plan integration of `TraceFilterConfig::io` toggles with runtime IO capture enablement before moving into WS6.

design-docs/py-api-001.md

@@ -61,6 +61,10 @@ class TraceSession:
 ## Environment Integration
 - Auto-start tracing when `CODETRACER_TRACE` is set; the value is interpreted as the output directory.
 - When `CODETRACER_FORMAT` is provided, it overrides the default output format.
+- Accept `CODETRACER_TRACE_FILTER` with either `//`-separated paths or multiple
+  entries (mirroring the CLI). The env-driven chain is appended after any
+  discovered project default `.codetracer/trace-filter.toml`, allowing overrides
+  to refine or replace default rules.
 
 ## Usage Example
 ```py