Feedback #

View this page as Markdown

Prompt:

That refusal made no sense to me. File it with the platform.

Also works:

  • "Report that the storage guide never says how big a transfer can be."
  • "Tell the platform we had to work around the missing rename."
  • "What happened to the report we filed yesterday?"

What your tool does #

Your tool does each of these with no browser approval:

  • Files the report with submit_feedback as its own filing, or as yours when you dictated it. It attaches the evidence: the action, the refusal name, and the refusal's reference.
  • Files one whenever something got in its way: an unexpected refusal, a workaround it needed, a missing capability, or a missing page. The platform welcomes these reports.
  • Quotes nothing of your own content and puts no personal details in a report. The text says what was attempted and what came back.
  • Reads a report's status later with read_feedback, by the id the filing returned, and retries the call when the platform says the fix is live.
  • Adds to a report you filed, or answers a question the platform asked about it, by calling submit_feedback again with the same problem_key and the new text. The filing joins the same issue as a further report. A reporter has no comment action on the platform's space, so its reports are the channel.
  • Corrects or withdraws a report you filed by calling submit_feedback with amends, the report's number, and the corrected words, or withdraws: true (step 3).

What you need #

  • The refusal you want to report, exactly as your tool showed it to you. A management action's refusal includes a ten-character reference code. Keep a copy of it.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • A signed-in session in your connected tool, or an account-scoped minted token (Connect Claude Code or Codex). A token scoped to one application is refused token_scope_refused on every feedback action. That application's backend reaches its own space through the egress gateway instead.
  • The refused call's action, refusal name, and reference, read from the refusal itself.

Steps #

The platform keeps its feedback in an issue service. An issue records one problem. A report is one filing about an issue, in the filer's own words, and is never edited. Several reports can belong to one issue.

1. File a report #

A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Leave out of a report anything you do not want us to have, or do not file the report. Your AI coding tools quote nothing of yours in a report of their own. The names of actions, refusals, applications, and files are not personal details.

Call submit_feedback. This report is the tool's own, about a refused deploy, its evidence copied from the refusal; the reference is an invented example of the form. A test checks these members against the action's request.

{
  "source": "agent",
  "kind": "bug",
  "title": "deploy refused health_path_unserved although server.mjs answers /health",
  "text": "Called deploy for a new application. The refusal said no source file names the health path's last segment, but server.mjs at the zip's root answers GET /health.",
  "impact": "worked_around",
  "workaround": "Moved the health route into a file named health.mjs.",
  "evidence": { "action": "deploy", "refusal": "health_path_unserved", "reference": "3f9c2a7b1d" }
}

The members submit_feedback takes:

Member What it contains
source Required. agent for the tool's own filing, person for a report you dictated.
provider, session Optional, for agent: the tool's provider name and its session id, both or neither.
kind Required. bug, gap for a capability you needed and could not find, docs for a page that is missing or wrong, friction for something that works but is hard, or praise.
title Required. Up to 200 characters.
text Optional. What was attempted and what came back, with no personal details, up to 20,000 characters.
impact Optional. What the problem cost you: blocked, worked_around, annoyed, or none.
workaround Optional. What you did to get past it, up to 4,000 characters.
proposed_resolution Optional. The fix you would suggest, up to 4,000 characters.
evidence Optional. action, refusal, reference, code_site, and a context of up to 20 short strings under keys of lowercase letters, digits, and underscores. The older environment and version give the build you saw. Any other member is refused. The refusal gives the members evidence takes or, for a long list, their count and the action's reference page.
labels Optional. Up to 20 short lowercase labels.
restricted Optional. true for a security concern. A read made for a reporter, as read_feedback makes on the platform's space, then never returns its issue to another reporter.
problem_key Optional. Your own name for the problem. A later filing with the same name adds a report to the same issue. Praise is the exception: praise and a report of another kind under one name go to two separate issues. Without one, the platform derives it from the kind, the title, and the evidence's action and refusal.
files Optional. Up to 4 screenshots, each a PNG, JPEG, or WebP file of at most 524,288 bytes that you stored first. Each names its application, area, and name, and its environment, the deploy target when you leave it out.

To attach a screenshot, store it first. Call mint_upload_grant for an application of your account and an area bound to it, run the put line it returns, and name the stored file in files. The platform reads each file under your own sign-in or token, before it files anything, so a file it cannot find, or one larger than 524,288 bytes, is refused and nothing is filed. The image is stored with your report as you sent it, and no page of the platform shows it.

