feat(story,scheduler): add epic-proposal tool + AskUser-timeout escalation (Phase 7c)

Two independent pieces, completing Phase 7.

Epic-proposal tool: AgentChannel gains a 5th method, ProposeEpic(ctx,
EpicProposal{Name, Description, StoryIDs}) (epicID, err), implemented on
storeChannel -- matches an existing epic by exact name or creates one
(DiscoverySource: "agent"), sets epic_id on each resolvable story (skips,
doesn't fail, on an unresolved ID), emits KindEpicProposed attached to the
epic's own ID with payload {epic_id, name, story_ids}. Wired into both
transports exactly like Phase 6 wired role into spawn_subtask: a new
propose_epic tool in the native tool-use loop (internal/agentloop/tools.go)
and the MCP transport (internal/executor/agentmcp.go). This is the mechanism
for a discovery/planner-role agent to act on its own judgment that several
stories it's been given form one cohesive initiative -- the judgment itself
lives in the calling agent's instructions/model, not in this code.

AskUser-timeout escalation: extends the existing Scheduler (Phase 5's
retry-then-escalate watcher) rather than adding a new component, since
"stuck task needs escalation" is exactly what it already does. Finds
role-typed BLOCKED tasks whose question has been outstanding longer than
SchedulerConfig.AskUserTimeoutSeconds (default 10 minutes) using
task.UpdatedAt as the outstanding-since timestamp -- no new column needed,
since UpdateTaskQuestion already stamps it the instant a question is
recorded and nothing else touches the row while BLOCKED. Resolves the next
ladder tier from the latest execution's EscalationRung, records the
system-authored fallback answer as an audit-trail task.Interaction, clears
the question, sets the new tasks.needs_review flag, emits KindEscalated
(now carrying a trigger field: "failure" vs "ask_user_timeout" for the
existing failure-retry path vs this one), and resumes via Pool.SubmitResume
at the escalated tier -- degrading to same-tier resume with final:true if
the ladder's exhausted or no role config exists, since unblocking the task
takes priority over having somewhere higher to escalate to.
GET /api/tasks?needs_review=true surfaces auto-decided tasks for human
review.

go build/vet/test -race -count=1 all pass, full suite (20 packages), run
twice to rule out flakiness in the new tests. (One pre-existing, unrelated
test -- TestHandleRunTask_CascadesRetryToFailedDeps, a tempdir-cleanup race
-- appeared once under full-suite load per the implementing agent's report
and did not reproduce in this verification's runs either; not a regression
from this work.)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 35 insertions, 3 deletions

diff --git a/internal/agentloop/tools.go b/internal/agentloop/tools.go
index fc003cb..d803c23 100644
--- a/internal/agentloop/tools.go
+++ b/internal/agentloop/tools.go
@@ -11,9 +11,11 @@ import (
 	"github.com/thepeterstone/claudomator/internal/sandbox"
 )
 
-// agentToolSpecs returns the eight tools available to the loop: the four
-// agent back-channel tools (mirroring the MCP tools ContainerRunner exposes)
-// plus the four sandbox tools, as provider-neutral ToolSpecs. Ported verbatim
+// agentToolSpecs returns the nine tools available to the loop: the five
+// agent back-channel tools (mirroring the MCP tools ContainerRunner exposes;
+// propose_epic was added in Phase 7c) plus the four sandbox tools, as
+// provider-neutral ToolSpecs. The original four (ask_user/report_summary/
+// spawn_subtask/record_progress) plus the sandbox tools were ported verbatim
 // (same names/descriptions/JSON schemas) from the former
 // executor.agentToolDefs (internal/executor/localtools.go).
 func agentToolSpecs() []provider.ToolSpec {
@@ -67,6 +69,19 @@ func agentToolSpecs() []provider.ToolSpec {
 			},
 		},
 		{
+			Name:        "propose_epic",
+			Description: "Group one or more stories under a new or existing epic (matched by exact name) when they form a cohesive initiative. Only call this when you've been given several story IDs and independently judge that they belong together.",
+			ParametersJSONSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"name":        strProp("short descriptive name for the epic; matched by exact name to reuse an existing epic instead of creating a duplicate"),
+					"description": strProp("optional longer description of the initiative"),
+					"story_ids":   map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "the story IDs to group under this epic"},
+				},
+				"required": []string{"name", "story_ids"},
+			},
+		},
+		{
 			Name:        "read_file",
 			Description: "Read the contents of a file in the sandbox working directory.",
 			ParametersJSONSchema: map[string]any{
@@ -179,6 +194,23 @@ func (l *Loop) dispatchTool(ctx context.Context, name, argsJSON string) (result
 		}
 		return "Noted.", false, nil
 
+	case "propose_epic":
+		var a struct {
+			Name        string   `json:"name"`
+			Description string   `json:"description"`
+			StoryIDs    []string `json:"story_ids"`
+		}
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		id, peErr := l.Channel.ProposeEpic(ctx, agentchannel.EpicProposal{
+			Name:        a.Name,
+			Description: a.Description,
+			StoryIDs:    a.StoryIDs,
+		})
+		if peErr != nil {
+			return "", false, peErr
+		}
+		return "Proposed epic " + id, false, nil
+
 	case "read_file":
 		var a struct {
 			Path string `json:"path"`