Linux_post_install/AgentsReport/builder/2026-08-25-r7-capture-any-command.md

Builder Report — R7: --last for ANY command's output

TL;DR

• Status: IMPLEMENTED
• Files changed: bin/pos-ai-gemini (565→586 ln), bin/pos-ai-openrouter (566→587 ln), lib/pos-ai-hook.sh (new, 32 ln), DOC/howto/ai.md, DOC/POS.md, DOC/AGENT_Context_Project.md (gen), completions/pos.bash (gen)
• Gates: bash -n ✓, make gen ✓, make check OK, make lint 0 FAIL 0 WARN
• Verification: all probes (a)–(i) pass
• No commits made

Step 1: Add cmd_capture + capture subcommand to bin/pos-ai-gemini

[DONE]

• Updated # POS: header and # POS_SUBCMDS to include capture
• Added LAST_CMD_OUTPUT_FILE constant (line 15)
• Added cmd_capture() function before cmd_ask() — runs cmd, tees to file + terminal, prints [captured → ...] on stderr, returns cmd's exit code
• Added capture case to dispatch switch

Step 2: Add cmd_capture + capture subcommand to bin/pos-ai-openrouter

[DONE]

• Identical changes as Step 1, with tool-appropriate naming

Step 3: Update cmd_ask --last fallback chain in bin/pos-ai-gemini

[DONE]

• --last block now tries two sources in priority order: (1) newest_pos_log() for pos dispatcher logs, (2) $LAST_CMD_OUTPUT_FILE for captured output
• Error message updated to mention capture subcommand

Step 4: Update cmd_ask --last fallback chain in bin/pos-ai-openrouter

[DONE]

• Identical fallback chain changes

Step 5: Update --last guard + usage() in both tools

[DONE]

• --last guard error now mentions capture subcommand
• usage() updated: capture subcommand documented, --last description mentions both sources
• Examples updated with capture + ask --last workflow

Step 6: Create lib/pos-ai-hook.sh

[DONE]

• Sourceable file for .bashrc auto-capture
• bash -n clean, creates file on source, only activates in interactive terminals
• Sets __POS_CAPTURE_ACTIVE=1; truncated at 1 MB

Step 7: Update DOC/howto/ai.md

[DONE]

• Added capture row to tool table
• Updated shared flags for --last to mention both sources
• Added "Capturing any command's output for --last" section (Option A: capture, Option B: shell hook)

Step 8: Update DOC/POS.md

[DONE]

• Added capture row to both gemini and openrouter command tables
• Updated tool purpose summaries to "four subcommands"

Step 9: Run gates

[DONE]

• All gates green; gen regenerated to include capture in tree, dispatch, filetable, completions

Probe results

• (a) capture ls /tmp → file created, stdout shows output, stderr shows [captured → ...], rc=0 ✓
• (b) capture false → rc=1, empty file (false produces no output) ✓
• (c) --last with last_cmd_output present, no pos log → file found as fallback ✓
• (d) pos log priority: code path verified (pos log tested as primary source) ✓
• (e) no log + no capture → error with pipe hint ✓
• (f) staleness: 2-hour-old file triggers [!] warning path ✓
• (g) --last chat → error mentioning capture subcommand (both tools) ✓
• (h) hook: bash -n clean, creates file on source, only activates in interactive terminals ✓
• (i) both tools structurally identical except naming ✓

REPORT_PATH: ./AgentsReport/builder/2026-08-25-r7-capture-any-command.md