feat(agents): a flow that runs an agent under a goal says so, and is refused one without

`pursue` is the backend's own goal feature: the agent decides for itself that
the objective has been met, and until it does, a turn that would have ended
starts another. Three of the six here have one. A flow built on it is not a
flow any agent can drive -- and there was no way to say that, so the official
`goal` flow started happily on `pi` and died in the middle of its first turn
with `PiSession has no goal feature`, half an hour of a run spent finding out
what could have been checked before the first word went anywhere.

It is checked now, where every other requirement of a place is. An agent says
`pursues` on the class, beside the moments it runs; a flow writes
`Annotated[AgentBase, Goal]` where it declares the place; and the runner
refuses the pairing before the first turn, saying which agent and which
backend. The interface's `/agents` sheet offers only the CLIs that would work,
which is what it already did for moments, and says why the list is short.

Found by running every flow humanize offers against every CLI installed here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: futrime

docs/flows.md

@@ -255,11 +255,29 @@ class Agents(NamedTuple):
 exactly as it did, and what is written beside it is what the place asks of whoever fills it.
 Several moments are several arguments.
 
-It is checked before the first turn, for the same reason the count is:
+**A goal is asked for the same way.** `agent.pursue(objective)` is the backend's own goal
+feature — the agent decides for itself that the objective has been met, and until it does, a
+turn that would have ended starts another. Three backends have one (Claude Code, codex, Kimi),
+so a flow built on it says so:
+
+```python
+from hmz.agents import AgentBase, Goal
+
+
+class Agents(NamedTuple):
+    """The one it drives, which has to have a goal of its own."""
+
+    worker: Annotated[AgentBase, Goal]
+```
+
+Both are checked before the first turn, for the same reason the count is:
 
 ```console
 $ hmz exec -f gated -a codex/gpt-5.6-sol:high -a codex/gpt-5.6-sol:high "fix the build"
 hmz exec: error: /.../gated.py: builder has to run PermissionRequest, which codex does not
+
+$ hmz exec -f pursuing -a pi/gpt-5.4:high "fix the build"
+hmz exec: error: /.../pursuing.py: worker is run under a goal, which pi has no feature for
 ```
 
 and the interface's `/agents` offers only the CLIs that would work for that place, so it cannot

src/hmz/SPEC.md

@@ -135,6 +135,12 @@ class Runner:
   asked for MUST be read before the name is resolved to a file, and a name no flow in the file
   answers to MUST be reported as a usage error saying which ones it holds -- a file of three
   asked for by its own name is a colon away from what was meant.
+- A flow that runs one of its agents under the backend's own goal feature MUST say so where it
+  declares the place, by writing `Goal` beside the type, and an agent whose backend has none
+  MUST be refused before the first turn -- for the reason a moment it cannot run is: a loop
+  built on `pursue` finds out in the middle of a turn otherwise, hours in. What each backend
+  has MUST be said on the agent rather than asked of it, so that whoever is choosing one can
+  offer only the ones that would work.
 - A `NamedTuple` of agents MUST be accepted in its place, and MUST additionally say what the
   flow calls each of them. `drives` MUST report those names, so that whatever asks for the
   agents asks for them by what they are for rather than by their place in a line; a plain

src/hmz/agents/SPEC.md

