Skip to content

Agent Zero AI framework

docs: explain plugin config caller context

Alessandro9cb6290aa9d4
diff --git a/plugins/README.md b/plugins/README.md
index 3b1723333..dcdbac72f 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -70,6 +70,29 @@ Plugins can also include an optional `hooks.py` at the plugin root. The framewor
In Docker, `hooks.py` normally affects `/opt/venv-a0`; the agent execution runtime is `/opt/venv`.
+### Configuration Hook Context
+
+Configuration hooks can distinguish why settings are being read or saved. Pass
+`caller="ui"` or `caller="agent"` to `get_plugin_config(...)` or
+`save_plugin_config(...)`; calls without it keep the compatible default,
+`"api"`.
+
+The hook receives this as `hook_context={"caller": ...}`:
+
+```python
+def get_plugin_config(default=None, hook_context=None, **kwargs):
+ caller = (hook_context or {}).get("caller", "api")
+ if caller == "ui":
+ return redact_for_display(default)
+ return default
+```
+
+Existing hooks need no change: hooks that ignore `hook_context`, including
+strict signatures without `**kwargs`, retain their previous behavior. Use the
+context only for behavior selection in plugin-controlled flows; it is not an
+authorization boundary. A `config.html` alone does not set the caller; the
+backend code loading or saving that configuration must pass it explicitly.
+
## Plugin Index & Community Sharing
The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-maintained registry of plugins available to all Agent Zero users.
diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.md
index 4327cdd45..9e7298741 100644
--- a/skills/a0-create-plugin/SKILL.md
+++ b/skills/a0-create-plugin/SKILL.md
@@ -177,6 +177,33 @@ save_plugin_config(
)
```
+### Configuration Hook Caller Context
+
+Use caller context only when the same settings need different behavior for a
+known origin. An unlabeled call remains compatible and uses `"api"`; a
+plugin-controlled runtime path can opt in explicitly:
+
+```python
+settings = get_plugin_config("my-plugin", agent=agent, caller="agent") or {}
+```
+
+Its `hooks.py` receives `hook_context={"caller": ...}`. For example, a plugin
+can redact a stored credential for a UI-specific path while preserving its
+normal runtime configuration:
+
+```python
+def get_plugin_config(default=None, hook_context=None, **kwargs):
+ caller = (hook_context or {}).get("caller", "api")
+ return redact_for_display(default) if caller == "ui" else default
+```
+
+The available values are `"ui"`, `"agent"`, and `"api"`. Existing hooks do
+not need to change: the framework safely ignores this new argument for hooks
+that do not accept it. This is behavior metadata, never authorization; do not
+use it to grant or deny access to secrets or other protected data. A
+`config.html` alone does not set the caller; its backend load/save path must
+pass it explicitly.
+
---
## Directory Layout