This page is the canonical inventory for current agent-facing tool contracts in Clapilot: which tools exist, which runtime surfaces expose them (native ClapilotAICore sessions, Live Voice / Realtime, chat context actions), where they execute in code, and which visible UI mutation each one produces. It is organized by feature area; each table row is one tool contract. The "Source of truth in code" list below names the files that define and execute these contracts — when doc and code disagree, code wins and this page must be updated.

Learning objects have read-only agent tools for approved, visible facts and procedure hints. Approved learning objects are also injected by the native runtime as a controlled prompt layer. Post-response maintenance optimistically activates safe, non-conflicting canonical durable facts. The protected Learning Curator automation then uses its explicitly selected model to inspect only unchecked or changed facts with bounded source evidence; validated high-confidence reject decisions remove false, noisy, unsafe, duplicate, temporary, or low-value facts, while uncertainty defaults to keep. Corrections and explicit conflicts remain staged. Wiki output remains proposal-only and always requires human review. Learning extraction, activation, curator review, and audit mutation remain control-plane/admin workflows rather than agent tools. Their contracts are documented in Clapilot-Agent Learning Contracts.

Keep this page synchronized whenever any of the following change:

• tool schema exposed to live agent / native runtime / Realtime
• /api/chat/live/tools implementation behavior
• chat context actions that mutate app state without going through the Realtime tool catalog
• visible UI mutation contracts such as highlight/focus/live update actions