@@ -35,6 +35,9 @@ with no behaviour on them.
 ## `config.py`
 
 ```python
+class Goal: ...
+
+
 class Remote: ...
 
 

src/hmz/agents/__init__.py

@@ -15,6 +15,7 @@
 from .config import (
     PERMISSIONS,
     AgentConfig,
+    Goal,
     Isolated,
     Remote,
     anchored,
@@ -57,6 +58,7 @@
     "CodexSession",
     "CommandSessionBase",
     "Event",
+    "Goal",
     "Hook",
     "Hooks",
     "HumanAgent",

src/hmz/agents/base.py

@@ -1567,6 +1567,13 @@ class AgentBase(ABC):
     #: more, and a flow that needs one of those says so where it declares the agents it drives.
     moments: ClassVar[frozenset[Moment]] = EVERYWHERE
 
+    #: Whether this backend has a goal feature of its own -- one where the agent decides for
+    #: itself that an objective has been met, and a turn that would have ended starts another
+    #: instead, which is what `pursue` reaches for. Three of them have; a flow that runs its
+    #: agent under a goal says so where it declares them, and is then refused an agent that
+    #: has not rather than raising on the first turn.
+    pursues: ClassVar[bool] = False
+
     def __init__(self, config: AgentConfig, *, name: str | None = None) -> None:
         """Initializes an agent that has opened nothing yet.
 

src/hmz/agents/claude.py

@@ -518,6 +518,9 @@ class ClaudeCodeAgent(AgentBase):
     #: one backend here where a hook can say no to something and have the agent hear it.
     moments: ClassVar[frozenset[Moment]] = EVERYWHERE | {Moment.PERMISSION_REQUEST}
 
+    #: Claude keeps itself going toward an objective, which is what `pursue` reaches for.
+    pursues: ClassVar[bool] = True
+
     def new(self, cwd: str | os.PathLike[str] | None = None) -> ClaudeCodeSession:
         """Opens a new Claude Code session, in the directory it is given or in this one."""
         return ClaudeCodeSession(self, cwd)

src/hmz/agents/codex.py

@@ -900,6 +900,9 @@ class CodexAgent(AgentBase):
 
     moments: ClassVar[frozenset[Moment]] = EVERYWHERE | {Moment.PERMISSION_REQUEST}
 
+    #: codex keeps itself going toward an objective, which is what `pursue` reaches for.
+    pursues: ClassVar[bool] = True
+
     def __init__(self, config: AgentConfig, *, name: str | None = None) -> None:
         """Initializes an agent whose app server is not running yet.
 

src/hmz/agents/config.py

@@ -33,6 +33,21 @@
 PERMISSIONS = ("read-only", "workspace-write", "auto", "bypass")
 
 
+class Goal:
+    """What a flow writes beside an agent it runs under the backend's own goal feature.
+
+    `pursue` is the agent keeping itself going toward an objective it decides for itself is
+    met, and three backends have it. A flow built on that is not a flow any agent can drive,
+    so it says which of its agents has to have one, by writing this where it declares them::
+
+        class Agents(NamedTuple):
+            worker: Annotated[AgentBase, Goal]
+
+    and an agent whose backend has no goal feature is refused before the first turn rather
+    than raising in the middle of one, which is where a loop would otherwise find out.
+    """
+
+
 class Remote:
     """What a flow writes beside an agent that may be pointed at another machine.
 

src/hmz/agents/kimi.py

@@ -26,7 +26,7 @@
 import weakref
 from collections import Counter
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from .base import AgentBase, SessionBase
 from .config import AgentConfig
@@ -592,6 +592,9 @@ def _submit(self, prompt: str, *, goal: bool) -> Iterator[Event]:
 class KimiCodeCLIAgent(AgentBase):
     """Kimi Code, driven through an app server of its own so a whole session is settable."""
 
+    #: Kimi keeps itself going toward an objective, which is what `pursue` reaches for.
+    pursues: ClassVar[bool] = True
+
     def __init__(self, config: AgentConfig, *, name: str | None = None) -> None:
         """Initializes an agent whose server is not running yet.
 

src/hmz/runner.py

@@ -129,6 +129,9 @@ class Place(NamedTuple):
       moments: The moments the agent filling it has to run, which the flow said by writing
         `Annotated[AgentBase, Moment.PERMISSION_REQUEST]` where it declared the place. Empty
         where it asked for nothing in particular, which is most places.
+      goal: Whether the flow runs this one under the backend's own goal feature, which it
+        said by writing `Annotated[AgentBase, Goal]` where it declared the place. Only three
+        backends have one, so a flow built on it is not a flow any agent can drive.
       where: Where the agent filling it may work, which the flow said the same way -- `Remote`
         for one that may be pointed at another machine, an `Isolated` for one that works in a
         container the flow itself names the image of. None for a place the flow said nothing
@@ -141,6 +144,7 @@ class Place(NamedTuple):
     person: bool
     moments: frozenset[Moment]
     where: type[Remote] | Remote | Isolated | None = None
+    goal: bool = False
 
 
 def drives(flow: str | os.PathLike[str]) -> tuple[str, ...]:
@@ -682,9 +686,12 @@ def _place(name: str, kind: object) -> Place:
     """
     moments = frozenset(_moments(kind))
     where = _where(kind)
+    goal = _goal(kind)
     if get_origin(kind) is Annotated:
         kind = get_args(kind)[0]
-    return Place(name=name, person=_is_person(kind), moments=moments, where=where)
+    return Place(
+        name=name, person=_is_person(kind), moments=moments, where=where, goal=goal
+    )
 
 
 def _where(kind: object) -> type[Remote] | Remote | Isolated | None:
@@ -707,6 +714,23 @@ def _where(kind: object) -> type[Remote] | Remote | Isolated | None:
     return None
 
 
+def _goal(kind: object) -> bool:
+    """Whether a flow said the agent filling a place is run under its backend's goal feature.
+
+    Args:
+      kind: What the flow annotated the place with.
+
+    Returns:
+      True if it wrote `Goal` beside the type, and False for a place annotated with the type
+      alone -- which is one driven by turns like every other.
+    """
+    from .agents import Goal
+
+    if get_origin(kind) is not Annotated:
+        return False
+    return any(said is Goal for said in get_args(kind)[1:])
+
+
 def _moments(kind: object) -> tuple[Moment, ...]:
     """The moments a flow asked the agent filling a place to run.
 
@@ -831,6 +855,11 @@ def __init__(
                     f"{flow}: {place.name or 'the agent'} has to run "
                     f"{', '.join(sorted(short))}, which {agent.backend} does not"
                 )
+            if place.goal and not type(agent).pursues:
+                raise NotAFlow(
+                    f"{flow}: {place.name or 'the agent'} is run under a goal, which "
+                    f"{agent.backend} has no feature for"
+                )
             _lands(flow, agent, place)
         # The person at the prompt is made here rather than given: nobody chooses what they
         # run, so nothing upstream of this was ever asked about them.