{"slug": "securely-share-passwords-with-your-agents", "title": "Securely share passwords with your Agents", "summary": "A tool called secret-scratch, published as the TypeScript library @inixiative/secret-scratch, intercepts secrets typed into coding-agent chats before inference, replacing them with opaque references such as †m1.1 and storing the real values in a 0600 scratch-pad file under ~/.secret-scratch/. The tool ships as a drop-in Agent Client Protocol middleware proxy that wraps Claude ACP, Codex ACP and Gemini CLI ACP agents, as a stdio MCP server exposing the secret_scratch and secret_pipe tools, and as a library for custom harnesses, with zero runtime dependencies on Node.js 20+ and Bun 1.4+. It matters because pasting an API key or private key into an agent chat otherwise sends the secret to the model provider and leaves it in session transcripts, tool logs and crash dumps.", "body_md": "Securely send secrets to your AI agent with `$$value` without the LLM, transcript, or logs ever seeing them.\n\n```\nYou type:       Put $$sk_live_9876543210 into .env.local as STRIPE_KEY, then push it to GitHub Actions.\nAgent sees:     Put †m1.1 into .env.local as STRIPE_KEY, then push it to GitHub Actions.\nAgent calls:    secret_scratch(action: \"env\", ref: \"†m1.1\", path: \".env.local\", key: \"STRIPE_KEY\")\n                secret_pipe(envFile: \".env.local\", key: \"STRIPE_KEY\", command: \"gh secret set STRIPE_KEY\")\nAgent gets:     { ok: true, exitCode: 0 }\nAgent tries:    cat .env.local  ->  BLOCKED (.env.local is held by secret-scratch)\n```\n\nZero runtime dependencies. Works with Node.js 20+ and Bun 1.4+. Ships three ways to integrate:\n\n1. **Drop-in Agent Client Protocol (ACP) middleware proxy** (`secret-scratch -- <acp-agent-command>` ) wrapping Claude ACP, Codex ACP, Gemini CLI ACP, or any ACP agent inside hosts such as Zed and JetBrains.\n2. **Stdio MCP server** (`secret-scratch mcp` ) exposing`secret_scratch` and`secret_pipe` .\n3. **TypeScript library** (`@inixiative/secret-scratch` ) for custom harnesses and agent runtimes.\n\nPasting an API key or private key into a coding agent chat sends the secret to the model provider, writes it into session transcripts, and leaves it in tool logs and crash dumps.\n\n`secret-scratch` intercepts secrets before they reach the model:\n\n1. **Lift before inference.** Any word prefixed with`$$` (plus common shaped tokens such as`sk-...` ,`ghp_...` ,`AKIA...` ,`AIza...` , and PEM private keys if you forget the prefix) is moved into a`0600` per-thread scratch pad file in`~/.secret-scratch/` (`0700` ) and replaced with an opaque reference like`†m1.1` .\n2. **Use by reference.** The agent receives two MCP tools:`secret_scratch` (`list` ,`env` ,`write` ,`consume` ) and`secret_pipe` (pipes a secret to a shell command's`stdin` , discards`stdout` and`stderr` , returns only`exitCode` ).\n3. **Block access to held files.** Every file written by`secret_scratch` is recorded in`held-files.json` . ACP permission requests, filesystem calls, and terminal calls targeting a held file, a`.private` path, or the scratch pad directory are denied at the proxy boundary.\n4. **Scrub outgoing updates.** Held values (6+ characters) are scrubbed from outgoing`session/update` frames back into their`†` reference as defense in depth.\n\nWrap any ACP agent command with `npx @inixiative/secret-scratch --`:\n\n```\nnpx -y @inixiative/secret-scratch -- <your-acp-agent-command> [args...]\n```\n\nOr install globally:\n\n```\nnpm install -g @inixiative/secret-scratch\nsecret-scratch -- <your-acp-agent-command> [args...]\n{\n  \"agent_servers\": {\n    \"Claude Code (secret-scratch)\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@inixiative/secret-scratch\", \"--\", \"claude-agent-acp\"]\n    },\n    \"Codex (secret-scratch)\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@inixiative/secret-scratch\", \"--\", \"codex-acp\"]\n    },\n    \"Gemini CLI (secret-scratch)\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@inixiative/secret-scratch\", \"--\", \"gemini\", \"--experimental-acp\"]\n    }\n  }\n}\n```\n\nWhen a session starts, the proxy:\n\n- Injects the `secret-scratch` stdio MCP server into`session/new` ,`session/load` ,`session/resume` , and`session/fork` (preserving all other MCP servers).\n- Lifts `$$value` markers and recognised secret shapes on`session/prompt` before forwarding to the agent, attaching usage guidance on the first turn that carries a secret.\n- Rejects `session/request_permission` ,`fs/read_text_file` ,`fs/write_text_file` , and`terminal/create` calls targeting held files,`.private` paths, or`~/.secret-scratch` .\n- Scrubs held values out of `session/update` notifications.\n\n```\nsecret-scratch [options] -- <acp-agent-command> [args...]\nsecret-scratch mcp --dir <path> --thread <id> [--cwd <path>]\nsecret-scratch list [--dir <path>] [--thread <id>]\nsecret-scratch clear <thread> [--dir <path>]\n\nOptions:\n  --dir <path>          Scratch pad directory (default: ~/.secret-scratch)\n  --private <glob>      Extra private path glob to block (repeatable)\n  --no-lift-shaped      Only lift explicit $$value markers\n  --no-scrub            Disable scrubbing held values from session/update\njs\nimport {\n  SecretScratchPad,\n  SHAPED_SECRET_PATTERNS,\n  privatePathGate,\n  scratchTarget,\n} from '@inixiative/secret-scratch';\n\nconst pad = new SecretScratchPad('~/.secret-scratch');\n\n// 1. Lift before sending to the LLM\nconst { text, refs } = pad.lift(\n  'Set STRIPE_KEY to $$sk_live_example1234567890 in .env.local',\n  { thread: 'thread_1', message: 'm1' },\n  { patterns: SHAPED_SECRET_PATTERNS },\n);\n// text === 'Set STRIPE_KEY to †m1.1 in .env.local'\n\n// 2. Write safely inside cwd (rejects .., symlink escapes, .git, .claude, .ssh)\nconst target = scratchTarget(process.cwd(), '.env.local');\npad.env({ ref: refs[0]! }, 'thread_1', target, 'STRIPE_KEY', { consume: true });\n\n// 3. Pipe straight to a CLI without returning stdout/stderr\nconst { exitCode } = await pad.pipe(\n  { envFile: target, key: 'STRIPE_KEY' },\n  'thread_1',\n  'gh secret set STRIPE_KEY',\n);\n\n// 4. Gate agent file/shell tools\nconst gate = privatePathGate({\n  scratchDir: pad.dir,\n  heldFiles: pad.heldFiles(),\n});\ngate({ toolName: 'Bash', toolInput: { command: 'cat .env.local' } });\n// { behavior: 'deny', message: '.env.local is private: ...' }\n```\n\nSee [docs/VERBS.md](https://github.com/inixiative/secret-scratch/blob/main/docs/VERBS.md) for the complete public API table.\n\n- **Prevents accidental exposure to the LLM, agent transcripts, and tool output.** Secrets lifted at the prompt boundary never enter model context, prompt caches, or downstream agent session transcripts.`secret_pipe` discards`stdout` and`stderr` and kills the whole process group on timeout.\n- **On-disk storage is `0600` plaintext in a `0700` directory.** Scratch pads live at`~/.secret-scratch/<thread>.pad` until consumed or cleared (`secret-scratch clear <thread>` ). They protect against LLM and transcript leakage, not against another process running as your OS user.\n- **Shell gating and `secret_pipe` defend against accidental leaks, not a hostile sandbox.** If a downstream agent runs shell commands directly inside its own process without asking the ACP host via`session/request_permission` or`terminal/create` , the ACP proxy cannot intercept those local subprocess calls. Likewise, an adversarial model that can pass arbitrary shell commands to`secret_pipe` could write stdin to an untracked file or encode bytes in the exit code. For enforcement against an untrusted model, pair`secret-scratch` with an OS sandbox or a harness that routes all tool calls through`privatePathGate` and restricts allowed pipe commands.\n- **Single-word marker.**`$$value` lifts up to the next whitespace. Multi-line secrets (such as PEM private keys) are lifted by shape automatically; arbitrary multi-line secrets should be passed by file or env key rather than`$$` .\n\nExtracted from [Foundry](https://inixiative.com/foundry/), a source-available (BSL 1.1) local agent harness built by [inixiative](https://inixiative.com).\n\nMIT", "url": "https://wpnews.pro/news/securely-share-passwords-with-your-agents", "canonical_source": "https://github.com/inixiative/secret-scratch", "published_at": "2026-11-21 20:36:25+00:00", "updated_at": "2026-11-21 21:15:04.906640+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "ai-safety", "developer-tools"], "entities": ["secret-scratch", "@inixiative/secret-scratch", "Claude ACP", "Codex ACP", "Gemini CLI", "Zed", "JetBrains", "Node.js"], "also_reported_by": [], "takeaway": "Prefix secrets with $$ (or rely on recognized shapes like sk-, ghp_, AKIA, AIza and PEM keys) so the ACP proxy lifts them into a 0600 scratch pad and the agent only ever sees a † reference, then use secret_pipe to pass the value to a command's stdin.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/securely-share-passwords-with-your-agents", "markdown": "https://wpnews.pro/news/securely-share-passwords-with-your-agents.md", "text": "https://wpnews.pro/news/securely-share-passwords-with-your-agents.txt", "jsonld": "https://wpnews.pro/news/securely-share-passwords-with-your-agents.jsonld"}}