Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/writes.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,12 @@ trigger_search { service: "radarr", id: "5" }
> - May grab and start downloading a release, which will appear in get_queue.
>
> To apply this, call trigger_search again with the same arguments plus
> `confirm` set to the token in `confirm_token`.
> `confirm` set to `v1.mu13yno6.uFRjMdu2jyooj1_7L79V--VMf0KvQGNLD-thQjSgD8U`.

The token is in the text as well as in the `confirm_token` field of
`structuredContent`, because not every client forwards the structured half to
the model, and a preview that only points at a field the model cannot see is a
handshake it can never complete.

Tokens are single-use, expire after five minutes, and are cryptographically
bound to the exact operation and arguments previewed — a token issued for one
Expand Down
16 changes: 12 additions & 4 deletions src/tools/write.ts
Original file line number Diff line number Diff line change
Expand Up @@ -314,23 +314,31 @@ export function registerWriteTool<Schema extends z.ZodObject>(

const id = audit.begin(record);
audit.settle(id, 'unconfirmed', `confirmation ${check.failure}`);
const fresh = confirm.issue(intent);
return respond(
preview({
audit_id: id,
confirm_error: check.remedy,
confirm_token: confirm.issue(intent)
confirm_token: fresh
}),
`Not applied — the confirmation token was rejected (${check.failure}). ${check.remedy} A fresh token for this exact operation is in \`confirm_token\`.`
`Not applied — the confirmation token was rejected (${check.failure}). ${check.remedy} ` +
`A fresh token for this exact operation: \`${fresh}\`.`
);
}
} else {
const id = audit.begin(record);
audit.settle(id, 'unconfirmed');
// The token goes in the text as well as in `confirm_token`. Not
// every client forwards structuredContent to the model (#234
// covered the list tools; Hermes since 2026.9.7 drops it whenever
// the text block is non-empty), and a preview whose text names a
// field the model cannot see is a handshake it can never complete.
const token = confirm.issue(intent);
return respond(
preview({ audit_id: id, confirm_token: confirm.issue(intent) }),
preview({ audit_id: id, confirm_token: token }),
`Not applied yet. ${plan.summary}\n\n` +
`${plan.effects.map(e => `- ${e}`).join('\n')}\n\n` +
`To apply this, call ${spec.name} again with the same arguments plus \`confirm\` set to the token in \`confirm_token\`.`
`To apply this, call ${spec.name} again with the same arguments plus \`confirm\` set to \`${token}\`.`
);
}

Expand Down
14 changes: 14 additions & 0 deletions test/writeTool.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,15 @@ describe('write tool harness — preview and confirm', () => {
expect(content[0]?.text).toContain('delete_media');
});

// A client that forwards only `content` (Claude's remote MCP path, #234;
// Hermes from 2026.9.7) never shows the model `structuredContent`, so the
// token has to be readable in the text or the handshake cannot complete.
it('puts the token itself in the text, not just a pointer to confirm_token', async () => {
const { content, structuredContent } = await harness.call('delete_media', { id: '5' });
expect(structuredContent.confirm_token).toBeTypeOf('string');
expect(content[0]?.text).toContain(structuredContent.confirm_token);
});

it('refuses to apply the same token twice', async () => {
const first = await harness.call('delete_media', { id: '5' });
const token = first.structuredContent.confirm_token;
Expand All @@ -149,6 +158,11 @@ describe('write tool harness — preview and confirm', () => {
expect(harness.apply).not.toHaveBeenCalled();
});

it('puts the fresh token from a rejection in the text too', async () => {
const { content, structuredContent } = await harness.call('delete_media', { id: '5', confirm: 'nonsense' });
expect(content[0]?.text).toContain(structuredContent.confirm_token);
});

it('lets the fresh token from a rejection be used', async () => {
const rejected = await harness.call('delete_media', { id: '5', confirm: 'nonsense' });
const applied = await harness.call('delete_media', {
Expand Down
Loading