Skip to content

Agent operations

Agent controls, action policies, assignments and handoff contracts are records in pkg/operations, backed by the same memory or Postgres state.Store as the rest of the platform. Each tenant is capped at 10,000 records. HTTP lists return at most 200 visible records; hidden projects, private threads and hidden agents contribute no rows or network counts. Updates use an expected version.

Controls and action policy

GET/PUT /api/agent-controls pauses or resumes new workspace admissions. GET/PUT /api/agents/{name}/control controls one agent and records its accountable manager and instructional stop rules. The manager is workspace-wide per agent; project action policies remain scoped to projects. Current and compatibility handles for a built-in agent share the same control. Pause changes serialize with admission, never mark a run stopped, and never grant tools. The ledger continues to determine every accepted run's actual outcome.

The action-policy routes cover workspace, project, agent and the reader's own personal scope. Allow, Ask and Never compose by taking the strictest rule across the workspace, the whole project chain, agent and person. A missing rule leaves the existing spec grants alone. Allow never adds a tool or a spawn grant. A lower policy cannot override an upper Ask or Never. Existing call allowlists, budget policies and callee approvals still apply independently.

Categories are read context, write files, publish artifacts, send external messages, call agents and other actions. MCP read groups are read context; write groups conservatively apply both other-actions and external-message rules. A provider's tool name is not evidence that an action is read-only.

Tool declarations

Every tool is declared once, in the system tool registry (internal/platform/systemtools.go): the operations of the API contract, the agent call and get_context, and every tool an agent's run may be offered (internal/platform/systemtools_run.go). A declaration states:

Field Meaning
Category The action-policy category of a call. A tool states it; it is never read from the tool's name.
Also, BothAllow A second category that holds the call too. github_apply_changes and github_create_fix_pr send something outside and change files; opening a fix pull request runs unasked only when both categories allow it.
ReadOnly, Destructive, Idempotent, Parallel What a call does. An MCP client is told the first three.
ActsForPerson The call runs with the credential of the person the run acts for (source_search, catalog_query, corpus_query).
Approval Who approves a call: the action policy for the category (the default), the tool's own approvers on every call, or nobody for an operation a signed-in person's own client calls.
Exposure Who is offered the tool: MCP clients at /api/mcp, agent runs, or both. The zero value offers it to nobody.

A turn's tools are built from these declarations, and one wrapper holds every call to the tool's declared approval and to the policy. The tools that change an agent, its evals or the shared instructions carry their own approvers:

Tool Approvers The person asking may approve
pause_agent, retire_agent, write_eval_suite, add_recorded_eval_case, apply_agent_change role:admin, role:manager Yes
set_workspace_prompt, apply_workspace_prompt role:admin No
agent The called agent's call policy, per call As that policy says
A person's own connected tool that is not a read That person, for 24 hours Yes

Every other run tool asks only where the policy says Ask: the agent's approvers, or the workspace's fallback approvers and the agent's manager, for 24 hours.

list_agents, list_alerts and run_eval_suite each name two tools with different implementations: an operation of the API contract, offered over MCP, and a builder or analyst tool, offered to runs. The run tool has a registry key of its own (run/<name>) and is never listed over MCP, so neither is reached through the other.

A tool that is not in the registry cannot declare a category: a tool of an extension catalog, or a tool provider's tool where only its name is known. Only for those, a name that says it sends a message is held as an external message and any other as other. session_read, session_link and ask_person are built by the runtime, which resolves them before it asks the platform's catalog, so the registry declares them but their calls do not pass the wrapper. The runtime's other session verbs (session_call, session_listen, session_status) and its per-agent tag_<agent> tools call an agent or wait on one, and are not offered: the agent tool is the one way a run calls an agent (agent calls).

Private context

The catalog preserves rich results and person-scoped credential behavior. Before a person-scoped tool executes, the run durably records that private context may enter its result. A failed marker write aborts execution. Raw publication of that call tree requires a reviewed summary, including after restart or when a helper result is opened on its own. MCP discovery uses the exact run actor, with a session bounded by that run's execution, and never borrows another actor or a process credential.

