Java Agent Tool Boundary

teaql-java 1.525-RELEASE provides a tool registry and policy boundary through teaql-context-runtime-tools. It does not make every possible I/O capability available automatically, and it does not replace application authorization, network policy, credential scoping, or output validation.

Verified Runtime Boundary

Stage	Verified behavior
Discovery	ContextTools loads ToolProvider implementations through Java ServiceLoader and accepts explicitly registered providers.
Availability	Tools.has(type) reports whether a provider was registered. Tools.get(type) throws when the tool is unavailable.
Risk classification	Each ToolDescriptor declares MEMORY_ONLY, EXTERNAL_RESOURCE, or PRIVILEGED.
Policy	The default allowStandardTools() policy allows only MEMORY_ONLY. External-resource and privileged tools require explicit policy.
Acknowledgement	A descriptor may require an exact environment acknowledgement. Missing acknowledgement causes SecurityException.
Intent	The verified HTTP API returns an intent phase; purpose(...) or auditAs(...) is required before execute() is exposed.

Provider presence is not authorization. A provider must be discovered, allowed by ToolPolicy, and—when its descriptor requires it—acknowledged. The application must still decide whether the current actor, tenant, destination, method, payload, and response are permitted.

Verified HTTP Tool

The current source tree contains one concrete tool module: io.teaql:teaql-tool-http. Its AgentHttpTool supports get(url) and post(url, body). The provider classifies it as EXTERNAL_RESOURCE, so the default policy denies it.

Tools tools = ContextTools.builder(userContext)
    .policy(ToolPolicy.builder().allow(AgentHttpTool.class).build())
    .build();

String body = tools.get(AgentHttpTool.class)
    .get("https://api.example.com/rates")
    .purpose("Fetch exchange rates for settlement")
    .execute();

For a side-effecting request, use an audit description:

String body = tools.get(AgentHttpTool.class)
    .post("https://api.example.com/inventory", payload)
    .auditAs("Synchronize approved inventory changes")
    .execute();

The verified implementation records intent in the UserContext trace around execution. It does not, by itself, enforce host allowlists, TLS pinning, response schemas, retry policy, rate limits, credential isolation, or payload redaction.

Not Verified as Current Modules

Earlier versions of this page listed teaql-tool-mq, teaql-tool-fs, teaql-tool-email, and teaql-tool-extra, together with guessed ctx.mq(), ctx.fs(), ctx.email(), and ctx.excel() APIs. Those modules and methods were not present in the verified 1.525-RELEASE source tree and have been removed from the current reference. Add a capability only after inspecting its released provider, descriptor, policy, acknowledgement, and intent API.

Production Checklist

• Register only required providers and dependencies.
• Start with denyAll() or an explicit allowlist for high-risk deployments.
• Treat acknowledgement variables as conscious deployment approvals, not as authorization credentials.
• Restrict outbound destinations and credentials outside the TeaQL tool API.
• Validate request payloads and response data at the application boundary.
• Review trace/log output for secrets and personal data.
• Test unavailable, policy-denied, acknowledgement-denied, and allowed paths.

See Security and Trust Boundaries and Java Runtime Extension Points.