gate4agent

gate4agent is a library that drives CLI coding agents — Claude Code, Codex, Kimi, Grok — over PTY, pipe, ACP, and daemon transports behind one API: spawn, stream, resume; see Transport core below. On top of that transport core it also carries the session runtime a node embeds to run those agents as managed sessions: an adapter/tool catalog, a session kernel, the native runtime, and per-CLI process hooks and history readers. The node/c2/harness/TUI stack that used to live in this repository is now hatchery, built on this library.

Provider tiers

Repository layout

The root src/ tree is the transport core — spawning, streaming, resuming, and owning interactive CLI-agent subprocesses through one API, published as the gate4agent crate. See Source layout below for its internal module structure.

crates/ holds the session runtime that a node embeds on top of the transport core, plus the in-house PTY backend:

• gate4agent-pty — the in-house PTY backend (std-only, zero external PTY dependencies: Windows ConPTY + a unix macOS/Linux backend).
• gate4agent-types — shared wire/data types.
• gate4agent-adapters — the adapter registry (Grok, qwen-code, and other CLIs wired outside the transport core's own pipe/PTY clients).
• gate4agent-catalog — the CLI interop reference registry.
• gate4agent-engine, gate4agent-kernel, gate4agent-handle — the session runtime substrate: catalog → kernel → runtime-native call down into the root crate's transports.
• gate4agent-tool-protocol, gate4agent-tool-engine — tool-call wire types and execution.
• gate4agent-shell-history, -shell-capabilities, -shell-hooks, -shell-managed-hooks, -shell-one-shot, -shell-native — per-CLI shell integration: history readers, capability probing, hook wiring.
• gate4agent-runtime-native — the native runtime a node embeds to run a managed session end to end.
• gate4agent-provider-ports — the provider-facing port/trait boundary.
• gate4agent-testkit — authentication-free provider fixtures and the Windows headless test supervisor (windows-headless-supervisor).
• g4a — a placeholder crate reserving the crates.io name.

All new development happens in crates/; the root library changes only when the transport core itself does.

Tests

Windows PTY/session-touching tests run only through the headless test supervisor (gate4agent-testkit's windows-headless-supervisor binary) — it suppresses Windows fault dialogs and enforces a hard per-test timeout that plain cargo test cannot:

target\release\windows-headless-supervisor.exe <timeout_ms> <ABS path to test exe> --exact <test_fn>

All builds share the workspace's own target/. A per-run --target-dir is a full copy of the dependency build and they pile up fast; when two builds overlap, Cargo's build lock simply makes the second wait. Tests gated by require_windows_headless_supervisor_for_test() reject themselves outright if run any other way.

Transport core

The root gate4agent crate is a standalone Rust library for spawning, streaming, resuming, and owning interactive CLI-agent subprocesses through one API — usable on its own, with no node/c2/harness in the loop.

Supported CLI tools

The table above is the transport core's own verified matrix. Grok and qwen-code ride the modern adapter registry (gate4agent-adapters) used by the node stack: Grok is a first-tier provider (a known resume gap is tracked); qwen-code is wired but unverified. The separate agent module also carries a 33-entry reference registry of CLI interop metadata derived from the Orca project's public tool descriptions (pinned by revision in gate4agent-catalog; credit to Orca for the original grounding); those entries are transitional code debt, not support claims. Gemini, OpenCode, and the other reference entries were last live-verified in the 0.2.5–0.2.6 era and are outside the current product target.

Quick start

use gate4agent::{CliTool, SessionConfig, AgentEvent, PipeSession, PipeProcessOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = SessionConfig {
        tool: CliTool::ClaudeCode,
        working_dir: std::env::current_dir()?,
        env_vars: vec![],
        name: None,
    };
    let session = PipeSession::spawn(config, "Say hello in 3 words", PipeProcessOptions::default()).await?;

    let mut rx = session.subscribe();
    while let Ok(event) = rx.recv().await {
        match event {
            AgentEvent::Text { text, .. } => print!("{text}"),
            AgentEvent::SessionEnd { .. } => break,
            _ => {}
        }
    }
    Ok(())
}

Resume an existing session with SpawnOptions { resume_session_id: Some("abc-123-session".into()), ..opts }; each active adapter handles it in its own way (Codex exec resume, Claude --resume <id>, Kimi --session <id>) behind that one field.

Transport classes

• Structured inline — spawn one owned vendor child, read JSONL, then create a new child with the provider session id to resume.
• PTY — own the interactive terminal process: ordered bytes, VT100 state, bounded replay, input, resize, interrupt, teardown. Never auto-accepts workspace-trust or update prompts; those stay visible for the operator.
• ACP and daemon modules are compatibility surfaces, not part of the current product target (acp::AcpSession, daemon::DaemonSession).

LaunchPlan (via plan_launch) always produces an executable plus an argument vector — it never concatenates a prompt into a shell command. prepare_input() produces bounded, UTF-8-safe writes with bracketed-paste neutralization of embedded terminal control sequences.

Source layout

src/
├── lib.rs      — library root, re-exports
├── agent/      — AgentId, registry, built-in specs, argv planner, typed input preparation
├── core/       — AgentEvent, CliTool, SessionConfig, AgentError
├── transport/  — TransportSession (thin router over PipeSession), SpawnOptions
├── pipe/       — PipeSession, per-CLI NDJSON parsers + command builders
├── pty/        — PtyWrapper, PtySession, VTE/screen parsers, per-CLI PTY parsers
├── acp/        — Agent Client Protocol transport (compatibility surface)
├── rpc/        — shared JSON-RPC 2.0 primitives, used internally by acp/
├── probe/      — probe_all(), CliProbe, cache logic
├── context/    — ContextTracker, TurnCompleteData
├── cure/       — runtime model discovery (OpenCode cache → OpenRouter → hardcoded)
├── daemon/     — DaemonSession, per-daemon adapters [skeleton, not functional]
└── history/    — per-CLI session history readers (Claude, Codex, Gemini, OpenCode)

Windows spawn strategy

Reviewed Claude, Codex, and Kimi npm installations resolve to their direct executable or JavaScript entrypoint, so prompts stay real argv/stdin data instead of being reparsed by a .cmd shim. Unknown legacy wrappers fall back to a shell. Unix uses direct process execution.

Current live testing status

Vendor-live inline/PTY tests are opt-in (--ignored) — they need an installed, authenticated CLI and network access. Plain cargo test is hermetic and never touches a provider account.

Prerequisites

At least one CLI agent must be installed on the host. gate4agent does not install them.

Versioning

• 0.4.1 — ordinary patch bump after websession→master merge (bridge skeleton, Claude ProviderHome --settings network overlay, dig2 station probe/lease). Same first crates.io wave crates; not published to crates.io from this tip (owner publish later).
• 0.4.0 — breaking: non-fleet vendors cut (Gemini, OpenCode, Qwen parsers, pipe builders and history readers removed); the rusqlite dependency is gone, so the transport core no longer pins libsqlite3-sys against consumers on rusqlite 0.32+; the harness mailbox moved out into its own service. Same first crates.io wave: gate4agent-pty, gate4agent-types, gate4agent-adapters, gate4agent-catalog, gate4agent, g4a.
• 0.3.0 — the workspace era. The repo is an agent workbench (node / c2 / harness / TUI over the transport core), not a single-crate library; the vendored portable-pty fork is replaced by the in-house gate4agent-pty (std-only, zero external PTY dependencies: Windows ConPTY + a unix macOS/Linux backend, verified on all three OSes); first crates.io wave published at 0.3.0: gate4agent-pty, gate4agent-types, gate4agent-adapters, gate4agent-catalog, gate4agent, g4a (the remaining workbench crates publish after the planned crate consolidation).
• 0.1.x — original 3-CLI library (Claude, Codex, Gemini)
• 0.2.0 — breaking: 6 CLIs, TransportSession, AgentEvent renamed, PipeSession removed, OpenClaw fantasy transport
• 0.2.1 — cleanup: OpenClaw removed (was never functional), PipeSession restored for 0.1.x compatibility, TransportSession is now a thin router over PipeSession
• 0.2.2 — parser isolation: NdjsonParser trait extracted, per-CLI parser modules split out
• 0.2.3 — source tree restructure into core/pty/pipe layout; proper pipe builders+parsers for Codex, Gemini, Cursor, OpenCode (research-based, NOT yet tested against live CLI output)
• 0.2.4 — docs update, Codex flags fixed (--full-auto replaces removed --ask-for-approval)
• 0.2.5 — live integration tests: fixed Codex flags, OpenCode run subcommand, Gemini -p flag, Windows cmd /C quoting; all parsers verified against real CLI output
• 0.2.6 — Gemini + OpenCode live-verified; OpenCode parser rewritten from real CLI output
• 0.2.7 — Cursor removed (no native Windows support, broken headless mode, closed-source CLI). 4 CLI tools remain: Claude Code, Codex, Gemini, OpenCode.
• 0.2.8 — SpawnOptions extended: continue_last, allowed_tools, permission_mode, mcp_config, max_turns, sandbox. Per-CLI builders updated.
• 0.2.9 — Daemon transport skeleton: DaemonSession, DaemonConfig, DaemonType (OpenCode, OpenClaw). Not yet functional — API surface documented for future implementation.
• 0.2.10 — Bidirectional JSON-RPC 2.0 primitives: RpcRequest, RpcResponse, RpcNotification, PendingRequests, HostHandler, MethodRouter. Shared infrastructure for ACP transport.
• 0.2.11 — Critical bugfixes: stale transport_session cleared on exit, send_prompt() returns BrokenPipe instead of silent no-op, OpenCode emits SessionStart, Gemini skips non-JSON banners silently, history readers for Codex/Gemini/OpenCode
• 0.2.12 — Test coverage: Gemini parser (14 tests), Claude parser (+8), builder argv parity (22 tests), PipeSession live test. README/DEBUGGING.md fixed. Examples added.
• 0.2.13–0.2.15 — OpenCode default model, env sanitization, test cleanup, TermCell improvements
• 0.2.16 — ACP transport: full Agent Client Protocol (JSON-RPC 2.0 over stdio) implementation. AcpSession with initialize + session/new handshake, multi-turn prompt(), session/update streaming, agent→host callbacks (fs, terminal, permissions). Live-verified with Gemini, OpenCode, Claude, Codex. 199 unit tests.
• 0.2.17 — Cursor removed again (no Windows binary: node_sqlite3.node is a Linux ELF, crashes on Windows with "is not a valid Win32 application"; no official Windows build exists). 4 CLI tools remain: Claude Code, Codex, Gemini, OpenCode.
• 0.2.18 — ACP host handler extended: TerminalAcpHandler with real terminal execution, FilesystemAcpHandler root whitelisting.
• 0.2.19 — RpcSession removed: standalone RPC transport was a pre-ACP intermediate step, now superseded by AcpSession. Shared JSON-RPC primitives (message, pending, handler, id) retained in rpc/ for ACP internal use.
• 0.2.20 — History readers: workdir scoping for Codex (cwd field), Gemini (projects.json slug), OpenCode (directory field). All readers now filter sessions by working directory.
• 0.2.21 — Docs: fixed README Quick Start example, renamed rpc_hello → acp_hello example.
• 0.2.22 — History readers: preview extraction for Codex/Gemini/OpenCode (first real user message), system message filtering (Codex injected XML/AGENTS.md content excluded).
• 0.2.23 — History readers: Codex zombie session filter (sessions with no user input excluded), OpenCode SQLite reader (reads from ~/.local/share/opencode/opencode.db instead of nonexistent ~/.opencode/).
• 0.2.24 — History readers: Codex duplicate message fix (skip response_item with role=user), old .json session format removed (no cwd field = leaked into all projects).
• 0.2.25–0.2.28 — CliCapabilities API: ModelInfo, PermissionModeInfo, CliFeatures per CLI tool. Gemini --model flag support, Codex configurable permission modes, Claude conditional --dangerously-skip-permissions.
• 0.2.29 — Dynamic model discovery: discover_capabilities() reads CLI configs (Codex ~/.codex/config.toml, OpenCode opencode.json). Model picker enrichment at runtime.
• 0.2.30 — Probe + Context tracking: probe_all() discovers installed CLIs with caching (~/.gate4agent/probe-cache.json). ContextTracker accumulates tokens per session, computes remaining context. Extended TurnComplete with cache_read_tokens, cache_write_tokens, reasoning_tokens, context_window, is_cumulative. Codex event_msg/token_count parser (cumulative totals + model_context_window). Claude/Gemini/OpenCode parsers extract cache and reasoning tokens. Fixed Claude model IDs (4 → 4.6). Removed image_to_prompt_reference() and PipeSession::tool().
• 0.2.31 — ContextTracker wired into runtime: AgentInstance now holds a ContextTracker, updated on every TurnComplete event. AgentRenderSnapshot gains context_percent: Option<f64> — consumers get live context window usage without any extra work.
• 0.2.37 — Full OpenCode model catalog + remove Claude aliases. All 49 OpenCode built-in models (12 free first, 37 paid). Removed redundant opus/sonnet/haiku alias entries from Claude.
• 0.2.36 — feat: cure runs lazily on first history load or session start. ensure_cure_once() populates ~/.gate4agent/models.json from OpenCode cache before tool.capabilities() is called, so context windows are accurate from the first interaction.
• 0.2.35 — feat(history): SessionUsage from loaded sessions. load_session_with_usage() extracts token counts from Claude JSONL history. Context tracker is initialized when loading past sessions, so context_percent shows real values in UI instead of 0%.
• 0.2.34 — fix(context): correct usage_percent formula + cure module. used_tokens() now = input + output + cache_read + cache_write (matches OpenCode's formula). Per-turn mode: input/cache REPLACE (snapshot), output ACCUMULATES. Codex event_msg normalizes input_tokens by subtracting cached_input_tokens to avoid double-counting. New cure module: runtime model discovery from OpenCode disk cache (~/.cache/opencode/models.json) with optional OpenRouter fallback (cure-network feature). Persists to ~/.gate4agent/models.json, overlays context windows onto hardcoded capabilities.
• 0.2.33 — fix(capabilities): correct context windows and model IDs for all 4 CLIs — Claude Opus/Sonnet 4.6 → 1M tokens, Codex all → 272K, Gemini preview IDs fixed, OpenCode models updated to current.
• 0.2.32 — Fix context_percent always 0%: Initialize ContextTracker from model capabilities at SessionStart (matches model ID → context_window). Reset tracker on new session spawn so stale data doesn't persist across sessions.

The phased roadmap (P1–P4: one app↔harness protocol, light-harness extraction, full node-surface relay, cowork) was for the node/c2/harness/TUI stack and now lives in hatchery's ROADMAP.md, not here.

Migration guide

0.2.0 → 0.2.1

• OpenClaw removed — CliTool::OpenClaw no longer exists. If you matched on it, delete that arm. OpenClaw was never functional (unverified daemon protocol, fictional acpx API surface).
• PipeSession restored — 0.1.x callers that used PipeSession::spawn(config, prompt, options) compile again. The PipeSession now includes SessionEnd synthesis (previously only in the 0.2.0 pipe_runner).
• TransportSession is now a thin wrapper over PipeSession. Its public API (spawn, subscribe, session_id, send_prompt, kill) is unchanged. Internal: no more TransportHandle enum, no dead Pty variant.
• DaemonNotRunning / DaemonProbeTimeout error variants removed — they were only reachable via OpenClaw. Remove any match arms for these.

0.2.18 → 0.2.19

• RpcSession removed — if you were using gate4agent::rpc::RpcSession or the top-level gate4agent::RpcSession / RpcSessionOptions / RpcSessionError re-exports, migrate to [AcpSession] instead. ACP does everything RpcSession did (bidirectional JSON-RPC 2.0, host handlers, multi-turn) but follows the standard Agent Client Protocol.
• Shared rpc primitives unchanged — RpcRequest, RpcResponse, RpcError, RpcNotification, RpcId, HostHandler, MethodRouter, RejectAllHandler, PendingRequests, IdGen, classify_line are all still exported. Only the RpcSession transport struct is gone.

0.1.x → 0.2.1

1. Events: AgentEvent::Pipe* → neutral names. Rename all match arms:

   • PipeText → Text
   • PipeToolStart → ToolStart
   • PipeToolResult → ToolResult
   • PipeThinking → Thinking
   • PipeTurnComplete → TurnComplete
   • PipeSessionStart → SessionStart
   • PipeSessionEnd → SessionEnd

2. PipeSession::spawn — signature unchanged: PipeSession::spawn(config, prompt, options). Compiles directly.

3. SpawnOptions: new unified struct. Fields: working_dir, prompt, resume_session_id, model, append_system_prompt, extra_args, env_vars.

4. CliTool is now non-exhaustive in effect (new variant: OpenCode). Add arms or a _ => fallback.

Support the Project

If you find this tool useful, consider supporting development:

License

MIT