The request also takes older names for some members and kinds, which Actions lists. A question or a task from your tool is refused, because only the platform team files those kinds.

The response contains your report as filed, the issue it belongs to, and an outcome:

  • filed: a new issue was opened for it.
  • linked: the report joined an existing issue.
  • retried: the same filing arrived again, and nothing changed.
  • noted: praise, recorded and closed at once.
  • confirmed: you called again with report and repeat_of, and your report now belongs to the issue you named (step 3). On the platform's own space, where that issue was merged as a duplicate, your report belongs to its master instead.
  • amended: you called with amends, and your correction or withdrawal was filed as a further report beside the one it amends (step 3).
  • related: you sent repeat_of, and one of the two is praise and the other is not. Nothing is joined. Your report stays on its own issue, which the response returns as issue. The two issues are related, unless either is restricted, and no member of the response names that relation.

On the platform's own space, candidates is an empty list: the platform team links your report to any issue it repeats when it triages it. issue is null when your report belongs to a restricted issue, including when your own filing set restricted; your report and the outcome are returned as before. masked lists the kinds of credential the service found in your text and hid. Rotate each one.

personal_removed lists the kinds of personal detail the platform removed from your report before storing it: email_address, telephone_number, or card_number, in that order. Each detail is replaced by a mark, such as [email address removed], and the list is empty when nothing was removed. What is kept says where each kind is removed.

2. Read its status #

Call read_feedback with issue set to the id the filing returned. The id below is an example. A test checks these members against the action's request.

{ "issue": "#4127" }

The response shows the issue as a reporter sees it:

  • its state: new, open once it has been triaged, waiting while it needs something before it can move on, fixed once a fix is built and being released, or closed;
  • its outcome once closed, such as verified, done, as_designed, declined, or duplicate;
  • a one-sentence sentence that describes the state and outcome in words;
  • the workaround, when the platform team wrote one;
  • the note, a message written for everyone who reported the issue, or null. In it the platform team asks a question or gives news on any state. A landed fix writes when its change landed and that it serves from the first release that carries it, shown while the issue is fixed, or closed done or verified;
  • live_in, the build the fix is live in, or null;
  • your own reports on it, and never another reporter's words.

A report another account filed is refused not_found. So is an issue number someone quotes to you that differs from the identifier submit_feedback returned to you. Where one of your own reports joined that issue, the refusal may name your own submission for it, which read_feedback with that identifier reads. It only ever names an issue you can read. For another account's issue, a restricted issue, or a number no issue has, it names nothing, so all three look the same.

Call read_feedback with no argument to list your own submissions. Add state to list only one state, or query to search your own submissions for words. Nothing is deleted when the state moves, and a closed issue stays readable.

3. Add to a report, correct or withdraw it, or join it to an issue #

To add to a report you filed, or to answer a question the platform asked about it, call submit_feedback again with the same problem_key and the new text. The filing joins the same issue as a further report, since a report is never edited. The platform's question reads in the issue's note. Where the platform team is waiting on your answer, the filing returns the issue to its queue. A reporter has no comment action on the platform's space: commenting, updating, and settling are the platform team's to do, so your reports are the channel.

To correct a report you filed, call submit_feedback with amends, the report's number from the filing's response, never the issue's id, and the corrected title, text, impact, workaround, or proposed_resolution. To withdraw a report filed in error, send withdraws: true with amends. The example below withdraws report 57, an invented number. A test checks these members against the action's request.

{ "source": "agent", "amends": 57, "withdraws": true, "text": "Filed against the wrong application." }

The correction is filed as a further report beside the one it amends, which stands as you filed it, and the platform team reads the two side by side. It joins every issue the first report belongs to at that moment, and the response's outcome reads amended. Where you name no title or impact, the amendment keeps the first report's, except that a withdrawal with no impact carries none. A text, workaround, or proposed_resolution you leave out is empty on the amendment, so repeat any words that still stand.

A withdrawal changes nothing on its own: the platform team reads it and settles the issue. Your latest amendment of a report is your standing word, so withdraws: false takes a withdrawal back. An amendment takes no kind, evidence, problem_key, labels, restricted, report, repeat_of, or files, and each is refused invalid_request. A report another account filed is refused 404 not_found, as a number no report carries is.

When you know the issue your report repeats, such as the issue an earlier report of yours belongs to, call submit_feedback again with report, your report's number, and repeat_of, that issue's id. A new filing can also name repeat_of directly, which adds it to that issue as a further report.

