synthesised tools: HTTP-restricted sandbox, tool-declared categories, env forwarding

[emesal]

motivation

The gersemi Trading 212 plugin needs to run as a sandboxed synthesised tool with constrained HTTP access. tein now supports ContextBuilder::http_allow() for URL-prefix-restricted HTTP in sandboxed contexts (tein#145). chibi needs plumbing to connect this to synthesised tool loading, plus several related capabilities for tools that make network calls with permission gating.

Full design spec: gersemi/docs/plans/2026-03-17-chibi-plugin-design.md

changes needed

Four independently landable chunks, plus one follow-up:

1. tool-declared category and summary_params

Synthesised tools currently get ToolCategory::Synthesised hardcoded at registration. Allow tools to declare their category.

Convention format:

(define tool-category "network")
(define tool-summary-params '("ticker" "quantity"))

define-tool format:

(define-tool t212_place_market_order
  (description "Place a market order")
  (category "network")
  (summary-params '("ticker" "quantity"))
  (parameters '(...))
  (execute (lambda (args) ...)))

Changes:

• Extend syntax-rules in HARNESS_PREAMBLE with additional patterns (with/without category, with/without summary-params)
• %tool-registry% entry grows from 4 to 5+ elements: (name desc params handler category-or-#f)
• extract_multi_tools reads category + summary_params from entries
• Convention format: check for tool-category / tool-summary-params bindings post-eval
• Map category string → ToolCategory variant; unknown strings → keep Synthesised

Valid category strings: "network", "fs_read", "fs_write", "shell", "memory", "flow", "vfs", "index", "eval".

2. network category: no-URL fallback in permission prompt

The ToolCategory::Network match arm in send.rs calls args.get_str("url") and classifies it. For synthesised tools categorised as network that don't have a url parameter, classify_url("") returns Sensitive(Unparseable) — producing a confusing prompt.

New behaviour: when a network-categorised tool has no url arg (or empty), build the display text from tool name + summary_params values and fire check_permission with that. The prompt becomes:

[t212_place_market_order] market buy 10x AAPL_US_EQ [Y/n]

3. HTTP-restricted sandbox for synthesised tools

Enable sandboxed synthesised tools to make HTTP requests to specific URL prefixes.

tein dep: enable http feature in Cargo.toml (currently ["json", "regex"]).

Config:

[tools.http.allow]
"/tools/shared/trading212.scm" = [
    "https://demo.trading212.com/",
    "https://live.trading212.com/",
]

Longest-prefix match, same pattern as [tools.tiers].

build_tein_context: gains http_prefixes: Option<Vec<String>> parameter. When Some and tier is Sandboxed, calls .http_allow(&prefixes) on the tein builder. SandboxTier stays as-is (two-variant Copy enum) — prefixes travel alongside, not inside.

load_tools_from_source_with_tier: resolves HTTP prefixes from ToolsConfig for the VFS path and passes them through.

4. env var forwarding into sandboxed contexts

New config section for forwarding real process env vars into sandboxed tein contexts:

[tools.env]
"/tools/shared/trading212.scm" = [
    "T212_KEY", "T212_SECRET", "T212_ENV",
    "T212_ALLOW", "T212_DENY", "T212_DEFAULT",
]

During tool loading, chibi checks [tools.env] for the VFS path, reads the listed vars from the real process env, and passes them to ContextBuilder::environment_variables(). Scheme code accesses them via (get-environment-variable "T212_KEY").

Currently build_tein_context never calls .environment_variables() — this is new infrastructure.

5. (follow-up) trust-declared HTTP prefixes

Tools can declare what HTTP prefixes they need:

(define tool-http-allow '("https://demo.trading212.com/" "https://live.trading212.com/"))

Config controls whether these are honoured:

[tools.http]
trust-declared = false  # global toggle

[tools.http.allow]
"/tools/home/admin/" = "trust-declared"  # per-path trust

This is a convenience feature on top of chunk 3. Not needed for MVP — explicit [tools.http.allow] per-path grants are sufficient.