Ask uses fiber's existing durable approval mechanism. Questions, deadlines, edited approved arguments and continuation use the existing runtime records. Never and pause are checked again at tool execution and on every agent call. Internal Turn.ForceAsk tightens a draft test to Ask without weakening Never. A pinned skill may restrict exact tool names with operations.MetaTools; explicit [] grants no actions. Restrictions and ForceAsk follow helper calls so delegating does not escape the test or skill's restrictions.

Assignments and contracts

Assignments have an owner, project, optional conversation, goal, done-when, deadline and optional five-field cron expression. A manual run reserves its deterministic identity before calling the existing conversation composer and Invoke. A repeated request joins that reservation, including after a crash between reservation and admission. An assignment in an existing conversation must pass the same posting rule, including private-thread participation.

A manual assignment may carry done_checks: up to eight text rules its agent's answer must pass (contains, not_contains, equals, matches). They are the answer checks of an eval and ask no model. A check reads the answer's text and nothing else, so it cannot tell a statement from its denial: contains "DONE" passes "this is not DONE". Where the answer must be an exact completion, use equals, or matches with the pattern anchored to the start or the end of the answer. With them, a completed run does not settle the assignment by completing. An answer that fails a check is continued: the platform reserves the next run under a deterministic identity, then asks the same agent in the same conversation to go on, as the owner, naming the checks that failed. It does so at most max_continue times (3 when left out, 10 at most), after which the assignment is blocked for its owner with the checks that never passed. The owner's project membership is rechecked before each continuation. The reservation is written before the run is admitted, so a restart between the two admits the same run again. An assignment on a clock or a source change takes no checks: each of its occurrences is its own run. Checks are part of the execution contract, so a change to them needs a new assignment; a change that names none keeps them.

Standing assignments are project-scoped. Cron plus an existing conversation is refused, so a private conversation goal cannot be replayed into a wider room. Every occurrence rechecks the owner's ordinary project membership without borrowing a sign-in or bearer scope. Losing access pauses and blocks the work. Ordinary schedule mutation routes cannot bypass the assignment owner. The reservation stores the exact clock occurrence before ledger acceptance. Restart reconciliation retries that occurrence through current admission checks, preserving its ID, time and metadata. Older uncertain clock reservations without that record become blocked for explicit review.

Source-change assignments use a durable content-version cursor. Creating one requires knowledge read access and an existing source grant on its agent or project. The source-lifecycle layer registers its resident SourceChanges provider. Missing tracking, a hard-stale source or lost project membership blocks work. The existing reconciliation ticker scans at most 200 watchers per page, coalesces changes while work is active and raises deterministic tags through Invoke. Unchanged refreshes start no run; cursor and admission are kept together, and restart resumes observing after the stored version. Source recovery never resumes blocked work without an explicit owner action.

Standing assignments create paused schedules in the existing cron store. The schedule activates only after the contract is durable and the assignment is accepted or watching. Cancel pauses the schedule before saving the state. Changing an execution contract requires a new assignment, so an old scheduled occurrence cannot execute newly substituted instructions. No second scheduler, agent loop or model invocation path is introduced.

An observed terminal run and periodic reconciliation settle work from the run index's ledger-backed status. Success records a result; a standing assignment returns to watching. Failure records a blocker. A missing or silent run is not considered complete. Missed deadlines become Needs a person while retaining the actual run reference. The inbox uses a deterministic key per work item and state version so recovery between the operations write and inbox write does not create duplicate Needs-you items. Deadlines and pending work survive restart.

Every pkg/call invocation records a handoff contract before admission: typed input references, goal, done-when, deadline, chain and accountable manager. Callers may supply explicit contract terms. For old callers, the input and response format supply terms with a 24-hour deadline. A cycle or more than three hops records an escalation and refuses the child. Cross-project handoff remains the design spec's open question. Calls keep the existing root-project, thread, source and accounting boundary; a child agent unavailable there is refused without fabricating a run in another project. The run ledger, not the contract, determines whether accepted helper work succeeded.

GET /api/agent-network derives bounded visible edges from those contracts. Operation attention has its own inbox kind and part. Deadlines and escalation never claim a successful run failed, offer Retry Run or create a synthetic runtime question. Open Assignment and Open Handoff navigate to the actual versioned record; acknowledgement uses the existing inbox resolver.

