feat: agents spec - #78

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/cli/agents_commands_test.go`:
- Around line 24-30: The tests calling withWorkingDir (e.g.,
TestExecCommandPassesSelectedAgentIntoWorkflowConfig) mutate the process-wide
working directory while marked t.Parallel(), causing racey failures; fix by
either removing t.Parallel() from any test that calls withWorkingDir (and the
other affected tests at the indicated ranges) or, better, change the helper and
command invocations to avoid os.Chdir: update withWorkingDir and any command
execution to set the working directory locally (use exec.Command.Dir or
equivalent) so tests can remain parallel-safe and no longer rely on process-wide
cwd.

In `@internal/cli/agents_commands.go`:
- Around line 62-65: The agents command group never registers the hidden
mcp-serve subcommand, so newMCPServeCommand() is defined but unreachable; add
newMCPServeCommand() to the cmd.AddCommand call in the same scope where
newAgentsListCommand() and newAgentsInspectCommand() are registered (i.e.,
include newMCPServeCommand() alongside the existing commands), ensuring any
required hidden flag/state set by newMCPServeCommand() remains unchanged.
- Around line 442-449: The helper optionalExistingPath currently returns "" for
any os.Stat error, hiding useful paths on permission errors or broken symlinks;
change it so it only returns "" when the path is blank or when os.Stat returns
an IsNotExist error (os.IsNotExist(err)); for any other non-nil error return the
original path so callers (e.g., agents inspect) can show the actual path and
surface the underlying failure; update function optionalExistingPath to use
os.IsNotExist(err) to distinguish the ENOENT case.

In `@internal/cli/reusable_agents_doc_examples_test.go`:
- Around line 17-20: Set HOME and XDG_CONFIG_HOME to isolated temp dirs before
running the CLI fixture so global agent discovery cannot influence resolution;
specifically, in the test(s) that create workspaceRoot and call
writeCLIWorkspaceConfig, copyCLIDocumentedAgentFixture("reviewer") and
withWorkingDir, create two temp dirs, set os.Setenv("HOME", tmpHome) and
os.Setenv("XDG_CONFIG_HOME", tmpXdg) before invoking the CLI actions, and
restore the original env values (defer reset) after the test; apply the same
change to the other similar test that uses the same sequence of
workspaceRoot/writeCLIWorkspaceConfig/copyCLIDocumentedAgentFixture/withWorkingDir
calls.

In `@internal/core/agent/client_test.go`:
- Around line 845-846: The test is flaky because req.McpServers vs
a.scenario.ExpectedNewSessionMCPServers can differ only by ordering of Env
slices; before the DeepEqual checks (for req.McpServers and the similar check at
871-872), normalize ordering deterministically by sorting each server's Env
slice and then sorting the server slice itself (e.g., by a stable key like
Host/Port or Name) so comparisons are order-insensitive; update the assertions
to compare these normalized copies of req.McpServers and
a.scenario.ExpectedNewSessionMCPServers (and the other pair) instead of the raw
values.

In `@internal/core/agent/client.go`:
- Around line 765-789: toACPMCPServers currently drops MCPServer entries with
nil Stdio, allowing invalid/partial MCP configurations to proceed; change it to
fail fast by returning an error when any src[i].Stdio == nil (include
identifying info such as index or server name from model.MCPServer in the error
message). Update the function signature from toACPMCPServers(src
[]model.MCPServer) []acp.McpServer to return ([]acp.McpServer, error) (or
perform equivalent upstream validation before calling it), and ensure callers
handle and propagate the error so create/resume rejects unsupported transports
instead of silently omitting them.

In `@internal/core/agents/agents_test.go`:
- Around line 14-506: Multiple standalone tests (e.g.,
TestDiscoverParsesValidAgentDefinition,
TestDiscoverRejectsReservedAndInvalidAgentNames,
TestDiscoverRejectsUnsupportedDeferredMetadataFields, etc.) must be converted to
a single table-driven test using t.Run("Should ...") subtests; refactor by
creating a TestDiscover (or consolidate within an existing TestDiscover*) that
defines a slice of cases (name, setup parameters like homeDir/workspaceRoot,
agent files via writeWorkspaceAgent/writeGlobalAgent, expected
catalog/Problems/assertions) and loops over them calling t.Run("Should
<behavior>", func(t *testing.T){ /* run per-case setup using newTestRegistry,
call registry.Discover, and perform the existing assertions */ }); reuse helpers
newTestRegistry, writeWorkspaceAgent, writeGlobalAgent, validAgentMarkdown, and
problemsByName to remove duplicated setup and preserve each original case's
assertions inside the corresponding subtest.

In `@internal/core/agents/agents.go`:
- Around line 212-219: The discovery currently aborts when r.globalAgentsRoot()
(called from Discover) fails, making workspace agent discovery unavailable;
change the logic so Discover treats failure to resolve the global root as
non-fatal: if r.globalAgentsRoot() returns an error, set globalCandidates and
globalProblems to empty (or nil) and proceed to call scanScope only when a valid
root is present, rather than returning the error; update the handling around
r.globalAgentsRoot(), scanScope, and the variables
globalCandidates/globalProblems so the Discover function continues discovering
workspace-local agents even when global lookup fails.

In `@internal/core/agents/execution.go`:
- Around line 109-145: The agent metadata is injected raw into the prompt tags
and can break framing or allow prompt injection; update buildAgentMetadataBlock,
buildAvailableAgentsBlock and formatDiscoveryCatalogEntry to escape/serialize
agent.Name, agent.Metadata.Title and agent.Metadata.Description before
concatenating into the XML-like blocks (e.g., JSON-serialize the strings or
escape control characters and angle-brackets/newlines), and use the escaped
values in the returned strings so tags like </agent_metadata> or newlines in
fields cannot break the host-owned prompt structure.

In `@internal/core/agents/mcpserver/server.go`:
- Around line 121-129: The loader function loadHostContextFromEnv currently
returns a zero HostContext when the reserved env var
reusableagents.RunAgentContextEnvVar is missing, causing fail-open behavior;
change loadHostContextFromEnv so that if lookupEnv reports the var absent or
blank it returns a non-nil error (with a clear message referencing the missing
COMPOZY_RUN_AGENT_CONTEXT) instead of HostContext{}, and ensure callers (e.g.,
server startup that may call RunStdio) propagate or handle that error (tests
should call RunStdio with an explicit HostContext to continue exercising the
server).

In `@internal/core/plan/prepare_test.go`:
- Around line 387-389: The test currently sets workspaceRoot and homeDir but
only overrides HOME, so ResolveExecutionContext may still read a pre-existing
XDG_CONFIG_HOME; create a separate temp dir (e.g., xdgConfigDir := t.TempDir())
and call t.Setenv("XDG_CONFIG_HOME", xdgConfigDir) alongside t.Setenv("HOME",
homeDir) (references: workspaceRoot, homeDir) to isolate config discovery and
prevent flaky catalog assertions.

In `@internal/core/run/exec/prompt_exec.go`:
- Around line 51-60: After writeStarted succeeds but buildMCPServers fails,
route the error through the same terminal-completion path by invoking
completeTurn (using state and cfg) with a failure result before returning;
specifically, in the buildMCPServers error branch (the call to
buildMCPServers(state.runArtifacts.RunID)), call completeTurn to mark the run as
completed/failed and persist the terminal state, then return
PreparedPromptResult{} with the original error — ensuring the branch mirrors the
execution-error handling rather than returning early and leaving a started run
hanging.

In `@internal/core/run/internal/acpshared/command_io.go`:
- Around line 125-136: The current call to emitReusableAgentSetupLifecycle (with
req.Context, req.RunJournal, req.Config.RunArtifacts.RunID, req.Job) aborts
setup on error by closing outFile/errFile, closing client, calling
releaseClient(), and returning the error; change this to best-effort: invoke
emitReusableAgentSetupLifecycle and if it returns an error, log a warning with
the error details but do NOT close outFile/errFile, do NOT close or release the
client, and do NOT return; allow the ACP session to continue (optionally spawn a
non-blocking retry/report task), so failures in telemetry emission degrade to
warnings instead of failing session startup.

In `@internal/core/run/internal/acpshared/reusable_agent_lifecycle.go`:
- Around line 159-177: The code is mutating h.nestedToolCalls before calling
submitReusableAgentLifecycle, which can leave the map out-of-sync if
runJournal.Submit fails; update handleNestedReusableAgentToolUse so it calls
submitReusableAgentLifecycle first and only inserts the nestedToolCalls entry
after the submit succeeds (or, alternatively, perform the insert then roll it
back if submit returns an error), and apply the same change to the analogous
block referenced at lines 219-223 (handleNestedReusableAgentToolResult deletion)
so deletions are performed only after a successful submit or are reverted on
submit failure; use the nestedToolCalls map, submitReusableAgentLifecycle,
handleNestedReusableAgentToolUse and handleNestedReusableAgentToolResult
identifiers to locate and update the logic.

In `@internal/core/run/internal/acpshared/session_handler.go`:
- Around line 109-112: The call to h.emitReusableAgentLifecycleFromUpdate after
h.applySessionUpdate must not abort the parent session on failure; instead,
catch the error from emitReusableAgentLifecycleFromUpdate, log a warning that
includes concrete failure modes (e.g., "decoding error", "submission error",
"journal hiccup") and relevant context (session id, update id), and continue
normal execution so the parent session stays healthy; update the code around
applySessionUpdate/emitReusableAgentLifecycleFromUpdate to handle the error
non-fatally (log + continue) rather than returning it.

In `@internal/core/run/internal/runshared/config.go`:
- Line 48: The Job.ReusableAgent field is declared but not propagated in
NewJobs, so Job.ReusableAgent remains nil for cloned jobs; update the
NewJobs/job cloning code that maps from the source "item" (the constructor
creating new Job instances) to copy item.ReusableAgent into the new
Job.ReusableAgent, performing a deep copy if ReusableAgent is a mutable struct
or contains pointers/slices (e.g., call a Clone/DeepCopy method or manually copy
nested fields) to avoid shared mutable state; ensure the new mapping uses the
exact symbol names Job.ReusableAgent, item.ReusableAgent and the
NewJobs/job-constructor function so downstream consumers receive an independent
copy.

In `@internal/setup/bundle.go`:
- Around line 35-38: The current code returns nil, err after calling
InstallBundledReusableAgents (successes, failures, err), discarding the
accumulated result of successful installs; instead populate or update the
existing result variable with the successes/failures and return that result
along with a wrapped error (preserving err) so partial phase-one results are
returned on phase-two failure; locate InstallBundledReusableAgents, the
successes/failures variables, and the result variable and change the return from
nil, err to return result, wrappedErr (using the project's error-wrapping
convention) so callers receive both the partial result and the error.

In `@internal/setup/install_test.go`:
- Around line 145-207: Both tests hardcode the expected number of bundled
reusable agents (6) and duplicate setup/assertion logic; change them to a single
table-driven test with two subtests ("preview" and "install") that share setup
and derive the expected roster dynamically from the source of truth for bundled
agents (e.g., call whichever function or variable your package exposes that
lists bundled reusable agents — reference PreviewBundledReusableAgentInstall and
InstallBundledReusableAgents to run the respective flows), assert len(results)
== len(bundledRoster) rather than == 6, and keep the existing per-item path
assertions (TargetPath and success.Path) inside the subtests. Ensure you replace
the two test functions
TestPreviewBundledReusableAgentInstallUsesGlobalCompozyAgentsDir and
TestInstallBundledReusableAgentsCopiesCouncilRosterIntoGlobalCompozyAgentsDir
with the consolidated table-driven t.Run structure and derive expected counts
from the bundled roster.

In `@internal/setup/reusable_agents.go`:
- Around line 121-141: The current install flow deletes/cleans the final target
(cleanAndCreateDirectory on targetPath) before copying, which can leave a
partial or missing agent if copyBundleDirectory fails; change the flow to create
a sibling temp directory (e.g., tempTarget := targetPath + ".tmp" or use
ioutil.TempDir in the same parent), call cleanAndCreateDirectory on that
tempTarget, then call copyBundleDirectory into tempTarget; if copy succeeds,
atomically replace the old installation by renaming tempTarget to targetPath
(os.Rename) and if it fails remove tempTarget and append the
ReusableAgentFailureItem with Error set to the copy error; ensure you still use
reusableAgent.Directory and bundledagents.FS for the copy and preserve existing
failure handling for cleanup and continue.

In `@pkg/compozy/events/kinds/reusable_agent.go`:
- Around line 48-53: The JSON tags on the ReusableAgent event struct currently
use `omitempty` for fields whose zero values are meaningful; remove `omitempty`
from NestedDepth, MaxNestedDepth, Success, and Blocked (fields named
NestedDepth, MaxNestedDepth, Success, Blocked in reusable_agent.go) so
zero/false values are preserved in serialized payloads; update the struct tags
to plain `json:"nested_depth"`, `json:"max_nested_depth"`, `json:"success"`, and
`json:"blocked"` and run tests/serialization checks to ensure downstream
consumers receive explicit zero/false values.

---

Outside diff comments:
In `@internal/core/run/exec/exec.go`:
- Around line 237-263: The persisted exec resume flow currently doesn't bind the
resolved reusable-agent identity to the run, allowing resumes with a different
agent; fix this by persisting the resolved agent identity/config at run start
and validating it on resume: when creating a new run, capture the resolved agent
info returned by reusableagents.ResolveExecutionContext (agentExecution) and
write a stable identifier/config snapshot into the run record (e.g., in
prepareExecRunState/state.writeStarted where runArtifacts/record are persisted);
then update validateExecResumeCompatibility to load and compare that persisted
agent identity/config from state.record against the current
ResolveExecutionContext result and return an error if they differ so
newExecRuntimeJob/resume cannot attach a different agent to an existing run.

In `@internal/setup/install.go`:
- Around line 268-305: copyBundleDirectory currently recreates files with fixed
0644 and directories with 0755, losing execute bits; fix by reading the source
file/directory mode via Stat on the opened bundle entry (use the existing
bundle.Open(current) / source.Stat() to get FileInfo.Mode()), then use that mode
when creating directories (os.MkdirAll(target, fi.Mode().Perm())) and when
creating files (os.OpenFile(target, os.O_CREATE|os.O_TRUNC|os.O_WRONLY,
fi.Mode().Perm())); also after copying, ensure the target file mode is set
(file.Chmod(fi.Mode().Perm()) if needed) so executable bits on source entries
are preserved (apply changes around the existing variables current, entry,
source, file inside copyBundleDirectory).

In `@pkg/compozy/events/docs_test.go`:
- Around line 11-56: The test TestEventsDocumentationEnumeratesAllPublicKinds
currently iterates over multiple EventKind values in a single test so a failure
aborts the rest; convert the loop so each EventKind is validated inside its own
subtest using t.Run with a descriptive name (e.g., the kind string), call
t.Parallel() at the start of each subtest, and perform the strings.Contains
check inside that subtest (keeping the same failure assertion but scoped to the
subtest) to ensure each kind is tested independently and in parallel.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/core/agents/agents.go`:
- Around line 157-159: The current loop returns fmt.Errorf("resolve agent %q:
%w", normalized, problem.Err) which unwraps only the inner error and loses the
richer Problem diagnostics; change the wrap to use the whole Problem value
(e.g., fmt.Errorf("resolve agent %q: %w", normalized, problem)) so callers
retain Problem.Error() context and unwrapping still works; update the return in
the loop that iterates c.Problems (where problem.Name == normalized) to wrap
problem instead of problem.Err.

In `@internal/core/agents/execution_test.go`:
- Around line 11-385: These tests use flat top-level test functions instead of
the repository standard table-driven subtests; refactor each
TestResolveExecutionContextAppliesRuntimePrecedence,
TestResolveExecutionContextAppliesAgentModelWhenModelFlagIsUnset,
TestResolveExecutionContextPublicWrapperCapturesBaseRuntimeBeforeOverrides,
TestExecutionContextSystemPromptUsesCanonicalOrder,
TestExecutionContextSystemPromptKeepsDiscoveryCatalogCompact,
TestExecutionContextSystemPromptEscapesHostOwnedMetadataBlocks,
TestExecutionContextSystemPromptFallsBackToBasePromptWhenNoAgentSelected, and
TestResolveExecutionContextPreservesExistingRuntimeWhenAgentOmitsField to wrap
their assertions inside t.Run("Should <behaviour>", func(t *testing.T){ ... })
(or a table of named cases with t.Run for multiple scenarios), preserving
existing setup and assertions but moving them into appropriately named subtests
so failures report the descriptive subtest name and conform to the repository
testing pattern.

In `@internal/core/agents/mcpserver/server_test.go`:
- Around line 78-99: The test uses NewServer() and HostContext{} which can pick
up real-agent files; make the failure-path hermetic by creating a temp workspace
and config dirs and wiring them into the server/runtime before invoking handler:
set the server's BaseRuntime.WorkspaceRoot to t.TempDir() (or otherwise point
BaseRuntime on the created temp dir) and set the environment variables HOME and
XDG_CONFIG_HOME to temp dirs (via t.TempDir()) before calling
server.runAgentTool(HostContext{}) and executing handler(context.Background(),
...), ensuring the real runner workspace/config cannot resolve a
"missing-agent".
- Around line 21-187: Convert the top-level tests into t.Run subtests with
"Should..." names: create a single Test... wrapper (e.g., TestServerBehaviors)
and move the bodies of TestLoadHostContextFromEnvParsesReservedPayload,
TestLoadHostContextFromEnvRejectsMissingPayload,
TestRunAgentToolMarksStructuredFailuresAsToolErrors,
TestNewServerAppliesOptionsAndDefaults,
TestLoadHostContextFromEnvUsesProcessEnvironment, and
TestServeStdioReturnsWhenContextIsCanceled into individual t.Run("Should ...",
func(t *testing.T){ ... }) blocks (keep t.Parallel() where used), rename each
subtest description to start with "Should" (e.g., "Should parse reserved payload
from env"), and remove the original top-level TestXxx functions so the file uses
the required subtest pattern while preserving all assertions and helper setup
(e.g., stdioSwapMu, ServeStdio, LoadHostContextFromEnv, NewServer,
runAgentTool).

In `@internal/core/run/exec/prompt_exec.go`:
- Around line 81-86: The current logic calls executeExecJob and then
state.completeTurn(result) but if both completeTurn and result.err are non-nil
it returns only result.err, hiding the persistence failure; change the control
flow in the block around executeExecJob / state.completeTurn so you capture the
error returned by state.completeTurn (e.g., errComplete :=
state.completeTurn(result)) and if errComplete != nil return
buildPreparedPromptResult(state, result), errComplete (before returning
result.err), otherwise proceed to return result.err if present or the successful
value; this ensures state.completeTurn failures (persistence/terminal-state
errors) are surfaced instead of being masked by result.err.

In `@pkg/compozy/events/kinds/reusable_agent_test.go`:
- Around line 9-36: The test
TestReusableAgentLifecyclePayloadJSONPreservesMeaningfulZeroValues should be
converted to a table-driven test with subtests using t.Run("Should ...") and
t.Parallel() called inside each subtest: create a slice of cases (with name and
payload), iterate cases and call t.Run(caseName, func(t *testing.T){
t.Parallel(); marshal the case.payload, assert the JSON contains the expected
fields like `"nested_depth":0`, `"max_nested_depth":0`, `"success":false`,
`"blocked":false` and use t.Fatalf on errors }), keeping the same assertions and
referencing ReusableAgentLifecyclePayload and
ReusableAgentLifecycleStageNestedCompleted to locate the payload construction.

---

Nitpick comments:
In `@internal/core/run/internal/acpshared/reusable_agent_lifecycle.go`:
- Around line 248-264: decodeRunAgentToolInput and decodeRunAgentToolResult
currently swallow json.Unmarshal errors; update both functions to log the
unmarshal error at debug level when json.Unmarshal(raw, &payload) fails (while
keeping the current continue behavior) so malformed block.Input or
block.RawInput are recorded for troubleshooting; reference the functions
decodeRunAgentToolInput/decodeRunAgentToolResult and the variables block.Input,
block.RawInput and payload when adding a debug log call that includes the error
and some context (e.g., which raw field failed).
- Around line 96-98: Remove the defensive fallback that sets ctx =
context.Background() when ctx is nil; instead validate the incoming ctx variable
and fail fast by returning an explicit error (e.g., return fmt.Errorf("nil
context passed to <functionName>") ) or by propagating an error up the call
chain from the function that currently contains the check (replace the current
block that uses ctx and context.Background()). Update the function signature to
return an error if needed and update its callers to provide a non-nil context
(or handle the returned error), so nil contexts surface as bugs rather than
being silently replaced by context.Background().

In `@internal/setup/reusable_agents.go`:
- Around line 221-225: The cleanup call to removeReusableAgentPath(backupPath)
can fail after the new agent is already installed to targetPath, causing the
function to return an error and incorrectly signal install failure; change this
to log the cleanup failure instead of returning it (or aggregate cleanup errors
separately) so the function returns nil on successful install—specifically, in
the block that calls removeReusableAgentPath(backupPath) avoid returning
fmt.Errorf on error and instead call the appropriate logger with context about
backupPath and continue, or append the cleanup error to a separate variable that
does not affect the install success return.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/core/agents/mcpserver/server_test.go`:
- Around line 158-190: The test currently redirects stdout to a pipe but never
consumes stdoutRead, which can cause ServeStdio to block on writes; spawn a
background goroutine that calls io.ReadAll(stdoutRead) (or otherwise
continuously drains stdoutRead) immediately after creating the pipe and before
calling ServeStdio so the pipe buffer can't fill and block the server; reference
stdoutRead/stdoutWrite and ServeStdio(ctx, HostContext{}) when adding the drain
goroutine and ensure it runs until stdoutWrite is closed.

In `@internal/core/run/exec/exec_test.go`:
- Around line 20-205: Combine the related validation cases in
TestExecutePreparedPromptValidatesInputs into a table-driven set of subtests
using t.Run("Should ...") (e.g., "Should error when config is nil", "Should
error when prompt is empty") that call ExecutePreparedPrompt and assert specific
errors using ErrorContains/ErrorAs or errors.Is/strings.Contains rather than
only checking err == nil; update other tests that currently do weak assertions
to similarly assert the expected error type/message. Also fix the helper
preparedPromptTextContentBlock to call t.Helper() and replace any panic(err)
with t.Fatalf to surface failures via the testing.T; use the function names
ExecutePreparedPrompt, TestExecutePreparedPromptValidatesInputs, and
preparedPromptTextContentBlock to locate the changes. Ensure each subtest uses
t.Parallel appropriately and preserves existing setup/cleanup semantics.

In `@internal/core/run/exec/prompt_exec.go`:
- Around line 64-67: The current branch in prompt_exec.go returns only
completeErr when both err (the MCP-builder failure) and completeErr (the
completion failure from state.completeTurn) exist and differ, which masks the
original err; change the return to preserve both errors using errors.Join(err,
completeErr) (or errors.Join(completeErr, err)) so callers see both failures,
keeping the same returned prepared result from buildPreparedPromptResult(state,
failure) and referencing state.completeTurn, buildPreparedPromptResult, err and
completeErr to locate the code to update.

---

Duplicate comments:
In `@internal/core/agents/mcpserver/server_test.go`:
- Around line 21-192: The tests are top-level functions and must be converted to
subtests using the t.Run("Should ...") pattern; replace each Test... function
(TestLoadHostContextFromEnvParsesReservedPayload,
TestLoadHostContextFromEnvRejectsMissingPayload,
TestRunAgentToolMarksStructuredFailuresAsToolErrors,
TestNewServerAppliesOptionsAndDefaults,
TestLoadHostContextFromEnvUsesProcessEnvironment,
TestServeStdioReturnsWhenContextIsCanceled) with a single top-level TestServer
(or similar) that contains t.Run("Should parse reserved payload", ...),
t.Run("Should reject missing payload", ...), t.Run("Should mark structured
failures as tool errors", ...), etc., moving each function body into its
corresponding subtest and preserving behavior including t.Parallel() inside each
subtest where applicable and keeping references to functions/types like
loadHostContextFromEnv, LoadHostContextFromEnv, NewServer, server.runAgentTool,
ServeStdio, reusableagents.RunAgentContextEnvVar, and others so tests still call
the same code paths.

---

Nitpick comments:
In `@internal/core/run/exec/exec_test.go`:
- Around line 459-466: preparedPromptTextContentBlock currently panics on
json.Marshal errors; change it into a test helper that accepts t *testing.T,
call t.Helper() at the top, and use t.Fatalf (or t.Fatalf with the marshal
error) instead of panic to fail the test with proper attribution; update all
call sites that invoked preparedPromptTextContentBlock(text) to pass the
testing.T (e.g., preparedPromptTextContentBlock(t, text)) and adjust imports if
needed.

In `@internal/core/run/exec/prompt_exec.go`:
- Around line 42-43: The code currently returns raw errors from calls like
agent.EnsureAvailable(ctx, cfg) and other branches returning
PreparedPromptResult{}, which makes diagnostics hard; update each return that
directly forwards err (including the EnsureAvailable call and the other branches
around the Prepare/execute logic referenced in the diff) to wrap the error with
operation context using fmt.Errorf("failed to ensure agent available: %w", err)
(and similar contextual messages for the other operations), e.g., replace
returns of the form `return PreparedPromptResult{}, err` with `return
PreparedPromptResult{}, fmt.Errorf("<operation description>: %w", err)` so
callers get wrapped errors with clear context.