The suggest-task tool and service

A suggested task is a follow-up that a chat offers when it notices work beyond the current one. The offer waits, and nothing starts by itself. This page is the developer reference for the tool behind an offer, suggest_task, and for the service that records offers and turns one of them into a new chat. For what you see and do with a suggestion in the app, see Suggested tasks.

The tool and its fields

One offer per call. suggest_task offers a single out-of-scope follow-up. Its description reads: Offer one out-of-scope follow-up the user can start in a new chat; never for work you can do now.
Three required fields. Every call carries a title, a short reason and a brief for the new chat. All three are trimmed, and none may be empty.

Field	How the field is described	Limit
`title`	`Imperative title, at most 60 characters.`	60 characters
`tldr`	`Why it is worth doing, at most 240 characters.`	240 characters
`brief`	`Self-contained instructions for the new chat, at most 4000 characters.`	4000 characters

The success line. A recorded offer answers with: Suggested "<title>". The user decides whether to start it; do not start it yourself.

When an offer is refused

Only the top-level chat may offer a suggestion. A helper's call is refused with suggest_task is only for the top-level agent; report the follow-up in your result instead. A forked helper still sees the tool, but the call is refused when it runs.

The other refusals name their reason:

Situation	The refusal
The chat runs in a scheduled task's folder	`suggest_task: this chat runs in a scheduled task folder, where no new chat can start; offer no suggestions here`
Ten offers already made in this chat	`suggest_task: this chat already offered 10 suggestions; offer no more`
Three offers already waiting	`suggest_task: 3 suggestions already wait for the user; offer no more until one is started or dismissed`
A second offer in one turn	`suggest_task: one suggestion per turn; this turn already offered one`
No open turn to attach the offer to	`suggest_task: requires an open model turn`
The call has no chat behind it	`suggest_task requires an owning agent session`
A field is empty	`suggest_task: <field> must not be empty`
A field is over its limit	`suggest_task: <field> must be at most <limit> characters (got <n>)`

How offers and settlements are recorded

Durable records. Every offer and every settlement is recorded on the chat's session log, and survives a restart; the suggestion list is rebuilt from the log.
Two orders. Open offers are listed newest first. Settled offers keep the order in which their offers appeared.
One settlement at a time. A new settlement replaces the previous settlement of the same offer, and a restore removes it, so the offer is open again.
Four outcomes. An offer is settled as started, drafted, dismissed or restored, and a started settlement carries the id of the new chat. Started, drafted and dismissed apply only to an open offer; restored applies only to a dismissed one.
Checked as the log is read. A settlement that names no offer, or an outcome that does not fit the offer's standing, changes nothing. The character limits are checked when an offer is made, not while records are read, so a chat recorded under an older limit still opens.

What Start does

A new chat in the same workspace. Start creates the chat in the offering chat's workspace, titles it after the suggestion, and sends the brief as its first message.
Single-flight. Start is single-flight for one chat and one suggestion: repeating it returns the same chat, and two concurrent starts create one chat.
The dismissal window. A suggestion dismissed while its chat is being created stays dismissed and receives no brief; starting it again fails with task-suggestion/not-open.
Restore has a ceiling. A dismissed suggestion can be restored while fewer than three suggestions are open; with three open, the restore fails with task-suggestion/open-limit.
Failures carry their payloads. The service answers with a code and the detail the caller needs:

Code	The answer	What it carries
`task-suggestion/not-found`	`no suggestion "<id>"`	the id that was asked for
`task-suggestion/not-open`	`suggestion "<id>" is <outcome>`	the outcome it already has
`task-suggestion/open-limit`	`3 suggestions are already open`	the limit
`task-suggestion/workspace-missing`	`session "<id>" belongs to no workspace` or `session "<id>" runs in a scheduled task's folder`	the chat id

What a started chat runs as

Inherited settings. The new chat runs on the offering chat's preset, model and permission. When no preset applies, Oda copies the offering chat's sandbox and approval settings instead.
Never more permission. A started chat never runs with more permission than the chat that offered it; a brief started from a Full access chat runs with Full access (Permissions, approvals and feature controls).
Not the person's words. The brief is attributed to the suggestion, not to the person. Checks that require a person's own instruction, such as creating or completing a goal, do not accept it; the started chat has to ask first.

How it ships

No configuration. Oda runs the service once so every chat can use it, and the presets that should offer suggestions carry the tool. Neither part takes configuration.

Questions, answered

What are the character limits for a suggestion?

A title is at most 60 characters, a tldr at most 240, and a brief at most 4000. All three are trimmed, and none may be empty.

How many suggestions can a chat offer?

At most one per turn, three waiting at a time and ten in a chat's lifetime. The three-open ceiling also applies when a dismissed suggestion is restored.

Can a chat that runs in a scheduled task's folder offer a suggestion?

No. Such a chat refuses with suggest_task: this chat runs in a scheduled task folder, where no new chat can start; offer no suggestions here, because a new chat cannot start there. See Scheduled tasks.

Can a helper offer a suggestion?

No. Only the top-level chat may offer one; a helper's call is refused with suggest_task is only for the top-level agent; report the follow-up in your result instead. A forked helper still sees the tool, but the call is refused when it runs.

What does the model see after a successful offer?

The result reads Suggested "<title>". The user decides whether to start it; do not start it yourself. The offer itself waits in the chat.

Do offers survive a restart?

Yes. Offers and settlements are durable records on the chat's session log, and the suggestion list is rebuilt from the log when the chat comes back.

What happens if Start is called twice for one suggestion?

The second call returns the same chat. Start is single-flight for one chat and one suggestion, so even two concurrent calls create one chat.

What does a started chat run with?

The offering chat's preset, model and permission. When no preset applies, the sandbox and approval settings are copied from the offering chat instead. A started chat never runs with more permission than the chat that offered it.

Can a brief create or complete a goal?

No. The brief is attributed to the suggestion rather than to a person, and checks that need a person's own instruction do not accept it; the started chat has to ask first.

What happens to a suggestion dismissed while its chat is being created?

It stays dismissed and receives no brief. Starting it again fails with task-suggestion/not-open.

What do the failure codes carry?

Each code carries the detail the caller needs: task-suggestion/not-found names the id, task-suggestion/not-open names the outcome the suggestion already has, task-suggestion/open-limit carries the limit, and task-suggestion/workspace-missing names the chat.