Improve agent tracking

[FireSquid6]

When a user starts a task using opencode and puts it in the plan agent, it will be unable to use the fagent cli (since opencode plan agents can't use bash afaik). Thus opencode will be stuck with a false status as idle for the whole session.

We need to:

1. Figure out how to give opencode access to the fagent command while in plan mode (or any mode that doesn't have read/bash access)
2. Figure out ways to further improve the opencode plugin we install to automatically switch status based on hooks
3. Figure out ways to further improve the claude plugin we install to automatically switch status based on hooks

[FireSquid6]

@claude Do some preliminary research on how to accomplish this

[claude]

Claude finished @FireSquid6's task in 2m 24s —— View job

---

Tasks

• Read issue and understand request
• Explore fagent CLI implementation
• Explore opencode plugin implementation
• Explore claude plugin implementation
• Research how opencode plan/read-only modes restrict tool access
• Write up research findings and recommendations

Findings

Note on method: WebSearch/WebFetch were not authorized in this sandbox, so I couldn't pull the current OpenCode/Claude Code docs live. The design below is based on reading this repo's existing plugin code (packages/fleet-ship/plugins/opencode.js, packages/fleet-ship/plugins/claude-code/hooks/) plus general knowledge of both tools' hook/plugin architectures. Please double-check exact hook names against current docs before implementing.

The core problem: status reporting today depends entirely on the agent itself running fagent agent status ... through its own Bash tool (see skill/SKILL.md). In OpenCode's plan mode (or any Claude Code mode without Bash), the agent has no way to invoke that command, so the workspace status gets stuck at whatever it was set to on fagent agent init.

The key insight that unblocks all three sub-questions: the existing session.start-style plugin (packages/fleet-ship/plugins/opencode.js) already proves that plugin/hook code runs outside the agent's own tool-permission sandbox. FleetAgentActivation calls fagent agent in-workspace via the host-provided $ regardless of what tools the LLM agent is currently allowed to use — because it's the OpenCode host process running that shell command, not the model invoking a "bash tool". The equivalent is true for Claude Code hooks: hook scripts (hooks/activate-fleet-skill.sh) are executed directly by the harness process, not gated by the model's own allowed-tools list. Plan mode (or a read-only Claude Code mode) restricts what the model can invoke, not what the harness's own lifecycle hooks can do.

So the fix for (1) isn't "give the plan-mode agent bash access to fagent" — it's "stop routing status updates through the agent's own tool calls, and instead drive them from host-side hooks that already have shell access unconditionally."

1. OpenCode access to fagent in plan mode / no-bash modes

Don't try to expose fagent as a tool the plan-mode agent must remember to call. Instead, move status transitions into the plugin itself, which already runs with full shell access independent of the agent's mode. Candidate OpenCode plugin hooks (in addition to the experimental.chat.system.transform already used):

• tool.execute.before / tool.execute.after — fires whenever the agent invokes any tool, in any mode (read tools are still tools). Use this to flip status to building (or verifying for test/build-looking tool names) the first time a tool executes after being idle/awaiting.
• event (subscribing to session-level events such as an idle/turn-complete event) or chat.message on assistant messages with no follow-up tool call — use this to flip to awaiting when the agent finishes a turn and is waiting on the user (covers plan-mode responses, which are exactly assistant messages with no tool calls).

Because these hooks run in the OpenCode host process, they work the same whether the active agent/mode allows Bash or not — solving (1) without needing the model to have Bash at all.

2. Improving the OpenCode plugin

Concrete additions to packages/fleet-ship/plugins/opencode.js:

• Track last-reported state in a module-level variable to avoid redundant fagent agent status calls (each one is a subprocess spawn).
• Add a tool.execute.before hook: on first tool call after idle/awaiting, call fagent agent status building -d "..." (or verifying if the tool/command looks like a test/build/lint run).
• Add a turn-completion signal (whatever OpenCode's SDK exposes for "assistant finished, no more tool calls queued") to call fagent agent status awaiting -d "...", mirroring the skill's current manual instruction ("before presenting any question or plan, switch to awaiting") but enforced by the host instead of trusted to the model.
• Keep the existing in-workspace guard (silent no-op outside a fleet workspace / without fagent on PATH) as the entry condition for all new hooks, same as today.
• This also fixes the general reliability problem beyond plan mode: today status is only as accurate as the model's discipline in following the skill's instructions. Host-driven hooks make status accurate even when the model forgets or gets distracted mid-task.

3. Improving the Claude Code plugin

Currently packages/fleet-ship/plugins/claude-code/hooks/hooks.json only wires SessionStart. Claude Code supports several other hook events that would let the plugin auto-track status the same way, all executed by the harness (so they work regardless of the model's current permission mode):

• PreToolUse (matcher on tool names, e.g. Bash|Edit|Write|MultiEdit) → call fagent agent status building/verifying similarly to the OpenCode tool.execute.before idea.
• Stop (fires when Claude finishes responding and is about to hand control back to the user) → call fagent agent status awaiting. This is the Claude Code analogue of "assistant message with no more tool calls" and directly covers the plan-mode / question-presenting case from the issue.
• Notification → could also map to awaiting for permission-prompt-style interruptions.

This mirrors the OpenCode design so both plugins converge on the same host-driven approach instead of depending on the skill instructions alone.

Suggested next step

This is a moderately-sized implementation (new hook scripts/plugin hooks, state-dedup logic, tests for each provider, doc updates in apps/docs/src/content/docs/guides/agent-integrations.md). I'd recommend confirming the exact current hook/event names for both OpenCode plugins and Claude Code hooks against their live docs before implementation, since I couldn't verify them here. Happy to implement the design above in a follow-up if you'd like — let me know if you want me to proceed or if the direction needs adjusting first.