docs(types): clarify hooks dispatch is concurrent, not sequential (#956)

## Problem

`ClaudeAgentOptions.hooks` docstring is silent on dispatch order. The
official docs example implies sequential execution:

```python
hooks={
    "PreToolUse": [
        HookMatcher(hooks=[rate_limiter]),         # First: check rate limits
        HookMatcher(hooks=[authorization_check]),  # Second: verify permissions
        HookMatcher(hooks=[input_sanitizer]),      # Third: sanitize inputs
        HookMatcher(hooks=[audit_logger]),         # Last: log the action
    ]
}
```

The comments ("First", "Second", "Third", "Last") and the example
pattern (rate limiter gating an action it runs concurrently with) only
make sense if hooks execute sequentially. But they don't.

Empirical testing in #910 across Python, TypeScript, and Kotlin SDKs
confirms the CLI fires all `hook_callback` control requests for a given
event **in parallel**. In Python, `_spawn_control_request_handler` is
fire-and-forget — all matchers on the same event start at the same
instant. Total wall time ≈ max single hook delay (not sum), and exit
order is reversed from registration order.

This is a real footgun: a rate limiter or authorization check that runs
concurrently with the action it is supposed to gate **cannot actually
gate it**.

## Fix

Add a **Dispatch order** note to the `hooks` docstring in
`ClaudeAgentOptions` documenting the actual concurrent behavior, so
callers know not to design hooks that depend on sequential ordering.

This is a docs-only change — no runtime behavior changes.

## Tests

- `mypy src/`: clean
- `ruff check src/ tests/`: clean
- `pytest tests/`: not run (docs-only change, no logic touched)

Closes #910.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Ameen-Alam

src/claude_agent_sdk/types.py

@@ -1762,6 +1762,12 @@ class ClaudeAgentOptions:
 
     Hooks can modify behavior, add context, or implement custom logic. See
     https://docs.anthropic.com/en/docs/claude-code/hooks.
+
+    **Dispatch order:** multiple matchers registered on the same event are
+    dispatched **concurrently** by the CLI — all ``hook_callback`` control
+    requests for a given event fire in parallel, not sequentially. Design
+    each hook to be independent; do not rely on one completing before
+    another starts.
     """
 
     user: str | None = None