[BUG] Subagent stalls or completes near artifact finalization without writing required Markdown report

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

```markdown
A general-purpose` subagent can run a long analysis task, reach the final artifact-writing stage, and then stop/return without producing the required Markdown file artifact.

In my workflow, the parent Claude Code session launched multiple parallel general-purpose agents. One reviewer/challenger-style agent was explicitly instructed to write a Markdown report file:

/workspace/.harness/features/<feature-id>/challenge-report.md
````

The report was required to contain sections such as:

```markdown
## Summary
## Critical Challenges
## Warnings
## Assumption Risks
## Overlooked Risks
## Recommended Mitigations

The subagent performed substantial repository analysis and reached an intermediate state equivalent to:

Now I have a thorough understanding of the codebase.
Let me write the challenge report.

However, the expected report file was not created.

After more than 30 minutes, the parent session resumed and reported something equivalent to:

All four parallel agents completed. Let me verify the outputs and proceed with semantic reconciliation.

The parent then verified the output directory and found that the challenger report was missing:

The challenger agent ran but didn't produce the file. Let me check and regenerate it.

The parent launched another general-purpose subagent to regenerate the missing report. That recovery subagent again performed many read/search operations and reached the same artifact-finalization point:

Bash(mkdir -p /workspace/.harness/features/<feature-id>)

At that point, the transcript still did not show a corresponding Write(...) call or shell redirection writing the requested challenge-report.md.

This should not happen. Claude Code appears to treat subagent lifecycle completion as if the task completed, even though the expected artifact was not produced.

In short:

agent lifecycle completed != task completed
task completed != artifact valid

````

What Should Happen?

If a subagent is explicitly instructed to write a required file artifact, and the parent session later treats that subagent as completed or returned, then one of the following should be true:

1. The requested file artifact exists and is valid;
2. The parent session receives a clear timeout, failure, or missing-artifact status;
3. The parent session receives enough final output to deterministically recover.

Claude Code should not report or imply successful completion for a subagent whose required output file was never created.

If the subagent reaches an intermediate state such as:

```text
Let me write the challenge report.
````

but never actually calls `Write(...)` or writes the target file, the parent session should receive a structured incomplete status such as:

```text
INCOMPLETE_RESULT
MISSING_ARTIFACT
TIMEOUT_WITHOUT_ARTIFACT

The parent/orchestrator should be able to distinguish subagent lifecycle completion from task/artifact completion.

````

Error Messages/Logs

The original subagent was explicitly instructed to write:

/workspace/.harness/features/<feature-id>/challenge-report.md

Required sections:

## Summary
## Critical Challenges
## Warnings
## Assumption Risks
## Overlooked Risks
## Recommended Mitigations

Observed parent-session output after the original subagent returned:

All four parallel agents completed. Let me verify the outputs and proceed with semantic reconciliation.

The challenger agent ran but didn't produce the file. Let me check and regenerate it.

Recovery subagent transcript reached the same finalization point:

Agent(Regenerate challenge-report.md for <anonymized feature>)
...
Read(...)
Bash(find ...)
Bash(grep ...)
Read(...)
Bash(mkdir -p /workspace/.harness/features/<feature-id>)

At this point, the transcript still did not show a corresponding Write(...) call or shell redirection writing:

/workspace/.harness/features/<feature-id>/challenge-report.md

In a similar run, a task notification marked the subagent as completed, but the returned result was only an intermediate planning sentence equivalent to:

Let me write the challenge report.

No final report content and no expected file artifact were produced.
`

Steps to Reproduce

````markdown

1. Start Claude Code CLI on a Linux workspace.

1. Use a prompt or command that launches multiple parallel general-purpose subagents from one parent session.

1. Give one subagent a reviewer/challenger-style task that requires producing a Markdown artifact, for example:

```text
You are a reviewer/challenger agent.
Analyze the assumptions and risks in this multi-repo workflow.
Write the output to:

/workspace/.harness/features/<feature-id>/challenge-report.md

The file must include:
## Summary
## Critical Challenges
## Warnings
## Assumption Risks
## Overlooked Risks
## Recommended Mitigations

````

1. Let the subagent perform repository analysis using Read, Bash(find ...), Bash(grep ...), and similar tools.

1. Observe that the subagent reaches an intermediate finalization state similar to:

``text
Now I have a thorough understanding of the codebase.
Let me write the challenge report.
``

1. Wait for the parent session to resume after the subagent stops, returns, or times out.

1. Observe that the parent may say something equivalent to:

``text
All four parallel agents completed. Let me verify the outputs and proceed with semantic reconciliation.
``

1. Check the expected output file:

``bash
test -s /workspace/.harness/features/<feature-id>/challenge-report.md
grep -q '^## Summary' /workspace/.harness/features/<feature-id>/challenge-report.md
grep -q '^## Critical Challenges' /workspace/.harness/features/<feature-id>/challenge-report.md
grep -q '^## Recommended Mitigations' /workspace/.harness/features/<feature-id>/challenge-report.md
``

1. The expected file is missing or incomplete even though the subagent lifecycle appears to have ended.

1. If the parent launches another subagent to regenerate the missing artifact, the recovery subagent may again reach the same finalization point:

``text
Bash(mkdir -p /workspace/.harness/features/<feature-id>)
``

without showing a corresponding Write(...) call for the target Markdown report.

````

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

Unknown / not applicable.

Claude Code Version

2.1.144 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

````markdown
This looks like a subagent finalization / artifact handoff problem rather than a filesystem permission issue.

The mkdir -p command itself is not the problem. The issue is that the subagent reaches the artifact-finalization stage, ensures the output directory exists, but does not reliably proceed to write the required Markdown report.

The parent session can later discover the missing artifact through filesystem validation, but by then the original subagent has already consumed significant wall-clock time and tokens.

This is especially problematic for multi-agent workflows where files are used as phase handoff artifacts. A parent/orchestrator session needs a reliable way to distinguish:

agent lifecycle completed != task completed
task completed != artifact valid
````

Suggested improvements:

* Distinguish `agent lifecycle completed` from `artifact/output completed`.
* If a subagent is instructed to write a file, verify that the file exists before surfacing the subagent as successfully completed.
* If the subagent exits or times out without producing the expected artifact, return a structured status such as `MISSING_ARTIFACT`, `INCOMPLETE_RESULT`, or `TIMEOUT_WITHOUT_ARTIFACT`.
* Do not return intermediate planning text such as `Let me write the report` as the completed result.
* Surface subagent finalization/timeout failures clearly to the parent session.

Related issues that appear similar but may not cover this exact artifact-contract case:

* #27281 — repeated “let me write the document” without executing the write
* #51343 — Task/Agent tool returns missing result when subagent completes work
* #37521 — agent/subagent freezes indefinitely on Opus 4.6
* #4462 — sub-agents claim file creation but files do not persist
* #4877 — missing tool result block in sub-agent workflow

Privacy note: all paths, feature names, repository names, and business/domain details in this report have been anonymized.