Document harness safety and first-run push-back

Merged
YO
3d ago
+84-3

Summary

Closes dagucloud/dagu#3616 and dagucloud/dagu#3617.

The reference pages behind the Agent Loops guides were missing three things that real agent runs turned up.

  • Model output in shell commands (quoting page): which run positions are unsafe, with env as the fix, and what dagu validate now warns about.
  • Agent configuration on the host (harness page): agent CLIs load the personal config of the account running Dagu. It covers a dedicated account, setting_sources, and CODEX_HOME, and warns that Claude Code's bare flag cannot use a subscription login, per claude --help.
  • Push-back on a first run (human-in-the-loop, harness, and outer-loop pages): a step first running after a push-back keeps its prompt, and reads the feedback only from its environment.

The inner-loop page also gains a line on the repeat count in dagu status.

Merge order

This describes behaviour in dagucloud/dagu#3619, #3620, and #3621, so it should merge after them.

Verification

  • pnpm validate:examples with a build of those branches, and pnpm build.
  • The unsafe run table was tested with a stub agent, for each position and payload.
  • CODEX_HOME was tested with a real Codex run, with auth.json linked into a separate directory. setting_sources was tested with a real Claude Code run. The harness page states only that it leaves out user settings, because I could not confirm that it also excludes a global CLAUDE.md.

Summary by cubic

Documents three gaps real agent runs surfaced in the agent loop reference pages, and follows two product changes.

Changes

  • Quoting page: no way of quoting model output in run is safe; pass it through env and read it per context — "$SUMMARY" only in a local POSIX/Nix shell, printenv in containers, and the language API under other interpreters. NUL bytes cannot go through env, and dagu validate warns on model output in shell commands, except for validation-limited fields. Links the loop pages to this guidance.
  • Harness page: agent CLIs load the personal config of the account running Dagu; narrow it with setting_sources or CODEX_HOME, and note Claude Code's bare flag can't use a subscription login.
  • Loop pages and human-in-the-loop: a step first running after a push-back keeps its prompt and reads feedback only from its environment; reference it in the prompt when the model needs it.
  • Inner-loop page: dagu status shows the repeat count.

This describes behavior in dagucloud/dagu#3619, #3620, and #3621, so it should merge after them.

Summary by CodeRabbit

  • Documentation
    • Clarified how dagu status reports repeat-step attempts and how push-back feedback is provided to steps that run afterward.
    • Added guidance on configuring built-in CLI agents, including which settings and authentication methods they use.
    • Expanded shell-safety guidance for model-generated output, with an example using environment variables. Documented when dagu validate warns about model-generated values used in shell commands.