Claude CLI Quirks (kalamos runtime)

These apply to the Claude CLI invocation path inside kalamos containers. Not customer-specific; they’re properties of how kalamos uses Claude.

Headless / `--print` mode

Kalamos invokes Claude via subprocess in --print mode (packages/adapters/claude-local/src/server/execute.ts). All input goes via stdin (--print -); output streams as --output-format stream-json.
Interactive permission prompts are unanswerable in this mode → --dangerously-skip-permissions is set by default. Agents must therefore use Claude CLI’s tool permission system (allow/deny lists) at config time, not runtime.

Anthropic prompt caching is automatic when the system prompt + tool bundle hash is stable across calls. Kalamos’s prompt-cache.ts produces a content-hashed bundle directory → same hash = cache hit (within the 5-minute TTL).
Stable prefix order matters. The kalamos-brain content is injected via --append-system-prompt-file; ordering inside that file is part of the hash. Random reordering busts cache.
Per-issue scratchpad rides in stdin (user message slot), not in the cached prefix. This is intentional: scratchpad changes per call.

claude_local adapter detects ANTHROPIC_API_KEY env. If set, billing is API/metered. If not, billing is the user’s Claude.ai subscription.
Subscription mode counts “messages” (~per call). API mode counts tokens (input + output, with 90% discount on cached input).
Per ADR-025: kalamos at 23 agents on subscription will exhaust limits in ~30 min without idle-suppression. Always use the wake-source-driven design.

Bun (OpenCode runtime) writes transpiler cache to /tmp by default. Without BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/bun-cache, the cache scatters across /tmp and accumulates ~5 MB shards forever.
mktemp -d /tmp/kalamos-opencode-config-* dirs from the precheck wrapper accumulate ~55 MB each per run. Without tmpfs: /tmp:size=2g,mode=1777,exec in compose, these fill the disk.
ADR-025’s compose patch fixes both. If you see /tmp filling, check that the kalamos container has the tmpfs mount.

The claude_local adapter passes --add-dir <bundle> to expose skills + tools. The bundle is built fresh per agent run from the agent’s role config + project SKILL.md + kalamos-brain content (post-Phase 2.3).
MCP server config is NOT in the prompt — it’s at ~/.config/opencode/opencode.json inside the container, bind-mounted from the host. Editing the host file requires a restart of the container to pick up.

OpenCode 1.4.10: permission (not tools) field in config; external_directory needs entries for /root/.kalamos/** AND /srv/workspaces/** AND (post Phase 2.1) /srv/kalamos-brain/**.