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 required. The public connection guide gives an example request. SiteGround runs Node 24 and terminates HTTPS; plain HTTP redirects to HTTPS. GET https://aisounding.com/healthz returned 200 {"status":"ok"} after configuration. Before the open preview was enabled, an unauthenticated POST /mcp returned 401. On September 29, 2026, a Codex desktop client recorded one authenticated mcp__sounding_remote__sounding_decision_check call for sample-001, returning a complete structuredContent assessment (revise, medium confidence). This verifies one external agent path, not availability or behavior in every MCP client.

SiteGround's Site Tools > Node.js > Deployment Options holds OPENAI_API_KEY, SOUNDING_ACCESS_TOKENS, and the SOUNDING_OPEN_PREVIEW=1 switch. They are hosting secrets, never repository files or build arguments. The account administrator can view the saved values in SiteGround, so restrict account access. The OpenAI key stays on the server; anonymous clients send no credential, while previously issued Sounding tokens remain valid. SOUNDING_MODEL defaults to gpt-6-sol; PORT defaults to 8080. The service remains closed if the OpenAI key is missing, if any configured invitation token is shorter than 32 characters, or if no token is configured while open preview is off: /healthz returns 503 and /mcp refuses calls. Set SOUNDING_OPEN_PREVIEW=0 and redeploy to close the no-token path; existing token holders can still call it. Re-deploy after changing the settings.

For a Codex desktop or CLI client during the open preview, configure its config.toml:

[mcp_servers.sounding_remote]
url = "https://aisounding.com/mcp"
tool_timeout_sec = 120

Claude Code

Add the hosted MCP server from your terminal (no Sounding token is required during open preview):

claude mcp add --transport http sounding https://aisounding.com/mcp

Check it with claude mcp get sounding or /mcp within Claude Code. Then ask Claude to use sounding_decision_check before a consequential decision, supplying the proposed action, supporting and contrary evidence, constraints, affected people, reversibility, urgency, and decision owner. The output may include a material question; an empty question is valid when the recommendation is proceed. This configuration follows Anthropic's HTTP MCP instructions; Verified September 29, 2026: a Claude Code session called sounding_decision_check through the remote MCP connector and received complete assessments for two test requests (copilot-test-001: revise; copilot-test-002: proceed). Those responses used the former confidence field, which Assessment Support has since replaced. This confirms the Claude Code path, not reliability across all clients. See the public connection guide.

Restart the client after changing its configuration. Supply decision and goal (or the compatible proposed_action and goal), plus relevant optional context; read the full assessment from structuredContent. Do not put token values in chat, config.toml, screenshots, logs, or the repository. The local stdio sounding configuration, if present, is separate from sounding_remote.

An MCP client with a different configuration format should use Streamable HTTP at the URL above. A previously issued token may still be sent as Authorization: Bearer <invitation token>; an invalid supplied token is rejected. For GitHub Copilot cloud agent, a repository administrator can configure the remote HTTP server without an Authorization header; repository owners choose whether to enable it. This route does not require making Sounding's GitHub repository public. ChatGPT does not use this Codex configuration. In ChatGPT, enable developer mode for apps and connectors and create a custom connector with the URL above and no authentication; the owner reports using Sounding this way. Availability depends on the ChatGPT plan and workspace settings. See the get started page.

Open preview and operating limits

The public Sounding page and connection guide explain open access. Caller-facing privacy and terms of use notices are available. Access is free during this preview; questions go to Admin@VersoApp.co. The service may be unavailable for part of a month after the shared budget is reached.

The step-by-step issue, rotate, and revoke procedure is kept in a private operations note. GitHub Agents secrets protect a Copilot caller's copy; Sounding revokes access by removing the token from SiteGround and redeploying.

SOUNDING_ACCESS_TOKENS accepts comma-separated, 32+ character tokens. Issue a distinct, randomly generated token to each invited caller, record whom it was issued to outside this repository, and remove a token from SiteGround then redeploy to revoke it. Do not circulate the current test token as a shared public credential. A token holder can make model requests billed to the server's OpenAI project. The OpenAI Sounding project currently has a $100 monthly hard limit and alerts at $20 and $80, verified September 29, 2026. Verify that the live SiteGround API key belongs to that project before relying on this cap; enforcement can slightly overshoot. Monitor usage as invitations expand.