A new filing's response then carries repeat_of where the platform joined your report to that issue on this call. Where the service's own match had already linked the report there when it was filed, the response carries no repeat_of. Where one of the two is praise and the other is not, your report keeps its own issue, the outcome reads related, and the response carries no repeat_of. On the platform's own space, repeat_of names only an issue that holds one of your own reports.

There, an issue merged as a duplicate counts as its master: your report joins the master, and the response's issue and any repeat_of give the master. A repeat_of naming a restricted issue, or an issue that holds none of your reports, is refused 404 not_found, as one naming no issue is. The lookup counts against read_feedback's per-minute limit. The report is still filed: send the same call without repeat_of to get it back.

Known issues in a refusal #

A refusal can point to a known issue. When the platform team already knows about a refusal you receive, its detail ends with a sentence that gives the issue and any workaround. Once the fix is released, that sentence gives the build that includes it.

What the platform adds to a report #

When your evidence quotes the reference of one of your own calls, the platform reads its own record of that call. For a bug about a call that was refused, it adds the action, the refusal, the place in its code that returned the refusal, and the build that handled the call. The response then contains stamped: true, and the report's evidence is marked stamped. The platform can match a stamped report to others with the same cause, without anyone reading its text.

Any other report is not stamped: a report about a call that succeeded or was held for your approval, and a report of another kind. The platform still adds the action and the build, but the response says stamped: false, the evidence is claimed, and any refusal or code_site you wrote is replaced by the record's action. So the platform never matches such a report to another only because both mention the same call.

The platform can find a call for 25 days after it was made. A reference it cannot find under your account stays as you wrote it, marked claimed. The day after you file, the platform checks a claimed reference again. It marks the report confirmed when the report names the refusal, the call its reference quotes was refused or failed under your account near that time, and the issue is a bug. Otherwise the report stays claimed, and nothing else about it changes.

A refusal that includes a reference also includes help, the address of its row in the refusals reference. Read its cause and remedy there before you file. Over MCP, a refused result includes a second content block that gives the refusal and its reference, so your tool can copy them.

What happens to a report after it is filed #

The platform's triage passes read new reports with an AI model every five minutes. They record the issue's kind, the part of the platform it concerns, and its priority, and link a report to an issue it repeats, merging duplicates where the platform's own records back the match. A report whose text reads as an instruction to whoever reads it is left for a person, and neither pass deletes a report or changes its text. The platform team also settles issues by hand. Your report's issue shows what was decided, whether by the passes or by a person.

A fixed issue closes as verified once the fix has been used. The platform counts calls of the same action that completed on a build that includes the fix, and your tool's retry is one of them. After a platform incident closes, the next daily pass files an issue for it and links each report made while the incident was open, up to a limit. What the triage passes do describes the passes in full, as they run in your own spaces too.

What is kept #

A report is kept as the platform's own record of the problems builders meet. It identifies the account that filed it. What you file becomes the platform's to keep and use; the terms of service say so.

Before a report is stored, the platform takes reasonable measures to remove confidential details that someone pastes into it: email addresses, telephone numbers in international form, and payment card numbers. It does not guarantee that every such detail is removed. The rest of the text stays as written, including where it identifies you, so keep personal details out of it, as step 1 asks.

Where each kind is removed:

  • An email address and a telephone number are removed from the report's words, its title, text, workaround, and proposed resolution, and from the technical details your tool attaches, each context value of the evidence.
  • A payment card number is removed from the report's words alone. A context value keeps it, because the technical details hold the identifiers a fix needs, and a long number among them can look like a card number.
  • The action, the refusal, the reference, and the code site in the evidence are never changed.

An image you attach is stored exactly as you sent it, because the platform cannot find personal details in an image, so crop out or leave out anything you do not want kept.

A report filed before the platform began removing these details stays as written.

When the account is deleted, the account's identity is erased from every report it filed. No report is deleted, and each keeps its text as written.

The platform's triage passes read report text with an AI provider under the platform's own key. The privacy page lists the recipients and the retention.

Your own issue spaces #

An issue space of your account stores issues and reports in the same way as the platform's own space, for a repository's issue list or a program's test results. Creating one, minting its token, and working it through relay_issue_act need Turn Zero Team (tzTeam). Keep your own issue list covers that task: the space, its token's grant levels, the relayed operations, and how its issues get their priority.

Feedback in your application's space #

An application that declares the issue_tracking service in its manifest has a space of its own, where its backend files its users' reports through the Issue Tracking client. That page describes the space: how reports are stamped with their environment and version, the build records, and what a deletion removes. Bind an application to the space binds it to a space of your account instead.

