configure_debug_logging

Configure runtime log level and optional file logging for target.

Intended to be called once on the deepagents_code package logger; child module loggers reach the same handlers via propagation, so individual modules do not configure logging themselves.

DEEPAGENTS_CODE_LOG_LEVEL controls the package logger level independently of file logging. If it is unset, DEEPAGENTS_CODE_DEBUG=1 defaults to DEBUG; otherwise the runtime level defaults to INFO.

When DEEPAGENTS_CODE_DEBUG is truthy, a file handler is attached. The log file defaults to DEFAULT_DEBUG_FILE but can be overridden with DEEPAGENTS_CODE_DEBUG_FILE. The handler appends (mode='a') so logs are preserved across separate process runs. Calling this again with the same resolved path does not stack duplicate handlers: the existing tagged handler is reused and its level re-applied. If the resolved path changes, the stale handler is closed and replaced.

The file is created or tightened to user-only access first. If that fails, no file handler is attached: captured MCP server stderr can carry credentials, so no file log is safer than one that could not be secured.