Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Clarify timeout: safe_first does not authorize a consequential question

Barack Sokullu524c88d9faf5
diff --git a/docs/security-model.md b/docs/security-model.md
index 0e60de74c..b7e37c419 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -248,8 +248,11 @@ The model classifies every question with `consequence`. A question whose
answer would approve a deletion, a payment, credentials, the recipient of a
message, or a publication the user did not ask for (any `consequence` other
than `none`, or a recipient `purpose`) always times out to its safe first
-option, whatever the setting. So does a question the model did not classify:
-only `consequence: "none"` lets a timeout finish the task. Instant (a timeout
+option, whatever the setting, and that answer authorizes nothing, even when
+the model marked it `safe_first`: consequential actions and a success
+completion stay blocked until the user answers directly. So does a question
+the model did not classify: only `consequence: "none"` lets a timeout finish
+the task. Instant (a timeout
of 0) answers by the same rules. A timed-out answer is never recorded as the
user's own words in the task authority or the publication contract. WebBrain's
own confirmation cards (site permissions, form submits, recipients, deletions)
diff --git a/src/chrome/src/agent/clarify-timeout.js b/src/chrome/src/agent/clarify-timeout.js
index d5acd5beb..a591ea67b 100644
--- a/src/chrome/src/agent/clarify-timeout.js
+++ b/src/chrome/src/agent/clarify-timeout.js
@@ -11,9 +11,10 @@
// A question whose answer would authorize one of the short list of
// consequential actions (deleting data, spending money, credentials, who
// receives a message, publishing something the user did not ask for) always
-// uses 'safe', whatever the setting, so walking away never approves one. The
-// model classifies every question with `consequence`; only 'none' lets a
-// timeout finish the task, so a question it did not classify fails closed.
+// uses 'safe', whatever the setting, and its timeout authorizes nothing, even
+// with safe_first, so walking away never approves one. The model classifies
+// every question with `consequence`; only 'none' lets a timeout finish the
+// task, so a question it did not classify fails closed.
// WebBrain's own confirmation cards (permissions, form submits, recipients,
// deletions) are separate prompts and never time out.
//
@@ -51,7 +52,9 @@ export function clarifyQuestionIsHard(consequence) {
/**
* Decide, when the question is asked, what a timeout will answer.
* `options` are the displayed options after validation; `finishOption` must
- * already match one of them exactly. Returns
+ * already match one of them exactly. A hard question answers options[0] and
+ * is never authorized: safe_first is the model's own hint, and the model may
+ * have put the consequential option first. Returns
* { policy, answer, authorized, chosen } where `chosen` is one of
* 'finish_option' | 'safe_first' | 'continue' | 'first_option' | 'none'.
*/
@@ -76,7 +79,7 @@ export function clarifyTimeoutChoice({
return {
policy: effective,
answer: list.length > 0 ? list[0] : CLARIFY_TIMEOUT_ANSWER,
- authorized: safeFirst === true && list.length > 0,
+ authorized: !hardQuestion && safeFirst === true && list.length > 0,
chosen: list.length > 0 ? 'first_option' : 'none',
};
}
diff --git a/src/chrome/src/agent/tools.js b/src/chrome/src/agent/tools.js
index 7decc0a68..9373a4e86 100644
--- a/src/chrome/src/agent/tools.js
+++ b/src/chrome/src/agent/tools.js
@@ -912,7 +912,7 @@ export const AGENT_TOOLS = [
type: 'function',
function: {
name: 'clarify',
- description: 'Pause the run and ask the user a clarifying question. The run resumes when the user answers OR when the configurable clarify timeout elapses (default 60s; Settings can set Instant auto-select or Off to wait forever). What a waited timeout answers (source=timeout) follows the user\'s setting for a question whose consequence is "none": by default ("finish the task") finish_option is selected and applies as the user\'s answer, so name the option that keeps the task going; without finish_option you continue with the choice that best completes the task. On the "play it safe" setting, and always unless consequence is "none", options[0] is selected as a safe default rather than authorization for destructive/costly actions, unless safe_first is true. When Settings is Instant, the same answer is selected immediately with source=auto (intentional unattended auto-approve β€” continue with that answer). Put the safe choice FIRST in options and set safe_first only when options[0] is a safe affirmative choice. USE ONLY WHEN MATERIALLY AMBIGUOUS β€” when the task cannot be resolved by reading the page, when a wrong guess would cost the user real time/money/data, or when the user\'s request has two equally-likely interpretations that lead to different actions (e.g. "my API key" on a site with WP REST app-passwords AND multiple plugin keys). DO NOT use as a confidence crutch: do not call before every step, do not call to confirm tool calls that are clearly correct, do not call instead of doing the obvious thing. Prefer doing the most-likely interpretation and reporting it in `done.summary` for trivial ambiguities. Each clarify call breaks user flow; budget at most 1-2 per run.',
+ description: 'Pause the run and ask the user a clarifying question. The run resumes when the user answers OR when the configurable clarify timeout elapses (default 60s; Settings can set Instant auto-select or Off to wait forever). What a waited timeout answers (source=timeout) follows the user\'s setting for a question whose consequence is "none": by default ("finish the task") finish_option is selected and applies as the user\'s answer, so name the option that keeps the task going; without finish_option you continue with the choice that best completes the task. On the "play it safe" setting, options[0] is selected as a safe default rather than authorization for destructive/costly actions, unless safe_first is true. A question whose consequence is not "none" always times out to options[0] as a safe default that authorizes nothing, safe_first or not. When Settings is Instant, the same answer is selected immediately with source=auto (intentional unattended auto-approve β€” continue with that answer). Put the safe choice FIRST in options and set safe_first only when options[0] is a safe affirmative choice. USE ONLY WHEN MATERIALLY AMBIGUOUS β€” when the task cannot be resolved by reading the page, when a wrong guess would cost the user real time/money/data, or when the user\'s request has two equally-likely interpretations that lead to different actions (e.g. "my API key" on a site with WP REST app-passwords AND multiple plugin keys). DO NOT use as a confidence crutch: do not call before every step, do not call to confirm tool calls that are clearly correct, do not call instead of doing the obvious thing. Prefer doing the most-likely interpretation and reporting it in `done.summary` for trivial ambiguities. Each clarify call breaks user flow; budget at most 1-2 per run.',
parameters: {
type: 'object',
properties: {
@@ -927,7 +927,7 @@ export const AGENT_TOOLS = [
},
safe_first: {
type: 'boolean',
- description: 'Set true only when options[0] is a safe affirmative choice that should apply if the user does not answer before the timeout. Without it, a timed-out selection is a safe default, not authorization for destructive or costly actions.',
+ description: 'Set true only when options[0] is a safe affirmative choice that should apply if the user does not answer before the timeout. Without it, a timed-out selection is a safe default, not authorization for destructive or costly actions. It has no effect unless consequence is "none".',
},
finish_option: {
type: 'string',
@@ -936,7 +936,7 @@ export const AGENT_TOOLS = [
consequence: {
type: 'string',
enum: ['none', 'deletion', 'money', 'credentials', 'recipient', 'publication'],
- description: 'Classify every question. "none" when answering approves nothing below: a timeout then follows the user\'s setting (finish_option by default). Otherwise the approval it asks for: deleting data (deletion), spending money (money), entering or revealing a password, key or code (credentials), who receives a message (recipient), or publishing something the user did not ask to publish (publication). Such a question, and one without consequence, always times out to options[0], the safe choice, whatever the setting.',
+ description: 'Classify every question. "none" when answering approves nothing below: a timeout then follows the user\'s setting (finish_option by default). Otherwise the approval it asks for: deleting data (deletion), spending money (money), entering or revealing a password, key or code (credentials), who receives a message (recipient), or publishing something the user did not ask to publish (publication). Such a question, and one without consequence, always times out to options[0], the safe choice, whatever the setting, and the timeout approves nothing (safe_first does not apply).',
},
reason: {
type: 'string',
@@ -2268,7 +2268,7 @@ Available tools:
- find_text: Select one literal page-text match instead of Ctrl/Cmd+F. Each call replaces the previous selection; it does not open browser Find UI or keep multiple terms highlighted.
- press_keys: Press only unmodified Escape/Tab/Enter/arrows or ; (semicolon). Modifier combinations and browser shortcuts are unsupported.
${BROWSER_TAB_LIMITATION}
-- clarify: Pause and ask the user a question. Use ONLY for material ambiguity that you cannot resolve by reading the page (e.g. "my API key" on a site with multiple plugins that each have one). On a timeout (default 60s, source=timeout) the user\'s setting decides for a question with consequence "none": by default your finish_option applies as their answer; on the safe setting, and always for any other question, options[0] is a safe default that applies only with safe_first. Settings Instant yields source=auto (intentional auto-approve β€” continue). Put the safe choice first, name finish_option, and set consequence on every question: "none", or deletion, money, credentials, recipient or publication when answering would approve one of those. Do NOT use to confirm correct actions; do NOT call before every step. Budget 1-2 per run, max.
+- clarify: Pause and ask the user a question. Use ONLY for material ambiguity that you cannot resolve by reading the page (e.g. "my API key" on a site with multiple plugins that each have one). On a timeout (default 60s, source=timeout) the user\'s setting decides for a question with consequence "none": by default your finish_option applies as their answer; on the safe setting options[0] is a safe default that applies only with safe_first; any other question always takes options[0] as a safe default that approves nothing. Settings Instant yields source=auto (intentional auto-approve β€” continue). Put the safe choice first, name finish_option, and set consequence on every question: "none", or deletion, money, credentials, recipient or publication when answering would approve one of those. Do NOT use to confirm correct actions; do NOT call before every step. Budget 1-2 per run, max.
- done: Signal task completion
- verify_form: Verify HTML form fields before submitting; for form-less settings inspect the staged page state and intended save control instead.
- scratchpad_write: Pin a note in context that survives summarization (use on long tasks to remember download IDs, file paths, plans)
@@ -2633,7 +2633,7 @@ ${BROWSER_TAB_LIMITATION}
- fetch_url({url}) / research_url({url}): read OTHER URLs (not the active tab). list_downloads, download_files, download_resource_from_page, read_downloaded_file, upload_file({selector, attachmentId}) or upload_file({selector, downloadId}): file workflows. Use attachmentId for a current user-supplied file; use downloadId for a downloaded file. Use download_files for direct URLs and download_resource_from_page when the resource is attached to a visible page element or a blob: URL. Successful downloads auto-pin each file's downloadId to the scratchpad as an \`[auto]\` line β€” attach with upload_file({downloadId, selector}) and re-read with read_downloaded_file({downloadId}); no need to recall the path. A page_consumed attachment may clear its file input and show a preview/crop instead of a filename. Inspect the staged preview/crop or status and the current task-authorized Save/Submit/Commit controls; local attachment does not prove a remote upload or remote submission. Do not re-open the chooser or re-upload solely because the filename is absent or not rendered. Retry only if the file is genuinely missing or the user explicitly requests a new file.
- download_public_media (if enabled) / download_social_media: one-shot image/video download from supported public social sites; purpose-built download tools should be tried before manual DOM/resource workflows.
- verify_form: check HTML form field values before submitting; urlFilter inspects child frames only. For form-less settings inspect staged page state and the intended save control instead. scratchpad_write({text}): pin facts that survive context summarization. progress_update/progress_read: track repeated item/action progress.
-- clarify({question, consequence, options?, finish_option?, safe_first?}): ask the user only when materially blocked/ambiguous (budget 1-2 per run). Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; any other question takes options[0]; safe_first makes that selection apply, and source=auto Instant is intentional auto-approve. solve_captcha: one tool call, compatible enabled providers in descending weight order, falling back on failure or timeout; each may charge. Do not repeat the call for the same unresolved challenge. New challenges after verified clearance may be solved once. AWS WAF inputs and cookie application are handled automatically. hCaptcha requires enabled NopeCHA or NoneCap; use get_captcha_capabilities for additional native methods and apply_captcha_solution for their answers; missing inputs or failed solves require manual completion.
+- clarify({question, consequence, options?, finish_option?, safe_first?}): ask the user only when materially blocked/ambiguous (budget 1-2 per run). Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; safe_first makes that selection apply; any other question takes options[0] and approves nothing; source=auto Instant is intentional auto-approve. solve_captcha: one tool call, compatible enabled providers in descending weight order, falling back on failure or timeout; each may charge. Do not repeat the call for the same unresolved challenge. New challenges after verified clearance may be solved once. AWS WAF inputs and cookie application are handled automatically. hCaptcha requires enabled NopeCHA or NoneCap; use get_captcha_capabilities for additional native methods and apply_captcha_solution for their answers; missing inputs or failed solves require manual completion.
- Recording is user-driven only: tell the user to type \`/record\` or \`/record --full-screen\` instead of trying to start recording yourself; add \`--transcribe\` if they want a Whisper transcript after stop.
- done({summary, outcome}): signal completion; use outcome:"success" only after verifying success.
diff --git a/src/firefox/src/agent/clarify-timeout.js b/src/firefox/src/agent/clarify-timeout.js
index d5acd5beb..a591ea67b 100644
--- a/src/firefox/src/agent/clarify-timeout.js
+++ b/src/firefox/src/agent/clarify-timeout.js
@@ -11,9 +11,10 @@
// A question whose answer would authorize one of the short list of
// consequential actions (deleting data, spending money, credentials, who
// receives a message, publishing something the user did not ask for) always
-// uses 'safe', whatever the setting, so walking away never approves one. The
-// model classifies every question with `consequence`; only 'none' lets a
-// timeout finish the task, so a question it did not classify fails closed.
+// uses 'safe', whatever the setting, and its timeout authorizes nothing, even
+// with safe_first, so walking away never approves one. The model classifies
+// every question with `consequence`; only 'none' lets a timeout finish the
+// task, so a question it did not classify fails closed.
// WebBrain's own confirmation cards (permissions, form submits, recipients,
// deletions) are separate prompts and never time out.
//
@@ -51,7 +52,9 @@ export function clarifyQuestionIsHard(consequence) {
/**
* Decide, when the question is asked, what a timeout will answer.
* `options` are the displayed options after validation; `finishOption` must
- * already match one of them exactly. Returns
+ * already match one of them exactly. A hard question answers options[0] and
+ * is never authorized: safe_first is the model's own hint, and the model may
+ * have put the consequential option first. Returns
* { policy, answer, authorized, chosen } where `chosen` is one of
* 'finish_option' | 'safe_first' | 'continue' | 'first_option' | 'none'.
*/
@@ -76,7 +79,7 @@ export function clarifyTimeoutChoice({
return {
policy: effective,
answer: list.length > 0 ? list[0] : CLARIFY_TIMEOUT_ANSWER,
- authorized: safeFirst === true && list.length > 0,
+ authorized: !hardQuestion && safeFirst === true && list.length > 0,
chosen: list.length > 0 ? 'first_option' : 'none',
};
}
diff --git a/src/firefox/src/agent/tools.js b/src/firefox/src/agent/tools.js
index 1d99c5ef2..9f984ae17 100644
--- a/src/firefox/src/agent/tools.js
+++ b/src/firefox/src/agent/tools.js
@@ -774,7 +774,7 @@ export const AGENT_TOOLS = [
type: 'function',
function: {
name: 'clarify',
- description: 'Pause the run and ask the user a clarifying question. The run resumes when the user answers OR when the configurable clarify timeout elapses (default 60s; Settings can set Instant auto-select or Off to wait forever). What a waited timeout answers (source=timeout) follows the user\'s setting for a question whose consequence is "none": by default ("finish the task") finish_option is selected and applies as the user\'s answer, so name the option that keeps the task going; without finish_option you continue with the choice that best completes the task. On the "play it safe" setting, and always unless consequence is "none", options[0] is selected as a safe default rather than authorization for destructive/costly actions, unless safe_first is true. When Settings is Instant, the same answer is selected immediately with source=auto (intentional unattended auto-approve β€” continue with that answer). Put the safe choice FIRST in options and set safe_first only when options[0] is a safe affirmative choice. USE ONLY WHEN MATERIALLY AMBIGUOUS β€” when the task cannot be resolved by reading the page, when a wrong guess would cost the user real time/money/data, or when the user\'s request has two equally-likely interpretations that lead to different actions (e.g. "my API key" on a site with WP REST app-passwords AND multiple plugin keys). DO NOT use as a confidence crutch: do not call before every step, do not call to confirm tool calls that are clearly correct, do not call instead of doing the obvious thing. Prefer doing the most-likely interpretation and reporting it in `done.summary` for trivial ambiguities. Each clarify call breaks user flow; budget at most 1-2 per run.',
+ description: 'Pause the run and ask the user a clarifying question. The run resumes when the user answers OR when the configurable clarify timeout elapses (default 60s; Settings can set Instant auto-select or Off to wait forever). What a waited timeout answers (source=timeout) follows the user\'s setting for a question whose consequence is "none": by default ("finish the task") finish_option is selected and applies as the user\'s answer, so name the option that keeps the task going; without finish_option you continue with the choice that best completes the task. On the "play it safe" setting, options[0] is selected as a safe default rather than authorization for destructive/costly actions, unless safe_first is true. A question whose consequence is not "none" always times out to options[0] as a safe default that authorizes nothing, safe_first or not. When Settings is Instant, the same answer is selected immediately with source=auto (intentional unattended auto-approve β€” continue with that answer). Put the safe choice FIRST in options and set safe_first only when options[0] is a safe affirmative choice. USE ONLY WHEN MATERIALLY AMBIGUOUS β€” when the task cannot be resolved by reading the page, when a wrong guess would cost the user real time/money/data, or when the user\'s request has two equally-likely interpretations that lead to different actions (e.g. "my API key" on a site with WP REST app-passwords AND multiple plugin keys). DO NOT use as a confidence crutch: do not call before every step, do not call to confirm tool calls that are clearly correct, do not call instead of doing the obvious thing. Prefer doing the most-likely interpretation and reporting it in `done.summary` for trivial ambiguities. Each clarify call breaks user flow; budget at most 1-2 per run.',
parameters: {
type: 'object',
properties: {
@@ -789,7 +789,7 @@ export const AGENT_TOOLS = [
},
safe_first: {
type: 'boolean',
- description: 'Set true only when options[0] is a safe affirmative choice that should apply if the user does not answer before the timeout. Without it, a timed-out selection is a safe default, not authorization for destructive or costly actions.',
+ description: 'Set true only when options[0] is a safe affirmative choice that should apply if the user does not answer before the timeout. Without it, a timed-out selection is a safe default, not authorization for destructive or costly actions. It has no effect unless consequence is "none".',
},
finish_option: {
type: 'string',
@@ -798,7 +798,7 @@ export const AGENT_TOOLS = [
consequence: {
type: 'string',
enum: ['none', 'deletion', 'money', 'credentials', 'recipient', 'publication'],
- description: 'Classify every question. "none" when answering approves nothing below: a timeout then follows the user\'s setting (finish_option by default). Otherwise the approval it asks for: deleting data (deletion), spending money (money), entering or revealing a password, key or code (credentials), who receives a message (recipient), or publishing something the user did not ask to publish (publication). Such a question, and one without consequence, always times out to options[0], the safe choice, whatever the setting.',
+ description: 'Classify every question. "none" when answering approves nothing below: a timeout then follows the user\'s setting (finish_option by default). Otherwise the approval it asks for: deleting data (deletion), spending money (money), entering or revealing a password, key or code (credentials), who receives a message (recipient), or publishing something the user did not ask to publish (publication). Such a question, and one without consequence, always times out to options[0], the safe choice, whatever the setting, and the timeout approves nothing (safe_first does not apply).',
},
reason: {
type: 'string',
@@ -2027,7 +2027,7 @@ ${BROWSER_TAB_LIMITATION}
- upload_file({attachmentId?, targetId?}): Two steps: first call without targetId to discover file inputs; then call again with one returned targetId and the current attachmentId, or omit attachmentId on the second call for WebBrain's picker. Never guess a targetId. If discovery finds no input because the widget creates it lazily, make one guarded initializer click and repeat discovery. A page_consumed attachment may clear its file input and show a preview/crop instead of a filename. Inspect the staged preview/crop or status and the current task-authorized Save/Submit/Commit controls; local attachment does not prove a remote upload or remote submission. Do not re-open the chooser or re-upload solely because the filename is absent or not rendered. Retry only if the file is genuinely missing or the user explicitly requests a new file.
- scratchpad_write({text}): Save notes that persist across steps.
- progress_update({items}) / progress_read({status}): Structured progress ledger for the active repeated item/action task. On GitHub stargazers, only "Follow USER" buttons are follow targets when following is allowed by the task; "Unfollow USER" means skip/already followed unless the ledger shows acted.
-- clarify({question, consequence, options?, finish_option?, safe_first?}): Ask the user only when materially blocked or ambiguous. Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; any other question takes options[0]; safe_first makes that selection apply, and source=auto Instant is intentional auto-approve.
+- clarify({question, consequence, options?, finish_option?, safe_first?}): Ask the user only when materially blocked or ambiguous. Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; safe_first makes that selection apply; any other question takes options[0] and approves nothing; source=auto Instant is intentional auto-approve.
- done({summary, outcome}): Signal success, partial progress, or a failed blocker.
PATTERN:
@@ -2150,7 +2150,7 @@ Available tools:
- find_text: Select one literal page-text match instead of Ctrl/Cmd+F. Each call replaces the previous selection; it does not open browser Find UI or keep multiple terms highlighted.
- press_keys: Press only unmodified Escape/Tab/Enter/arrows or ; (semicolon). Modifier combinations and browser shortcuts are unsupported.
${BROWSER_TAB_LIMITATION}
-- clarify: Pause and ask the user a question. Use ONLY for material ambiguity that you cannot resolve by reading the page (e.g. "my API key" on a site with multiple plugins that each have one). On a timeout (default 60s, source=timeout) the user\'s setting decides for a question with consequence "none": by default your finish_option applies as their answer; on the safe setting, and always for any other question, options[0] is a safe default that applies only with safe_first. Settings Instant yields source=auto (intentional auto-approve β€” continue). Put the safe choice first, name finish_option, and set consequence on every question: "none", or deletion, money, credentials, recipient or publication when answering would approve one of those. Do NOT use to confirm correct actions; do NOT call before every step. Budget 1-2 per run, max.
+- clarify: Pause and ask the user a question. Use ONLY for material ambiguity that you cannot resolve by reading the page (e.g. "my API key" on a site with multiple plugins that each have one). On a timeout (default 60s, source=timeout) the user\'s setting decides for a question with consequence "none": by default your finish_option applies as their answer; on the safe setting options[0] is a safe default that applies only with safe_first; any other question always takes options[0] as a safe default that approves nothing. Settings Instant yields source=auto (intentional auto-approve β€” continue). Put the safe choice first, name finish_option, and set consequence on every question: "none", or deletion, money, credentials, recipient or publication when answering would approve one of those. Do NOT use to confirm correct actions; do NOT call before every step. Budget 1-2 per run, max.
- done: Signal task completion
- verify_form: Verify HTML form fields before submitting; for form-less settings inspect the staged page state and intended save control instead.
- scratchpad_write: Pin a note in context that survives summarization (use on long tasks to remember download IDs, file paths, plans)
@@ -2391,7 +2391,7 @@ ${BROWSER_TAB_LIMITATION}
- fetch_url({url}) / research_url({url}): read OTHER URLs (not the active tab). list_downloads, download_files, download_resource_from_page, read_downloaded_file, upload_file({selector, attachmentId}) or upload_file({selector, downloadId}): file workflows. Use attachmentId for a current user-supplied file; use downloadId for a downloaded file. Use download_files for direct URLs and download_resource_from_page when the resource is attached to a visible page element or a blob: URL. Successful downloads auto-pin each file's downloadId to the scratchpad as an \`[auto]\` line β€” attach with upload_file({downloadId, selector}) and re-read with read_downloaded_file({downloadId}); no need to recall the path. Omit both ids to prompt the user to pick a new local file. A page_consumed attachment may clear its file input and show a preview/crop instead of a filename. Inspect the staged preview/crop or status and the current task-authorized Save/Submit/Commit controls; local attachment does not prove a remote upload or remote submission. Do not re-open the chooser or re-upload solely because the filename is absent or not rendered. Retry only if the file is genuinely missing or the user explicitly requests a new file.
- download_public_media (if enabled) / download_social_media: one-shot image/video download from supported public social sites; purpose-built download tools should be tried before manual DOM/resource workflows.
- verify_form: check HTML form field values before submitting; urlFilter inspects child frames only. For form-less settings inspect staged page state and the intended save control instead. scratchpad_write({text}): pin facts that survive context summarization. progress_update/progress_read: track repeated item/action progress.
-- clarify({question, consequence, options?, finish_option?, safe_first?}): ask the user only when materially blocked/ambiguous (budget 1-2 per run). Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; any other question takes options[0]; safe_first makes that selection apply, and source=auto Instant is intentional auto-approve. solve_captcha: one tool call, compatible enabled providers in descending weight order, falling back on failure or timeout; each may charge. Do not repeat the call for the same unresolved challenge. New challenges after verified clearance may be solved once. AWS WAF inputs and cookie application are handled automatically. hCaptcha requires enabled NopeCHA or NoneCap; use get_captcha_capabilities for additional native methods and apply_captcha_solution for their answers; missing inputs or failed solves require manual completion.
+- clarify({question, consequence, options?, finish_option?, safe_first?}): ask the user only when materially blocked/ambiguous (budget 1-2 per run). Set consequence on every question ("none", or the approval it asks for). On timeout the user\'s setting picks finish_option (default) or the safe options[0] for consequence "none"; safe_first makes that selection apply; any other question takes options[0] and approves nothing; source=auto Instant is intentional auto-approve. solve_captcha: one tool call, compatible enabled providers in descending weight order, falling back on failure or timeout; each may charge. Do not repeat the call for the same unresolved challenge. New challenges after verified clearance may be solved once. AWS WAF inputs and cookie application are handled automatically. hCaptcha requires enabled NopeCHA or NoneCap; use get_captcha_capabilities for additional native methods and apply_captcha_solution for their answers; missing inputs or failed solves require manual completion.
- done({summary, outcome}): signal completion; use outcome:"success" only after verifying success.
CHAT IMAGES:
diff --git a/test/clarify-timeout-policy.mjs b/test/clarify-timeout-policy.mjs
index 4b4987d7a..ec6cdab57 100644
--- a/test/clarify-timeout-policy.mjs
+++ b/test/clarify-timeout-policy.mjs
@@ -55,6 +55,11 @@ for (const { build, Agent, policy, Capability } of builds) {
assert.deepEqual(clarifyTimeoutChoice({ policy: 'safe', options: [] }),
{ policy: 'safe', answer: CLARIFY_TIMEOUT_ANSWER, authorized: false, chosen: 'none' });
assert.equal(clarifyTimeoutChoice({ policy: 'safe', options, safeFirst: true }).authorized, true);
+ for (const policyName of ['finish', 'safe']) {
+ assert.deepEqual(clarifyTimeoutChoice({ policy: policyName, options, safeFirst: true, hardQuestion: true }),
+ { policy: 'safe', answer: 'Keep the draft', authorized: false, chosen: 'first_option' },
+ `${policyName}: safe_first must not authorize a hard question`);
+ }
});
test(`${build}: only a question classified 'none' may finish on its own; anything else fails closed`, () => {
@@ -152,6 +157,33 @@ for (const { build, Agent, policy, Capability } of builds) {
}
});
+ test(`${build}: safe_first does not let a consequential or unclassified question approve itself`, async () => {
+ const cases = [
+ { question: 'Delete all 40 archived emails?', options: ['Delete them', 'Keep them'], safe_first: true, consequence: 'deletion' },
+ { question: 'Delete all 40 archived emails?', options: ['Delete them', 'Keep them'], safe_first: true },
+ { question: 'Who should get this message?', options: ['Alex', 'Nobody yet'], safe_first: true, purpose: 'message_recipient', consequence: 'none' },
+ ];
+ for (const [index, args] of cases.entries()) {
+ for (const [mode, timeoutSec] of [['waited', 30], ['instant', 0]]) {
+ for (const timeoutPolicy of ['finish', 'safe']) {
+ const agent = new Agent({});
+ agent.clarifyTimeoutSec = timeoutSec;
+ agent.clarifyTimeoutPolicy = timeoutPolicy;
+ const tab = 9170 + index * 4 + (mode === 'instant' ? 2 : 0) + (timeoutPolicy === 'safe' ? 1 : 0);
+ const label = `${args.consequence || 'unclassified'}${args.purpose ? `/${args.purpose}` : ''} ${mode} ${timeoutPolicy}`;
+ const result = mode === 'instant'
+ ? await agent.executeTool(tab, 'clarify', args, () => {})
+ : (await askAndTimeOut(agent, tab, args, { answer: args.options[0] })).result;
+ assert.equal(result.answer, args.options[0], `${label}: the first option is the timed answer`);
+ assert.equal(result.authorized, false, `${label}: safe_first approved a consequential question`);
+ assert.equal(result.requiresExplicitConfirmation, true, label);
+ assert.ok(agent._clarificationAuthorizationBlock(tab, 'click_ax', {}, [Capability.CLICK]), `${label}: consequential actions stay blocked`);
+ assert.ok(agent._clarificationAuthorizationBlock(tab, 'done', { outcome: 'success' }, []), `${label}: success stays blocked`);
+ }
+ }
+ }
+ });
+
test(`${build}: the safe setting keeps today's behavior`, async () => {
const agent = new Agent({});
agent.clarifyTimeoutPolicy = 'safe';