prefect 3.9.2.dev4__py3-none-any.whl → 3.9.2.dev5__py3-none-any.whl

prefect/AGENTS.md

@@ -41,6 +41,7 @@ Runtime flow/task parameter values must come from `utilities.callables.get_call_
 - **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
 - **`ResultRecord` must be marked persisted after every storage write.** `ResultStore` calls `mark_persisted()` on every record it writes; `to_state_create` in `states.py` consults `is_persisted` as a fallback when `should_persist_result()` returns `False` (e.g., after run context teardown). Any new sync or async persist path that omits `mark_persisted()` will silently drop state metadata for already-written results.
 - **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
+- **Flow state hooks accept the same signatures on every execution path.** The sync and async flow engines and `runner/_hook_runner.py` share `_internal/engine.py::resolve_flow_hook_arguments`; `runner/_workspace_runtime_bootstrap.py` keeps its own copy because it may run under an older Prefect. Change the shared function and the copy together.
 - **Subflow tracking tasks use UUID dynamic keys when called from within a submitted task.** `flow_engine.py` marks the synthetic tracking `Task` with `_is_subflow_tracking_task=True`; `tasks.py` checks this flag to assign UUID-based (unstable) `dynamic_key` values when the tracking task runs inside a submitted task context. This prevents key collisions between concurrent sibling subflows on parent-flow retry. Direct subflow calls (no enclosing task context) keep stable sequential keys to preserve the retry optimization that reuses completed subflow results.
 
 ## Logging

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.9.2.dev4"
-__build_date__ = "2026-11-04 08:14:01.644568+00:00"
-__git_commit__ = "60d9ea54535ee10be2e7481fd1d930815c87b649"
+__version__ = "3.9.2.dev5"
+__build_date__ = "2026-11-05 08:14:46.658497+00:00"
+__git_commit__ = "7d8cf20e30b8d22e4fdc99bef3a99050ad0d7cf8"
 __dirty__ = False

prefect/_internal/engine.py

@@ -1,5 +1,6 @@
 """Internal engine utilities"""
 
+import inspect
 from collections.abc import Callable
 from functools import partial
 from typing import TYPE_CHECKING, Any, Union
@@ -9,6 +10,9 @@ from prefect.context import FlowRunContext
 from prefect.flows import Flow
 from prefect.tasks import Task, TaskRunNameCallbackWithParameters
 
+if TYPE_CHECKING:
+    from prefect.client.schemas.objects import FlowRun, State
+
 
 def dynamic_key_for_task_run(
     context: FlowRunContext, task: "Task[..., Any]", stable: bool = True
@@ -93,3 +97,58 @@ def get_hook_name(hook: Callable[..., Any]) -> str:
             hook.func.__name__ if isinstance(hook, partial) else hook.__class__.__name__
         )
     )
+
+
+def resolve_flow_hook_arguments(
+    hook: Callable[..., Any],
+    flow: "Flow[..., Any]",
+    flow_run: "FlowRun",
+    state: "State",
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    """
+    Return the positional and keyword arguments to call a flow state hook with,
+    checking its signature without calling it.
+
+    A hook that names its parameters `flow`, `flow_run` (or `run`) and `state`
+    gets them by name, in any order and including keyword-only parameters.
+    Otherwise, a hook that takes three positional arguments gets them in that
+    order, whatever their names, and a hook that only takes keyword arguments
+    gets them by name.
+
+    Raises:
+        TypeError: if the hook accepts none of these forms.
+    """
+    try:
+        signature = inspect.signature(hook)
+    except (TypeError, ValueError):
+        return (flow, flow_run, state), {}
+
+    def binds(*args: Any, **kwargs: Any) -> bool:
+        try:
+            signature.bind(*args, **kwargs)
+        except TypeError:
+            return False
+        return True
+
+    named = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    for flow_run_name in ("flow_run", "run"):
+        kwargs = {"flow": flow, flow_run_name: flow_run, "state": state}
+        declared = all(
+            name in signature.parameters and signature.parameters[name].kind in named
+            for name in kwargs
+        )
+        if declared and binds(**kwargs):
+            return (), kwargs
+
+    if binds(flow, flow_run, state):
+        return (flow, flow_run, state), {}
+
+    kwargs = {"flow": flow, "flow_run": flow_run, "state": state}
+    if binds(**kwargs):
+        return (), kwargs
+
+    raise TypeError(
+        f"Hook {get_hook_name(hook)!r} must accept the flow, the flow run and the"
+        " state as three positional arguments or as parameters named `flow`,"
+        " `flow_run` (or `run`) and `state`"
+    )

prefect/cli/AGENTS.md

@@ -4,7 +4,7 @@ Prefect command-line interface, powered by **cyclopts**.
 
 ## Key Contracts
 
-- **Use `rich` for all output.** Console output via `rich.console`, tables via `rich.table`, progress bars via `rich.progress`. Always use `exit_with_error` for error exits.
+- **Use `rich` for all output.** Console output via `rich.console`, tables via `rich.table`, progress bars via `rich.progress`. Always use `exit_with_error` for error exits. Unlike `console.print` and `exit_with_success`, it disables Rich markup by default because messages often carry user input, server errors, or `str(exc)` from non-CLI modules (deploy, provisioners) — keep markup out of exception messages; pass `markup=True` only for trusted styling and `rich.markup.escape` interpolated values.
 - **Support JSON output whenever possible.** Commands should have a `--json` flag or equivalent for machine-readable output. Any diagnostic or informational `print()` calls must be suppressed when JSON output is active — mixing human-readable text with the JSON payload breaks machine consumers.
 - **Print JSON, YAML, and other verbatim user data with `print_verbatim` from `_utilities.py`.** `console.print` otherwise parses `[...]` as Rich markup and `:name:` as emoji aliases, silently rewriting payloads (or raising `MarkupError` on stray closing tags). `print_verbatim` disables both and soft-wraps; `tests/cli/test_utilities.py` fails if serialized output goes through `console.print` directly. `print_json` and `Pretty` are not affected.
 - **Page through "all records" reads.** Client `read_*` list calls without `limit` return at most `PREFECT_SERVER_API_DEFAULT_LIMIT` (200) rows (server `LimitBody`) — or fewer when the client method has its own default `limit` (e.g. `read_global_concurrency_limits` defaults to 10) — so `--all`/bulk commands must loop on `offset`. When deleting while paging, re-read from offset 0 each pass — advancing `offset` skips rows that shifted into earlier pages.

prefect/cli/_utilities.py

@@ -15,8 +15,15 @@ import prefect.cli._app as _cli
 
 
 def exit_with_error(message: str | Exception, code: int = 1, **kwargs: Any) -> NoReturn:
-    """Print a stylized error message and exit with a non-zero code."""
+    """
+    Print a stylized error message and exit with a non-zero code.
+
+    Rich markup is disabled by default because messages often include user
+    input or server error text; pass `markup=True` for messages with trusted
+    markup and escape any interpolated values.
+    """
     kwargs.setdefault("style", "red")
+    kwargs.setdefault("markup", False)
     _cli.console.print(message, **kwargs)
     raise SystemExit(code)
 

prefect/cli/block.py

@@ -78,7 +78,7 @@ def _display_block_type(block_type: BlockType) -> Table:
         "Description",
         (
             block_type.description.splitlines()[0].partition(".")[0]
-            if block_type.description is not None
+            if block_type.description
             else ""
         ),
         end_section=True,
@@ -520,7 +520,7 @@ async def list_types(
                 str(blocktype.slug),
                 (
                     str(blocktype.description.splitlines()[0].partition(".")[0])
-                    if blocktype.description is not None
+                    if blocktype.description
                     else ""
                 ),
                 f"prefect block create {blocktype.slug}",

prefect/cli/config.py

@@ -11,6 +11,7 @@ from typing import Annotated, Any, Literal, Union, cast
 import cyclopts
 import orjson
 from dotenv import dotenv_values
+from rich.markup import escape
 
 import prefect.cli._app as _cli
 import prefect.context
@@ -71,9 +72,9 @@ def set_(
             for error in problem.errors():
                 help_message += (
                     f"[bold red]Validation error(s) for setting[/bold red] "
-                    f"[blue]{setting.name}[/blue]\n\n - {error['msg']}\n\n"
+                    f"[blue]{escape(setting.name)}[/blue]\n\n - {escape(error['msg'])}\n\n"
                 )
-        exit_with_error(help_message)
+        exit_with_error(help_message, markup=True)
 
     for setting, value in parsed_settings.items():
         _cli.console.print(f"Set {setting!r} to {value!r}.")

prefect/cli/deploy/_actions.py

@@ -234,7 +234,8 @@ async def _generate_default_pull_action(
                 exit_with_error(
                     "Your flow code must be copied into your Docker image to run"
                     " your deployment.\nTo do so, you can copy this line into your"
-                    " Dockerfile: [yellow]COPY . /opt/prefect/[/yellow]"
+                    " Dockerfile: [yellow]COPY . /opt/prefect/[/yellow]",
+                    markup=True,
                 )
             return await _generate_pull_step_for_build_docker_image(
                 console, deploy_config, auto=False

prefect/cli/deploy/_commands.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import Annotated, Any
 
 import cyclopts
+from rich.markup import escape
 from rich.prompt import Prompt
 from rich.table import Table
 
@@ -134,8 +135,9 @@ async def init(
     except ValueError as exc:
         if "Unknown recipe" in str(exc):
             exit_with_error(
-                f"Unknown recipe {recipe!r} provided - run"
-                " [yellow]`prefect init`[/yellow] to see all available recipes."
+                f"Unknown recipe {escape(repr(recipe))} provided - run"
+                " [yellow]`prefect init`[/yellow] to see all available recipes.",
+                markup=True,
             )
         else:
             raise

prefect/cli/deploy/_core.py

@@ -108,7 +108,7 @@ async def _run_single_deploy(
         if not is_interactive():
             raise ValueError(
                 "An entrypoint must be provided:\n\n"
-                " \t[yellow]prefect deploy path/to/file.py:flow_function\n\n"
+                " \tprefect deploy path/to/file.py:flow_function\n\n"
                 "You can also provide an entrypoint in a prefect.yaml file."
             )
         deploy_config["entrypoint"] = await prompt_entrypoint(console)

prefect/cli/deployment.py

@@ -105,7 +105,7 @@ deployment_app.command(schedule_app)
 
 
 def _assert_deployment_name_format(name: str) -> None:
-    if "/" not in name:
+    if name.count("/") != 1:
         exit_with_error(
             "Invalid deployment name. Expected '<flow-name>/<deployment-name>'"
         )
@@ -124,6 +124,7 @@ async def _get_deployment(
         except ObjectNotFound:
             exit_with_error(f"Deployment {deployment_id!r} not found!")
     elif name is not None and deployment_id is None:
+        _assert_deployment_name_format(name)
         try:
             deployment = await client.read_deployment_by_name(name)
         except ObjectNotFound:
@@ -684,6 +685,7 @@ async def delete(
             except ObjectNotFound:
                 exit_with_error(f"Deployment '{deployment_id}' not found!")
         elif name is not None:
+            _assert_deployment_name_format(name)
             try:
                 deployment = await client.read_deployment_by_name(name)
                 if _cli.is_interactive() and not confirm(

prefect/client/schemas/objects.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import datetime
+import json
 import warnings
 from collections.abc import Callable, Mapping
 from enum import Enum
@@ -17,7 +18,6 @@ from typing import (
 )
 from uuid import UUID
 
-import orjson
 from pydantic import (
     AfterValidator,
     ConfigDict,
@@ -1768,7 +1768,7 @@ class FlowRunInput(ObjectBaseModel):
         Returns:
             Any: the decoded value
         """
-        return orjson.loads(self.value)
+        return json.loads(self.value)
 
 
 class GlobalConcurrencyLimit(ObjectBaseModel):

prefect/flow_engine.py

@@ -59,7 +59,11 @@ from prefect._internal.control_listener import (
     get_intent,
     report_engine_outcome,
 )
-from prefect._internal.engine import get_hook_name, resolve_custom_flow_run_name
+from prefect._internal.engine import (
+    get_hook_name,
+    resolve_custom_flow_run_name,
+    resolve_flow_hook_arguments,
+)
 from prefect._internal.metrics import RunMetrics
 from prefect.client.orchestration import PrefectClient, SyncPrefectClient, get_client
 from prefect.client.schemas import FlowRun, TaskRun
@@ -1072,7 +1076,8 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                     f"Running hook {hook_name!r} in response to entering state"
                     f" {state.name!r}"
                 )
-                result = hook(flow, flow_run, state)
+                args, kwargs = resolve_flow_hook_arguments(hook, flow, flow_run, state)
+                result = hook(*args, **kwargs)
                 if asyncio.iscoroutine(result):
                     run_coro_as_sync(result)
             except Exception:
@@ -1803,7 +1808,8 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                     f"Running hook {hook_name!r} in response to entering state"
                     f" {state.name!r}"
                 )
-                result = hook(flow, flow_run, state)
+                args, kwargs = resolve_flow_hook_arguments(hook, flow, flow_run, state)
+                result = hook(*args, **kwargs)
                 if asyncio.iscoroutine(result):
                     await result
             except Exception:

prefect/flows.py

@@ -121,15 +121,22 @@ F = TypeVar("F", bound="Flow[Any, Any]")  # The type of the flow
 class FlowStateHook(Protocol, Generic[P, R]):
     """
     A callable that is invoked when a flow enters a given state.
+
+    It receives the flow, the flow run, and the state as its first three
+    parameters, whatever their names. A hook whose parameters are named `flow`,
+    `flow_run` (or `run`), and `state` receives them by name instead.
     """
 
     __name__: str
 
     def __call__(
-        self, flow: Flow[P, R], flow_run: FlowRun, state: State
+        self, flow: Flow[P, R], flow_run: FlowRun, state: State, /
     ) -> Awaitable[None] | None: ...
 
 
+_FlowStateHookT = TypeVar("_FlowStateHookT", bound="FlowStateHook[..., Any]")
+
+
 if TYPE_CHECKING:
     import logging
 
@@ -593,6 +600,11 @@ class Flow(Generic[P, R]):
         Validate parameters for compatibility with the flow by attempting to cast the inputs to the
         associated types specified by the function's type annotations.
 
+        Resolve saved block references by UUID or by a dictionary containing
+        `block_document_id` or `block_document_slug`. UUID strings, including UUID
+        URNs, retain their block-reference meaning. Other `$ref` values, such as
+        JSON Schema paths and URLs, are preserved as parameter data.
+
         Returns:
             A new dict of parameters that have been cast to the appropriate types
 
@@ -601,11 +613,24 @@ class Flow(Generic[P, R]):
         """
 
         def resolve_block_reference(data: Any | dict[str, Any]) -> Any:
-            if isinstance(data, dict) and "$ref" in data:
-                from prefect.blocks.core import Block
+            if not isinstance(data, dict) or "$ref" not in data:
+                return data
+
+            ref = data["$ref"]
+            if isinstance(ref, str):
+                try:
+                    UUID(ref)
+                except ValueError:
+                    return data
+            elif not isinstance(ref, UUID) and not (
+                isinstance(ref, dict)
+                and ("block_document_id" in ref or "block_document_slug" in ref)
+            ):
+                return data
+
+            from prefect.blocks.core import Block
 
-                return Block.load_from_ref(data["$ref"], _sync=True)
-            return data
+            return Block.load_from_ref(ref, _sync=True)
 
         try:
             parameters = visit_collection(
@@ -1004,23 +1029,23 @@ class Flow(Generic[P, R]):
                 _sla=_sla,
             )
 
-    def on_completion(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]:
+    def on_completion(self, fn: _FlowStateHookT) -> _FlowStateHookT:
         self.on_completion_hooks.append(fn)
         return fn
 
-    def on_cancellation(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]:
+    def on_cancellation(self, fn: _FlowStateHookT) -> _FlowStateHookT:
         self.on_cancellation_hooks.append(fn)
         return fn
 
-    def on_crashed(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]:
+    def on_crashed(self, fn: _FlowStateHookT) -> _FlowStateHookT:
         self.on_crashed_hooks.append(fn)
         return fn
 
-    def on_running(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]:
+    def on_running(self, fn: _FlowStateHookT) -> _FlowStateHookT:
         self.on_running_hooks.append(fn)
         return fn
 
-    def on_failure(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]:
+    def on_failure(self, fn: _FlowStateHookT) -> _FlowStateHookT:
         self.on_failure_hooks.append(fn)
         return fn
 

prefect/infrastructure/provisioners/coiled.py

@@ -215,7 +215,7 @@ class CoiledPushProvisioner:
                 else:
                     raise RuntimeError(
                         "Coiled credentials not found. Please create a new token by"
-                        " running [blue]coiled login[/] and try again."
+                        " running `coiled login` and try again."
                     )
 
             # Create the credentials block

prefect/infrastructure/provisioners/modal.py

@@ -220,7 +220,7 @@ class ModalPushProvisioner:
                 else:
                     raise RuntimeError(
                         "Modal credentials not found. Please create a new token by"
-                        " running [blue]modal token new[/] and try again."
+                        " running `modal token new` and try again."
                     )
 
             # Create the credentials block

prefect/input/actions.py

@@ -1,3 +1,4 @@
+import json
 from typing import TYPE_CHECKING, Any, Optional, Set
 from uuid import UUID
 
@@ -236,7 +237,7 @@ async def aread_flow_run_input(
             return None
         raise
     else:
-        return orjson.loads(value)
+        return json.loads(value)
 
 
 @async_dispatch(aread_flow_run_input)
@@ -261,7 +262,7 @@ def read_flow_run_input(key: str, flow_run_id: Optional[UUID] = None) -> Any:
                 return None
             raise
         else:
-            return orjson.loads(value)
+            return json.loads(value)
 
 
 @client_injector

prefect/locking/filesystem.py

@@ -194,13 +194,18 @@ class FileSystemLockManager(LockManager):
 
     def release_lock(self, key: str, holder: str) -> None:
         lock_path = self._lock_path_for_key(key)
-        if not self.is_locked(key):
-            raise ValueError(f"No lock for transaction with key {key}")
         if self.is_lock_holder(key, holder):
             Path(lock_path).unlink(missing_ok=True)
             self._locks.pop(key, None)
-        else:
-            raise ValueError(f"No lock held by {holder} for transaction with key {key}")
+            return
+        if not self.is_locked(key):
+            # The lock was already released or expired (e.g. its hold timeout
+            # elapsed or it was released during a task retry) — including
+            # between the checks above — so releasing it is a no-op, matching
+            # RedisLockManager.
+            self._locks.pop(key, None)
+            return
+        raise ValueError(f"No lock held by {holder} for transaction with key {key}")
 
     def is_locked(self, key: str, use_cache: bool = False) -> bool:
         if (lock_info := self._get_lock_info(key, use_cache=use_cache)) is None:

prefect/locking/memory.py

@@ -180,13 +180,18 @@ class MemoryLockManager(LockManager):
 
     def release_lock(self, key: str, holder: str) -> None:
         with self._locks_dict_lock:
-            if key in self._locks and self._locks[key]["holder"] == holder:
-                if (
-                    expiration_timer := self._locks[key]["expiration_timer"]
-                ) is not None:
+            lock_info = self._locks.get(key)
+            if lock_info is not None and lock_info["holder"] == holder:
+                if (expiration_timer := lock_info["expiration_timer"]) is not None:
                     expiration_timer.cancel()
-                self._locks[key]["lock"].release()
+                if lock_info["lock"].locked():
+                    lock_info["lock"].release()
                 del self._locks[key]
+            elif lock_info is None or not lock_info["lock"].locked():
+                # The lock was already released or expired (e.g. its hold
+                # timeout elapsed or it was released during a task retry);
+                # releasing it is a no-op, matching RedisLockManager.
+                return
             else:
                 raise ValueError(
                     f"No lock held by {holder} for transaction with key {key}"

prefect/locking/protocol.py

@@ -61,10 +61,16 @@ class LockManager(Protocol):
         """
         Releases the lock on the corresponding transaction record.
 
+        If the lock no longer exists (e.g. it expired or was already released),
+        this method is a no-op.
+
         Args:
             key: Unique identifier for the transaction record.
             holder: Unique identifier for the holder of the lock. Must match the
                 holder provided when acquiring the lock.
+
+        Raises:
+            ValueError: If the lock is held by a different holder.
         """
         ...
 

prefect/runner/AGENTS.md

@@ -142,6 +142,8 @@ These validations exist to prevent git argument injection. Do not bypass them wh
 
 **Automatic dependency installation:** By default, `WorkspaceResolvingEngineCommandStarter` does not install dependencies before starting a flow run. When no explicit command is passed and `PREFECT_RUNNER_AUTO_INSTALL_DEPENDENCIES` is true, it auto-selects `uv run --no-default-groups --project <project_root>` with the worker-supplied workspace bootstrap — but only when all three conditions hold: `pyproject.toml` exists at `project_root`, the `project.dependencies` list includes `prefect`, and `uv` is found via the workspace's `PATH` env var (not the system PATH). The bootstrap uses the prepared entrypoint with `prefect.flow_engine` when that module exposes its executable `_main`; older selected runtimes fall back to `prefect.engine` with `PREFECT__FLOW_ENTRYPOINT`, preserving the prepared workspace. If the setting is false or any condition fails, the command falls back to `None`. Explicit commands always take precedence.
 
+**Version skew in the runtime bootstrap:** `_workspace_runtime_bootstrap.py` runs inside the flow's selected runtime, which may ship an older Prefect than the worker. Do not make it depend on Prefect internals newer than that runtime; it keeps local copies instead. Its flow hook argument resolution is one such copy (see the hook-parity contract in `src/prefect/AGENTS.md`).
+
 ## Reference
 
 Full refactor design and rationale: plans/completed/2026-02-18-runner-refactor.md

prefect/runner/_hook_runner.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Awaitable, Callable, Protocol
 
 from prefect._internal.concurrency.api import create_call, from_async
-from prefect._internal.engine import get_hook_name
+from prefect._internal.engine import get_hook_name, resolve_flow_hook_arguments
 from prefect.logging.loggers import flow_run_logger
 from prefect.utilities.asyncutils import is_async_fn
 
@@ -35,12 +35,11 @@ async def _run_hooks(
                 hook_name,
                 state.name,
             )
+            args, kwargs = resolve_flow_hook_arguments(hook, flow, flow_run, state)
             if is_async_fn(hook):
-                await hook(flow=flow, flow_run=flow_run, state=state)
+                await hook(*args, **kwargs)
             else:
-                await from_async.call_in_new_thread(
-                    create_call(hook, flow=flow, flow_run=flow_run, state=state)
-                )
+                await from_async.call_in_new_thread(create_call(hook, *args, **kwargs))
         except Exception:
             logger.error(
                 "An error was encountered while running hook %r",

prefect/runner/_workspace_runtime_bootstrap.py

@@ -109,6 +109,52 @@ async def _load_flow(manifest: dict[str, Any]) -> Flow[Any, Any]:
         return await _run_sync(load_function_and_convert_to_flow, entrypoint)
 
 
+def _flow_hook_arguments(
+    hook: Callable[..., Any],
+    flow: Flow[Any, Any],
+    flow_run: FlowRun,
+    state: State,
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    # Same rule as `prefect._internal.engine.resolve_flow_hook_arguments`. This
+    # module runs with the flow's runtime, which may have an older Prefect
+    # without that function, so it keeps its own copy.
+    try:
+        signature = inspect.signature(hook)
+    except (TypeError, ValueError):
+        return (flow, flow_run, state), {}
+
+    def binds(*args: Any, **kwargs: Any) -> bool:
+        try:
+            signature.bind(*args, **kwargs)
+        except TypeError:
+            return False
+        return True
+
+    named = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    for flow_run_name in ("flow_run", "run"):
+        kwargs = {"flow": flow, flow_run_name: flow_run, "state": state}
+        declared = all(
+            name in signature.parameters and signature.parameters[name].kind in named
+            for name in kwargs
+        )
+        if declared and binds(**kwargs):
+            return (), kwargs
+
+    if binds(flow, flow_run, state):
+        return (flow, flow_run, state), {}
+
+    kwargs = {"flow": flow, "flow_run": flow_run, "state": state}
+    if binds(**kwargs):
+        return (), kwargs
+
+    hook_name = getattr(hook, "__name__", type(hook).__name__)
+    raise TypeError(
+        f"Hook {hook_name!r} must accept the flow, the flow run and the state as"
+        " three positional arguments or as parameters named `flow`, `flow_run`"
+        " (or `run`) and `state`"
+    )
+
+
 async def _run_hooks(
     hooks: list[Callable[..., Any]],
     flow_run: FlowRun,
@@ -121,14 +167,8 @@ async def _run_hooks(
     for hook in hooks:
         hook_name = getattr(hook, "__name__", type(hook).__name__)
         try:
-            result = await _run_sync(
-                functools.partial(
-                    hook,
-                    flow=flow,
-                    flow_run=flow_run,
-                    state=state,
-                )
-            )
+            args, kwargs = _flow_hook_arguments(hook, flow, flow_run, state)
+            result = await _run_sync(functools.partial(hook, *args, **kwargs))
             if inspect.isawaitable(result):
                 await result
         except Exception:

prefect/runner/storage.py

@@ -459,12 +459,27 @@ class GitRepository:
             # read-only attribute first to avoid `[WinError 5] Access is denied`.
             _clear_read_only_attributes(git_dir)
 
-            # Sparsely checkout the repository if directories are specified and the repo is not in sparse-checkout mode already
-            if self._directories and not await self.is_sparsely_checked_out():
+            # Make the checkout match the configured directories. The destination
+            # can be reused by runs whose `directories` differ (a redeploy that
+            # changed the list, or deployments sharing a working directory), so
+            # an existing sparse checkout only grows: narrowing it would remove
+            # files that another run may still be using.
+            is_sparse = await self.is_sparsely_checked_out()
+            if self._directories:
                 await run_process(
-                    ["git", "sparse-checkout", "set", "--", *self._directories],
+                    [
+                        "git",
+                        "sparse-checkout",
+                        "add" if is_sparse else "set",
+                        "--",
+                        *self._directories,
+                    ],
                     cwd=self.destination,
                 )
+            elif is_sparse:
+                await run_process(
+                    ["git", "sparse-checkout", "disable"], cwd=self.destination
+                )
 
             self._logger.debug("Pulling latest changes from origin/%s", self._branch)
             # Update the existing repository