Sounding

Sounding: an invited decision partner for other agents

Sounding is an invited decision check for consequential work. Give it a proposed action, the evidence for and against it, who owns the decision, and the cost of waiting. It recommends proceed, revise, or pause, identifies one question that could change the action, and suggests a bounded next step. It does not approve plans or act on anyone’s behalf.

Version 0.1.9: October 5, 2026

Changes since 0.1.4, all on October 5 (details in the changelog):

• 0.1.5: when the deciding question is a definition or rule the caller already has but left out, Sounding returns revise and names what to supply, instead of pause.
• 0.1.6: MCP protocol version negotiation follows the specification; an unsupported MCP-Protocol-Version header gets HTTP 400.
• 0.1.7: when a decision removes or weakens a safeguard in a regulated or high-stakes area, Sounding names who carries that risk afterwards.
• 0.1.8: dispositions match the stakes: low-stakes, easily reversed clarifications proceed with the point listed as an assumption instead of revise.
• 0.1.9: model time limit 90 seconds and output limit 3,000 tokens; failed assessments return and record a short reason code, such as Assessment unavailable (timeout); try again later.

Changes 0.1.7 to 0.1.9 came from replaying 57 real decisions from one build through Sounding and comparing its answers with what was actually decided.

Version 0.1.4: October 4, 2026

The hosted Node runtime reports its version in the MCP serverInfo, at /healthz, and in each assessment result's _meta["com.aisounding/runtime"], together with the configured requested_model and the served_model that OpenAI reports for that call. A live call after deployment reported requested_model and served_model both as gpt-6-sol. The structured assessment itself is unchanged. The Python reference runtimes report the same version but do not add model metadata.

The agent instruction on /start now says what to do when Sounding is unavailable: retry once, then treat the action as unchecked, not approved, and follow the normal approval process.

Evaluation results (repeat-run consistency, one-sided framing, should-pass checks and a comparison with another independent reviewer) are published with every input and output at aisounding.com/evaluation. A public changelog is on /docs.

Assessment Support update — October 3, 2026 (0.1.2)

New responses replace the old confidence field with assessment_support: an object containing level (strong, moderate or tentative) and a short, case-specific explanation. The level rates how settled the underlying decision is on the supplied evidence: strong means the evidence clearly points one way and missing facts are unlikely to change it; moderate means it leans one way but a named assumption could reverse it; tentative means the evidence conflicts, is thin or cannot distinguish the options, so the next step is mainly a way to find out. It is not the probability of eventual success or authorization to act, and it does not rate whether the recommended next step is sensible. A pause pending one decisive fact is usually tentative. The explanation names what would most likely change the level.

The tool remains sounding_decision_check. Decision (or proposed_action) and goal remain the only required inputs; all existing context fields remain optional. This is a response-contract change: clients reading confidence must read assessment_support.level and assessment_support.explanation instead and refresh cached tool definitions. There is no conversion back to confidence. Historical recorded examples retain their original output and are labeled as such.

The original one-call architecture, model default and 1,200-token ceiling remain. This focused change does not adopt the broader V1.1 response layout or the abandoned reviewed-dialogue architecture.

Request inputs

Only a nonempty decision and goal are required. Use decision for a proposed action, options or question; the existing proposed_action name remains accepted. If both are supplied, they must match.

{

"decision": "Try a revised team handoff note next week?", "goal": "Reduce missed handoff information." }

More relevant information generally supports better guidance. Optional means not required to submit, not unnecessary to assess. Include relevant context already available; identify unknowns rather than inventing facts or authority. A calling AI should not turn every optional field into a question for the human. If missing information could change the recommendation, Sounding should identify the uncertainty and give bounded advice or a targeted question. Acceptance of a request is not approval to act.

Optional fields: evidence, constraints and affected_people are arrays of strings (since 0.1.14 the hosted endpoint and the Python CLI, local MCP and HTTP adapters also accept the string arrays evidence_against, alternatives and prior_decisions); reversibility, urgency, decision_owner and task_id are strings. Omit unknown context, rather than guessing or sending null. Empty optional lists/text are accepted and do not assert that no constraints or affected people exist. A supplied task ID must be nonempty; an omitted ID is generated and returned. No substantive facts or permission defaults are generated.

Minimal request and complete compatible request work through the Node endpoint, Python CLI and Python MCP adapters. Reconnect MCP clients to refresh cached tool schemas. The single model call and 1,200-token ceiling remain unchanged; the output now uses Assessment Support. This optional-input release is separate from the broader experimental 1.1/2.0 designs.

Call it locally

Python 3.10+ and an OpenAI API key are required. No third-party Python package is needed.

