Goals Plugin

The Goals plugin provides long-lived intents: a goal is a knowledge-base tree on disk plus one or more workers that fire on a cron task, share that knowledge base, and pursue the intent over time. You (or the agent, through tools) set up a goal once; the Task Tools runs its workers after that.

Ask the agent to create a goal, list yours, pause one, or inspect what a worker last wrote — or use the Goals page in the web UI (/plugins/goals, also reachable from a chat-header chip and a welcome-page widget). You do not talk to a worker directly: input goes through the goal tools, or through a message left in the workers' inboxes from the Goals page.

Configuration

plugins:
  - module: codumentor.plugins.goals
    class: GoalsPlugin
    priority: 10
    args:
      enabled: true
      default_timezone: UTC
      # storage_repo: my-repo   # optional; see Storage below

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable or disable the plugin.
`default_timezone`	string	`"UTC"`	IANA timezone for interpreting worker cron expressions.
`storage_repo`	string	unset	Name of a configured repo (a key under `repos`) where goal trees are stored. When unset, falls back to the Agentic Memory plugin's repo, then to single-repo mode.
`storage_path`	string	`"goals"`	Path under the resolved repo root for goal trees.
`setup_agent.enabled`	bool	`false`	When `true`, `setup_goal` can draft the goal via a `goal`-role sub-agent and validate it before writing.
`setup_agent.max_iterations`	int	`12`	Re-prompt budget for that proposal.
`commit_enabled`	bool	`true`	Commit each goal's knowledge-base subtree into git so state is never only an uncommitted working tree. Set to `false` for a non-git workspace — otherwise the plugin warns once that it cannot commit.
`push_enabled`	bool	`true`	Push after committing, through the Agentic Memory plugin's shared push path. Ignored when `commit_enabled` is `false`.
`push_timeout`	int	`30`	Push timeout in seconds.
`push_max_consecutive_failures`	int	`5`	Consecutive push failures before the circuit breaker opens.
`commit_signature`	string	`"Made with Codumentor"`	Trailer appended to every goal commit.
`flush_after_minutes`	int	`30`	Commit a running worker's subtree once its state has gone this long uncommitted, so a long tick does not hold everything until it ends. `0` disables the flush.
`worker_denied_tools`	list	unset	Replaces the built-in list of general file tools hidden from goal workers. Omit to keep the built-in list; set `[]` to stop stripping file tools. Lifecycle tools and the allowed-subagents gate still apply.
`target_agents`	string	`"main"`	Which agents get the goal tools: `"main"`, `"subagent"`, or `"all"`. Default keeps create/delete/write off subagents.

Tools

The Goals tools are discovered on demand (they are not in the default tool list), so they do not clutter every turn.

Tool	Description
`setup_goal`	Create a goal: validate, write the knowledge-base tree, and register its cron workers
`list_goals`	List the caller's goals with status and worker summaries
`get_goal`	Read a goal's definition, state, and live worker tasks
`delete_goal`	Cancel all worker tasks (optionally delete the knowledge base)
`pause_goal` / `resume_goal`	Halt or restart every worker's cron ticks without deleting the goal
`import_goal`	Re-register a goal tree copied into the storage root (restore/portability)
`add_worker`	Add a cron worker to an existing goal
`remove_worker`	Remove one worker (task and its subtree)
`run_worker_now`	Fire one worker immediately as a one-off
`update_worker`	Change a worker's cron, instructions, role, allowed sub-agents, `timeout_seconds`, `token_budget`, or `model_role`
`goal_kb_read`	Read a file from the goal knowledge base by goal-relative path
`goal_kb_write`	Write a file in the goal knowledge base by goal-relative path
`goal_kb_append_entry`	Append one item to a YAML list in a knowledge-base file (for growing logs that are too large to rewrite whole)
`goal_kb_list`	List files/directories under a goal knowledge-base sub-path

Web UI and HTTP API

The plugin ships a web bundle (ui/plugins/goals) and an API mounted at /ui/plugins/goals: a fleet view with a "needs you" queue, per-goal activity, workers, knowledge-base browser and setup tabs, a per-worker history page, a run drawer showing each tick's commit diff, and a new-goal wizard. The API calls the same operations as the tools, with the same ownership rule (a goal you do not own answers 404). It is repository-scoped: a user whose access profile lacks full repository access gets neither the page's data nor the header chip. Alert acknowledgments are per user and kept in the app data dir (goal_alert_acks.sqlite3; override with CODUMENTOR_GOALS_ACK_DB_PATH), never in the goal's knowledge base.

Storage

Goal trees must live inside a configured repo so that workers running under Workspace Isolation can see them. The location is resolved in order: explicit storage_repo → Agentic Memory's repo → single-repo mode. If none apply, the plugin errors rather than writing outside the configured repos.

Under workspace isolation, workers should use the goal_kb_* tools to read and write the goal's files. Those tools write the shared tree on disk; ordinary file tools in a sandboxed worker would not persist for the next tick.

Notes

The knowledge base is the source of truth. Worker instructions live in the goal tree; editing them takes effect on the next tick without rescheduling.
Registration is all-or-nothing: if any worker fails to register, the whole goal is rolled back.
Your own changes are committed under your name. Creating a goal, adding, editing or removing a worker, deleting a goal, and (from the Goals page) messaging a goal or editing its protocol.md each commit just the files they wrote, as goal/<id>/user with a User: trailer — so a goal's git log separates human steering from worker ticks (goal/<id>/<worker>).
Commits recover on their own. A tick normally commits its subtree when the run ends. If that never happens (restart, timeout), the next tick of any worker — and the next server start — commits whatever is still dirty.
Requirements: the core Task Tools and job queue (both on by default); the propose flow additionally needs the Model Profiles goal role.
Per-worker tools. A worker may list the tools its role calls every tick (e.g. gmail_send for a reporter). Those the deployment has (and the owner's access profile allows) are loaded up front for its runs instead of waiting to be discovered. This adds no permission — the worker keeps its other tools. Editable via update_worker.
Per-worker model_role (cost lever). A worker may name a model_role — a profile the deployment configures under Model Profiles. Put high-frequency collectors on a cheap slot and analysts on the strong one; an unset or unmapped role falls back to the default agent model. Editable live via update_worker and inherited by run_worker_now.
Per-worker token_budget (spend guard). A worker may set token_budget (whole tokens, at least 1000) in its definition.yaml, from setup_goal / add_worker / update_worker, or in the worker edit form on the Goals page. It caps each tick's agent tokens — cached prompt tokens included, subagents and external agents included, auxiliary calls (titles, recall, compaction, judges) not — and rides beside timeout_seconds on the live task, so run_worker_now and the wizard's test fire use it too. Clearing it (emptying the form field, or null to update_worker / PATCH; the same works for timeout_seconds) returns the worker to the operator default (tasks.default_run_token_budget, often unlimited); tasks.max_run_token_budget caps any value. A tick that spends it stops at the next agent-loop iteration (it can overshoot by up to one iteration; the worker is told to wrap up at 80 %), is recorded failed with error_kind: token_budget, commits a <worker>: tick stopped at its token budget marker, and counts toward the worker's consecutive-failure auto-disable like a timeout. A tick stopped by the loop detector (the model kept repeating the same step) is likewise failed, error_kind: loop, with a <worker>: tick stopped repeating itself marker. See Admin Configuration Reference → Per-run token budgets.
Token reporting. The run panel shows each tick's tokens against its budget (84k / 100k (84 %), a Stopped at token budget badge on a budget stop), with input / cached / output and cost in its tooltip; cost reads unknown for an unpriced model, never $0. The worker page shows average tokens and the worker's budget per run.