refactor(agent): consolidate Agent model - Phase 1 complete

[yinwm]

Summary

This PR consolidates the Agent refactor from the refactor/agent branch into main. It represents the completion of Phase 1 of the Agent refactor tracked in #1216.

Core Implementations

Module	Files	Description
Agent abstraction	pkg/agent/definition.go	AGENT.md format with YAML frontmatter, backward compatible with AGENTS.md
AgentLoop	pkg/agent/loop.go, pkg/agent/turn.go	Lifecycle management, input/output boundaries, panic recovery
Event model	pkg/agent/eventbus.go, pkg/agent/events.go	18 event types for observability
Context management	pkg/agent/context.go, pkg/agent/context_budget.go	Boundary detection, proactive budget check, safe compression
Hooks	pkg/agent/hooks.go, pkg/agent/hook_*.go	Event-driven hook system
Steering	pkg/agent/steering.go	Scoped steering injection
SubTurn	pkg/agent/subturn.go	Subagent coordination with concurrency control

Workspace Changes

• AGENTS.md → AGENT.md (new format with YAML frontmatter)
• IDENTITY.md removed (consolidated into AGENT.md)
• SOUL.md, USER.md updated for new format

Documentation

• docs/agent-refactor/README.md
• docs/agent-refactor/context.md
• docs/hooks/README.md, docs/hooks/README.zh.md
• docs/steering.md
• docs/subturn.md

Merged PRs

• Feat/agent eventbus #1822 — EventBus
• Refactor/agent loop #1827 — Agent Loop
• feat(agent): steering #1517 — Steering
• Feat/issue 1218 agent md context structure #1705 — AGENT.md YAML frontmatter
• refactor(agent): context boundary detection, proactive budget check, and safe compression #1490 — Context boundary detection
• fix(agent) scope steering #1844 — Scoped Steering
• Feat/hook manager #1863 — Hook Manager
• feat(agent): subturn #1636 — SubTurn

Additional Changes

• Merged main into refactor/agent to include recent updates:
  • WeChat channel (pkg/channels/weixin/)
  • QQ audio duration handling
  • Frontend fixes
• Fixed flaky gateway tests (TestGatewayStatusReturnsRestartingDuringRestartGap, TestGatewayRestartReturnsErrorStatusWhenReplacementFailsToStart)

Tracking

Resolves #1316
Refs #1216

Remaining Work (Phase 2)

The following tasks have code implemented but need specification documentation:

• Persona / identity assembly rules documentation
• Subagent coordination rules documentation

Test plan

• All existing tests pass
• Gateway test flakiness fixed
• Agent package tests cover new functionality

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Consolidates Phase 1 of the Agent refactor into main, introducing a structured Agent definition format, an event-driven hook system (in-process + stdio JSON-RPC), and expanded observability/interruptibility primitives (steering, active turn tracking, SubTurn).

Changes:

• Add hooks configuration + auto-mounting (builtins + external process hooks) with defaults and tests.
• Introduce turn state tracking / steering improvements and new /subagents command for runtime observability.
• Update Agent definition loading to support AGENT.md YAML frontmatter with legacy fallback, plus new context budget utilities/docs.

Reviewed changes

Copilot reviewed 43 out of 64 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
pkg/config/config_test.go	Adds default + load tests for new hooks config surface.
pkg/config/config.go	Introduces HooksConfig, SubTurn defaults, steering mode, and context window settings.
pkg/commands/runtime.go	Extends runtime interface to expose active turn info to commands.
pkg/commands/cmd_subagents.go	Adds /subagents command for viewing active subagent activity.
pkg/commands/builtin.go	Registers the new subagents built-in command.
pkg/agent/turn.go	Adds active turn tracking + SubTurn-related state helpers, finishing/abort behavior.
pkg/agent/steering.go	Implements scoped steering queues, Continue(), and hard abort behavior.
pkg/agent/loop_test.go	Updates context exhaustion test assumptions re: session history composition.
pkg/agent/instance.go	Separates ContextWindow from MaxTokens with a default heuristic.
pkg/agent/hooks_test.go	Adds tests for in-process hook observation and interception.
pkg/agent/hook_process_test.go	Adds integration tests for stdio JSON-RPC process hooks.
pkg/agent/hook_process.go	Implements stdio JSON-RPC process hook client and mounting.
pkg/agent/hook_mount_test.go	Adds tests for config-driven auto-mounting of builtin/process hooks.
pkg/agent/hook_mount.go	Adds hook registry + config-driven auto-mount + env/observe validation helpers.
pkg/agent/events.go	Defines structured event kinds + payload types for observability.
pkg/agent/eventbus.go	Adds lightweight fan-out event bus with dropped-event metrics.
pkg/agent/definition_test.go	Adds tests for AGENT.md frontmatter parsing and legacy fallback behavior.
pkg/agent/definition.go	Implements AGENT.md YAML frontmatter parsing + tracked paths for cache invalidation.
pkg/agent/context_cache_test.go	Updates cache tests to use AGENT.md instead of IDENTITY.md.
pkg/agent/context_budget.go	Adds context budget estimation + safe turn-boundary compression helpers.
pkg/agent/context.go	Updates bootstrap loading + cache invalidation to follow new agent definition model.
docs/subturn.md	Documents SubTurn semantics, lifecycle, events, and operational constraints.
docs/steering.md	Documents scoped steering queues, Continue(), and interrupt behavior.
docs/design/steering-spec.md	Design spec for steering queue, bus drain, and loop integration.
docs/design/hook-system-design.zh.md	Chinese design doc for hook system layering and IPC strategy.
docs/agent-refactor/context.md	Documents context budgeting, compression paths, and token estimation model.
config/config.example.json	Adds context_window and hooks example configuration.
cmd/picoclaw/internal/onboard/helpers_test.go	Updates onboarding tests for structured agent bootstrap files.
README.zh.md	Updates README content but currently contains unresolved merge conflict markers.
README.vi.md	Updates README content but currently contains unresolved merge conflict markers.
README.pt-br.md	Updates README content but currently contains unresolved merge conflict markers.
README.fr.md	Updates README content but currently contains unresolved merge conflict markers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