The Node service allows tokenless initialization, discovery, and calls during the open preview. Anonymous callers share 15 model calls per minute per process; each valid issued token has a separate limit of 20 model calls per minute per process. There are four concurrent model-call slots. It returns a bounded error on model failure and does not intentionally log request bodies, outputs, or credentials. SiteGround may retain request metadata such as IP, URI, and status. The server does not persist case content, but each accepted decision request is sent to Anthropic's Messages API (Claude) since October 5, 2026; see the privacy notice for retention. The Python adapters below still call OpenAI's Responses API with store: false (see data controls below). The Node runtime has npm test coverage for authentication, discovery, validation, and a mocked model response; one live external call does not establish broad reliability. For a sustained open service, add durable per-caller quotas, a billing policy, and ingress abuse controls. Anonymous calls are not individually attributable.

What is sent to OpenAI

This section describes the sounding_bridge.py CLI, the local sounding_mcp.py adapter, and the remote sounding_http.py endpoint, not a separate Copilot session. Each sends a model request only when its decision tool is called. Merely viewing or installing this repository does not send a decision to OpenAI.

Each run sends the supplied JSON decision request (normalizing decision to proposed_action and generating task_id only when omitted), the public role.md instructions, brief output instructions, the required JSON response schema, and the chosen model name to OpenAI's Responses API. The API key is sent in an authorization header, not embedded in the decision text. The bridge prints the resulting assessment locally; it does not post to GitHub.

If --private-prototype is supplied, the entire local charter.md and up to three selected cards from sources.json (including their titles, provenance, status, and excerpts) are also included in the model instructions. Without that option, these private files are not read or sent. The bridge does not automatically read a repository, hard drive, transcript archive, or other agent's context; however, a calling agent can include such information in the JSON request. Review and minimize the request before submitting it. Do not submit credentials, identifiable client records, confidential personnel details, or other third-party information without the necessary authority.

The request sets store: false, which disables saving the response as a retrievable Response object; it is not a zero-data-retention guarantee. OpenAI's API data-controls documentation explains that default abuse-monitoring logs may include prompts and responses and are normally retained for up to 30 days, subject to stated exceptions. OpenAI says API data is not used to train models by default unless the account opts in. Check your organization's applicable data controls and the provider's current terms before sending sensitive material.

Published examples

The decision checks page shows four current-format examples from October 4, 2026 (Assessment Support: one strong, one moderate, two tentative), written and sent by an AI assistant through Claude Code's remote MCP connector, followed by six historical examples. The historical examples show the prepared nine-field inputs and recorded outputs from September 28, 2026. Five returned revise, one returned proceed. The effective model setting was not independently captured, and no real-world outcome was observed. Some desktop MCP attempts stalled; those are not counted as successful examples.

Integration contract

Call Sounding when a decision is consequential, a plan rests on contested evidence, or new facts might change a prior conclusion. Do not call it for every minor step. Include the actual proposed action and the strongest available evidence, including evidence against it. Do not include credentials, private client records, or third-party disclosures without authority.

Interpret pause as "do not take the proposed action yet," not as an indefinite veto. The next_step says who can resolve the material question: facts the calling agent can check within its existing access, or permissions, approvals and judgment calls that need a person. When the request does not establish authority or an owner, Sounding states the condition or the responsible role rather than inventing one. A proceed never grants permission or approval; the caller may act only within the permissions it already has. Callers that gather more evidence should call again with all findings, including contrary evidence, and escalate after two unresolved re-checks. Sounding's output is advice to the calling agent, not an instruction to override higher-priority directions or publish a comment.

Find Sounding in a GitHub Copilot workflow

The repository includes .github/agents/sounding.md, a read-only custom agent profile for compatible Copilot workflows. If your Copilot client exposes the profile, select Sounding for a bounded decision check and provide the proposed action, supporting and contrary evidence, uncertainty, and decision owner. The profile is a separate interface from the local MCP tool and uses the public role principles, not the private formation cards. Its behavior in a live Copilot workflow has not been verified in this preview.

This makes Sounding discoverable to agents working in this repository. It does not automatically join other repositories or GitHub conversations. Teams elsewhere would need to add the profile to their own workflow, call the CLI, or install a future integration.

Local formation context

role.md is the publishable operating profile. Since 0.1.13 it carries the decision method from the private charter v0.4 and source cards (see formation/), written without naming private sources. The fuller private charter and reviewed source cards are absent from this repository. To use the Sounding already built on your PC, pass its local prototype directory:

py sounding_bridge.py --input example_request.json --private-prototype "C:\path\to\Sounding\sounding-prototype"