Secret Paste Guard
Secret Paste Guard is a shipped, opt-in feature that keeps API keys and other secrets out of your AI conversation history: paste a secret into the session composer and Omniscio stores it locally under an opaque handle, substituting the real value only at execution time on Claude-based engines. On a non-Claude engine whose shell has been measured to inherit the session environment, Omniscio instead hands the value over as an environment variable (OMNISCIO_PASTE_<hex>) and the draft carries only that name, so the model can use the key without ever seeing it.
On this page
What it is
Secret Paste Guard is a shipped, opt-in feature (off by default) that keeps API keys and other secrets out of your AI conversation history. When you paste a secret into the session composer, Omniscio stores it locally under an opaque handle. For Claude-based engines it injects the real value only at the moment the agent actually uses it — in a shell command, a file write, or a web-form field — so the raw value never enters the model's conversation. For every engine, Omniscio's own stored history is scrubbed of the value. The protection is honest about what each engine can and can't do (see "The guarantee").
Where to find it
How to use it
Turn it on. Secret Paste Guard ships off by default — turn it on at Settings → Features → "Secret Paste Guard" (the
secretHandleEnabledsetting). Nothing about it runs until you enable it.Paste your secret into the composer. When the feature is enabled and Omniscio detects that what you typed looks like an API key or secret, it offers to store it securely.
The secret is stored locally. Omniscio saves the raw value in an encrypted, per-session store on your machine. On a Claude-based engine it also replaces the value in the composer with the opaque handle (
AMCSECRET-<hex>) — that handle is what the AI sees. On an engine whose shell has been measured to inherit the session environment, it replaces the value with the environment variable's name (OMNISCIO_PASTE_<hex>) and adds one line telling the model to use it by reference; the value is live in that session's processes. On any other engine it keeps the raw value in place (so the engine's tools still work) but tells you plainly that the engine still receives the key.The agent works with the handle (Claude engines). When the agent writes a shell command or file containing the handle, a PreToolUse hook substitutes the real value at execution — before the command runs — so the secret reaches its destination without appearing in the chat. Once the session ends, a log-scrub also cleans the value out of the Claude CLI's own local transcript.
Turn it off. Toggle secretHandleEnabled off in Settings; pasted secrets are then treated as plain text (the previous behavior).
How it behaves
What problem it solves
Normally, if you paste an API key directly into a chat message, that value lives in your history
forever: in the database, in search indexes, in exports, and — for Claude engines — in the Claude
CLI's own local transcript. Secret Paste Guard intercepts the secret before it gets that far. On
Claude-based engines the model only ever sees a placeholder like AMCSECRET-a3f9b2…; the real
value is substituted in privately, at execution time, by a hook that runs outside the
conversation. On other engines the value still reaches the engine, but Omniscio keeps it out of
your saved, searchable history.
The guarantee — the honest tiers by engine
Every engine: Omniscio's own stored history is always scrubbed — the raw value is never
written to conversation_messages, never indexed for search, never included in exports, and
never shown in the live chat (a persistence scrub strips it even if an agent echoes it back).
Tier 1 — Claude-based engines (the native Claude CLI plus the vendors that reuse it): the model never sees the value. The composer swaps your paste for a handle, and the PreToolUse hook substitutes the real value only at execution. A log-scrub also cleans the value out of the Claude CLI's own local transcript once the session's process exits.
Tier 1b — non-Claude engines whose shell inherits the session environment (measured only):
the model never sees the value, because it never enters the conversation — the draft carries the
variable's name (OMNISCIO_PASTE_<hex>) and the value sits in that session process's environment.
This covers shell commands only: a tool that must write the literal value into a file cannot use
it, and if the agent prints its environment the value reaches that engine's own log and the model
provider (Omniscio's own history is still scrubbed). A secret pasted while a persistent engine's
process is already running is refused, with a plain message saying the engine was already running —
a live process's environment cannot be changed. An engine joins this tier only after a recorded run
proves its shell inherits the variable; an unmeasured engine stays in the partial tier below.
Tier 2 — server-side secret tools (planned): for engines and tools this road cannot serve — a tool that must write the literal value into a file, most of all — the key is resolved and used server-side without ever appearing in the model's output.
Tier 3 — every other engine: partial protection. The key is kept in the composer so the engine's tools still work, but it is stored so Omniscio's saved history is scrubbed — the engine (and its own logs) still receive the value, and the offer says so honestly.
Honest residual (inherent): for the secret to be usable, it must be reachable at execution, so an actively-compromised or prompt-injected agent could still use or exfiltrate it. The guarantee is "never passively persisted in Omniscio history; scrubbed from the local Claude transcript" — not "immune to an actively-hijacked agent," the same trade-off other credential-proxy patterns accept.
Scope
- Full substitution (Tier 1) = the Claude-binary family — the native Claude CLI plus the vendors that reuse it. SSH/remote is out of scope.
- codex / gemini / cursor (Tier 2) get server-side secret tools as a planned fast-follow; until then they run in the partial tier.
- Every other engine (Tier 3) gets partial protection — Omniscio's saved history is scrubbed, but the engine still receives the value.
- Web-form fill via the AI Browser (
type/fill_formwith asecretHandle) resolves the value server-side. - The feature is desktop-only. The stash channel that accepts the secret is not reachable from the mobile or web bridge (blocked by design — a headless secret-injection endpoint would be a security risk).
A name is not a secret
The unlabelled-token heuristic flags a long, opaque, mixed-character string. A NAME that happens to
measure high on it — a git branch such as patch/homeschooling-scaffold-55df7e15 (37 characters,
4.155 bits/char, three character classes) — is not one. Since 2026-11-12 a token is treated as a name
only when it contains NO uppercase letter, is at least 40% lowercase letters, and is word-shaped (a
4+ letter lowercase run with a low class-switch rate). That narrowing is deliberate: an opaque key
mixes case, so abcdefgh12345678ABCDEFGH stays a secret while a lowercase slug does not. An approval
request that merely carries a branch name is therefore no longer refused as "it carries a secret"
(Help Desk #2043).
Where secrets are stored
Secrets are kept in a per-session, file-based store at <userData>/session-secrets/<id>.json,
encrypted with Electron's OS keyring (safeStorage — Windows DPAPI / macOS Keychain / Linux
libsecret). If safeStorage is unavailable, secrets are kept in memory only and never written
to disk as plaintext. The store is cleared when the session is deleted or reaches its retention
limit. There is no database table; no migration was added.
See also
- INDEX.md
- api-keys.md — manage and view stored API keys and secrets in one inventory
- automation-credentials.md — saved credentials for v2 automation actions (a separate, complementary secret-storage layer)
- git-guardrails.md — the PreToolUse hook system Secret Paste Guard composes alongside
Related
api-keys.md covers managing and viewing stored API keys in one inventory, automation-credentials.md the separate and complementary secret-storage layer for automation actions, git-guardrails.md the hook system this feature composes alongside, and INDEX.md is the library index.
Last verified 2026-11-15