Instance API-key management under Settings -> Developer is intentionally not an agent tool. Creating, revealing, or revoking external credentials remains an explicit admin control-plane action. The scoped GET /api/v1/subscription-usage and GET /api/v1/notifications endpoints are intended for external devices and do not create visible UI mutations. Notification polling is read-only and cursor-based; it does not mark a Team Chat room or personal chat session as read. External MCP servers and coding-agent skills may use creator-bound memory:read and memory:write keys for GET/POST /api/v1/memory; reads return only approved visible memory, while writes reuse native storeManualMemory safety, deduplication, assertion status, and review behavior. The separate inference:execute grant exposes OpenAI-compatible stateless model passthrough at /api/v1/inference/*: it records provider usage but creates no agent run/session, loads no agent context, and never executes client-supplied tools server-side. Trusted coding agents may instead receive the explicit high-privilege tools:execute grant and use clapilot-cli against POST /api/v1/tools/execute; the API binds execution to the key creator, ignores client identity/session fields, and reuses the existing tool dispatcher, module restrictions, approval flows, and UI mutation publication. This does not expose the internal agent secret. The isolated issue_reports:write scope is not agent-accessible: POST /api/v1/issue-reports accepts only repository-allowlisted public-client reports and creates an open Hub review item. GitHub issue or agent-task creation remains behind the existing human Hub approval action.

The external scripts/clapilot-memory-mcp.mjs adapter is a separate least-privilege MCP surface rather than an extension of the internal session-authenticated bridge:

Tools whose token variable is absent are omitted from tools/list. Authentication values are sent only in the upstream Authorization header and are never included in MCP results or errors. The adapter exposes server instructions covering untrusted-memory handling, durable-write eligibility, review state, and Retry-After; the companion workspace-seed/skills/clapilot-memory/SKILL.md adds the reusable Codex/Claude workflow policy.

Ollama provider configuration under Settings -> ClapilotAICore -> Providers & models is intentionally not an agent tool. Saving or removing an API key or browser Cookie header remains an explicit admin credential action. The API key authenticates inference but cannot read Ollama's 5-hour or weekly account windows; Subscription Usage uses the separately encrypted browser session, including when that provider has no routed models. Provider config writes invalidate the usage cache so credential changes apply on the next read. Subscription Usage passively reuses the configured Ollama and xAI providers and adds no agent mutation contract.

Hub Subscription Usage under Settings -> Hub is also intentionally an admin-only operational view rather than an agent tool. Connected instances push normalized read-only snapshots through the existing signed, per-instance-authenticated Hub channel. There is no chat action for refreshing providers, changing credentials, or querying customer account usage; this avoids turning subscription-account operations into an agent-accessible workflow.

Fleet administration

Fleet tools are available only in Hub mode and only to an admin identity loaded from the persisted agent_session_state; caller-supplied body.userId never authorizes Fleet access. The HTTP Fleet routes and agent handlers share fleetAdminAccessError(...); the handlers call only the existing src/lib/hub-fleet/* service layer and never bypass it with Fleet-table queries. fleet_create and fleet_destroy additionally require a persisted personal chat session and a one-time human approval: the first call performs no mutation and returns a signed, action-bound token plus an exact approval phrase. The authenticated admin must send that phrase as a new user message in the same chat, after which the unchanged action may be retried with approval_token. Tokens expire after ten minutes, are bound to user/session/action, and atomically consume the matching user message so the model cannot approve its own action or replay an approval.

The same schemas drive the generated CLI family: clapilot-cli fleet list, clapilot-cli fleet create, and clapilot-cli fleet destroy. Fleet is intentionally not exposed to public embeds or Live Voice.

Source of truth in code

• tool schema: src/lib/live-voice.ts
• live tool execution: src/app/api/chat/live/tools/route.ts
• Apple Watch live relay transport: src/lib/live-voice-relay.ts and src/app/api/chat/live/relay/**
• navigation target resolution: src/lib/clapilot-navigation.ts
• UI action contract: src/lib/clapilot-ui-actions.ts
• persisted UI mutation transport: src/lib/ui-mutation-events.ts
• live UI action dispatch: src/lib/use-live-voice-conversation.ts
• app-wide mutation stream bridge: src/components/clapilot-ui-mutation-bridge.tsx
• global navigation UI action consumer: src/components/clapilot-navigation-action-host.tsx
• module host forwarding: src/app/(app)/modules/[slug]/page.tsx
• chat context actions: src/app/api/chat/route.ts
• module-install advertisement gate: services/clapilot-agent/src/sessions/index.mjs and services/clapilot-agent/src/module-install-gates.mjs
• module-install execution gate: src/lib/agent-runtime/tool-proxy.ts

Module install gating

Native ClapilotAICore sessions advertise module-owned tools only while the owning bundled module is installed. The runtime applies the same blocklist to full, compact, ultra, skills-mode, and specialized-agent catalogs; routed bundles, on-demand family manifests, tool_catalog_search, and tool_catalog_expand omit gated tools. tool_execute rejects a gated target with module_not_installed:<slug>.

A tool that also belongs to any non-gated bundle is never install-gated: chat_wakeup_create sits in both the gated agent_orchestrator bundle and the core scheduled_tasks bundle, so it stays available even when Agent Orchestrator is uninstalled.

Install resolution mirrors the module store: a module_installs row overrides the active app_settings.module_install_policy; legacy_all otherwise honors .clapilot-bundled-modules.json.disabled, while minimal otherwise installs only notizen, excel-canvas, word-canvas, and agents. Runtime reads use a five-second cache and fail open when the database/install schema is unavailable, preserving the pre-gating catalog during transient infrastructure failures.

Advertisement filtering is a discovery and prompt-quality guard, not the security boundary. executeAgentToolProxy independently checks every module-owned tool immediately before dispatch. An uninstalled module returns the standard tool error payload with code="module_not_installed" and Das Modul "<slug>" ist nicht installiert.

Tool-family ids use social_media as the canonical Social Media family across native runtime manifests and MCP bridges. Catalog search and expansion also accept the legacy aliases social and social-media, normalize them to social_media, and return the complete social_media_* tool set. Weekly-focus changes must use social_media_update_weekly_prompt and then social_media_get_weekly_prompt to validate the persisted value before the agent reports success.

wiki is fixed and always installed. Core families are never install-gated: email, calendar, tasks, documents, Mandanten, memory, learning, shell, web, channels, images, livestream, widgets, mini apps, scheduled tasks, specialized agents, skills, Copilot UI, issue reporting, accounting, Google Meet, and agent core/context. file-explorer and terminal do not own dedicated native bundles. Startup validation fails loudly if the canonical module map references a missing bundle key or bundled-module directory.

Model selection: Mixture of Agents

Mixture of Agents presets are exposed as virtual models moa/<slug> and are selectable wherever a model is chosen (chat model picker, specialized agents, channels). Selecting one routes the turn through the preset's aggregator model after running its reference models in parallel; no separate agent tool is required. See Mixture of Agents.

• preset CRUD (admin): src/app/api/agent-runtime/moa-presets/** → native /internal/moa-presets
• runtime resolution + catalog: services/clapilot-agent/src/providers/index.mjs (resolveProviderSelection, listModels); model entries with a definitive failed save/activation capability probe are excluded before they reach chat, channel, scheduled-run, or Agent Orchestrator pickers. Agent Orchestrator further filters this catalog to non-subscription models for its canonical clapilot-code harness, which reuses the internal embedded_pi adapter
• reference fan-out + context injection: services/clapilot-agent/src/sessions/index.mjs (executeRun)

Provider/account capabilities are applied before this model selection catalog is exposed. In particular, OpenAI providers using Codex OAuth (ChatGPT subscription accounts) admit only OpenAI GPT/Codex chat model IDs; Grok chat models are admitted only from xai providers. Stale incompatible rows are warned about during runtime configuration load and omitted from selection, so the normal ordered provider fallback can handle the same user turn.

Codex OAuth refresh is coordinated inside ClapilotAICore per provider/account with a PostgreSQL advisory transaction lock. A refresh reloads the current credential after acquiring the lock, persists the rotated access and refresh tokens together to app_settings and matching encrypted provider rows, and makes later contenders reuse that committed credential. A Codex refresh token was already used response is classified as auth; the runtime reloads credentials and retries the interrupted RPC once. provider.oauth_refresh events contain only the provider, a hashed account scope, retry flag, state, and final flag—never token material. Webhook automation rows stopped by this recoverable auth condition are retried after 5 seconds against a larger auth-specific attempt budget (5 attempts by default, maxAuthAttempts on the queue job payload); a persistent auth failure exhausts that budget, marks the event failed with error code auth, and delivers the ordinary terminal failure notification once.

Agent-authored skills

The low-frequency skills family is discoverable through tool_catalog_search in native ClapilotAICore sessions and is not exposed to Live Voice. Reads span workspace, managed, and bundled roots with workspace precedence; mutations are restricted to agent-authored workspace skills. Draft and archived skills are returned only by an explicit inactive listing and never participate in normal agent catalog search.

Definitions live in services/clapilot-agent/src/tool-definitions.mjs, execution in src/lib/agent-runtime/tool-proxy.ts, and filesystem/frontmatter guards in services/clapilot-agent/src/skill-files.mjs.

UI mutation actions

Current structured UI actions emitted by tool execution:

Notes:

• uiActions[] are returned alongside output, triggerReload, refreshTopic, and a canonical mutationEventId from /api/chat/live/tools.
• native tool proxy results persist the same mutation metadata and are forwarded through /api/ui-mutation-events, so open app views can react even when the initiating mutation did not originate from the currently visible chat stream. Web uses the SSE form; Apple Aufgaben uses the bounded JSON cursor, refetches only referenced task IDs, and treats only explicit delete actions as deletion rather than inferring it from a paginated list.
• UI actions should be added only for deterministic, user-visible mutations.
• If a feature cannot yet apply a precise UI action, fall back to triggerReload / refreshTopic.

Navigation

Agent Google Workspace

Google Meet

Live Stream Studio

Live tool catalog

These tools are currently exposed to Live Voice / Realtime via CLAPILOT_LIVE_TOOLS.

Calendar

The same five calendar_* contracts are also available to the native ClapilotAICore runtime via src/lib/agent-runtime/tool-proxy.ts and the native tool catalog in services/clapilot-agent/src/sessions/index.mjs.

calendar.event.updated payloads now also preserve deadline metadata, Google conference fields (google_conference_url, google_conference_data), and provider-agnostic conference fields (conference_url, conference_provider) on calendar records so the Kalender module can render Fristen with countdowns, critical badges, source labels, Mandant context, and generated meeting links without a full reload.

The calendar page also subscribes to /api/calendar/live, which is fed from Postgres LISTEN/NOTIFY on calendar_entries, so visible event moves still animate even when the change originated outside the current chat/live-agent stream.

Google Meet

Aufgaben

The same aufgaben_* contracts are also available to the native ClapilotAICore runtime via src/lib/agent-runtime/tool-proxy.ts and the native tool catalog in services/clapilot-agent/src/sessions/index.mjs. Privileged service-principal sessions without a linked user can operate on shared boards and tasks; their task visibility queries use a nullable user scope and do not expose private boards. Persisted principals must still be active when execution begins; disabling one immediately removes its global task permission. A persisted active service principal is a complete system-automation identity even when the automation intentionally has no Team Chat room or user, so first-party jobs such as Morning Briefing can call media tools without fabricating a room membership. Caller-supplied principal fields do not establish that identity, and cross-session delegation is allowed only when both sessions persist the same principal ID. In Team Chat, the validated room service principal is the resource scope: task reads and mutations can see shared boards only, while the verified room member who triggered the turn remains the audit actor (erstellt_von). Team-created tasks receive a non-null unique source_id with source_type='team_chat'; web and Apple Aufgaben details show that localized Team Chat origin and link back to the originating room. Private boards are never borrowed from whichever member happened to send the latest message. Every successful shared-board task mutation publishes the returned UI actions as one audience-scoped mutation row visible in every user's live stream, avoiding per-user write and storage amplification while keeping open Aufgaben views synchronized for both user-bound and userless privileged execution. Creating a shared board and changing the workspace-global task statuses publish the same all-user reload so mounted board and status controls update immediately. Private-board mutations remain scoped to their owning user's stream. When a task moves from shared to private, former shared viewers receive only a removal action from an audience row that excludes the owner, while the owner receives the full private update on the owner-scoped stream; private task data is never broadcast. Once an ordinary all-user fanout reaches users, the direct response suppresses its duplicate UI action. Execution authorization and mutation audience use the same resolved task scope, so a user-bound shared mutation is not mistaken for private traffic and a private mutation cannot become a global broadcast. Task mutation actions carry semantic announceKey values localized by each receiving German, English, or Italian client. Aufgaben detail views merge partial live task records with the loaded record so fields omitted by agent-tool UI actions, such as attachments, remain intact; an active editor rebases untouched draft fields onto each live snapshot while preserving fields the user changed, preventing a later save from reverting concurrent agent updates. The Aufgaben list refetches the complete task record before applying a mutation so Mandant and source metadata remain searchable and visible, and per-task request ordering plus abort guards prevent a stale refetch from restoring a deleted task or overwriting a newer mutation. While the Apple Aufgaben screen is visible, iOS and macOS force an initial load and refresh the lightweight task snapshot every five seconds; open native details apply the same untouched-field rebase during editing, reconcile external changes, and close after external deletion, while transient polling failures retain the last usable snapshot. Tool-proxy responses expose the nested tool result at top-level ok as well, allowing ClapilotAICore to classify normalized failures correctly; handled failures retain the stable default code="tool_error" unless a more specific contract code overrides it, and serialization failures fail the top-level result with code="CLAPILOT_TOOL_OUTPUT_SERIALIZATION_FAILED". Uncaught proxy failures are logged server-side and normalized using the persisted session language into the standard JSON output { "ok": false, "message": "...", "code": "CLAPILOT_TOOL_EXECUTION_FAILED" }; raw database/runtime messages and codes are not exposed to the agent or user. Non-privileged calls that require an absent user context return code="CLAPILOT_NO_USER_CONTEXT".

The Aufgaben board renders the task_statuses.sort_order configuration. Category semantics are open, in_progress, waiting, and done; all non-done categories count as unfinished. The stable wiedervorlage key retains its special follow-up-date behavior only while that optional status exists.

Task list/detail payloads now also carry origin-traceability fields: source_type, source_id, optional source_label, optional source_url, and source_context_snapshot.

Mandanten

The same mandanten_* contracts are also available to the native ClapilotAICore runtime via src/lib/agent-runtime/tool-proxy.ts and the native tool catalog in services/clapilot-agent/src/sessions/index.mjs.

Cases

E-Mail Drafts

Geplante Aufgaben

scheduled_tasks_get returns recent agent_runs plus agent_events for the automation session. Native system automations that perform housekeeping without a model-backed conversation write compact job.completed / job.failed events so agents and the UI can still inspect whether the job actually ran. Scheduled-task reads overlay current agent_jobs state for native-backed rows so next/last run data remains fresh even if the compatibility row has not been resynchronized yet.

Single-command automations have a deterministic execution contract: when an unchained agentTurn prompt explicitly asks for exactly one command whose executable is below /app/workspace, using either the backtick form or the canonical unquoted Führe exakt dieses Kommando aus: /app/workspace/... form, ClapilotAICore bypasses provider inference and runs one exec_command step. Shell composition and ambiguous/multiple commands are not eligible. The runtime always injects the active CLAPILOT_SESSION_KEY, persists the command in tool_calls, records nativeToolSteps=1/maxToolSteps=1 plus matching tool events, and accepts either a user or service-principal execution identity. A non-zero exit or timeout fails the run with a concrete tool_error / tool_timeout; a successful .clapilot/agent-media/<owner>/... audio path is retained as the delivery attachment source.

Bundled automations and bundled specialized agents are shipped records marked with is_bundled and a stable bundled_key. They are listed in separate UI sections, are editable where the normal settings surface allows it, but are never deletable through UI, live tools, native tool proxy, or API routes. The bundled agent-orchestrator-supervisor automation is the control surface for the Orchestrator supervisor interval/enabled state, while the matching bundled specialist stores the supervisor model/default prompt.

The /geplante-aufgaben editor can also call /api/scheduled-tasks/profile-icon to generate and persist an optional profile_image_url for an automation. The generated avatar prompt applies the Clapilot tint palette/style guide; the saved URL is used in automation rows, the create/edit dialog, and automation result chat bubbles via message_meta.assistantAgentProfileImageUrl.

The same scheduled_tasks_* contracts are also available to the native ClapilotAICore runtime via src/lib/agent-runtime/tool-proxy.ts and the native tool catalog in services/clapilot-agent/src/sessions/index.mjs.

Heartbeat runs are intentionally not a tool contract. Per-user and Teamchat heartbeats are runtime-owned agent_jobs rows (job_type='heartbeat') configured through GET/POST /api/heartbeat/settings and manually triggered through POST /api/heartbeat/trigger (proxying native POST /internal/heartbeat/trigger). They are excluded from the native /internal/jobs listing and from the scheduled_tasks_* tool surface. A heartbeat run wakes the agent with recent per-scope context and posts into the user's main personal chat or the configured Teamchat room only when the run produces an actual message; runs that answer with the NO_MESSAGE token are suppressed and reported as suppressed in the heartbeat status. For agent-initiated one-shot wake-ups, chat_wakeup_create (above) remains the contract.

Widgets

The existing mini_apps_* contracts remain supported, and the native ClapilotAICore runtime now also exposes widgets_* aliases via src/lib/agent-runtime/tool-proxy.ts and the native tool catalog in services/clapilot-agent/src/sessions/index.mjs.

Widget hub distribution (/api/widget-store/catalog, /api/widget-store/publish, /api/widget-store/install) and specialized-agent hub distribution (/api/agent-store/catalog, /api/agent-store/publish, /api/agent-store/install) are currently Store/admin UI / HTTP API workflows and are intentionally not exposed as dedicated live or native agent tool contracts yet.

Microsoft 365 app connections (/api/integrations/microsoft/**) are currently a signed-in user UI / HTTP API workflow under Settings -> App Verbindungen. Enabled Microsoft Mail is merged into the personal inbox through /api/emails, including Graph-backed global search across Outlook custom folders/subfolders when emails_list_messages searches without a folder. Enabled OneDrive files are imported into the virtual Microsoft 365 document folder, and chat receives connection-status context, but dedicated live/native Microsoft sync tools are intentionally not shipped yet.

Apple iCloud app connections (/api/integrations/apple/**) are currently a signed-in user UI / HTTP API workflow under Settings -> App Verbindungen. Enabled Apple Mail is merged into the personal inbox through /api/emails with provider-prefixed apple: message ids and can send through the saved iCloud SMTP credentials; calendars sync via CalDAV and contacts load through CardDAV. iCloud Drive and Apple Notes are intentionally not exposed as server-side sync tools because Apple does not provide a Google Drive/OneDrive-style public API for the user's whole Drive or Notes store; Reminders require a native EventKit bridge rather than the server-side iCloud connection.

The legacy LinkedIn content workspace module has been replaced by the bundled Social Media module (bundled-modules/social-media), which ships the dedicated social_media_* tool family documented above. LinkedIn posting is now covered through that family (targets with platform=linkedin); no separate linkedin_* tool contracts exist.

The bundled Terminal module (/modules/terminal and /api/admin/terminal/**) is intentionally not exposed as a live/native agent tool. It provides direct Bash access to the Clapilot web container and is reserved for Developer-mode interactive admin maintenance/debugging with session lifecycle audit events. Agents that need shell execution should continue using their existing native runtime shell/tool contracts rather than this UI-only terminal.

The Agent Orchestrator's capability-gated Terminal detail mode does not change this boundary. It is a read-only projection of command and terminal events already emitted by a coding session through the existing detail and SSE contracts; it is not an agent tool and cannot start arbitrary shell commands.

Agent Orchestrator coding runs use the coding_core Clapilot tool profile across local Codex, Claude Code, and Clapilot Code/embedded-PI harnesses. The profile keeps repository primitives in the harness itself and exposes read-only organizational recall through context_search, context_get, memory_search, memory_get, memory_grep, memory_describe, memory_expand, the read-only Knowledge and Learning tools, web_search, and runtime status reads. Its only Clapilot business-state mutation is aufgaben_add_comment, which is server-bound to the exact originating Symphony task so the coding agent can record implementation results, validation, blockers, and questions. memory_store, generic tool_catalog_search/tool_execute, navigation, UI rendering, delegation, email, calendar, all other task mutations, note, and document actions are excluded. This is a real callable-tool boundary rather than prompt-only guidance: detached Claude/Codex CLI jobs receive the same restricted MCP catalog, while embedded-PI receives the corresponding native profile plus exec_command, package_install, and agent_todo_update for repository work.

X app connections (/api/integrations/x/**) remain connected under Settings -> App Verbindungen. Native ClapilotAICore sessions can publish through the dedicated x_create_post tool, which uses the current user-scoped X OAuth integration, enforces the existing tweet.write/tweet.read/users.read scopes through createXPost(...), and returns the tweet id plus public URL only after X confirms creation. The bundled clapilot-x skill (workspace-seed/skills/clapilot-x) remains available for broader X HTTP API workflows such as media upload, mentions/timeline reads, and profile lookup.

The X integration status is self-healing: getXIntegrationStatus(...) transparently refreshes an expired access token when a refresh token is stored (single-flight per user, with a 5-minute retry backoff after a failed refresh), so the status card, the chat user context, and the context_status tool all report post-refresh reality instead of a stale expiry. needs_reconnect is true only when the connection is genuinely unusable: no row, missing default-preset scopes, or an expired token whose refresh failed (last_error then carries the X error). Both agent context surfaces ([Clapilot User Context] in /api/chat and xIntegration in context_status) additionally state that expired tokens are renewed automatically on use, so agents must call x_create_post directly instead of asking the user to reconnect while needs_reconnect is false.

reMarkable app connections (/api/integrations/remarkable/**) are currently a signed-in user UI / HTTP API workflow under Settings -> App Verbindungen. Agents do not connect or sync the account directly; they operate on the resulting read-only source notes inside Notizen and can create editable local copies through the dedicated duplicate-local tool.

Document workflow automation (/api/documents/[id]/workflow, backed by src/lib/document-auto-flow.ts and the document_workflow_automations table) is the document-side analogue of the email-detail automation flow. After extraction it derives a summary plus detected work items and, unlike the gated email reply flow, AUTO-EXECUTES them: it creates one or more aufgaben tasks (a meeting summary can yield several), an optional calendar_entries deadline/event, and an optional follow-up, then renders the result as the "Workflow" timeline in the document detail view (web + Apple). Each task is linked back to the document (source_type='document', source_url=/dokumente/{id}); calendar entries use source_origin='document'. To avoid duplicates the flow matches each suggested task against existing open tasks for the same client and tasks already linked to the document, and UPDATES a strong title match instead of creating a new row (repointing a manual task, or appending the document link to an email-sourced task). Execution happens server-side when the workflow is computed; it is idempotent via a per-document content signature. This auto-execution is intentionally NOT exposed as an autonomous live/native agent tool (no documents_* workflow tool is added) — it is an app/runtime behavior. Agents that should act on a document on explicit user request continue to use the existing read/create tools (documents_get, aufgaben_create_task, calendar_create_event).

Web Search

web_search is part of the compact native/embedded-PI tool surface, so local OpenAI-compatible models receive it directly instead of first discovering it through tool_catalog_search. It is also available through clapilot-cli web search --query "...", and Codex and Claude subscription bridges receive the same Clapilot-native web_search MCP/function surface in addition to any provider-native search capability their own harness may expose.

Ollama Search calls the configured enabled Ollama provider's web-search proxy. Local Ollama requires ollama signin; Clapilot tries /api/experimental/web_search and then /api/web_search for version compatibility. SearXNG calls /search?format=json and supports private HTTP endpoints or HTTPS endpoints. DuckDuckGo scrapes the key-free HTML results page and is intentionally best effort because anti-bot challenges and markup changes can interrupt it.

News

The same news_* contracts are available to Live Voice / Realtime through src/lib/live-voice.ts, to /api/chat/live/tools, and to native ClapilotAICore sessions through src/lib/agent-runtime/tool-proxy.ts plus services/clapilot-agent/src/sessions/index.mjs.

Appointment Booking Tools

Public website specialist embeds may allow only the appointments_* tools needed for slot lookup and appointment requests. Internal appointment listing, appointment-type setup, weekly availability configuration, and pending-request confirmation remain signed-in Clapilot module/API capabilities. Confirming a pending appointment inside Clapilot sets its status to booked and sends the final customer confirmation email when the agent mailbox SMTP settings are configured.

Buchhaltung

The same accounting_* contracts are available to Live Voice / Realtime through src/lib/live-voice.ts and to native ClapilotAICore sessions through src/lib/agent-runtime/tool-proxy.ts plus services/clapilot-agent/src/sessions/index.mjs.

MM-Bridge

This is a read-only contract. Dependency and configuration failures are explicit (MM_BRIDGE_DEPENDENCY_MISSING, MM_BRIDGE_VISION_NOT_CONFIGURED, MM_BRIDGE_UNSUPPORTED_FORMAT) and never masquerade as an empty successful read.

Steuer-Manager

Native ClapilotAICore sessions expose all four contracts through src/lib/agent-runtime/tool-proxy.ts plus services/clapilot-agent/src/sessions/index.mjs. Live Voice / Realtime intentionally exposes only tax_manager_list_generations and tax_manager_get_generation; extraction and finalization run through the specialized Steuer-Manager agent. The agent uses the returned extracted_text first and calls documents_get only when it is missing or empty; a document is unreadable only when both sources yield no usable content. The agent never calculates totals or report HTML itself, and the generated output remains an ELSTER transfer aid / tax-adviser draft rather than ERiC filing or tax advice.

Social Media

Social Media AI generation resolves the signed-in user's durable content strategy and optional weekly focus before drafting or regenerating content. The weekly focus is stored separately through the module's GET/PUT /weekly-prompt API and acts as current context without rewriting the strategy.

The streamlined review workspace uses the global Settings image default for manual image generation unless the user selects Grok Imagine, which passes model=grok-imagine-image-quality to the existing generated-images API. This is a UI choice and does not change the social_media_* tool schema.

The same social_media_* contracts are available to Live Voice / Realtime through src/lib/live-voice.ts and to native ClapilotAICore sessions through src/lib/agent-runtime/tool-proxy.ts plus services/clapilot-agent/src/sessions/index.mjs. Publishing is real outbound delivery: agents must not claim a post was published unless social_media_publish_post returned per-platform results with remote ids/URLs, and per-platform text limits apply (X 280, Bluesky 300, Mastodon 500, LinkedIn 3000, YouTube 5000 description; a YouTube target requires exactly one attached video). x_create_post (see the X app-connection note below) stays reserved for standalone X replies/quotes outside the Social Media workflow; multi-platform posting goes through social_media_*. Page capabilities (services/clapilot-agent/src/page-capabilities.mjs) add a module action rule when /modules/social-media is open and a global hint that routes social-posting requests to this family from anywhere in the app.

Whiteboard

Whiteboard tools run through src/lib/agent-runtime/tool-proxy.ts with the authenticated user's module API token. services/clapilot-agent/src/page-capabilities.mjs uses the module page context's active boardId for references to “this board” and steers visual mutations to whiteboard_* instead of chat-only mockups. The Whiteboard rule explicitly routes UML, flowcharts, and architecture diagrams to shape and attached-arrow primitives so local models do not substitute text-art boxes or an unnecessary generated image. The web renderer shows a localized unavailable-source placeholder for legacy/corrupt image items instead of a browser broken-image icon. The same contracts are registered for Live Voice in src/lib/live-voice.ts and for CLI use through the generated clapilot-cli-whiteboard skill.

Excel Spreadsheet Editor

Word Document Editor

Legacy .doc inputs are supported by the Word document editor module API through a first-open conversion to .docx; after conversion the dokumente.file_path, MIME type, and file size are updated before tool reads or writes continue.

Canvas

In agent-facing routing, plain "Canvas" means the free-form Canvas HTML module. The Word document editor, Excel spreadsheet editor, and Website Canvas are neighboring surfaces and should only be selected when the user explicitly names that surface or the active UI context is already there.

While the Canvas module is active, images_generate and images_edit are removed from the current turn's tool surface unless the latest user message positively and explicitly requests an image asset. Negative instructions such as “kein Bild generieren”, “without generating an image”, “avoid generating an image”, and “never generate an image” remain blocked. The same decision is enforced at the tool-proxy boundary through a random run-scoped execution capability, so a shell-spawned CLI cannot bypass it by changing or clearing session metadata; the capability remains isolated to that originating run and therefore does not restrict legitimate image work in another concurrent chat for the same user. If a live steer changes this scope during a Codex subscription turn, the active turn is interrupted and its pending promise is settled before the old bridge session closes, allowing the message to restart immediately with the refreshed tool catalog. Existing Canvas files must be loaded before mutation and their content preserved unless the latest request explicitly replaces or removes it. Adding another profile, section, or slide to an open shortlist/deck updates the active file and must not create a second Canvas file. Completion may only be reported after the corresponding Canvas mutation tool succeeds in that run.

Images supplied with the current request are transiently exposed through canvas_get_turn_assets, mapped to explicit presentation slides, and embedded as existing URLs; this path must not route to images_generate. In active Canvas context the runtime also hides and rejects detached image generation unless the latest request explicitly asks for a separate standalone raster asset. Before a broad presentation redesign, canvas_duplicate_file preserves the exact open deck as a new selected version, after which the agent changes and visually verifies one named example slide before requesting approval for wider rollout. The latest user request and active page context are authoritative, and success may only be reported after a Canvas mutation succeeds in that turn.

For rebuilds, the latest user instruction plus pageContext.activeFilePath and canvasTitle are the source of truth; retrieved memory and older turns are reference-only and cannot replace the active presentation. The agent duplicates the active source, leaves that source untouched as backup, transfers only request-relevant decisions, and stops after one rendered example slide until the user explicitly approves applying the design system to the remaining slides.

Canvas tools are native ClapilotAICore tools exposed through src/lib/agent-runtime/tool-proxy.ts and services/clapilot-agent/src/tool-definitions.mjs. They are the canonical path for agent-created HTML visualizations; agents should not use raw shell writes for normal Canvas edits. For localized changes to an existing file, canvas_edit_file applies exact string replacements (loaded via canvas_get_file) without regenerating or restyling the document; canvas_update_file is reserved for full rewrites. canvas_create_file, canvas_update_file, and canvas_create_template apply the instance-wide Canvas style to agent-authored HTML by default. The optional use_canvas_style=false flag is reserved for cases where the user explicitly supplied or requested a custom preserved style. Before authoring fresh Canvas HTML (unless the user supplied an explicit style or template), agents MUST read the brand tokens with canvas_get_style_settings and build colors, fonts, headings, boxes, tables, and the logo from them; canvas_update_style_settings changes that instance-wide default (with reset=true restoring the Clapilot styleguide) and is reserved for explicit user requests. Both style tools belong to the native canvas tool family/bundle, so they are exposed together with the other canvas_* tools whenever the Canvas family is routed or expanded — including from the main chat — not only while the Canvas module is open. Canvas templates are stored separately from Canvas files, so agents must not treat an empty canvas_list_files result as proof that no template exists. For recurring documents, agents should first use canvas_list_templates/canvas_get_template, then canvas_create_file_from_template; when the UI context has activeTemplateId, canvas_get_template and canvas_create_file_from_template may omit template_id. When a user uploads a source layout and asks Clapilot to learn it, the agent should refine or replace the uploaded draft via canvas_create_template using semantic {{field}} placeholders. When a user asks for a PDF export of the open Canvas file, agents should call canvas_export_pdf so the result lands in Documents. Canvas sharing is owner-controlled: canvas_share_item makes a file, folder, or template visible and editable for every user in the instance (folders share their whole subtree), while canvas_unshare_item revokes a share and, like deletion, is restricted to the owner. Shared records use the canonical agent reference shared:<path-or-template-id>; the tool proxy strips that marker and forwards ?shared=1, and an open shared Canvas publishes the same reference as activeFilePath. Canvas list/get responses (canvas_list_files, canvas_get_file, canvas_list_templates, canvas_get_template) include shared and owned_by_me per record, so agents can edit shared content but must check ownership before attempting an owner-only unshare or delete.

The optional onboarding "templates" step reuses these same tools rather than adding new ones: POST /api/onboarding/templates enqueues a one-off, user-owned background agent run (via createScheduledTask) that calls documents_get to read each selected or uploaded document and canvas_create_template to author one reusable template per document. The run's final reply is delivered to the user's main session (chat + push) through the standard scheduled-task notify target, so generated templates surface in Canvas with a completion notification without any onboarding-specific tool contract.

Call & Fax Agent

The same call_agent_* and faxes_* contracts are available to:

• Live Voice / Realtime via src/lib/live-voice.ts
• /api/chat/live/tools
• native ClapilotAICore sessions via src/lib/agent-runtime/tool-proxy.ts
• services/clapilot-agent/src/sessions/index.mjs

DGX Cluster telemetry

Model training

Specialized agents in chat

Native-only specialist management and delegation tools

The main/default native runtime treats day-start briefings, updates, overviews, analyses, search results, prioritization requests, and multi-step workflow summaries as preferred copilot_ui_render opportunities when 2-6 clear next actions exist. The runtime still avoids artificial follow-up cards when the answer is complete or no meaningful choices are available.

Canonical tool lifecycle events may include todoList: Array<{ id: string; label: string; status: "pending" | "active" | "done" }> alongside fields such as uiActions. Every update replaces the complete list. Producers trim labels to 200 characters, drop empty labels, cap lists at 20 items, and omit the field when no items survive normalization. Claude CLI maps both TodoWrite and full task-tool snapshots maintained from TaskCreate/TaskUpdate, Codex app-server maps turn/plan/updated (step, pending|inProgress|completed) and defensively recognized plan-tool payloads, and native/embedded PI maps agent_todo_update (label, pending|active|done).

The one-shot missed-render retry is limited to human-facing chat runs; when an assistant reply itself ends with an actionable choice follow-up but no card was rendered, the retry event uses the reason unrendered_choice_followup_in_reply.

Native-only tool catalog expansion

Rules:

• Native Ultra chats always retain tool_catalog_search and tool_execute, independent of the message text. This lets workspace policy trigger a real capability lookup when the small routed schema set omits the needed family, without introducing entity-specific answers or deterministic chat-intent routes.
• These specialist-management and delegation tools are exposed only to the main/default agent path.
• specialized_agents_* is admin-only and main-agent-only. The tools check the linked session user's user_profiles.role before mutating the catalog.
• Specialized agents do not receive delegate_to_specialized_agent, spawn_clapilot_subagents, or specialized_agents_*, even if an admin tries to add them to their explicit tool allowlist.
• The specialized_agents_create and specialized_agents_update tool schemas intentionally do not accept Telegram/WhatsApp channel tokens or other secrets. External channel links stay in the settings UI and channel-specific admin routes.
• The delegate_to_specialized_agent tool schema accepts handle or agent_id, required message, and optional base64 attachments[].
• spawn_clapilot_subagents accepts tasks[] with required message, optional label, optional model, optional provider, optional strict allowed_tool_names[], and optional base64 attachments[]; top-level model and provider are defaults for tasks that omit them. The tool is for generic temporary fan-out. It must not be used when the user specifically asks for a configured specialist identity.
• The admin specialized-agent settings UI now reads /api/agent-runtime/tool-catalog, which mirrors the native tool inventory from services/clapilot-agent/src/sessions/index.mjs and marks delegate_to_specialized_agent, spawn_clapilot_subagents, plus specialized_agents_* as visible but not selectable for specialist allowlists.
• The same settings UI now also reads /api/agent-runtime/auth-catalog, which exposes the configured provider/runtime auth scopes as a dedicated picker separate from tools and skills.
• The specialist editor groups the permission/tool catalog by category and lets admins select a whole group, such as Agent Orchestrator, in one action. It also exposes select-all/clear actions for tools, skills, and available auth/API scopes.
• Local skill entries may declare required_tool_names[] and required_auth_resource_keys[] in SKILL.md frontmatter. When an admin selects such a skill for a specialist, the editor automatically adds the selectable tool permissions and available auth/API scopes needed by that skill, while still showing missing/unconfigured auth scopes as setup work.
• browser_use_run executes an explicitly requested complex web task through Browser Use Cloud V4, resolves the encrypted browser_use_api credential only on the server, and copies generated remote workspace files into the shared Clapilot workspace. The bundled clapilot-browser-use skill declares both the tool and auth resource; ordinary lookup should continue to use web_search.
• Specialist sessions now persist allowed_auth_resource_keys[] and include_core_memory_tools in addition to allowed_tool_names[], so access to stored provider/runtime secrets can be scoped independently from tool exposure.
• Public website/API-key specialist runs do not inherit specialized_agents.allowed_tool_names[], Core Memory, auth scopes, or runtime-bypass settings. They use only specialized_agent_embed_deployments.public_allowed_tool_names[] after the public-safe filter; an empty public allowlist means zero public tools.
• Specialists can now also persist an optional default_model_ref. Resolution order is: explicit tool/runtime override, then the specialist default model, then the active chat/session model, then the normal global runtime default.
• Specialists can now also be linked to external channels from their admin settings. A per-agent Telegram bot token is stored encrypted and polled by clapilot-agent; inbound messages for that bot run inside the linked specialist's prompt/tool/auth envelope. WhatsApp uses the same QR-based WhatsApp Web flow as ClapilotAICore -> Kanäle, but with a specialist-scoped auth directory and socket; after the QR scan, the runtime derives the linked number (selfE164) and stores it back on the specialist for display/routing metadata. Specialist Telegram/WhatsApp approvals are listed and decided in the specialist settings, not the global channel settings, and do not require mapping the external thread to a Clapilot user. Per-agent allow_without_approval switches can bypass approval while still executing in the specialist's isolated prompt/tool/auth envelope.
• The default specialist memory/session tools are no longer hardwired. Admins can disable the entire Core-Memory bundle for stricter public or sandboxed specialists while still selectively granting other tools.
• Runtime enforcement blocks specialist tool calls that need stored media auth when the matching runtime scope is missing. images_generate and images_edit require image_generation_runtime; videos_generate and videos_status require video_generation_runtime; media_tts_speak and media_register_audio require tts_runtime; and media_stt_transcribe requires stt_runtime. The selected provider credentials are resolved server-side and never reach the agent, so a media-runtime grant covers any enabled provider for that capability and does not also require a provider-API scope.
• Holding a runtime grant now also entitles the specialist to that runtime's first-party tools at runtime: buildSpecializedAgentAllowedToolNames unions the granted auth resources' relatedToolNames (for example tts_runtime → media_tts_speak/media_register_audio, stt_runtime → media_stt_transcribe, image_generation_runtime → images_generate/images_edit, video_generation_runtime → videos_generate/videos_status) into the effective allowedToolNames. Granting the runtime is sufficient; the tool checkbox does not need to be re-saved separately.
• Clapilot now ships a bundled @pet-creator specialist backed by the seeded clapilot-pet-creator skill. It is enabled by default, appears in Settings -> Agent -> Spezialisierte Agenten, and is intended for Profile Pet still-image prompts, generated preview/source images through images_generate/images_edit, laptop-working animation prompts, and registering generated pets through profile_pets_register so they appear in Settings -> Profile -> Pet. If activity_image_id is omitted or static, the register handoff derives the app-facing transparent looping laptop-working GIF from preview_image_id. Its default media auth is scoped to image_generation_runtime, openai_api, google_gemini_api, xai_oauth, xai_api, and codex_oauth.
• In Settings -> Agent -> Spezialisierte Agenten, admins now manage specialists from a list view with a Neuer Agent button; create/edit opens in a dedicated dialog instead of keeping the full setup form expanded inline.
• The same specialist editor now has a Capability Graph option beside the normal form. It uses the React Flow canvas pattern from automations, but its nodes are capability bindings rather than directional execution steps: the center specialist node connects to selected Skills, grouped Tool capability families, Auth/API resources, and the optional Core-Memory capability. Exact tool grants such as read/write/get/create remain stored in allowedToolNames and are toggled from the grouped tool node inspector. Adding, moving, right-click deleting, or removing graph nodes writes the existing skillKeys, allowedToolNames, allowedAuthResourceKeys, and includeCoreMemoryTools fields, so it does not introduce a separate graph schema or runtime contract.
• The specialist editor now stores a profile_image_url. New or reset specialists receive a deterministic built-in SVG fallback avatar derived from name, handle, and description so lists, Team Chat, and assistant bubbles never render a broken generic state when image generation is unavailable. The editor can call /api/specialized-agents/profile-icon to generate a square avatar from the specialist name, handle, description, and prompt through the configured image-generation runtime, or upload a PNG/JPG/WebP data URL up to 2 MB. The generated avatar prompt applies the Clapilot tint palette/style guide so avatars share the same indigo, soft-blue, violet, slate-blue, pale-blue, and pale-lavender visual language; the saved URL is then used in the Agenten segment under /geplante-aufgaben?view=agents, the add/edit dialog, Team Chat's Agents rail, and specialist assistant bubbles. Image-generation failures are shown as a user-facing retry/upload message instead of raw provider result text.
• The Store now has a Special Agents tab backed by the same admin-only Agent Hub workflow as the specialist settings. Publishing creates a versioned JSON snapshot with only the portable specialist definition (prompt, model, selected skills, explicit tool allowlist, auth scope keys, and Core-Memory flag). Installing from the hub creates or updates the local specialist but never imports embed API keys, public deployment settings, secrets, or the runtime-permission-bypass flag.
• The same specialist dialog now also contains an Embed & API Keys section where admins can create one restricted public/embed deployment per specialist, define public_slug, toggle enablement, decide whether that public widget should expose file uploads, maintain an origin allowlist, and mint or revoke per-agent publishable API keys plus an HTML snippet template for future external website embeds. Specialist settings also include an explicit allow_runtime_permission_bypass flag; it is off by default and must be enabled before a signed-in specialist run may launch Codex or Claude CLI bridges with full filesystem/shell bypass permissions.
• Embedded specialists now also have a dedicated public runtime path outside the signed-in chat APIs: /api/public/agents/[slug] for widget bootstrap metadata and /api/public/agents/[slug]/messages for isolated message execution with X-Clapilot-Embed-Key plus origin allowlist enforcement. Public embed runs now also execute with a dedicated restricted service principal, use a public-facing specialist runtime prompt instead of the normal internal Clapilot-Core prompt, and explicitly strip user-scoped/internal tool families such as calendar, documents, tasks, notes, mail, Website Canvas, Agent Orchestrator, shell/package install, and other private workspace tools even if an admin accidentally selected them on the specialist, because anonymous website visitors do not carry a signed-in Clapilot user context. Public embeds always force the safe bridge permission mode: Codex subscription bridge sessions use a read-only sandbox, and Claude CLI bridge sessions run without bypassPermissions plus deny built-in filesystem/shell tools. The public runtime is also intentionally stateless on the hidden server side: it does not replay stored specialist history or hidden bootstrap context between turns, so a website visitor cannot inherit internal session context through the embed. The public /messages endpoint now also supports streamed NDJSON output for real-time assistant deltas, and the shipped website widget/module at /embed/agent.js consumes that stream so assistant replies appear live while they are generated instead of only after the final response is complete. The widget keeps only a lightweight browser-local sessionId, auto-renders as a floating launcher by default, exposes window.ClapilotEmbeddedAgent.mount(...) for host pages that want inline mounting plus configurable title, colors, launcher behavior, sizing, and custom loading-animation assets, and renders assistant replies with built-in markdown formatting for common website-chat output such as bullet lists, emphasis, links, and fenced code blocks. Public embed traffic is now additionally guarded before runtime execution by server-side abuse controls: obvious prompt-injection / system-prompt extraction attempts, obvious secret/credential exfiltration requests, and obvious internal activity/workspace probing requests are blocked with a safe assistant reply, and each public deployment enforces fixed per-IP session/message limits so one visitor cannot spin up unlimited public website sessions.
• Specialists without the default Core-Memory bundle now also execute internally with a lighter hidden envelope: the runtime no longer replays stored specialist history for those runs and stays on the ultra-light tool/context profile, so a narrowly scoped subagent with only one or two explicit tools does not silently inherit broader session context.
• The end-user-friendly Agenten hub is part of the combined /geplante-aufgaben workspace behind the top segmented control (/geplante-aufgaben?view=agents). It lists all specialists in compact outlined rows, highlights currently running specialist sessions in the header area, lets rows expand into recent visible specialist run history, and opens the same specialized-agent editor used by Settings -> Agent -> Spezialisierte Agenten for admin create/edit actions so sensitive controls such as runtime permission bypass and public embed/API-key setup stay centralized behind admin-only UI gates.

Specialist transcript metadata

Specialized-agent replies reuse the normal persisted chat tables but now carry agent identity inside message_meta.

Current specialist metadata fields:

• assistantAgentId
• assistantAgentHandle
• assistantAgentName
• assistantAgentProfileImageUrl
• delegatedByAgentId
• delegatedByAgentName
• invocationType with mention or delegation

Current personal-chat assistant origins:

• assistant_automation
• assistant_specialist
• assistant_specialist_delegated
• assistant_async_callback

Current rendering contract:

• direct @agentHandle invocation posts one visible pending specialist assistant bubble per target immediately and finalizes each later from its detached specialist task; Team Chat accepts multiple explicitly mentioned invited targets in one turn, while personal chat remains single-target
• main-agent delegation posts one visible pending specialist assistant bubble immediately; once the detached specialist finishes, the chat also receives a later main-agent callback bubble with the follow-up answer that uses the specialist result

Channels

Successful channel_send_message calls return { channel, recipient, text, media_count, target_label, approval_id, subject_key, group_room_id, mirrored_room_id }. group_room_id is the matched Clapilot Team Chat room id when the approved target maps to a room. mirrored_room_id is set only when that outbound message was actually mirrored into the room; automation delivery deduplication uses this field. Successful calls are also recorded into the target conversation's runtime context when approval metadata maps the recipient to a Clapilot conversation. Telegram media sends include internal workspace file references so follow-up questions can reason about the delivered files. A tool send to an instance_bridge target is delivered to the peer Clapilot instance as an agent-kind bridge message (raw text plus attachment-name placeholders in v1); the peer mirrors it as an agent message and never triggers its own agent run from it.

Automatic automation-result delivery reserves a durable Run-ID + physical-target key before any external channel provider call. Retries that encounter an existing reservation are treated as duplicates, including after an ambiguous provider timeout, so a callback cannot repeat an external side effect. Explicit agent sends made during an automation remain independent messages. Their Team Chat mirrors carry the automation Run ID only after persistence; when a mirror request times out ambiguously, the automatic final-result path waits briefly for that persisted row before deciding whether it still needs to deliver the configured result. Team Chat automation delivery also preserves the persisted service-principal media owner end to end: owned TTS paths become authenticated audio attachments, and owned /api/generated-images/<id> Markdown is materialized as a durable image attachment before the user-scoped source URL is removed.

Reverse Team Chat forwarding calls the same /internal/channels/send contract with messageOrigin: "team_chat_forward". That origin preserves the external provider send but suppresses sendOutbound's normal Team Chat mirror, preventing the forwarded message from creating a duplicate row in its source room. When a Telegram reverse-forward contains both text and media[], this origin also sends the text first and then the media items; other outbound origins keep the normal media-first order.

The embedded ClapilotAICore webchat runner reuses the same proxy path for native runtime tools. When a chat run uses the embedded agent loop instead of the plain /internal/runs tool executor, exec_command, context_search, context_get, memory_search, memory_store, memory_get, memory_grep, memory_describe, memory_expand, knowledge_search, knowledge_get_entity, knowledge_neighbors, knowledge_explain_claim, learning_search, learning_get_object, and session_status are forwarded through /api/agent-runtime/tool-proxy to clapilot-agent POST /internal/tools/execute.

Main-agent capability restrictions are fail-open and opt-in. With the default app_settings.main_agent_tool_restrictions_enabled = false, no tool is removed, hidden, or rejected for the built-in main agent; every configured Clapilot tool remains reachable through the active native or skill/CLI surface. Enabling the setting applies only the explicit app_settings.main_agent_disabled_tool_names denylist. Admins manage that list under Settings → ClapilotAICore → Runtime → Tool Surface, where the collapsed catalog supports group-level and per-tool allow/block switches. Module installation state and Canvas intent detection no longer implicitly override the main-agent selection. Specialized-agent allowlists, module/context gates in specialist runs, auth-resource scopes, signed-in user authorization, service-principal permissions, and public embed boundaries are separate security controls and remain enforced regardless of this setting.

Native tools in direct human-facing chat turns run inside a configurable tool-phase budget; background workloads (jobs, automations, channel runs, orchestrator turns) are exempt and may run tools without a budget. There is no total direct-chat budget and no implicit whole-conversation timeout. A still-running budgeted tool produces periodic tool.progress events with the tool name, call ID, and elapsed turn time. Phase-budget expiry terminates the chat run with PHASE_BUDGET_EXCEEDED and passes an abort signal into the tool. User-requested run cancellation uses the same signal for foreground and background runs. Active rows first enter cancelling; local shell tools terminate their complete process group with SIGTERM and a SIGKILL fallback, and only the run finalizer writes cancelled. The abort endpoint waits for that finalizer and reports an unconfirmed cancellation as an error, preventing callbacks and post-response file actions from treating a still-running worker as stopped. Provider requests receive the abort signal, while provider-side jobs that offer no cancellation API remain explicitly outside the confirmed local-process guarantee. Provider retries and fallbacks in direct chat keep their own independent phase safeguards.

When an interactive conversation aborts on a provider timeout or phase budget (PHASE_BUDGET_EXCEEDED) after producing text or completing a tool, ClapilotAICore writes a durable timeoutRecoveryCheckpoint into the session state before finalizing the failed run. The user-visible partial output contains a localized checkpoint summary and the latest completed tool names; the original request, bounded tool-result previews, Run ID, and adaptive model recommendation remain in the session state and replay history. On the next turn in that conversation, the runtime consumes the pending checkpoint and uses its recommended model for that recovery turn even when the original adaptive decision was recorded in shadow mode. A model explicitly supplied on the recovery request remains authoritative. Successful recovery clears the pending checkpoint and records the prior Run ID, so the recommendation cannot silently pin later turns. Older persisted TURN_BUDGET_EXCEEDED checkpoints remain readable for upgrade compatibility, but current runs no longer emit that code.

Channel-to-Team-Chat visibility uses the internal POST /api/agent-runtime/channel-mirror endpoint. It requires x-clapilot-agent-secret and accepts either a participant payload { kind: "participant", channelType: "telegram" | "whatsapp" | "slack", roomId, text?, attachments?, sender: { key?, name?, username? }, eventId?, subjectKey?, subjectLabel? } or an agent payload { kind: "agent", channelType, roomId, text?, attachments?, agentName?, sourceType? }. attachments is capped at 10 items; each item has { type: "image" | "file" | "audio", name, mimeType, relativePath, size?, durationMs? }, where relativePath is a workspace-relative path without traversal segments. At least text or one valid attachment is required. The web side verifies that every file is readable and contained by the configured shared workspace, then stores a cookie-authenticated file-explorer download URL in the Team Chat attachment. A successful agent write returns { ok: true, messageId, roomId }; a successful participant write returns { ok: true, messageId, roomId, specialistDispatched, suppressChannelReply }. Participant mirrors additionally run the same room-specialist dispatch as the web Team Chat: one or more explicit @handle mentions enqueue that complete invited target set in parallel and return suppressChannelReply: true when at least one specialist was queued (the channel runtime then skips its own default-agent conversation for that inbound message), while mention-free messages enqueue every invited all_messages specialist in parallel with the normal channel conversation. Specialist replies reach the external channel through the existing Team-Chat-to-channel forward path, which now prefixes forwarded agent messages with [<AgentName>] so multi-bot rooms stay attributable. Beyond that dispatch, the endpoint only persists the Team Chat display copy and sends the existing Team Chat push notification; it never appends the agent reply to the runtime session, because the channel runtime already owns that context.

Inbound WhatsApp audioMessage payloads use a separate transport preflight before that mirror/run boundary. clapilot-agent downloads the Baileys media bytes, writes a workspace-relative .clapilot/channel-media/whatsapp/... audio file, and calls the internal-secret-only POST /api/agent-runtime/channel-audio-transcription contract with { filePath, mimeType? }. The app resolves the configured STT provider/model server-side through the same transcribeAgentAudio runtime used by media_stt_transcribe, then returns { ok, transcript, provider, providerType, model }. The transcript replaces the channel placeholder for the agent run, while the persisted source becomes the mapped Team Chat audio attachment; provider credentials never cross into clapilot-agent.

For Anthropic-Claude subscription rows that execute through the Claude CLI bridge, these same Clapilot-native tool contracts are exposed into Claude through the runtime MCP stdio bridge. That means a subscription-backed Claude run can use Claude built-in tools such as Bash, Read, Grep, Glob, WebFetch, and WebSearch alongside Clapilot-owned MCP tools such as documents_list, documents_get, calendar_*, aufgaben_*, notizen_*, and the other native tool-proxy contracts listed on this page. The web chat surfaces those lifecycle events as clapilot.tool status lines inside the active assistant bubble.

For OpenAI-Codex subscription rows that execute through the Codex app-server bridge, normal chat turns expose the Clapilot-native contracts through a Codex MCP stdio bridge backed by /api/agent-runtime/tool-proxy. Agent Orchestrator coding turns use the restricted coding_core subset described above instead of inheriting normal-chat business actions. Codex app-server coding threads pass the current Clapilot session_key on each Clapilot MCP call; detached local CLI jobs inherit their job-scoped session identity in the MCP environment.

Generated Images

Generated Videos

Assistant replies that contain /api/generated-videos/<id> are verified against the signed-in user's generated_videos rows before persistence. Ready assets keep their links and render as inline HTML video players with native controls in chat; premature links become an honest generating status, and missing or failed rows cannot be presented as completed videos.

Video Studio AI

The module-gated native bundle is video_studio_ai. Its writes emit the video_studio_ai_updated action so an open Video Studio can refresh either the character catalog or one project. Reads do not emit a mutation.

Video Studio AI data is workspace-global: projects, scenes, characters, and character voices are shared across all users. Every tool reads and mutates the shared workspace set; owner_user_id is retained only as creator attribution on newly created rows. Read tools therefore also work in team/service-principal scopes without a resolved user id, while tools that create rows or submit provider jobs (video_studio_create_character, video_studio_create_ai_project, video_studio_regenerate_frame, video_studio_regenerate_scene_video, video_studio_start_generation, HTML-block renders, and portrait regeneration) still require an authenticated user for attribution and provider identity.

Live Voice / Realtime exposes the deliberately smaller subset video_studio_create_ai_project, video_studio_get_ai_project, video_studio_update_ai_project, video_studio_dub_scene, video_studio_add_scene, video_studio_delete_scene, video_studio_reorder_scenes, video_studio_regenerate_frame, video_studio_regenerate_scene_video, and video_studio_start_generation. The full eighteen-tool bundle remains available to native ClapilotAICore sessions and the normal Video Studio chat flow. Project deletion is intentionally excluded from Live Voice / Realtime.

Generated Audio (TTS/STT)

Video Studio's Feinschliff UI uses the same server-side TTS contract for post-production voiceover. It persists one audio file per scene and can regenerate a single segment, then remuxes those scene-aligned files without invoking HyperFrames. Provider secrets remain inside generateAgentSpeech(...); the browser only selects the provider family and voice.

First-party, server-side media so agents never need a provider API key, env variable, or extracted database secret. The provider key is resolved in-process from the configured TTS/STT Runtime (resolveTtsRuntimeConfig / resolveSttRuntimeConfig) and the rendered file is written into the shared /app/workspace volume, which clapilot, clapilot-agent, and clapilot-streamer all mount — so the agent's exec_command (ffmpeg / HyperFrames) can consume it by path. TTS may resolve OpenAI, Gemini, or an OpenAI-compatible /audio/speech provider; compatible providers may be authless and may use an exact manually configured gateway model alias. STT retains its separate provider allowlist and is not enabled merely because a compatible provider supports TTS. Agents reach these through clapilot-cli media tts-speak / clapilot-cli media stt-transcribe in skills mode, or as native tools in typed mode. This is the only supported path for first-party speech; agents must not call external TTS CLIs/APIs (including HyperFrames' own TTS) or read provider keys directly.

Website Canvas

website_ensure_session and website_apply_change accept an optional idempotency_key. Reusing a key with the same authenticated user, caller scope, and normalized operation payload while work is active or within five minutes after success returns the original operation; a key reused from another chat or for different work cannot collide with it. Failed operations release their keys immediately for retry. When omitted, the tool proxy derives a stable key from the tool/session arguments, except that each implicit force_new_session request receives a fresh key. force_new_session ignores a supplied prior session and always creates a new isolated checkout. Specialists granted either asynchronous starter automatically receive the companion website_get_operation status tool. Each status call waits for a terminal result for up to 20 seconds before returning queued/running. All-passive status batches do not consume the normal mutation/tool-step budget or trip the identical-batch guard, but they have a separate hard limit of 60 polls (up to 20 minutes of long-poll wait) so polling cannot run indefinitely. A single checkout-scoped mutation queue serializes asynchronous operations and direct ensure/sync/chat/commit/push calls against one shared repo or isolated checkout. Completed records remain queryable for eight hours. Operation status includes started, timestamps, the eventual result, or a structured failure; this makes proxy/client timeouts distinguishable from work that was never accepted.

Agent Orchestrator

These contracts are currently available to the native ClapilotAICore runtime via services/clapilot-agent/src/sessions/index.mjs and src/lib/agent-runtime/tool-proxy.ts. They are the preferred path for general repository coding, bugfix, branch, commit, and PR-preparation tasks outside Website Canvas.

The web Agent Orchestrator module and Settings -> Agent Orchestrator UI are hidden unless Developer mode is enabled; the native/tool-proxy contracts remain the backend integration path.

The Agent Orchestrator module API also exposes inspector contracts that are intentionally not native agent tools: GET /sessions/{id}/workspace and GET /jobs/{id}/workspace return ownership-checked, trusted-root, bounded Files/Changes snapshots for local coding workspaces, while GET /remote-runners/{runnerId}/codex-sessions and GET /remote-runners/{runnerId}/codex-sessions/{sessionId} provide remote-runner diagnostics. The only session mutation in this inspector family is POST /remote-runners/{runnerId}/codex-sessions/{sessionId}/follow-up with { message, model? }; it creates a decoupled Codex resume job pinned to that runner and is blocked by the shell-tools kill switch. The /remote-runners/* module API path accepts the existing Hub shared-secret HMAC and, for Fleet-managed runners, a per-machine HMAC whose x-clapilot-instance-id is the machine UUID. That Fleet credential is scoped to the remote-runner prefix and does not authorize other module APIs.

Symphony-dispatched coding jobs retain the originating aufgaben ID in symphonyTaskId. Their coding MCP session key carries the same task id in a server-validated scope. aufgaben_add_comment requires the full task UUID and rejects any id other than that scoped origin, including calls from ordinary coding jobs without a Symphony task. Symphony prompts direct the agent to comment immediately for blockers or concrete questions and once after implementation with changes, validation, and the PR/MR URL when available; comments are stored as autor_typ='agent', autor_name='Symphony', and identical text is deduplicated. Separately, when job output contains a newly opened GitHub PR, the backend writes a system comment with canonical PR URL, number, and open status to that task. The PR-link comment uses the task creator's persisted UI language (de, en, or it), falls back to the private-board owner and then German, and the write is transactionally URL-idempotent per task. It is independent of tracked-PR follow-up registration; distinct PR URLs remain visible as separate task comments.

Emails

Documents

Notizen

Wiki

Mandanten

Cases

The same cases_* contracts are available to Live Voice / Realtime through src/lib/live-voice.ts and to native ClapilotAICore sessions through src/lib/agent-runtime/tool-proxy.ts plus services/clapilot-agent/src/sessions/index.mjs. The module is optional; if the bundled module is disabled or unavailable, tool calls return the module API error instead of falling back to generic Mandanten/Dokumente/Aufgaben mutations.

Delegation

Intentionally not exposed

• The admin demo-data controls (/api/admin/demo-data) are intentionally not exposed as chat/live-agent tools, including the scenario switch between steuerberaterkanzlei and rechtsanwaltskanzlei and the destructive wipe_operational_data admin action.
• Reason: the flow is destructive, resets DB state, writes and deletes tagged IMAP mails in a real mailbox, and is meant to stay behind explicit admin UI confirmation.
• The athlete-brand-matching module-local state API (/api/modules/athlete-brand-matching/api/state) is intentionally not exposed as a chat/live-agent mutation tool yet. The iframe owns manual capture, CSV/JSON import, matching selection, and outreach state writes; agents receive page context only.

Live fallback behavior:

• Web and Apple Live clients now send the latest user utterance with each /api/chat/live/tools request.
• /api/chat/live/tools may automatically fall back from certain lookup-oriented direct tools (documents_*, mandanten_*) into clapilot_delegate when the direct tool path returns "not found" style results or an empty search result.
• Validation, auth, and transport/system failures are excluded from this automatic fallback so the agent can still ask a focused clarification or surface a real blocker.

Chat context actions

These are current agentic mutation shortcuts in /api/chat that are not part of the Realtime function catalog but still need to stay documented.

Native runtime internal tools

These are internal tools used inside the native clapilot-agent loop. They are not part of the Realtime function catalog, but the embedded ClapilotAICore webchat runner now reaches the same tool implementations through the internal tool proxy path. The stdio MCP bridge and the Codex MCP rescue path do not impose their own wall-clock timeout on a tool-proxy request, so long media and agent operations are not aborted after 30 seconds. Cancellation remains owned by the surrounding run/session and the native runtime's phase safeguards.

Parallel tool-call policy

ClapilotAICore does not globally enable parallel tool execution for every tool. The native provider loop only opts into parallel tool batches when every requested tool in that batch is read-only and explicitly allowlisted. Current parallel-safe tools are:

• memory_search
• memory_get
• memory_grep
• memory_describe
• memory_expand
• context_search
• context_get
• knowledge_search
• knowledge_get_entity
• knowledge_neighbors
• knowledge_explain_claim
• learning_search
• learning_get_object
• session_status
• clapilot_context_status
• documents_list
• documents_get
• emails_list_messages
• emails_get_message
• emails_list_drafts
• emails_get_draft
• agent_orchestrator_list_repos
• agent_orchestrator_list_jobs
• agent_orchestrator_get_job
• agent_orchestrator_list_sessions
• agent_orchestrator_get_session
• mini_apps_list
• mini_apps_get
• widgets_list
• widgets_get
• notizen_list_folders
• notizen_list_notes
• notizen_get_note
• wiki_search
• wiki_get_page
• excel_list_documents
• excel_read_document
• excel_read_cell
• word_list_documents
• word_get_document
• canvas_list_files
• canvas_get_file

Mutating tools like exec_command, package_install, Excel writes, Word writes, Canvas writes, and channel sends still run serially to avoid race conditions.

A runner terminates the complete process group on Unix and the complete process tree on Windows. It treats an authoritative terminal rejection (CLAPILOT_SHELL_TOOLS_DISABLED, invalidated claim, removed ownership, or missing job) as the server's acknowledgment and releases its local capacity; transport and server failures remain retryable.

exec_command and package_install are instance capabilities controlled by the hub-owned, per-instance CLAPILOT_SHELL_TOOLS_ENABLED setting stored with that Fleet instance's provisioning policy. Existing and fresh instances stay fully capable by default, including the normal full-capability Claude/Codex subscription bridge permission envelope. A Hub administrator can opt one selected instance out with the Shell tools toggle on that instance's Fleet detail page; the action persists the exact value false only after deployment succeeds and redeploys only that instance. Before a true-to-false transition, the Hub calls the instance's Agent Orchestrator security preflight. Running remote jobs must be drained by a cancellation-aware runner (codex-remote-runner/0.2.2 or clapilot-remote-runner-mac/0.2.0 or newer); the runners report active job IDs, terminate their complete live process groups when the instance requests cancellation, and retain the active claim proof while retrying the terminal status until the server acknowledges it. An authoritative module_not_installed response means Agent Orchestrator has no callable runner surface and does not block opt-out. The transition otherwise fails closed while the instance is stopped or unreachable, so an administrator must start it, update and drain any runner, disable shell tools, and then stop it again. Fleet-wide environment defaults cannot silently apply the restriction to every instance, and later redeploys reapply the selected instance's persisted policy. While explicitly disabled, the web proxy, native dispatcher, direct package-install endpoint, deterministic scheduled-command path, Agent Orchestrator job/session creation and continuation (including direct module endpoints, webhooks, manual/background poll loops, and remote-runner claim/event endpoints), Website Canvas session/apply/sync/commit/push operations (including direct module endpoints), and every initial or updated Live Voice catalog all omit or reject shell-capable entry points. Nonterminal remote assignments are invalidated before a disabled instance handles runner traffic. A configured skills tool surface falls back to typed non-shell native tools so calendar, email, tasks, documents, and other ordinary app capabilities remain available without clapilot-cli. Restricted Claude bridges use an isolated clean working directory with disk setting sources disabled, keep only the explicit Clapilot MCP configuration, disallow command and broad filesystem built-ins, and may read only exact per-turn attachment paths; Codex subscription threads explicitly disable shell_tool and unified_exec, receive image attachments through native app-server input_image content, and cannot use exec-based reference or rescue finalizers. Shell-capable bridge threads are never reused after opt-out. Read-only Agent Orchestrator and Website Canvas status/session surfaces remain available, as do stop/archive cleanup actions.

| clapilot_context_status | Read the effective Clapilot UI/module/document context for the current session, including linked-user fallback context for channels when available, the active ClapilotAICore media defaults for image generation, TTS, STT, and realtime, plus mediaDefaultsGuidance reminding agents to use the configured Clapilot TTS route instead of raw provider secret checks | internal tool proxy session-context lookup in src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | context_search | Primary unified read-only retrieval across approved Learning objects, Wiki pages, native durable memory, lossless session history/summaries, and the source-backed Knowledge Graph; supports intent, sources, depth, include_provenance, limit, optional scope="personal"|"shared"|"all", and Learning-source filters object_type="durable_fact"|"procedure_proposal" plus include_hot_snapshots | native orchestration in services/clapilot-agent/src/sessions/index.mjs, combining agent_learning_objects, src/lib/wiki.ts, agent_memories, agent_context_*, and agent_knowledge_* | No direct UI mutation; /internal/runs can emit tool stream events | | context_get | Read one source-qualified result returned by context_search such as learning:<id>, wiki:<id-or-slug>, memory:<id>, history:<id>, knowledge_claim:<id>, or knowledge_entity:<id> | native orchestration in services/clapilot-agent/src/sessions/index.mjs with source-specific detail calls | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_list_repos | List GitHub and GitLab repositories available to the bundled Agent Orchestrator for coding and pull/merge-request work | agent-orchestrator module API POST /repos via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_start_job | Start a repo coding or PR-preparation job through the bundled Agent Orchestrator with auto, codex, claude, or local clapilot-code; forwards forge provider, named connection, instance, and clone metadata returned by repository listing; may pass executionTarget: "remote" for Codex remote-runner execution and codexGoalEnabled for Codex/Claude /goal first-turn setup | agent-orchestrator module API POST /jobs via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_list_jobs | List current/recent Agent Orchestrator jobs | agent-orchestrator module API GET /jobs via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_get_job | Read one Agent Orchestrator job including recent logs | agent-orchestrator module API GET /jobs/{id} via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_stop_job | Stop/remove an Agent Orchestrator job on explicit user request | agent-orchestrator module API DELETE /jobs/{id} via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_follow_up_job | Continue a detached Agent Orchestrator job with another prompt and optional attachments[]; session-backed jobs resume the linked background session, plain CLI jobs rerun Codex/Claude/OpenClaw in the original job workspace, and remote Codex jobs are requeued for the remote workspace | agent-orchestrator module API POST /jobs/{id}/follow-up via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events and the module/native clients can continue session-backed, CLI-backed, or remote Codex jobs | | agent_orchestrator_start_session | Start an interactive repo session via the native session broker; forwards forge provider, named connection, instance, and clone metadata returned by repository listing; clapilot-code maps to internal adapter embedded_pi, and the initial turn can contain text, attachments[], an optional model, optional Codex/Claude codexGoalEnabled, or both | agent-orchestrator module API POST /sessions via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events and the module can show the live session stream | | agent_orchestrator_send_turn | Continue an existing interactive repo session with text and/or attachments[] | agent-orchestrator module API POST /sessions/{id}/turns via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events and the module can show the live session stream | | agent_orchestrator_list_sessions | List interactive Agent Orchestrator sessions | agent-orchestrator module API GET /sessions via src/lib/agent-runtime/tool-proxy.ts; defaults to compact session summaries | No direct UI mutation; overview clients reconcile without embedded history payloads | | agent_orchestrator_get_session | Read one interactive Agent Orchestrator session including recent events | agent-orchestrator module API GET /sessions/{id} via src/lib/agent-runtime/tool-proxy.ts; selected web sessions use the corresponding SSE stream with replay=0 | No direct UI mutation; selected session details remain live through SSE | | agent_orchestrator_fork_session | Fork an interactive Agent Orchestrator session | agent-orchestrator module API POST /sessions/{id}/fork via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | agent_orchestrator_close_session | Close/archive an interactive Agent Orchestrator session | agent-orchestrator module API DELETE /sessions/{id} via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | issue_reporter_create | Create an issue report from the active Clapilot session with current route/page context and linked chat transcript when available; accepts optional repository-basename app (default clapilot), details, and platform (web_ios_mac, web, ios, mac, or general); explicit apps resolve the Agent Orchestrator repo-to-board mapping | shared Issue Reporter backend via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | documents_list | List visible Clapilot document records when the user asks about a document but no active document is selected | DB-backed documents read path through src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | documents_get | Load one visible Clapilot document by id, returning metadata plus readable text or extracted preview when available | DB-backed documents read path through src/lib/agent-runtime/tool-proxy.ts, optionally enriched from the Word document editor / document analysis | No direct UI mutation; /internal/runs can emit tool stream events | | documents_list_folders | List visible Clapilot document folders, including the authenticated user's private Persönlich folder | /api/documents/folders via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | documents_create | Create a new Clapilot Word, Excel, or Markdown document in Root-Dokumente or a specified folder; supports template_key="vollmacht" plus mandant_id to generate a linked standard power-of-attorney Word draft from Mandant context; new Word/Excel/Markdown files may still use _inbox/... as file_path while remaining in the standard document list when folder_id stays empty | word-canvas or excel-canvas module create API via src/lib/agent-runtime/tool-proxy.ts, optionally followed by Word document editor save and /api/documents/[id] | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_create_folder | Create a Clapilot document folder | /api/documents/folders via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_update_folder | Rename or move a Clapilot document folder | /api/documents/folders/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_delete_folder | Delete a Clapilot document folder | /api/documents/folders/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_update | Update a Clapilot document metadata record, including extracted tax fields and related_mandant_ids for additional document parties | /api/documents/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_move | Move a Clapilot document into another folder | /api/documents/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_delete | Delete a Clapilot document record | /api/documents/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_create_share | Create or return the active public share link for a Clapilot document | /api/documents/[id]/share via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | documents_revoke_share | Revoke the active public share link for a Clapilot document | /api/documents/[id]/share via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | postal_mail_list | List recent physical-post jobs sent via Deutsche Post E-POSTBUSINESS | /api/postal-mail via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | postal_mail_get | Load one physical-post job including provider status and event history | /api/postal-mail/[id] via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | postal_mail_send | Send an existing PDF document as physical post; V1 is outbound-only and rejects non-PDF inputs. registered_letter is constrained to Einschreiben, Einwurf Einschreiben, Einschreiben Rückschein; country only for international mail as German uppercase country name | /api/postal-mail/send via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | postal_mail_refresh | Refresh one physical-post job from the provider polling API | /api/postal-mail/[id]/refresh via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events, then the app reloads the document view | | mini_apps_list / widgets_list | List the current user's installed Widgets, optionally restricted to dashboard-visible rows | Mini Apps DB-backed read path via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | mini_apps_get / widgets_get | Read one installed Widget by id or slug | Mini Apps DB-backed read path via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | mini_apps_create / widgets_create | Create a Widget with an optional structured widget_definition; supported widget types are stats, list, table, notice, and sections. If omitted, Clapilot infers a native widget from latest_data | Mini Apps DB-backed create path via src/lib/agent-runtime/tool-proxy.ts | refreshTopic=mini-apps; /internal/runs can emit tool stream events and visible pages refetch | | mini_apps_update / widgets_update | Update a Widget name, description, or structured widget_definition content | Mini Apps DB-backed update path via src/lib/agent-runtime/tool-proxy.ts | refreshTopic=mini-apps; /internal/runs can emit tool stream events and visible pages refetch | | mini_apps_update_data / widgets_update_data | Update the latest data payload of a Widget; basic inferred layouts can auto-upgrade when richer collection data arrives | Mini Apps DB-backed data update path via src/lib/agent-runtime/tool-proxy.ts | refreshTopic=mini-apps; /internal/runs can emit tool stream events and visible pages refetch | | notizen_list_folders | List Clapilot note folders in the active Notizen workspace | notizen module API via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | notizen_create_folder | Create a Clapilot note folder | notizen module API via src/lib/agent-runtime/tool-proxy.ts | Emits notizen.folder.updated; /internal/runs can stream the tool event and the app applies the folder update/highlight live | | notizen_list_notes | List Clapilot notes, optionally filtered by the active folder | notizen module API via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | notizen_get_note | Load one Clapilot note with its pages, using active note context when available | notizen module API via src/lib/agent-runtime/tool-proxy.ts | No direct UI mutation; /internal/runs can emit tool stream events | | notizen_create_note | Create a Clapilot note using the active folder context when available | notizen module API via src/lib/agent-runtime/tool-proxy.ts | Emits notizen.note.updated; /internal/runs can stream the tool event and the app applies the note update/highlight live | | notizen_update_note | Update a Clapilot note title or folder assignment | notizen module API via src/lib/agent-runtime/tool-proxy.ts | Emits notizen.note.updated; /internal/runs can stream the tool event and the app applies the note update/highlight live | | notizen_create_page | Create a page inside the active or specified Clapilot note | notizen module API via src/lib/agent-runtime/tool-proxy.ts | Emits notizen.page.updated; /internal/runs can stream the tool event and the app applies the page/editor update/highlight live | | notizen_update_page | Update a Clapilot note page including text/html content, font formatting, and persisted page attachment metadata such as audio_attachments | notizen module API via src/lib/agent-runtime/tool-proxy.ts | Emits notizen.page.updated; /internal/runs can stream the tool event and the app applies the page/editor update/highlight live |

For Notizen page payloads, audio_attachments[] is now part of the canonical page record alongside asset_items[]. Each attachment entry contains id, title, and optional transcript, mime_type, file_size, duration_ms, and created_at.

Use context_search and context_get as the primary retrieval pair. For broad Wiki synthesis or "look deeply in memory" requests, pass depth=deep or intent=wiki_synthesis so the runtime checks Learning, Wiki, canonical assertions/native memory, lossless history/session summaries, and the Knowledge Graph together. Cross-source hits use reciprocal-rank fusion with canonical assertion/topic keys, a small confidence contribution, and a per-source reservation before the final limit. The memory_*, learning_*, wiki_*, and knowledge_* families remain registered as specialized fallbacks for source-specific drill-down, graph traversal, or writes. knowledge_search remains a graph entry point, not a complete memory harvest by itself.

For a specialized-agent run with personal memory enabled, memory_store defaults to personal, while memory_search and context_search default to all. scope="personal" is always bound to the current specialist's id; it cannot name or read another specialist. Main-agent runs and specialists with personal memory disabled keep the existing shared defaults. If either kind of run explicitly requests unavailable personal scope, the tool returns an empty result with a notice instead of failing. Default bootstrap, Learning injection, Wiki/Dreaming inputs, and Knowledge Graph projection remain shared-only in P1.

Learning mutation contracts are documented separately because agent-facing learning extraction, proposal, approval, promotion, and audit tools are intentionally not active. Approved-learning prompt retrieval, conservative post-response extraction, versioned deterministic safe fact/preference activation, reversible system-policy decisions, and exception review remain runtime/control-plane infrastructure.

Sync rules

The per-user Settings -> Profile -> Speech to text choice and the administrator-owned Settings -> ClapilotAICore -> Audio -> API Live Transcribe capability gate are intentionally not agent tools or visible mutation contracts. They control how microphone audio becomes composer text before a chat turn exists and may determine whether audio leaves the device. Agents receive the resulting text through the normal chat contract and never receive the Realtime client secret or provider credential. The administrator gate selects the OpenAI API Realtime provider and compatible live-transcription model; disabled or invalid configuration fails session creation closed without an agent-controlled fallback.

Whenever a tool or context action is added or changed, update:

1. this page
2. API Reference if request/response shape changed
3. the relevant module/feature spec page if the behavior is module-specific

If a visible mutation is added, document both:

• the write path
• the user-visible UI action path

Specialized-agent calendar capability and mutation validation

Internal specialized-agent runs receive their persisted allowed_tool_names as their authoritative scoped tool catalog, including any granted calendar_* tools. Before reporting that a capability is unavailable, the specialist must inspect that scoped catalog and attempt the matching allowed tool.

Calendar creation uses a read-before-write/read-after-write contract: the specialist lists the relevant time range before creating an event to avoid duplicates across retries or concurrent agents, then validates every create, update, or delete with calendar_get_event or calendar_list_events. An ambiguous mutation response is not a valid basis for saying that an event was not booked; the calendar read-back is authoritative.

Failed run diagnostics

Every newly terminal agent_runs.status = 'failed' record carries error_code, error_message, and a structured usage_json.runDiagnostics object. The object records the abort cause, provider/model and runtime path, the last persisted turn event, and the last tool snapshot when one exists. Runtime finalizers write the full diagnostic; a database trigger supplies a conservative fallback for process termination, bridge/reconciler failures, and any direct SQL failure transition. Runtime-authored summaries use schema version 1 and set fallbackGenerated to false; event-snapshot database fallbacks use schema version 2 and set it to true. Session APIs expose the latest run's usageJson and runDiagnostics so web, iOS, and macOS clients render the same persisted evidence. Migration 265 also repairs failed records from the preceding 90 days; its standard update trigger refreshes updated_at for those repaired rows.