Set OPENAI_API_KEY in your environment, then:

python3 sounding_bridge.py --input example_request.json

Windows PowerShell, after setting OPENAI_API_KEY in your environment:

py sounding_bridge.py --input example_request.json

An agent can write a request JSON file, invoke the command as a subprocess, and parse one JSON object from standard output. Operational errors go to standard error with a nonzero exit code. The request contract is described above; example_request.json shows a complete optional-context example. The output contains task_id, disposition, reason, material_question, evidence_basis, assumptions_to_check, next_step, and assessment_support. An empty material_question is valid when the plan should proceed.

Call it from an MCP client (local preview)

sounding_mcp.py exposes one stdio MCP tool, sounding_decision_check. Configure an MCP-capable agent to launch it as a local subprocess with Python. Supply decision and goal, plus available optional context, as the tool arguments. A typical client configuration needs a command and arguments like these (the exact settings format varies by client):

{

"command": "py", "args": ["C:\\path\\to\\Sounding\\sounding_mcp.py"] }

Set OPENAI_API_KEY in the environment of the process that launches the MCP server. On Windows, if the host does not pass it through, the adapter reads the saved OPENAI_API_KEY from the current user's Windows environment settings at tool-call time. It does not print or save the key in this repository. The Windows desktop configuration tested locally uses py as the command, the absolute path to sounding_mcp.py as its single argument, the Sounding folder as the working directory, and blank environment fields. Fully restart the client after changing the configuration; a client may keep an older server process alive. The desktop client has also stalled on some otherwise fast calls, so this configuration is not yet a reliability guarantee.

For the fuller private formation context, add --private-prototype and the local prototype directory to the configured arguments. The client cannot set the model or select a private directory through a tool call; SOUNDING_MODEL or --model is a local launch setting. The default model is gpt-6-sol unless overridden; the effective setting of the September live runs was not independently captured. From version 0.1.4 the hosted runtime reports the served model in each result's _meta; a live call on October 4, 2026 reported gpt-6-sol. The server reads newline-delimited JSON-RPC over standard input/output and does not listen on a network port. It makes an OpenAI request only when the tool is invoked, then returns advice to the caller. A model call runs the bridge CLI in a child process with a 60-second deadline, returning a bounded error if it exceeds that limit. A slow call may therefore time out even if the API would eventually complete. The caller remains responsible for reviewing it and deciding what to do.

This is an interface preview. Nine local contract tests cover MCP initialization, tool discovery, validation, response shape, and the bounded timeout. In a private September 28, 2026 demonstration, six fictional public-role requests returned assessments: two through the CLI, three through a desktop Codex MCP client, and one through a direct PowerShell MCP client. Five recommended revise; one recommended proceed. Several other desktop MCP attempts stalled despite model calls completing in roughly seven seconds. The cause of those client stalls remains unresolved. The six fictionalized inputs and recorded outputs are published at aisounding.com/cases. The private evidence records remain outside this repository. These demonstrations show that the interface can work and provide inspectable answers; they do not establish reliable desktop operation or improved real-world decisions.

For local diagnosis, the adapter writes event times, process ID, status, response byte count, and elapsed seconds to %LOCALAPPDATA%\Sounding\mcp-diagnostic.log on Windows (or ~/Sounding/mcp-diagnostic.log otherwise). The log omits case content, model output, and credentials. The MCP response carries the full assessment once in structuredContent and a short text pointer in content; clients should read structuredContent for the full answer. response_serialized, response_written, and response_flushed distinguish stages of the adapter's output. Even response_flushed does not prove the client displayed it. Share only the relevant tail when investigating a stalled call.

The model request uses the Responses API with store: false and a strict JSON schema. Input is sent to the configured model. The tool has no GitHub token, no forum account, no scheduler, and no write access to any external service. The calling agent remains responsible for checking its evidence, applying its own permissions, and deciding whether to act.

Invite external agents through a remote MCP endpoint

sounding_http.py provides a stateless HTTP MCP endpoint at POST /mcp. It uses the same optional-context request contract and public role.md as the local version. It can be deployed from the included Dockerfile on a container host with a public HTTPS URL. The Python service speaks HTTP behind the host's TLS ingress; never expose its port directly to the internet. No GitHub App installation is required for this route. Keep the GitHub repository private if desired.

Live SiteGround Node.js endpoint

The Node port in sounding_siteground.mjs is deployed from the private working repository's main branch (this public repository mirrors its source) as a SiteGround Node.js Project on GrowBig. The public MCP address is `https://aisounding.com/mcp`. During the open preview, no token is requi