llm-cli-gateway: Skill for Claude Code

Provider: Claude Code CLI

Process guidance for keeping the gateway's Claude (claude) integration aligned with the upstream CLI. This skill does not define argv/env behaviour; the single mechanical source of truth is UPSTREAM_CLI_CONTRACTS.claude in src/upstream-contracts.ts, enforced by validateUpstreamCliArgs / validateUpstreamCliEnv. Never re-encode flags, output modes, permission modes, or session rules here or in TOML.

Identity

These values mirror UPSTREAM_CLI_CONTRACTS.claude.upstreamMetadata and docs/upstream/provider-sources.dag.toml ([providers.claude]). The TypeScript metadata is authoritative; the TOML is scanner input only.

When to use

• An Anthropic Claude Code release lands and you need to check for contract drift.
• A claude request fails the upstream contract check before spawn.
• npm run upstream:scan -- --live reports a change on the Claude changelog.

How LLM agents should use Claude through the gateway

1. Discover the live gateway/provider surface before relying on provider-specific controls:

   provider_tool_capabilities({cli:"claude"})
   

   For a cached read-only resource, use provider-tools://claude.
2. Use claude_request for normal turns and claude_request_async for long-running review, implementation, or analysis. Sync calls may auto-defer; poll llm_job_status and fetch with llm_job_result when that happens.
3. Omit model unless the caller explicitly asked for a specific variant; the gateway resolves the configured Claude default.
4. For review or code-reading tasks, keep tool access available. Claude supports allowedTools, disallowedTools, and tools, but do not pass an empty allowlist for reviews. Under mcp_managed, non-empty allowedTools or tools is a high-risk managed input that requires approval plus LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1, but remains bounded.
5. Use mcpServers only for gateway-known MCP servers. Under legacy approval, strictMcpConfig defaults to false; set it to true when missing MCP access should fail fast. Under mcp_managed, the gateway forces strictMcpConfig:true, so Claude uses only the generated configuration and only provisioned gateway-owned local definitions are eligible. Dynamic npx, ambient-PATH, and Codex-config overrides remain legacy-only; a caller-supplied false cannot weaken that boundary.
6. Prefer approvalStrategy:"mcp_managed" over raw dangerouslySkipPermissions. Under managed approval, a direct dangerouslySkipPermissions or permissionMode:"bypassPermissions" request is honored only with an explicit caller request, approval-manager approval, and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. Settings or setting sources, agents, native forks, plugins, added directories, non-empty systemPrompt / appendSystemPrompt, prompt-file controls (systemPromptFile / appendSystemPromptFile), safeMode:true, bare:true, and debugFile are high-risk managed inputs: they require approval and the operator setting, but remain bounded and do not select full permission on their own. A gateway-created worktree is also a high-risk managed input under the same conditions.
7. Use createNewSession, sessionId, or continueSession for real Claude continuity. Under mcp_managed, native continuation is also a high-risk input that requires approval plus the operator setting but remains bounded. Claude also supports structured output via outputFormat and jsonSchema.
8. Select local repository work with workingDir, a verified registered workspace, or gateway worktree. An unscoped CLI child uses a fresh neutral temporary cwd, not the gateway repository. A cwd-scoped continuation needs a stable selected target.
9. Claude's ordinary print path, including promptParts without effective cache control, carries the prompt in argv. Oversized UTF-8 input on that path fails before spawn as non-retryable input_too_large; the gateway does not truncate instructions. Effective cache-control requests require outputFormat:"stream-json" and carry the assembled content blocks through stream-json stdin instead. All other caller-controlled argv values are admitted in their final encoded form before spawn. Embedded NUL bytes return non-retryable invalid_input without exposing the rejected value. The stdin branch completes only after the full payload write callback succeeds; a clean child exit with closed or pending delivery is a fixed non-sensitive failure.