ziro 0.2.9

LangGraph conversational agent with persistent memory, RAG, progressive tool loading, MCP support, skills library, configurable guardrails, and automatic context compaction. Backed by OpenRouter (any LLM) and Langfuse (observability). Two runtime modes: SQLite/FAISS for local dev, PostgreSQL/pgvector for production.

Features

• Multi-agent: run as one of several named agents, each with its own persona, model, tools, MCP servers, guardrails, and compaction policy; per-agent on/off flags
• Long-term memory for user- and agent-scoped facts persisted across sessions
• Thread resumption lets you pick up any prior conversation by thread ID
• Context compaction: older turns are auto-folded into a running summary when a request nears the model's context window; recent turns kept verbatim; YAML-driven, model-aware budgeting
• RAG: semantic search over indexed documents (.txt, .pdf, directories)
• Skills library: index SKILL.md files, and the agent retrieves relevant skills and loads reference files on demand
• Progressive tool loading. Tools are deferred by default; the LLM discovers and activates only what it needs via search_tools / load_tools
• Subagents delegate a self-contained subtask to a child subagent in isolated context. Each one is a single-file *.agent.md definition (persona + scoped tools/skills) with inherited, never-widened permissions
• Tool permissions (F06): per-agent allow/deny/ask policy over tool/namespace globs; ask triggers a human-in-the-loop approval, with allow-once / allow-thread / allow-always memory; shell:* ships dangerous-default-deny
• Hooks (F01 / F30) provide declarative lifecycle interception (session_start, pre/post_turn, pre/post_tool, pre/post_model, plus session_end, pre_compact, subagent_stop, notification); Python-dotted or shell callables with glob matchers; powers permission gating, shell audit, memory reflection, and trusted-plugin hooks
• Human handoff (F07): an optional request_handoff tool that pauses the turn for a human operator and injects their reply back into the conversation
• Clarifying questions. The core ask_user_question tool (mirrors Claude Code's AskUserQuestion) pauses the turn to ask 1-4 structured multiple-choice questions and folds the answers back in; it shares the same HITL interrupt path as F06/F07
• Task / todo list (F08): write_todos / update_todo state tools; the running todo list renders in the TUI side pane
• Self-improving memory (F03): per-agent memory_policy.yaml governs how facts are extracted and reflected into long-term store
• Multimodal input (F02): attach images via /img <path> or --attach; vision-capable models receive image blocks, text-only models degrade gracefully (attachment_policy.yaml)
• Filesystem tools: cross-platform core tools read_file, grep, glob_files for local file inspection, plus deferred, ask-gated write_file/edit_file mutating tools (separate fs_write namespace); pure stdlib (identical on Windows + POSIX), path-confined to the project root, on by default (fs_policy.yaml)
• Web fetch, an optional SSRF-guarded web_fetch(url) tool that returns cleaned, length-capped page text
• Shell execution: an optional run_shell tool that runs real commands on the host or in a Docker sandbox; default-deny + human approval (F06/HITL), denylist backstop, timeout + process-tree kill, output caps, env scrubbing, and full audit.
• Bash parity. A cross-platform bash interpreter (Git Bash/WSL-probed on Windows) makes pipes/quoting/heredocs behave identically on every OS; an optional persistent per-thread bash session keeps cd/env vars across calls
• Multi-provider LLM adapter: an LLMAdapter abstraction (ziro/llm/) decouples the graph from any single provider. OpenRouter, Anthropic, and OpenAI ship live; per-agent provider: selection in meta.yaml, global default via ZIRO_LLM_PROVIDER. Custom providers (any OpenAI- or Anthropic-compatible endpoint) are user-definable in ~/.ziro/custom_providers.json or added interactively via the setup wizard, with no code change
• Local voice: optional push-to-talk speech I/O (F11) with faster-whisper STT + Piper TTS, fully on-device, no cloud key required (cloud STT/TTS also pluggable)
• MCP support (F18): connect external MCP servers (stdio, SSE, streamable HTTP, WebSocket) with OAuth; a live McpManager (re)ingests tools into the shared registry, persistent sessions cut per-call latency, failures non-fatal
• Plugins (Track J): install Claude-Code plugins from a git url, local path, or marketplace and use their skills, agents, prompt-macro commands, MCP servers, and hooks in the running agent, driven from the /plugins command or the ziro plugin CLI. Third-party code (shell hooks, stdio-MCP subprocesses) is trust-gated: inert until you consent, and any file edit re-revokes trust. Live hot-load (no restart): a newly installed plugin's skills/MCP/commands surface immediately. Reads the native Claude-Code layout (~/.claude/plugins), so nothing needs re-authoring
• AGENTS.md ingestion (F31): a workspace AGENTS.md (fallback CLAUDE.md) is size-capped and injected as project instructions on top-level turns
• Interactive TUI (F12): Textual front-end (transcript, todo/active-tools side pane, status footer, approval/question modal); paints in ~1.6s and is usable while the engine builds on a background thread (F26); slash-commands, live themes (carbon/nord/gruvbox), a context-usage meter (F16), and an MCP control panel (F17, Ctrl+O); session state is a single reactive UIStore, with SVG snapshot tests + a textual serve browser demo for UI peek
• Slash commands (F14) grouped by category: control (/help /stop /quit), session (/user /agent /thread), config (/settings /model /think), tools (/voice /img /mcp /capability /skills), transcript (/save); dispatched in the driver loop before the LLM (no model call, no transcript pollution)
• Chat queue (F13): an in-flight buffer captures mid-turn input; an optional background worker pool (chat_once --submit/--status) survives restart
• Guardrails: configurable input/output guards (regex injection, ML classifier, PII, Llama Guard content safety); YAML-driven, no code changes to add rules
• Agent persona: configurable soul_prompt, system_prompt, and fallback_messages via the agent's agent_config.yaml
• Resilient replies. Empty reasoning-only turns are re-prompted once, then served a non-blank fallback rather than a blank message
• Thinking / reasoning: optional extended reasoning via OPENROUTER_REASONING_EFFORT, switchable live with /think <high|medium|low|off> (F15)
• Fast startup: embeddings warmup is off the critical path (F24); the TUI shell + graph build are torch-free, and torch loads on a background thread (F26)
• Dual backends: dev (SQLite + FAISS, zero infra) / prod (PostgreSQL + pgvector)
• Observability: Langfuse and LangSmith tracing, both optional

Quickstart

Install with the script for your platform. It needs only Python 3.11.9+ and creates an isolated environment; no pipx, no uv, no admin rights.

# macOS / Linux
curl -fsSL https://ziro-agent.com/install.sh | bash

# Windows
iwr -useb https://ziro-agent.com/install.ps1 | iex

Then:

ziro

Both scripts take --version <v>, --uninstall, and --help. They are served as static assets by the web app and live in apps/web/public/, which is the single source of truth for them. To run one from a checkout: bash apps/web/public/install.sh.

ziro with no arguments walks you through first-run setup in the TUI: an API-key wizard (get one at openrouter.ai/keys), then model/theme/advanced sections (all skippable but the key), then user / thread / agent pickers, then straight into chat. Re-run the wizard any time with ziro setup. User ids are 1-64 chars of [A-Za-z0-9_-]; a legacy pre-F28 id with other characters still works with the headless -p / chat_once paths, but --user on the interactive TUI/REPL rejects it with a clear error.

Running from a source checkout instead of a published package:

# 1. Install dependencies, including the local guardrail backends
#    (Presidio PII + Llama Guard content safety).
uv sync

# 2. (Optional) local voice: faster-whisper STT + Piper TTS (push-to-talk, no cloud key)
uv sync --group voice-local

# Download the local models the installed backends need (spaCy, Llama Guard GGUF,
# and, only if the voice group is installed, the default Piper voice).
# Fetches just what's missing.
python -m app.cli.startup

# 3. (Production only) start PostgreSQL + pgvector
docker compose up -d

# 4. Run (same first-run wizard as above)
python -m app.main --user alice

Resume a previous session:

python -m app.main --user alice --thread alice_abc12345

Single-shot (JSON output, for programmatic / LLM-driven use):

python -m app.cli.chat_once --user alice --message "Hello"

Documentation

The full docs site lives in apps/docs/ and is built with Mintlify. It is a pnpm + turborepo workspace, independent of the Python uv workspace; the two never import each other.

pnpm install
pnpm docs          # preview at http://localhost:3000
pnpm build         # mint validate (strict)
pnpm check         # mint broken-links

apps/docs/docs.json owns the sidebar: a page not listed in its navigation does not appear. See apps/docs/README.md for the page layout and brand tokens.

Environment Variables

Commands

uv sync                                                              # install dependencies (incl. local guardrail backends)
uv sync --group voice-local                                          # + faster-whisper STT + Piper TTS (optional local voice)
python -m app.cli.startup                                            # download spaCy + Llama Guard + default Piper voice if absent
python -m app.main --user <USER_ID>                                  # start chat session (interactive agent picker)
python -m app.main --user <USER_ID> --agent <AGENT_ID>              # start with a specific agent
python -m app.main --user <USER_ID> --voice                         # push-to-talk voice I/O (needs voice-local + voice_policy enabled)
python -m app.main --user <USER_ID> --thread <THREAD_ID>            # resume session
python -m app.cli.chat_once --user <USER_ID> --message <MSG>        # single-shot JSON output
python -m app.cli.chat_once --user <USER_ID> --agent <AGENT_ID> --message <MSG>  # single-shot, specific agent
python -m app.cli.manage_agents list                                 # list agents + per-agent on/off state
python -m app.cli.manage_agents add <AGENT_ID> --name NAME          # scaffold a new agent
python -m app.cli.manage_agents remove <AGENT_ID>                   # delete an agent
python -m app.cli.manage_agents enable <AGENT_ID>                   # turn a single agent ON
python -m app.cli.manage_agents disable <AGENT_ID>                  # turn a single agent OFF
python -m app.cli.manage_agents set-default <AGENT_ID>              # set the default agent
python -m app.cli.manage_agents set-model <AGENT_ID> <MODEL>        # set an agent's model (or 'none' to clear)
python -m app.cli.manage_agents add-subagent <AGENT_ID> --tools a,b --namespaces rag --skills x  # scaffold a single-file subagent
python -m app.cli.manage_agents remove-subagent <AGENT_ID>          # delete a subagent definition
ziro plugin list                                                     # Track J: list installed plugins
ziro plugin install <git-url|path|market:plugin> [ref] [--yes|--safe]  # install (consent-gated; --yes trusts, --safe inert)
ziro plugin {update|remove|enable|disable|info} <id>                # manage an installed plugin
ziro plugin marketplace {add <name> <src>|list|remove <name>|search <query>}  # marketplace registry (F35)
python -m app.cli.run_scenarios                                      # replay scenario files in tmp/
python -m ziro.rag.indexer <path>                                    # index docs (dir, .txt, or .pdf)
python -m skills.loader                                              # index all SKILL.md files
python -m ziro.tools.indexer                                         # re-index tool descriptions
python -m app.tui.demo                                               # scripted TUI demo (UI peek); textual serve "python -m app.tui.demo" for a browser demo
mypy .                                                               # type check
pytest tests/test_tui_snapshots.py --snapshot-update                 # regenerate TUI SVG snapshot baselines after a UI change
docker compose up -d                                                 # start PostgreSQL + pgvector (prod)
docker compose build pdf-sandbox                                     # build F10 sandbox image (ziro-pdf:latest) for researcher_docker

Visualize the graph

python -m app.cli.show_graph                          # ASCII to stdout (requires grandalf: uv sync --group dev)
python -m app.cli.show_graph --format mermaid         # Mermaid markdown to stdout
python -m app.cli.show_graph --format mermaid -o g.md # Mermaid to file
python -m app.cli.show_graph --format png -o g.png    # PNG (requires graphviz system package)

Slash commands (in-session)

Typed into the running session (TUI or REPL), dispatched before the LLM, so there is no model call and no transcript pollution (F14):

Architecture

User input → [input_guard] → [compaction] → agent node → LLM with tools → DynamicToolNode → back to agent → ... → [output_guard] → final response

input_guard, output_guard (toggled by the agent's guardrails_policy.yaml), and compaction (toggled by compaction_policy.yaml) are conditional nodes. A blocked request returns a refusal message without reaching the LLM. The agent injects long-term user memories, the configured persona, and the running compaction summary into the system prompt before each LLM call. An empty reasoning-only reply is re-prompted once (reprompt), then replaced by a non-blank fallback (reply_fallback).

Multi-Agent System

The agent can run as one of several named agents, each with its own persona, tool policy, MCP servers, and guardrails.

• Per-agent folders. Each agent lives in packages/ziro-core/src/ziro/agents/<agent_id>/ (older docs say app/agents/<id>/, a historical import alias) and is self-contained, with its own agent_config.yaml, tool_policy.yaml, mcp_servers.yaml, guardrails_policy.yaml, compaction_policy.yaml, meta.yaml, and the other per-concern policy files. The shipped agents are default (the autonomous Generalist), life_coach (the Four-Blocks coaching persona), researcher (factual research aide with lighter guardrails; run_shell enabled in host mode), and researcher_docker (same persona with run_shell in Docker-sandbox mode).
• Config layering: an agent's files resolve most-specific-first across three roots: <project>/.ziro/agents/<id>/ → ~/.ziro/agents/<id>/ → the bundled package. So you can override or add agents for an installed ziro without touching the package: drop files under ~/.ziro/agents/<id>/. A missing file at every layer degrades to built-in defaults; a dangerous file (permissions/mcp/hooks) in an untrusted project .ziro is skipped (F19b trust gate).
• Per-agent model & provider. meta.yaml's model sets the model for that agent (in the naming its provider uses); omit / null → the provider's env default. provider: selects the LLM adapter (openrouter / anthropic / openai / a custom label; default ZIRO_LLM_PROVIDER, see LLM Adapter).
• Per-agent on/off: meta.yaml's enabled flag controls whether an agent is selectable. Toggle with manage_agents enable|disable <id>.
• Manifest. app/agents/registry.yaml records the default agent. If the default is disabled, the first enabled agent is used.
• Memory isolation: long-term memory is keyed per (user_id, agent_id), so each agent keeps its own facts per user.

Progressive Tool Loading

Tools are split into three tiers:

Discovery loop: search_tools("<keyword>") → pick names → load_tools([...]) → call the tool. Activated tools persist for the rest of the thread (up to max_active, LRU eviction after that).

MCP Integration

External MCP servers are declared in the agent's mcp_servers.yaml. On startup, tool metadata is fetched from all enabled servers and registered into the ToolRegistry under their server name as namespace. MCP tools enter the same deferred-discovery surface as local tools: they are NOT bound to the LLM until activated via load_tools.

Supported transports: stdio, sse, streamable_http, websocket, plus OAuth (F18). A live McpManager (app/tools/mcp_manager.py) owns per-server state and a ServerStatus snapshot, holds a persistent session per server (one owner task keeps it open so tool calls reuse it, a large latency win), and re-ingests tools into the shared registry on every connect so discovery stays current. connect / disconnect / reconnect are driven live from the F17 panel or /mcp. OAuthConfig picks the flow (auto / authorization_code / device_code; device-code when headless); tokens are cached and refreshed per request. Server failures are non-fatal; the rest of the registry is unaffected.

Plugins (Track J)

ziro/plugins/ is a full Claude-Code-plugin system (discover → surface → trust-gate → install → manage) driven from the /plugins command (alias /plugin) and the ziro plugin CLI. It reads the native Claude-Code layout (.claude-plugin/plugin.json + skills/agents/commands/hooks/.mcp.json) into a provider-neutral canonical model, so existing plugins work without re-authoring.

• Surfacing. An enabled plugin's components fold into the running agent, namespaced <plugin>:<name> (a native component of the same id shadows the plugin one): skills (join /skills + search_skills), agents (spawn-only subagents, permissions still intersected), commands (prompt-macros, where /<plugin>:<name> args expands $ARGUMENTS/$1..$9/@file into a normal turn), MCP servers (folded into the live McpManager), and hooks (run at the mapped lifecycle event).
• Trust & consent. Third-party code is dangerous: shell hooks (shell_exec), stdio-MCP subprocesses (process_spawn), and permission-widening (permission_widen). These stay inert until the plugin is trusted. Trust is keyed on a content hash of the plugin tree (ziro/core/trust.py), so editing any file re-revokes it. Trust is fail-closed under ZIRO_STRICT_SECURITY or a headless run (-p, the background worker). Safe components (skills, agents, http-MCP, non-!bash commands) load from any enabled plugin. Install shows a consent manifest (component counts + the exact dangerous grants) before you approve.
• Install sources: a git url, a local path, or <marketplace>:<plugin> (register a Claude-Code marketplace with ziro plugin marketplace add). The installer clones/copies at a pinned ref into <scope>/.ziro/plugins/, records the decision in a ledger, and reloads. --yes trusts, --safe installs with dangerous parts inert; a non-interactive install is fail-closed.
• Live hot-load. A /plugins mutation reindexes skills, reconciles the live MCP server set (McpManager.sync_servers), and re-registers prompt-macro commands, so a newly installed plugin is usable without a restart.

The two surfaces are equivalent: /plugins … in-chat and ziro plugin … on the CLI (the latter for scripting / headless). Discovery imports the user's already-installed CC plugins from ~/.claude/plugins/installed_plugins.json, plus native <proj>/.ziro/plugins and ~/.ziro/plugins.

Subagents

The parent can delegate a subtask to a child subagent via spawn_subagent (or dispatch_subagents for parallel fan-out). Each child is a fresh graph on a namespaced thread with its own persona, empty history, and a restricted toolset; only a compact result is folded back into the parent.

• Single-file definitions. Subagents live in app/agents/.subagents/<id>.agent.md: YAML frontmatter (name, description, enabled, model, which accepts a ${EXECUTION_MODEL}-style tier token, allowed tools:/namespaces:, scoped skills:, optional soul) plus a Markdown body that becomes the system prompt. The .subagents/ dir is spawn-only, so subagents never appear in the interactive picker. Shipped: scout (source-grounded research), solver (a capable generalist that drives a self-contained problem to a verified result), and reflector (reflection coach).
• Permission inheritance: a child's tool rights are the intersection of its declared surface and the parent's current rights, never wider. Namespace tokens (rag, rag:*) expand to the concrete tools available in the (possibly restricted) registry view.
• Skill scoping: a subagent's skills: allowlist restricts its search_skills / load_skill_ref to only those skills.
• Runaway guards. Per-parent subagent_policy.yaml sets enabled, allowed_children/denylist, max_depth (default 1), max_spawns_per_thread, and parallelism limits; each child runs under a recursion_limit.

Scaffold one with manage_agents add-subagent <id> --tools … --namespaces … --skills ….

Web Fetch

An optional web_fetch(url) deferred tool (namespace webfetch) fetches an http/https page and returns cleaned, length-capped text. Gated by the agent's webfetch_policy.yaml: when enabled: false the tool is never registered (invisible to discovery). An SSRF guard resolves the host and refuses loopback / private / link-local / reserved targets, re-checking the final URL after redirects.

Filesystem Tools

Three cross-platform core tools (namespace fs) give the agent Claude-Code-style local file inspection: read_file, grep, and glob_files. They are pure Python stdlib (pathlib / re / os / fnmatch), with no new dependency and no shelling out, so behavior is identical on Windows and POSIX.

• read_file(path, offset?, limit?) reads a UTF-8 text file as numbered lines; byte-capped (max_read_bytes) with an offset/limit line window (max_read_lines); binary files are detected and skipped.
• grep(pattern, path, glob?, output_mode?, case_insensitive?) runs a regex search over file contents under a path; glob filters filenames; output_mode is content / files / count; prunes ignored dirs (.git, node_modules, …) and skips binaries; capped at max_grep_matches.
• glob_files(pattern, path?) finds files by glob (incl. **), returned repo-relative and mtime-sorted (newest first), capped at max_glob_results.

Every path is resolved against the project root and refused if it escapes (FsConfig.confine, default on). On by default via the agent's fs_policy.yaml (missing file → defaults); added to each shipped agent's core_tools and inherited by subagents through the rights intersection (like web_fetch). There is no F06 gate; only shell:* is dangerous-default-deny.

Mutating tools (write_file / edit_file) are deferred counterparts registered under a separate fs_write namespace so F06 can ask on writes while reads stay allow; byte-capped at max_write_bytes (512KB). Gated by FsConfig.allow_write (default on): set false for a read-only agent.

Shell Execution

An optional run_shell(command, cwd?) deferred tool (namespace shell) runs real shell commands, on the host by default or inside a Docker sandbox via a config flip. The trust model is Claude-Code-like: a human approves what runs.

• Default off & default-deny, gated by the agent's shell_policy.yaml (enabled: false → never registered). Even when enabled, shell:* is dangerous-default-deny in the permission system (F06); an agent must explicitly allow-list shell:run_shell in its permissions.yaml. Recommended recipe = allow + ask (human approval on every call via HITL). chat_once auto-denies an ask interrupt (fail-closed), so single-shot runs never hang.
• ShellGate backstop: a non-removable hardened denylist (rm -rf, sudo, dd, mkfs, fork bombs, …) plus optional per-agent regex allow/deny and opt-in confine cwd containment.
• Two executors: host (create_subprocess_shell, real shell with pipelines) and sandbox (create_subprocess_exec with a pluggable sandbox_launcher template for Docker/WSL/nsjail). Both sit behind the same gate, audit, and tool body.
• Bash parity. ShellConfig.interpreter defaults to "bash": the command runs as one argv element via create_subprocess_exec (no shell-launcher involved), so bash tokenizes pipes/quoting/heredocs identically on every OS. On Windows this probes Git Bash then falls back to wsl bash. The previous approach (pinning shell_executable through create_subprocess_shell) was unreliable there, since Windows always runs {executable or COMSPEC} /c {command} regardless of the executable. interpreter: "host" restores the old cmd.exe//bin/sh behavior. An optional persistent per-thread bash -l session (session: "persistent") keeps cd/env vars/venv activation across calls.
• Always-on safety: timeout_s with process-tree kill, output capped twice (at the source and at ingestion), and env scrubbing so secrets (OPENROUTER_API_KEY, DATABASE_URL, LANGFUSE_*) never reach the child.
• Loop guards. pre_tool hooks (app/hooks/guards.py) flag repeated near-identical run_shell commands (shell_loop_guard) and repeated identical failure signatures across different commands (verification_loop_guard, catching pytest/mypy/tsc/panic tracebacks that recur while the fix isn't landing).
• Audit: pre_tool / post_tool hooks log every invocation (intent + outcome, including blocked/timeout) to data/audit/shell-audit.jsonl (dev) or a tool_audit table (prod). See docs/audit-log.md.

Two agents ship the opt-in: researcher (host mode; its persona bakes a map-reduce flow for summarizing large PDFs without overflowing context) and researcher_docker (mode: sandbox, launcher docker run --rm --network none -v {workdir}:/work -w /work {image}, image ziro-pdf:latest, built with docker compose build pdf-sandbox).

Local Voice

Optional push-to-talk speech I/O (F11): the turn is bracketed by STT (your speech → the user message) and TTS (the post-output-guard reply → audio). Default backends are fully local (faster-whisper for STT, Piper for TTS), so no cloud API key is needed (cloud STT/TTS over httpx are also pluggable per agent). Gated by the agent's voice_policy.yaml (enabled: false by default).

Setup is two commands:

uv sync --group voice-local   # faster-whisper STT + Piper TTS (+ sounddevice/PortAudio)
python -m app.cli.startup     # downloads the default Piper voice into data/voices/ (gitignored)

Then enable it in the agent's app/agents/<id>/voice_policy.yaml:

enabled: true
tts_backend: local
tts_model: data/voices/en_US-amy-medium.onnx   # path to the downloaded .onnx (config .onnx.json resolved alongside)

Run with python -m app.main --user <id> --voice, or toggle /voice on in the TUI (Ctrl+R to start/stop recording). Piper voices come from the Rhasspy catalog (<lang>-<name>-<quality>); download others with python -m piper.download_voices <voice-id> --download-dir data/voices and point tts_model at the new .onnx. The researcher agent ships voice-enabled.

Tool Permissions (F06)

Every tool call passes a per-agent permission gate (app/permissions/) wired as a pre_tool hook. The agent's permissions.yaml declares allow / deny / ask globs over tool/namespace qualified names plus a default_action; dangerous_default_deny (ships ["shell:*"]) forces a default-deny for dangerous namespaces. An ask decision raises a human-in-the-loop interrupt (the TUI ApprovalModal, REPL prompt, or auto-deny in chat_once); approvals can be remembered once, for the thread, or always (remember_default_scope, persisted per user/agent). Tool args are redacted (secrets masked, long values truncated) before display.

Hooks (F01)

app/hooks/ is a declarative lifecycle-interception layer. An agent's hooks.yaml lists HookSpec entries. Each binds a HookEvent (session_start, pre_turn, post_turn, pre_tool, post_tool, pre_model, post_model), an fnmatch matcher (over tool qualified names for tool events), and a callable (Python dotted path or shell command). Hooks return a HookDecision (allow / deny / modify / interrupt); the runner short-circuits on deny/interrupt and folds modify. Hooks are ordered once at startup, so a no-hook registry has zero per-turn cost. This path powers the F06 permission gate and the F10 shell audit (*run_shell pre/post_tool).

Human Handoff (F07)

An optional request_handoff(reason) core tool (app/handoff/) lets the agent escalate to a human. It pauses the turn, surfaces the reason to an operator, accepts a human-authored reply, and resumes with that reply injected as the next message (assistant or tool, per config). The agent's handoff_policy.yaml (HandoffConfig) sets enabled, the operator prompt, a timeout with an on_timeout fallback, and inject_as.

Clarifying Questions

A core ask_user_question(questions) tool (app/clarify/) mirrors Claude Code's AskUserQuestion: pauses mid-turn to ask 1-4 structured clarifying questions (2-4 options each, optional multi-select, implicit free-text "Other"), then folds the human's answers back into the tool result. It shares the same HITL interrupt module as F06/F07 (app/graph/interrupts.py, InterruptKind.ASK_USER_QUESTION) rather than a bespoke pause mechanism; the TUI renders a QuestionModal, the REPL prints numbered options. Gated by clarify_policy.yaml (ClarifyConfig: enabled, max_questions, max_options; missing file → on by default).

Task / Todo List (F08)

app/tasks/ adds state-based todo tracking via two core tools: write_todos(todos) (full rewrite) and update_todo(id, status|content|result). Todos live in AgentState.todos (merged by a per-id reducer), survive checkpointing, and render live in the TUI side pane. A todo can carry an agent_id to mark subagent delegation.

Multimodal Input (F02)

Images attach via the /img <path> directive or the CLI --attach flag (app/io/attachments.py). build_human_message checks supports_multimodal(model): vision-capable models receive base64 data-URI image blocks in a multimodal HumanMessage; text-only models get a graceful notice instead. Bounded by the agent's attachment_policy.yaml (enabled, max_image_bytes, allowed_image_types).

Interactive TUI & Themes (F12 / F16 / F17)

app/tui/ is a Textual front-end over the shared TurnRunner: a transcript, a todo/active-tools side pane, a status footer, and an ApprovalModal rendering the shared HITL interrupt. It paints in ~1.6s and is usable immediately while the engine builds on a background thread; any turn typed early is queued and runs in order (F26). Extras:

• Themes. app/tui/theme.py maps semantic color slots (not literal hex) to Textual + Rich widgets. Carbon (amber + steel on carbon black) is the default; nord and gruvbox also ship. Palettes are discovered from three roots (bundled app/tui/themes/, project ./themes/, home ~/.ziro/themes/); selected in the setup wizard and switched via /settings (live, persisted to data/ui_prefs.json).
• Context meter (F16): a ContextMeter widget reveals at ≥50% of the usable input budget and shades muted → amber → red as the request approaches the compaction trigger, with a trip-line marker at the trigger line.
• MCP control panel (F17). Ctrl+O (or /mcp in the TUI) opens a modal McpPanel: a live table of servers (state, transport, auth, tool count) with Connect / Disconnect / Reconnect, tool peek, and an OAuth device-code prompt.
• Reactive state + UI peek. Session state (identity/lifecycle/content/chrome) lives in one reactive UIStore (app/tui/store.py) mutated only through typed messages (app/tui/messages.py); widgets bind via watch() instead of imperative update_*() calls. python -m app.tui.demo (or textual serve "python -m app.tui.demo" for a browser demo) drives a scripted fake runner for visual review; SVG snapshot regression tests live in tests/test_tui_snapshots.py (pytest --snapshot-update to refresh baselines). See docs/tui-peek.md.

LLM Adapter

ziro/llm/ wraps LangChain's Runnable behind an LLMAdapter ABC (invoke/ainvoke/stream/astream, bind_tools(), context_window()/supports()), decoupling the graph from any single provider. ziro/llm/registry.py resolves a provider (meta.yaml's provider: field, else the ZIRO_LLM_PROVIDER global default) to a ProviderSpec and build_adapter() builds the adapter after resolving its connection; unknown providers fail fast, and get_llm()/get_agent_llm()/get_summary_llm() in ziro/core/config.py are thin wrappers over build_adapter(). Everything provider-specific lives in a self-contained ziro/llm/providers/<name>/ folder (adapter + catalog + connection); a neutral ziro/llm/capabilities.py facade serves per-model capability lookups so consumers never import a provider module.

Live providers: openrouter, anthropic, and openai all ship registered (stub=False). Each folder is drop-in: a new native provider is a new providers/<name>/ folder plus one registry line.

Custom providers: any OpenAI- or Anthropic-compatible third-party endpoint can be added without code by defining a labelled entry in ~/.ziro/custom_providers.json (ziro/llm/custom.py): {"mylab": {"style": "openai"|"anthropic", "base_url": "...", "headers": {...}, "models": ["..."]}}. Each label registers as a first-class ProviderSpec at import (reusing the matching native adapter pointed at your base_url), so it appears in the provider picker and provider: field exactly like a built-in. Its capability source fetches the endpoint's live /models list (24h disk-cached) and falls back to the typed models when the endpoint is unreachable. The parsing is tolerant: a missing/malformed file, one bad entry, or a label colliding with a built-in name is skipped, never fatal. The setup wizard's "add a custom provider" flow (TUI + console) writes this file and its <LABEL>_API_KEY for you.

Context Compaction

Each agent has a compaction_policy.yaml. When a turn's request exceeds trigger_pct of the model's usable input budget (window minus reserved output and schema headroom), the compaction node folds older messages into a running summary (injected into the system prompt) and drops them from live history via RemoveMessage, shrinking both the in-flight request and the persisted checkpoint. The keep_recent_min most-recent messages are always kept verbatim, and the split is chosen to never orphan a ToolMessage from its parent call.

Budget math is model-aware: app/llm/openrouter_catalog.py (formerly app/core/model_specs.py) reads the OpenRouter /models catalog once per process for each model's context_length, max_completion_tokens, and supported_parameters, so the trigger, the reserved-output carve-out, and the max_tokens sent to the LLM stay consistent. Strategy is hybrid (summarize the dropped span via a clean tool-free LLM) or trim (drop only). Setting enabled: false restores un-compacted behavior exactly. A separate max_tool_message_tokens / max_tool_message_pct cap bounds a single oversized ToolMessage at ingestion. See docs/chat-compression.md.

Tools available to the LLM

Runtime Modes

Key Modules

Guardrails

Policies are declared in the agent's guardrails_policy.yaml. Each rule references a named backend from the backends: pool. Multiple backends run concurrently; first block in declaration order wins. Rules support refusal_templates lists for randomized refusals.

Extending

Add documents:

python -m ziro.rag.indexer ./my-docs/

Add a skill:

mkdir -p skills/my-skill/references
# create skills/my-skill/SKILL.md
# (optional) add reference files to skills/my-skill/references/
python -m skills.loader

Add an agent:

python -m app.cli.manage_agents add my-agent --name "My Agent"
# Edit app/agents/my-agent/agent_config.yaml, tool_policy.yaml, etc.

Add a subagent:

python -m app.cli.manage_agents add-subagent my-scout --tools rag:search_rag --namespaces rag --skills deep-research
# Edit app/agents/.subagents/my-scout.agent.md (frontmatter tools/namespaces/skills + persona body)

Add an MCP server: add an entry to the agent's app/agents/<id>/mcp_servers.yaml, restart the agent.

Install a plugin (Track J):

ziro plugin install https://github.com/owner/some-plugin.git   # or a local path
ziro plugin install --yes owner/repo                            # trust dangerous grants non-interactively
# or via a marketplace
ziro plugin marketplace add acme https://github.com/acme/marketplace.git
ziro plugin install acme:some-plugin

In-chat equivalents: /plugins install <src> → /plugins confirm [safe], /plugins marketplace search <q>, /plugins list. Dangerous components (shell hooks, stdio MCP) stay inert until you confirm trust.

Add a guardrail rule: edit the agent's app/agents/<id>/guardrails_policy.yaml, adding a backend entry and a rule referencing it. No code changes needed.

Change default model:

OPENROUTER_MODEL=anthropic/claude-sonnet-4-5

Change model for a specific agent:

python -m app.cli.manage_agents set-model <AGENT_ID> anthropic/claude-sonnet-4-5

Enable reasoning:

OPENROUTER_REASONING_EFFORT=medium

Configure agent persona: edit app/agents/<id>/agent_config.yaml (system_prompt, soul_prompt, fallback_messages).