activeTurnStates is keyed by sessionKey in registerActiveTurn, but hard-abort cascading here looks up children by childID (which appears to be a turn ID). This makes cascading abort unreliable (children won't be found, or the wrong entry could be finished). Align the keying strategy (e.g., store turnStates by turnID for all turns, or keep a separate map for turnID → turnState, or ensure childTurnIDs stores the same key used in activeTurnStates).

Suggested change

	ts.mu.RLock()
	children := append([]string(nil), ts.childTurnIDs...)
	ts.mu.RUnlock()
	for _, childID := range children {
	if val, ok := ts.al.activeTurnStates.Load(childID); ok {
	val.(*turnState).Finish(true)
	}
	}
	// We don't rely on the key type of activeTurnStates (which may be session keys);
	// instead, we find children by their parentTurnState pointer.
	ts.al.activeTurnStates.Range(func(_ any, value any) bool {
	childTS, ok := value.(*turnState)
	if !ok {
	return true
	}
	if childTS.parentTurnState == ts {
	childTS.Finish(true)
	}
	return true
	})

[Copilot]

Continue() currently refuses to run if any active turn exists (since GetActiveTurn() returns the first active turn found). In the new architecture that supports multiple concurrent turns, this can incorrectly block Continue() for an idle session if another session is still active. Consider checking activity for the requested session scope (e.g., GetActiveTurnBySession(sessionKey) or getActiveTurnState(sessionKey)) instead of a global 'any active turn' check.

Suggested change

	if active := al.GetActiveTurn(); active != nil {
	if active := al.GetActiveTurnBySession(sessionKey); active != nil {

[Copilot]

This exported API returns an unexported concrete type (*turnState). That makes the API awkward for external packages and tightly couples them to internal implementation details. Prefer returning an exported interface (e.g., TurnState with only the safe methods) or an exported struct snapshot type, and keep turnState unexported.

[Copilot]

Returning any here forces command handlers to use type assertions and makes the runtime contract ambiguous. A maintainable alternative is to define a small shared struct/interface in pkg/commands (or a tiny pkg/runtime/pkg/observer package) that both commands and agent can depend on without circular imports (e.g., type ActiveTurnView struct { ... } or type ActiveTurnProvider interface { ActiveTurnTree() (string, bool) }).

[Copilot]

Spawning a goroutine per outbound message can become costly under high event/intercept rates, and if ctx is canceled while stdin.Write blocks, the goroutine may linger until the write unblocks. Consider a single dedicated writer goroutine with a buffered channel (or reuse the existing writeMu and perform a direct write with bounded timeouts at higher call sites), so cancellation doesn't create unbounded goroutines.

Suggested change

	done := make(chan error, 1)
	go func() {
	_, writeErr := ph.stdin.Write(body)
	done <- writeErr
	}()
	select {
	case err := <-done:
	if err != nil {
	return fmt.Errorf("write process hook %q message: %w", ph.name, err)
	}
	return nil
	case <-ctx.Done():
	return ctx.Err()
	}
	if _, err := ph.stdin.Write(body); err != nil {
	return fmt.Errorf("write process hook %q message: %w", ph.name, err)
	}
	return nil

[Copilot]

The file contains unresolved Git merge conflict markers (<<<<<<<, =======, >>>>>>>). Resolve the conflicts and remove all markers.

Suggested change

=======

[Copilot]

The file contains unresolved Git merge conflict markers (<<<<<<<, =======, >>>>>>>). Resolve the conflicts and remove all markers.

Suggested change

>>>>>>> refactor/agent

[Copilot]

The file contains unresolved Git merge conflict markers (<<<<<<<, =======, >>>>>>>). Resolve conflicts and remove all markers prior to merge.

Suggested change

<<<<<<< HEAD

[Copilot]

The file contains unresolved Git merge conflict markers (<<<<<<<, =======, >>>>>>>). Resolve conflicts and remove all markers prior to merge.

Suggested change

=======

[Copilot]

The file contains unresolved Git merge conflict markers (<<<<<<<, =======, >>>>>>>). Resolve conflicts and remove all markers prior to merge.

Suggested change

>>>>>>> refactor/agent