feature: Allow extensions to access the current agent (visitor/inspector)

[pawamoy]

Is your feature request related to a problem? Please describe.

When working with docstrings, we often need to pass down the docstring parser options selected by the user. The only way to access those is through the agent, but we don't have any reference to the agent from extension hooks.

Describe the solution you'd like

Pass the agent reference to extension hooks. This will require inspecting the signature of hooks first (in v0). For forward-compatibility, we could add **kwargs to all hooks, so that users remember to add it to their own hooks (IDEs will help by copying the signature).

def on_attribute_instance(self, *, node: AST | griffe.ObjectNode, attr: griffe.Attribute, agent: griffe.Visitor | griffe.Inspector, **kwargs: Any) -> None:
    ...

Accepting **kwargs means users could also avoid listing node: ast.AST | griffe.ObjectNode in their hook parameters (not often used), or any other parameter, simplifying signatures and imports.

def on_attribute_instance(self, *, attr: griffe.Attribute, **kwargs: Any) -> None:
    ...

Describe alternatives you've considered

Attaching the agent reference to the extension itself, in an attribute. But that's ugly and error prone (state to manage).
Or always inspecting the hook signature to know which arguments to pass, to avoid type errors (even in v1).

Additional context

/

[pawamoy]

By the way, this could allow extensions to trigger other extensions when they create objects. For example:

class MyExtension(griffe.Extension):
    def on_attribute_node(self, *, node, agent, **kwargs):
        ...
        attr = Attribute(...)
        agent.extensions.call("on_attribute_instance", node=node, attr=attr, agent=agent, **kwargs)