Your backend reaches its application's own space at the report grant level, so the answers it reads leave out every restricted issue. To read the space's restricted issues whole, call relay_issue_act under an owner token for that space; no deployment reads them.

The feedback actions reach that space when you name it in space, as the response of submit_manifest gives it. They also reach one space of an application that kept a space for each environment, and a space of your account's own.

  • submit_feedback files into that space as your account's own actor.
  • read_feedback reads the whole space: with no other argument, its issues newest first; with issue, any one of its issues; and with queue: true, the selected list (Reading the queue).
  • settle_feedback settles one of its issues, or triages one with its kind or component.

None of them needs a grant.

A filing that names a space returns up to three existing issues your report may repeat as candidates, each with its id, its state, and any workaround a trusted actor wrote. A candidate's title is null when a report other than the platform team's own gave it, when the platform team has not yet reviewed the issue, or when a triage pass wrote the title.

Each candidate also carries the issue's kind and component, and its summary where a trusted actor wrote one. Its matched_evidence names the members of your evidence, such as action or code_site, that equal those of the standing reports whose evidence chose the issue, and none where only your title's words matched.

A candidate can be an issue closed declined or as_designed. Its outcome and its sentence, such as "Not taken.", mean the request was considered and not taken. Filing it again does not reopen it. A candidate's outcome is null while its issue is not closed.

A candidate with a null title asks nothing of you, because your report is already filed. Confirm a candidate with repeat_of only where you know it is the same issue. Otherwise nothing more is needed: the triage passes look for duplicates themselves.

A token scoped to an application is refused all three token_scope_refused, and its backend reaches the space through the gateway at its grant level. A request that passes application or environment is refused invalid_request, and the refusal gives space: pass the space in space instead. A space your account does not have is refused not_found before any credential is read, whoever has it.

The platform measures each space's stored bytes without reading any record's content, and that measurement counts against no plan quantity. Your account's export includes only your account's own filings in each space, not the records your end users filed there.

To keep those records before you delete the application, export the space with the export operation of relay_issue_act under an owner token for that space (Keep your own issue list). That token needs tzTeam. Without it, or where the application kept a space for each environment, read the space with read_feedback: its issues page by page, then each issue's reports with issue. Deletion and copies says what a deletion removes.

Expected result #

submit_feedback returns 200 with your report, an issue whose state is new or open, an outcome of filed, and a reference for the call itself. read_feedback with that issue's id returns the same issue with your report on it. Over MCP, read_feedback, submit_feedback, settle_feedback, and relay_issue_act each return one block. It opens with an untrusted-content marker and contains the JSON between two delimiter lines, because the text inside is what reporters wrote. Every other call returns a JSON block.

Refusals #

This table lists the refusals these steps most often meet; the refusals page lists all of the platform's refusals, with the cause and remedy of each. A backend package's own failures are listed on its package page.

A refusal gives the action and its cause in detail. It files no report; the platform's record of the call contains the refusal and its reference. Keep your own issue list lists the refusals of the issue-space actions.

Refusal Status Cause Remedy
invalid_request 400 A member breaks the rules in step 1, a file in files holds more than 524,288 bytes, or the request passed application or environment; detail gives the member to correct. Correct the named member and call again; name a space in space.
feedback_rate_limited 429 A limit was passed: the account's share in a minute, a space's limit, the platform's cap, or the issue service's own rate limit. detail says which. Wait for the minute to turn and repeat the call with the same key.
issue_service_unreachable 503 The platform's issue service did not respond; detail contains the cause word. export_account returns this refusal too, rather than an export without its feedback. Repeat the call after a short wait with the same key.
not_found 404 read_feedback named a submission that is not the account's own, or space matches no space your account has. A filing's files names a file that your call cannot read. Use the submission detail names, where it names one, or an id from read_feedback with no argument. For a space, use the identifier that submit_manifest or list_issue_spaces returns.
grant_required 403 read_feedback was called with queue on the platform's space, or settle_feedback on it, which only platform staff can do, under the feedback_queue grant. Call read_feedback without queue for your own submissions, or name your space.
token_scope_refused 403 The call came under a token scoped to one application, which no feedback action accepts. Use the session or an account-scoped token. The application's backend reaches its space through the gateway.
not_yet_provisioned 501 The platform you reached runs no issue service, which every feedback action needs, so the actions are absent from your tool's listing. Nothing on your side corrects this. Report through your usual channel.