# libtmux.neo._token_scope

- **Module:** libtmux.neo
- **Package:** libtmux
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux/blob/38e368c11117fb4aeb2f082d552cd4f210eae06a/src/libtmux/neo.py#L180
- **Page:** https://libtmux.org/en/py/stable/reference/libtmux-neo-_token_scope/

```
libtmux.neo._token_scope(field_name: str) -> str
```

Resolve a format token's scope from its name.

Returns ``"universal"`` for cross-scope tokens (e.g. ``version``,
[`socket_path`](/en/tmux/latest/catalog/formats/socket_path/), ``host``). Returns ``"event"`` for runtime-only tokens
that never appear in a ``list-*`` output (mouse, cursor, selection,
popup). Returns ``"context"`` for tokens registered outside
``format.c``'s static table (only resolve in a specific command or
mode context). Returns ``"pane"`` / ``"window"`` / ``"session"`` /
``"client"`` / ``"buffer"`` for scope-prefixed tokens.

Fields that don't match any prefix, override, or known-token table
fall back to ``"unknown"``. ``"unknown"`` is intentionally absent from
every :data:`SCOPES_BY_LIST_CMD` entry, so an unclassified field is
excluded from every ``list-*`` ``-F`` template — preventing a future
untracked field from being silently emitted under a list command
where it might crash older tmux. Add such a field to
:data:`_SCOPE_OVERRIDES` (or the appropriate prefix / known-token
table) to admit it.

### Notes

Fields whose name doesn't carry one of the scope prefixes in
:data:`_SCOPE_PREFIXES` (for example, [`bracket_paste_flag`](/en/tmux/latest/catalog/formats/bracket_paste_flag/) and
[`synchronized_output_flag`](/en/tmux/latest/catalog/formats/synchronized_output_flag/), which are pane-scope but don't start
with ``pane_``) MUST be classified via :data:`_SCOPE_OVERRIDES` —
otherwise the fail-closed default returns ``"unknown"`` and
excludes them from every ``list-*`` ``-F`` template. The drift
catcher ``test_every_obj_field_classifies_to_known_scope`` enforces
this on the base :class:`Obj`; subclasses that add custom fields
must classify them via the same tables.

## Examples

```python
>>> from libtmux.neo import _token_scope
>>> _token_scope("pane_id")
'pane'
>>> _token_scope("window_zoomed_flag")
'window'
>>> _token_scope("client_name")
'client'
>>> _token_scope("version")
'universal'
>>> _token_scope("mouse_x")
'event'
```

Tokens whose name doesn't carry a scope prefix can still be scope-gated via :data:`_SCOPE_OVERRIDES` (verified against tmux's ``format_cb_*``). The override also corrects prefix-misclassified tokens — e.g. ``mouse_all_flag`` is a per-pane mode bit, not a runtime mouse event:

```python
>>> _token_scope("mouse_all_flag")
'pane'
>>> _token_scope("active_window_index")
'session'
```

Context-only tokens (registered outside ``format.c``'s static table) route to the ``"context"`` scope and are excluded from every ``list-*`` ``-F`` template:

```python
>>> _token_scope("command_list_alias")
'context'
>>> _token_scope("search_match")
'context'
```

Unclassified tokens fall back to ``"unknown"``, also excluded from every list command:

```python
>>> _token_scope("libtmux_test_nonexistent_token")
'unknown'
```

## Parameters

- `field_name` (`str`)