Persisted leader/subagent ownership. An explicit ping resumes an independent peer; a managed session stays under its team rule.
Persisted leader/subagent ownership. An explicit ping resumes an independent peer; a managed session stays under its team rule.
(ask env question)(ask env question opts)As a subagent, ask your parent for a decision and wait for the reply text. If only the person can decide, your parent asks the person and you keep waiting. Returns None when the parent stops or does not reply within timeout_secs (default 600). Then choose the safest option and say so in your answer.
As a subagent, ask your parent for a decision and wait for the reply text. If only the person can decide, your parent asks the person and you keep waiting. Returns None when the parent stops or does not reply within timeout_secs (default 600). Then choose the safest option and say so in your answer.
(ask-budget env iterations reason)(ask-budget env iterations reason opts)As a subagent, ask your parent for more model iterations and wait for the answer. Ask before your budget ends, with the number that you need and the reason. Returns a dict with granted (0 when the parent refuses), iteration_budget and reply. reply is None when the parent is not running or does not answer within timeout_secs (default 600).
As a subagent, ask your parent for more model iterations and wait for the answer. Ask before your budget ends, with the number that you need and the reason. Returns a dict with granted (0 when the parent refuses), iteration_budget and reply. reply is None when the parent is not running or does not answer within timeout_secs (default 600).
(ask-files env files reason)(ask-files env files reason opts)As a subagent, ask your parent for file access and wait for the answer. files holds write, read_only and deny rules: paths or globs, absolute, ~ or relative to the parent's workspace root. Give at least one rule. deny wins over read_only, and read_only wins over write.
Returns a dict with granted, files (your grant now), missing and reply. granted is True only when the grant covers every write rule that you asked for. missing lists the others. reply is None when the parent is not running or does not answer within timeout_secs (default 600).
After a grant, your Python sandbox restarts before the next block and restores your saved helpers.
As a subagent, ask your parent for file access and wait for the answer. files holds write, read_only and deny rules: paths or globs, absolute, ~ or relative to the parent's workspace root. Give at least one rule. deny wins over read_only, and read_only wins over write. Returns a dict with granted, files (your grant now), missing and reply. granted is True only when the grant covers every write rule that you asked for. missing lists the others. reply is None when the parent is not running or does not answer within timeout_secs (default 600). After a grant, your Python sandbox restarts before the next block and restores your saved helpers.
(cancel-agent env session-id)Cancel a subagent, including its queued work. Returns its record.
Cancel a subagent, including its queued work. Returns its record.
(checkpoint! env messages)Capture the last complete model input, before its in-flight tool call. Never copy runtime handles.
Capture the last complete model input, before its in-flight tool call. Never copy runtime handles.
(claim-iteration! env)Reserve one model iteration. A child budget is durable across replies, turns and restarts.
When the budget ends in a turn, that turn gets one more iteration without a claim for the
handoff of the child. A later claim refuses, and the child becomes budget_limited.
Reserve one model iteration. A child budget is durable across replies, turns and restarts. When the budget ends in a turn, that turn gets one more iteration without a claim for the handoff of the child. A later claim refuses, and the child becomes `budget_limited`.
(controls? db actor-id target-id)A leader controls its children. A subagent controls only itself.
A leader controls its children. A subagent controls only itself.
(deny-agent env session-id reason)Refuse the open budget or file request of a subagent, with a short reason. The child keeps its budget and its files. Returns the record.
Refuse the open budget or file request of a subagent, with a short reason. The child keeps its budget and its files. Returns the record.
(enabled? db sid)Whether session sid can use managed subagents. A new session starts without the session
settings of its source, so a managed child reads the setting of its leader. Without such a
session setting, or with an invocation value, the configuration decides. Subagents run on
Council messages, so they are off while Council is off.
Whether session `sid` can use managed subagents. A new session starts without the session settings of its source, so a managed child reads the setting of its leader. Without such a session setting, or with an invocation value, the configuration decides. Subagents run on Council messages, so they are off while Council is off.
(extend-agent env session-id iterations)Give a subagent more model iterations. Use it to answer a budget request (status asking with budget_request), or before a follow-up ping to a budget_limited child. A budget stays at most 600. Returns the record.
Give a subagent more model iterations. Use it to answer a budget request (status asking with budget_request), or before a follow-up ping to a budget_limited child. A budget stays at most 600. Returns the record.
(finish! db sid status)Store the status of a finished child turn. A child that ended its turn in its handoff
iteration becomes budget_limited, so its parent knows that it needs council.extend before
a follow-up ping. A child that answered within its budget is completed. The first end of a task
stores finished_at, and a task without council.result gets the first line of its answer.
Store the status of a finished child turn. A child that ended its turn in its handoff iteration becomes `budget_limited`, so its parent knows that it needs council.extend before a follow-up ping. A child that answered within its budget is `completed`. The first end of a task stores `finished_at`, and a task without council.result gets the first line of its answer.
(follow-up-refusal db author-id target-id)The refusal of a ping from author-id to its idle child target-id, as [error message], or
nil. A ping from the parent or the leader gives an idle child a follow-up task. The child
needs iterations left. A cancelled child also needs a running turn of its leader. So a late
ping cannot restart a child that the user stopped.
The refusal of a ping from `author-id` to its idle child `target-id`, as `[error message]`, or nil. A ping from the parent or the leader gives an idle child a follow-up task. The child needs iterations left. A cancelled child also needs a running turn of its leader. So a late ping cannot restart a child that the user stopped.
(grant-files env session-id files)Add file rules to the grant of a subagent. Use it to answer a file request (status asking with files_request). For a follow-up task with other files, pass files to council.publish instead.
files holds write, read_only and deny rules, like a task dict. Give at least one rule. deny wins over read_only, and read_only wins over write.
Returns the record. Its warning names write rules that changed nothing and active siblings that can write the same files.
A grant gives at most your own access. A write rule outside your writable roots or under your deny rules fails, and your deny rules stay closed to the child. A write rule under a read_only or deny rule of the child fails too. A child without write rules already writes where you write, so a write grant changes nothing for it. The child gets the new access at its next block.
Add file rules to the grant of a subagent. Use it to answer a file request (status asking with files_request). For a follow-up task with other files, pass files to council.publish instead. files holds write, read_only and deny rules, like a task dict. Give at least one rule. deny wins over read_only, and read_only wins over write. Returns the record. Its warning names write rules that changed nothing and active siblings that can write the same files. A grant gives at most your own access. A write rule outside your writable roots or under your deny rules fails, and your deny rules stay closed to the child. A write rule under a read_only or deny rule of the child fails too. A child without write rules already writes where you write, so a write grant changes nothing for it. The child gets the new access at its next block.
(handoff messages)The parent's model input without tool work, like a Codex fork. It keeps system messages, requests, fold gists, Council messages, notes and answers. It drops tool calls, tool results and reasoning, and joins neighbouring text of one role. A closing message marks the conversation as the parent's context, so a child does not act on the parent's requests.
The parent's model input without tool work, like a Codex fork. It keeps system messages, requests, fold gists, Council messages, notes and answers. It drops tool calls, tool results and reasoning, and joins neighbouring text of one role. A closing message marks the conversation as the parent's context, so a child does not act on the parent's requests.
(interactive? env)True when a person can answer in the session of env. A one-shot :cli run has nobody to
answer or approve.
True when a person can answer in the session of `env`. A one-shot `:cli` run has nobody to answer or approve.
(latest-note db row now)The newest progress note of child row in its current task, clipped, or nil. The leader reads
the same notes when it waits, and the team rows show the newest one.
The newest progress note of child `row` in its current task, clipped, or nil. The leader reads the same notes when it waits, and the team rows show the newest one.
(leader-id db sid)The leader of session sid as a string: the team leader for a subagent, else sid.
The leader of session `sid` as a string: the team leader for a subagent, else `sid`.
(open-questions db sid)The open questions that the children of session sid wait on, as {:session_id child :entry_id id} rows. A child asks its own parent, so the row of a deleted child stays out.
The open questions that the children of session `sid` wait on, as `{:session_id child
:entry_id id}` rows. A child asks its own parent, so the row of a deleted child stays out.(open-request sid)The open question that child sid waits on its parent to answer, or nil: {:question text :entry_id id}, plus :budget or :files for a budget or file request.
The open question that child `sid` waits on its parent to answer, or nil: `{:question text
:entry_id id}`, plus `:budget` or `:files` for a budget or file request.(operation! env operation opts)Run one managed-subagent operation for the calling session and answer its plain result.
Gateway routes and extensions call this entry point; model tools call the same functions.
operation is :spawn, :list, :route, :run, :wait, :cancel, :extend, :deny, :answer,
:grant or :timeline. Records answer in their wire form.
Run one managed-subagent operation for the calling session and answer its plain result. Gateway routes and extensions call this entry point; model tools call the same functions. `operation` is :spawn, :list, :route, :run, :wait, :cancel, :extend, :deny, :answer, :grant or :timeline. Records answer in their wire form.
(person-answers? db sid)True when a person answers the questions of session sid. A managed subagent has no
person: its leader answers its questions and decides its grants.
True when a person answers the questions of session `sid`. A managed subagent has no person: its leader answers its questions and decides its grants.
(prompt-cache-key environment)The provider prompt-cache key of environment: a short hash of its workspace root.
Sessions of one workspace share the core and project prefix. A new session and a
subagent then reach the warm cache of earlier requests. Without a workspace root, the
leader id keeps one key for each team. The raw path never leaves the host.
The provider prompt-cache key of `environment`: a short hash of its workspace root. Sessions of one workspace share the core and project prefix. A new session and a subagent then reach the warm cache of earlier requests. Without a workspace root, the leader id keeps one key for each team. The raw path never leaves the host.
(publish-with-files! env opts publish!)Publish Council entry opts with publish!, a function of the opts. With :files, the one
ping recipient must be an idle subagent of the caller. Its grant then changes before the wake,
so its follow-up task starts in that scope (#414). A failed publication or an unavailable reply
restores the old grant.
Publish Council entry `opts` with `publish!`, a function of the opts. With `:files`, the one ping recipient must be an idle subagent of the caller. Its grant then changes before the wake, so its follow-up task starts in that scope (#414). A failed publication or an unavailable reply restores the old grant.
(queue-turn! db sid)Queue subagent sid for a follow-up turn. A Council ping from its parent uses it, so
council.wait reports only the answer of the new turn. A follow-up can pass the active cap; only
a new spawn counts against it. Answers a function that undoes the change, or nil when the child
has no iterations left, or is cancelled while its leader runs no turn. A child that already runs
stays as is.
Queue subagent `sid` for a follow-up turn. A Council ping from its parent uses it, so council.wait reports only the answer of the new turn. A follow-up can pass the active cap; only a new spawn counts against it. Answers a function that undoes the change, or nil when the child has no iterations left, or is cancelled while its leader runs no turn. A child that already runs stays as is.
(reconcile-orphans! db live-sids)Fail the children that a dead process left queued or running. Spare a child or a leader
that live-sids names: a live process still owns that team. Returns the count.
Fail the children that a dead process left queued or running. Spare a child or a leader that `live-sids` names: a live process still owns that team. Returns the count.
(refusal-answer env report)The answer of a child turn that claim-iteration! stopped: the stop reason, then the last
report of the turn. Without a report, it names where the parent can read the work.
The answer of a child turn that `claim-iteration!` stopped: the stop reason, then the last report of the turn. Without a report, it names where the parent can read the work.
(report-result env text)(report-result env text opts)As a subagent, report the result of your task in one line, before your final answer. An example is "All 42 tests pass". text is one line of at most 200 characters. As a verifier, also give outcome "passed" or "failed". A later call replaces the line.
As a subagent, report the result of your task in one line, before your final answer. An example is "All 42 tests pass". text is one line of at most 200 characters. As a verifier, also give outcome "passed" or "failed". A later call replaces the line.
(require-enabled! db sid)Refuse new managed work before bootstrapping a session or consuming a checkpoint.
Refuse new managed work before bootstrapping a session or consuming a checkpoint.
(restrict-router env router)Apply the routing limits of a subagent to every request and retry, including automatic fallback. An inherited allowlist narrows the providers. A 429 ends the request at once, without a wait or another provider: the parent chooses the next route from the record of the child.
Apply the routing limits of a subagent to every request and retry, including automatic fallback. An inherited allowlist narrows the providers. A 429 ends the request at once, without a wait or another provider: the parent chooses the next route from the record of the child.
The subagent roles of the agents contract, in its order: const, title and description.
A role is a label. It sets no tool, file or model limit.
The subagent roles of the agents contract, in its order: `const`, `title` and `description`. A role is a label. It sets no tool, file or model limit.
(routing-change env before)The route command issued for this session since before, as
{:preference {:provider :model} :command command}, or nil. Agent routing and the
engine's authentication rescue issue commands; a manual pick is composer state that
the next submitted turn snapshots, so it never re-routes a running turn.
The route command issued for this session since `before`, as
`{:preference {:provider :model} :command command}`, or nil. Agent routing and the
engine's authentication rescue issue commands; a manual pick is composer state that
the next submitted turn snapshots, so it never re-routes a running turn.(run env tasks)(run env tasks opts)Run each task in its own subagent and wait for all of them. A task is a string or a dict with task and optional title, role, model, provider, iteration_budget and files. iteration_budget defaults to 120 (max 600). Give a large task more at the start.
title is a short label for people: one line of 1 to 40 characters, such as "Fix login test". Without it, people see the child number, such as #2.
role is research, implement, verify or audit. It is a label for people and sets no tool, file or model limit. Choose it by the result that you need: facts, changed files, a pass or fail, or findings.
files is a file grant: {"write": [...], "read_only": [...], "deny": [...]}. Give only the lists that you need. An empty list adds no rules. Each rule is a path or a glob, relative to your workspace root, ~ or absolute, and also covers files that do not exist yet.
With write, the child can change only the files that its rules match. deny wins over read_only, and read_only wins over write. Without files, the child writes where you write. With the jail off, only host file tools follow all rules: Python follows only write, and shell follows none.
A child gets the system prompt, your requests, notes and answers, and its task. It does not get your tool calls or their output. Children share the checkout. Only a leader starts subagents.
Records have session_id, status, answer and question. More than 16 tasks start as earlier ones finish. timeout_secs defaults to 240 (max 1800). If a status is still running, call council.wait. A failed record can have error with its code and message.
The call also returns when the first child ends, asks or publishes a message. A running child's record then also has activity, notes, messages, step_secs, elapsed_secs and alerts.
asking with budget_request needs council.extend or council.deny. asking with files_request needs council.grant or council.deny. budget_limited needs council.extend before a follow-up ping, and it stays budget_limited until that ping.
Run each task in its own subagent and wait for all of them. A task is a string or a dict with
task and optional title, role, model, provider, iteration_budget and files. iteration_budget
defaults to 120 (max 600). Give a large task more at the start.
title is a short label for people: one line of 1 to 40 characters, such as "Fix login test".
Without it, people see the child number, such as #2.
role is research, implement, verify or audit. It is a label for people and sets no tool, file or
model limit. Choose it by the result that you need: facts, changed files, a pass or fail, or
findings.
files is a file grant: {"write": [...], "read_only": [...], "deny": [...]}. Give only the
lists that you need. An empty list adds no rules. Each rule is a path or a glob, relative to
your workspace root, ~ or absolute, and also covers files that do not exist yet.
With write, the child can change only the files that its rules match. deny wins over read_only,
and read_only wins over write. Without files, the child writes where you write. With the jail
off, only host file tools follow all rules: Python follows only write, and shell follows none.
A child gets the system prompt, your requests, notes and answers, and its task. It does not get
your tool calls or their output. Children share the checkout. Only a leader starts subagents.
Records have session_id, status, answer and question. More than 16 tasks start as earlier ones
finish. timeout_secs defaults to 240 (max 1800). If a status is still running, call
council.wait. A failed record can have error with its code and message.
The call also returns when the first child ends, asks or publishes a message. A running
child's record then also has activity, notes, messages, step_secs, elapsed_secs and alerts.
asking with budget_request needs council.extend or council.deny. asking with files_request
needs council.grant or council.deny. budget_limited needs council.extend before a follow-up ping,
and it stays budget_limited until that ping.(runtime-op! env operation opts)Validate opts and run one gateway runtime operation: :spawn, :list, :cancel, :route or :grant.
Validate `opts` and run one gateway runtime operation: :spawn, :list, :cancel, :route or :grant.
(stable-prefix env session-context)The stable prompt prefix of a child: the parent handoff, then the child's own session block. Each request of the child starts with it, also after a fold or in a later turn. Nil for a leader.
The stable prompt prefix of a child: the parent handoff, then the child's own session block. Each request of the child starts with it, also after a fold or in a later turn. Nil for a leader.
(stop-reason env)Give the cause when claim-iteration! refuses the child session of env.
Give the cause when `claim-iteration!` refuses the child session of `env`.
(task-request db sid entry)The turn request of a Council wake from the parent of managed child sid, or nil for another
author. The entry is the child's task, so the request gives its text as an instruction. It asks
for the whole result as the final answer, because council.wait returns that answer.
The turn request of a Council wake from the parent of managed child `sid`, or nil for another author. The entry is the child's task, so the request gives its text as an instruction. It asks for the whole result as the final answer, because council.wait returns that answer.
(timeline db sid child-id)The steps of child child-id of session sid, oldest first: the start of each child turn, its
progress notes, its Council messages and the end of its current task with its result. Copied
turns of the fork are older than the child, so they never count.
The steps of child `child-id` of session `sid`, oldest first: the start of each child turn, its progress notes, its Council messages and the end of its current task with its result. Copied turns of the fork are older than the child, so they never count.
(wait-agents env)(wait-agents env ids-or-opts)(wait-agents env ids opts)Wait again for subagents by session_ids (default: all your children). Same records and timeout as council.run.
Wait again for subagents by session_ids (default: all your children). Same records and timeout as council.run.
(wake-allowed? db author-id recipient-id)Automatic resume has two sources: an explicit ping between independent sessions, and a managed team. A child may return to its leader; siblings must share a task team. A managed session keeps its team rule, so an exhausted subagent stays idle. A cancelled subagent wakes only for a running turn of its leader. Only a managed subagent wakes itself; an independent session stays idle.
Automatic resume has two sources: an explicit ping between independent sessions, and a managed team. A child may return to its leader; siblings must share a task team. A managed session keeps its team rule, so an exhausted subagent stays idle. A cancelled subagent wakes only for a running turn of its leader. Only a managed subagent wakes itself; an independent session stays idle.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |