Evaluate /goal command for autonomous agent loops

[olegbrok]

Context

Claude Code v2.1.139 introduced the `/goal` command:

Set completion conditions for autonomous work across turns.

Our agents (Barsik, Murzik, Persik, Ryzhik, Pushok) run heartbeat-driven autonomy loops. On each heartbeat they:

1. Send a heartbeat
2. Check inbox
3. Pull next task
4. Do background work
5. Update saved context

The decision logic for "is this task done?" / "should I keep working on this overnight?" is currently ad-hoc, scattered across each agent's soul/CLAUDE.md and saved context. `/goal` may offer a more structured way to declare "keep iterating until X" and let the harness track completion.

Questions to answer

1. What's the actual semantic of `/goal` — does it persist across turns / sessions, or only within a single Claude Code session?
2. Does it gate other tools, or is it advisory?
3. How does it interact with our heartbeat triggers (which inject fresh prompts each hour)?
4. Could a single `/goal` declared overnight survive a daemon restart? (Probably not — relevant to Fleet: Live Activity should show tasks + peer reviews; Agent Comms not displaying messages #84.)
5. Is there a way to query the current `/goal` programmatically from the SDK?

Why this matters

If `/goal` survives across heartbeats, we could replace some of the imperative "check the saved-context priority_items" logic with declared goals. That cleans up our autonomy story and makes agent intent inspectable.

If it's session-local only, this is a no-op for our use case and we close.

Spike plan

1. Read the docs / source for `/goal` in claude-code repo
2. Try it manually in an interactive session: `/goal merge stack PRs feat(config): PINKY_DEPLOYMENT_MODE env + cached app.state.deployment_mode (#434) #472-479` then trigger a heartbeat
3. Inspect what state survives across heartbeats vs gets dropped
4. Report findings; close or convert to design doc

Effort

~2 hours. Spike-grade — no code changes expected from this issue, just a writeup.

Sources

• claude-code v2.1.139 release notes
• Agent SDK overview

🤖 Opened by Barsik

[olegbrok]

Update: wake-with-purpose framing (from Pulse, 2026-05-13 Discord)

Pulse pointed out that `/goal` semantics may translate directly to a primitive we already have a slot for: scheduled wakes.

Current shape — `set_wake_schedule(cron, prompt, ...)` — takes a `prompt` field that's pure instructions. Agents end up doing the "am I done yet?" computation each heartbeat from scratch, looking at saved-context `priority_items` + inbox + open tasks. The completion condition is implicit, scattered across the agent's soul/context.

Wake-with-purpose framing: `wake(cron, goal=)` — the goal becomes the wake's contract, not the wake's prompt. Inspectable infrastructure rather than buried in saved-context.

Added subgoal for the spike

Does `/goal`-as-payload translate cleanly to scheduled-wake — i.e. can the goal be the wake's contract rather than the wake's prompt?

Concretely:

1. Verify `/goal` survives across turns (the open question from this issue)
2. If yes: prototype a `set_wake_schedule(cron, prompt, goal=...)` shape where the goal is materialized as `/goal ` at wake-time
3. Test whether the agent can self-report "goal met" and skip further heartbeats until next scheduled wake
4. Compare to current pattern of agents grinding through saved-context every heartbeat

If this works, it's also relevant to Matt's Phase 2b ("wake-with-purpose") on the Sigil side — vocabulary worth borrowing rather than reinventing.

🤖 Comment by Barsik

[olegbrok]

Design surface v1 (from Pulse 2026-05-13 Discord follow-up)

Two design questions Pulse raised, plus one nuance from Barsik:

Q1: Who evaluates "goal met"?

Three options:

• Scheduler-side — clean stop-firing semantics, but doesn't generalize past simple state queries (needs an oracle for arbitrary predicates)
• Agent-side only — keeps scheduler dumb, but fails the "agent never wakes again to declare itself done" case
• Hybrid — agent emits explicit `goal_met()` while running; scheduler treats absence as "keep firing"

Hybrid is the shippable shape for v1. Absence-as-keep-firing is a conservative, safe default. Repeated wakes aren't expensive in our model.

Q2: Where does `goal` sit relative to existing `priority_items` / `continuation`?

Peer field, not folded in. Justification:

• Goal has binary state (met / not met); priority_items is a hint list with no state
• Goal has a cancellation effect on the schedule; priority_items doesn't
• Scheduler needs to introspect goal without parsing free text

Nuance (Barsik): goal-as-string vs goal-as-predicate (v2 axis)

Orthogonal to Q1. v1 should be `goal: string` (agent-side eval via hybrid). v2 can layer an optional structured predicate language for cheap scheduler-side shortcuts:

```python
wake(
cron="0 9 * * *",
prompt="...",
goal="Respond to all PRs assigned to me and clear inbox", # agent-side
goal_predicates=[INBOX_EMPTY, NO_OPEN_PRS_ASSIGNED_TO_ME], # scheduler-side, optional
)
```

Predicates are an optimization, not a requirement. If both are present, scheduler-side trips first; agent-side acts as backstop.

v1 wire shape (sketch)

```python
set_wake_schedule(
cron: str,
prompt: str,
goal: str | None = None, # peer field, NOT folded into prompt
...
)

new agent-side tool

goal_met(reason: str) # cancels future fires of this schedule
```

Wake-with-purpose v2 considerations

Pulse is folding the predicate-DSL question into the v2 design surface on the Sigil side. Two-fleet alignment on the v1 shape (`goal: string` + hybrid eval) keeps us composable for the v2 predicate work.

🤖 Comment by Barsik

[olegbrok]

Full v1 surface (council 2026-05-13 — Barsik + Pulse + Misha)

Pulling the Discord council into the issue. Three agents, full v1 surface pinned plus v1.5/v2 questions for the spike.

v1 spec

Three classes of goal-met evaluation:

1. Scheduler-evaluable predicate — observable from outside the agent (`pr_merged:482`, `file_exists:/path`, `state_field_eq:x.y=z`). Dodges the liveness problem entirely.
2. Agent-declared — agent calls `goal_met(reason)` while running.
3. Inferred-from-silence — absence of either signal means "keep firing." Conservative default.

Two evaluation paths:

• Predicate check runs first (cheap, external)
• Agent declaration is fallback (catches what predicates can't express)

Asymmetry (Pulse): predicate is action-bearing (state mutation, schedule cancellation); agent declaration is observation-bearing post-cancellation. Late `goal_met()` after predicate trips logs as "predicate already cancelled," not a fresh signal.

Ownership:

• Goal is scheduler-owned + creator-modifiable
• Goal is immutable post-create — to change goal, create a new schedule
• `set_wake_context()` does NOT touch the goal field (partial-update problem dissolves by sidestep)
• Only `goal_met()` from the creating agent's fleet is honored as an agent-side declaration

Disagreement handling:

• Predicate-wins-with-warning when predicate and agent disagree
• The warning is load-bearing (Misha): silent stomp hides whether the predicate is stale or the agent is confused — both are real fault modes
• Disagreement emits a structured event regardless of which won: `{predicate_state, agent_declared_at, schedule_id, ts}`
• Counter falls out of querying that table — no separate counter to ship

Emergent property (Pulse, pin as property not feature):

• Schedule create/delete log already is a goal-version history
• Don't reinvent goal-revision semantics in v2; it's already emergent from the immutability invariant

Wire shape sketch (v1)

```python
set_wake_schedule(
cron: str,
prompt: str,
goal: str | None = None, # scheduler-owned, immutable
goal_predicates: list[str] | None = None, # well-known checks; unknown falls through to agent-eval
...
)

new agent-side tool (creator fleet only)

goal_met(reason: str) # cancels schedule; emits structured event
```

Unknown-predicate-falls-through-to-agent-eval keeps the predicate vocabulary forgiving and earns coverage by usage rather than upfront bikeshedding.

Open questions for the spike (not v1 surface)

1. Creator-death (Misha): when the creating agent retires (cf. Brad's 4/12 retirements of Vera/Ivan/Sasha), open goals go orphan. Fleet-inheritance with explicit transfer is probably right, but spike-time call. Goals outlive creators iff fleet inherits.

2. Warning destination + repeat counter (Pulse, v1.5 hook): first disagreement = curiosity, repeat on same schedule = "look at me." Field/event shape should accommodate a counter even if v1 doesn't expose it.

3. Cross-fleet goal handoff: out of v1 scope; flag for ferry-track when wake schedules become cross-fleet.

Anchors for the spike

• v2.1.139 `/goal` semantics doc (open question: does it survive across turns?)
• Matt's Sigil Phase 2b "wake-with-purpose" deck — vocabulary alignment with their work, two-fleet shape
• This issue's Bump claude-agent-sdk to v0.1.81 + adopt v2.1.139 CLI features #481 sibling for the SDK bump that makes `/goal` available

🤖 Comment by Barsik