The console components expose controls, policy editing, creation and running of assignments, recorded run links and contract inspection. Navigation and phone/desktop captures are integrated by the presentation layer of the stack.

Private assignment and handoff provenance is not automatically published with a conversation. The operations publication guard requires reviewed summary publication for any retained linked contract, and legacy operation reads must pass both the original project and current conversation audience. A host setup gate may allow an exact draft-owner/revision test to bypass that agent's pause only with ForceAsk. Setup readiness remains a separate admission check, so an ordinary unpause cannot activate an incomplete setup. Workspace pause and Never still deny those tests and their tools.

Source-hard-staleness admission and source dependency presentation are supplied by the source-lifecycle layer. The operations store does not infer source health or silently resume work when a source recovers.

Verification

The store tests run memory and Postgres restart, failed-write, version-conflict, reservation, policy tightening, contract bounds and deadline cases. HTTP tests exercise actual assignment execution and settlement, paused admission, missing and hidden objects, query bounds and the OpenAPI response sweep. The exhaustive confinement sweep includes assignments in hidden projects and private threads. Tool tests cover Never, unapproved Ask, pause and ForceAsk without adding grants; the existing person-credential and approval regressions cover MCP identity. Console DOM tests exercise successful and refused pauses, policy changes, assignment run references and network contract navigation.

Reviewing effective controls and deadlines

Controls report the effective pause and its workspace, agent or incomplete-setup cause. Local resume never clears a workspace pause or marks an incomplete setup ready. The console refreshes this state while preserving unsaved changes and requires review when another writer changes the control version. Policy views show the strongest applicable rule and its controlling scopes. A hidden ancestor has a generic inherited label, without its name or the number of hidden scopes. The editor cannot weaken an inherited restriction. This explanation grants no tool or access permission.

A missed deadline retains the recorded run and asks for human review. Extending or clearing the deadline observes that same run, including a still-running or completed result; it cannot reserve a duplicate run. Result state requires a completed ledger record. A late successful run records a result instead of silently restarting standing work with an expired deadline. The native cron schedule is paused during deadline attention and resumes only from a reviewed, future-dated eligible assignment.

Unanswered-question reminders default to four hours and blocked-work reminders to two hours. Workspace controls set the default, and agent controls can override the timer or disable it with zero. The maximum interval is seven days. These are real persisted inbox timers, reconciled through the existing platform ticker. A reminder checks the native pending question or the exact current blocked-work cause, updates the same inbox item once, and makes it unread for its authorized readers. It never approves a question, fabricates a run, or restarts work. Failed writes leave read counters unchanged; restart does not duplicate a reminder. The original requester and accountable manager receive operation attention, subject to the same project and thread confinement as every other inbox read.

Assignment links from an agent preselect that agent, open the creation form for writers and apply the same server-side filter before the row cap. Handoff review shows its actual typed inputs, accountable person's name and immutable artifact revision links after each referenced object passes its own read rule. Reviewing a contract cannot remove or replace its original conversation boundary.

Builder and health console integration

The console creates a canonical session with humagen, the entry agent, for New Agent. It took over from humagen-builder, which still reads as it. Management sessions use a per-agent label and reopen an existing personal session before posting any new intent. Agent setup aliases remain explicit builder entry points. The directory's operational filter is addressable and combines authoritative roster failures with read-confined evaluation health.

AgentHealth reads /api/agents/{name}/health and /changes; it shows counts, failed checks and retained score summaries, without reconstructing omitted candidate prompts or case text. Prompt diffs and tools come only from a recorded preview_agent_change or preview_workspace_prompt tool result. AgentChangeCards renders that result as presentation data and performs no API calls or approval writes. Applying the change still uses the runtime's governed apply_agent_change approval.

Console interaction tests exercise session reuse, permission-preserving creation, health refresh, state filters, and incomplete/regressed change cards. Real native-provider delivery and responsive browser checks are not established by those fixture tests. Optional authorized connection and listening summaries show current configured routing and status. Omitted metadata is not a claim of no connections, and configured placement is not evidence of live delivery or proposed installation.