axio-tui-guards
Permission guard plugins for axio-tui.
Guards intercept tool calls before execution and can allow, modify, or deny them. Ships two guards: a path-access guard that asks the user before touching filesystem locations, and an LLM-based guard that reviews tool calls for safety.
Features
- PathGuard - intercepts tools that touch the filesystem; prompts the user once per directory and remembers the decision for the session
- LLMGuard - runs a secondary LLM call to review each tool invocation before allowing it
- PermissionGuard protocol - both guards implement
axio.PermissionGuardand compose cleanly - TUI-aware - prompts appear as native
axio-tuidialogs, not blocking stdin reads
Installation
pip install axio-tui-guards
Or install as part of the TUI bundle:
pip install "axio-tui[guards]"
Guards
PathGuard
Intercepts tool calls that contain filesystem paths (file_path, filename, directory, path, cwd). On the first access to a new directory it asks the user to allow, allow all (subtree), or deny.
from axio_tui_guards.guards import PathGuard
from axio.tool import Tool
guard = PathGuard() # uses TUI prompt_fn by default
tool = Tool(
name="write_file",
description="Write a file",
handler=write_file,
guards=(guard,),
)
Decision caching:
- Allow - grants access to the parent directory for the current session
- Allow all - grants access to the directory and all subdirectories
- Deny - blocks this path; raises
GuardErrorimmediately on retry
LLMGuard
Uses a secondary LLM call to review the tool handler arguments before execution. If the reviewer deems the call unsafe it raises GuardError with the reason.
from axio_tui_guards.guards import LLMGuard
from axio.agent import Agent
from axio.context import MemoryContextStore
from axio.testing import StubTransport, make_text_response
reviewer = Agent(system="", tools=[], transport=StubTransport([make_text_response("allow")]))
guard = LLMGuard(agent=reviewer, context=MemoryContextStore())
Composing guards
Guards are applied in order - attach both for layered protection:
from axio_tui_guards.guards import PathGuard, LLMGuard
from axio.agent import Agent
from axio.context import MemoryContextStore
from axio.testing import StubTransport, make_text_response
from axio.tool import Tool
reviewer = Agent(system="", tools=[], transport=StubTransport([make_text_response("allow")]))
tool = Tool(
name="shell",
description="Run shell commands",
handler=shell,
guards=(PathGuard(), LLMGuard(agent=reviewer, context=MemoryContextStore())),
)
Custom guards
Implement the PermissionGuard protocol to write your own:
from typing import Any
from axio.permission import PermissionGuard
from axio.exceptions import GuardError
class MyGuard(PermissionGuard):
async def check(self, tool: Any, **kwargs: Any) -> dict[str, Any]:
if "rm -rf" in str(kwargs.get("command", "")):
raise GuardError("Refusing to run rm -rf")
return kwargs
Plugin registration
[project.entry-points."axio.guards"]
path = "axio_tui_guards.guards:PathGuard"
llm = "axio_tui_guards.guards:LLMGuard"
Part of the axio ecosystem
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for axio-tui-guards 0.11.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| axio_tui_guards-0.11.1.tar.gz | 86.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| axio_tui_guards-0.11.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 93.8 kB
Release files / axio_tui_guards-0.11.1.tar.gz
| Download URL | axio_tui_guards-0.11.1.tar.gz |
|---|---|
| Size | 86.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
edf11c16feff6f02defaa8037c8c82eb873fa48029c5acf6ba9fddcf7fa92489
|
|
BLAKE2b-256 checksum How to use checksums |
3bdb45ae6ed664eb51f6343f03357f1cdd10de408620083cbfa3b14f007d56d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logRelease files / axio_tui_guards-0.11.1-py3-none-any.whl
| Download URL | axio_tui_guards-0.11.1-py3-none-any.whl |
|---|---|
| Size | 7.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b9aebf3cbb6ae22db8977af454df0db7ab7ce70ff0e871358402f4d1e33b0fcd
|
|
BLAKE2b-256 checksum How to use checksums |
c3fe37720dd5046e23153f58fa43fcbb69fc296c10ac696f859110f9cc148453
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency log
