polyctl 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,120 @@
1
+ {
2
+ "id": "antigravity",
3
+ "name": "Antigravity CLI (agy)",
4
+ "project_config": [".agents", ".gemini", "AGENTS.md", "GEMINI.md"],
5
+ "verified": "full",
6
+ "verified_version": "agy 1.3.0 for print, its result record and a resume; agy 1.4.0 and 1.4.2 for the reviewer agent and the record it returns",
7
+ "actor_name": "agy",
8
+ "family": "google",
9
+ "models": {
10
+ "default": "gemini-4-argon-high",
11
+ "review": "gemini-4-argon-high",
12
+ "_note": "polyctl init --profile and the reviewer default read these; change here when Google ships new ids"
13
+ },
14
+ "observation_mode": "call-return",
15
+ "notes": "Verified against a running install, agy 1.1.19; print, the result record and a resume by conversation id measured again on agy 1.3.0 on 2026-10-06; print and its result record measured again on agy 1.4.0 and 1.4.2 on 2026-10-18, where a resume was not asked. Keeps no local transcript we could find; instead every print-mode call returns a complete JSON record including the conversation id and full token accounting. The orchestrator persists that record itself, so observation and telemetry are better here than with a passive store — at the cost of only seeing turns it started.",
16
+
17
+ "syntax_warning": "Go-style flags: the prompt must be ATTACHED to the flag. `agy --print='...'` works; `agy -p '...'` silently takes the next argument as the flag value and drops the prompt. A space-separated form fails without writing anything, which looks exactly like the agent doing nothing.",
18
+
19
+ "detect": { "headless": ["--print"] },
20
+
21
+ "send": {
22
+ "argv": ["agy", "--print={prompt}", "--output-format=json"],
23
+ "cwd_matters": true
24
+ },
25
+ "resume": {
26
+ "argv": ["agy", "--conversation={session}", "--print={prompt}", "--output-format=json"],
27
+ "continue_last": ["agy", "--continue", "--print={prompt}", "--output-format=json"]
28
+ },
29
+
30
+ "options": {
31
+ "trust_none": [],
32
+ "trust_none_why": "no flag denies tools - --dangerously-skip-permissions only widens them - so a reviewer runs as an agent of polyctl's own that only reads, options.reviewer_agent",
33
+ "reviewer_agent": {
34
+ "argv": ["--agent={agent}"],
35
+ "release": "1.4",
36
+ "path": ".agents/agents/{agent}.md",
37
+ "format": "frontmatter",
38
+ "config": {
39
+ "name": "{agent}",
40
+ "description": "polyctl's reviewer: it reads, and has no tool that writes or runs a command",
41
+ "mainAgent": true,
42
+ "subagent": false,
43
+ "commandExecutionPolicy": "off",
44
+ "mcpServers": [],
45
+ "tools": ["view_file", "grep_search", "find_by_name", "list_dir"]
46
+ },
47
+ "body": "You review what the prompt hands you. You read files and write nothing, and you run nothing.",
48
+ "settings": {
49
+ "path": "~/.gemini/antigravity-cli/settings.json",
50
+ "allow": ["permissions", "allow"],
51
+ "reads": ["read_file("],
52
+ "why": "an agent's tools leave out the servers the person's own MCP settings attach, and a print run denies a call to one only because no rule allows it"
53
+ },
54
+ "note": "Measured on agy 1.3.0, 2026-10-06. A print run denies every write and command it cannot ask about, and ends with an empty response and the action in denied_actions. Run as this agent it read the file it was asked to and had no tool to write a file or run a command, and wrote nothing. The person's MCP servers stay attached, Linear's writing tools among them, and a call to one was denied only by that headless rule; excludeDefaultComponents took them away but denied every read too, and --mode=plan changed neither. So polyctl refuses the reviewer while the person's settings allow more than reading. Measured again on agy 1.4.0 and again on 1.4.2 the same day: the same agent, handed a prompt asking for a read, a write and a `touch`, answered the marker word it had read, said the other two were not permitted, and left no file behind, and its record carried the same fields; the release this agent was measured on is therefore 1.4 (docs/audit/2026-10-18-agy-1-4-reviewer.md)."
55
+ },
56
+ "model": ["--model={model}"],
57
+ "effort": ["--effort={effort}"],
58
+ "effort_values": ["low", "medium", "high", "xhigh", "max"],
59
+ "agent_profile": ["--agent={agent}"],
60
+ "output_json": ["--output-format=json"],
61
+ "output_stream": ["--output-format=stream-json"],
62
+ "answer_record": {
63
+ "argv": ["--output-format", "json"],
64
+ "text": "response",
65
+ "denied": "denied_actions",
66
+ "error": "error",
67
+ "transient": ["(?i)network issue", "(?i)connection (refused|reset)", "(?i)no route to host", "(?i)i/o timeout|TLS handshake timeout|context deadline exceeded", "(?i)temporarily unavailable|service unavailable|\\b50[234]\\b", "(?i)rate.?limit"],
68
+ "note": "One JSON record on stdout; its response is the answer. A tool the run was denied ends it on an empty response, named in denied_actions, with exit 0 and a notice on stderr (agy 1.3.0). A run that failed says why in the record's error and on stderr, with status ERROR: agy 1.3 ended a review with exit 3 on 'There was a network issue connecting to the server, please try again.', and with exit 1 on 'Eligibility check failed: ... connection refused' where it could not reach its service; those transient are asked again once."
69
+ },
70
+ "structured_output": ["--json-schema={schema}"],
71
+ "mode": ["--mode={mode}"],
72
+ "mode_values": ["accept-edits", "plan"],
73
+ "add_dir": ["--add-dir={dir}"],
74
+ "sandbox": ["--sandbox"],
75
+ "trust_all": ["--dangerously-skip-permissions"],
76
+ "bypass": {
77
+ "--dangerously-skip-permissions": { "roles": ["implementer"],
78
+ "why": "Kept: without it a print run of agy 1.3.0 denies every write and every shell command it cannot ask about (1.1.19 wrote files and soft-denied commands), and the rules that allow a command (permissions.allow) live only in the person's own settings file, which polyctl does not write; --sandbox isolates commands but runs them unprompted only under a setting too. Read on 2026-09-17 from antigravity.google/docs/cli/headless, antigravity.google/docs/cli/permissions and antigravity.google/docs/cli/sandbox." }
79
+ },
80
+ "timeout": ["--print-timeout={timeout}"]
81
+ },
82
+
83
+ "subcommands": {
84
+ "list_agents": ["agy", "agents"],
85
+ "list_models": ["agy", "models"],
86
+ "mcp": ["agy", "mcp"],
87
+ "plugins": ["agy", "plugin"]
88
+ },
89
+
90
+ "result_record": {
91
+ "session_id": "conversation_id",
92
+ "status": "status",
93
+ "status_values": ["SUCCESS"],
94
+ "text": "response",
95
+ "turns": "num_turns",
96
+ "duration": "duration_seconds",
97
+ "verified_example": "{\"conversation_id\":\"a0a7445c-…\",\"status\":\"SUCCESS\",\"response\":\"…\",\"duration_seconds\":18.8,\"num_turns\":1,\"usage\":{…}}"
98
+ },
99
+
100
+ "busy": {
101
+ "kind": "orchestrator-owned",
102
+ "note": "Print mode is synchronous, so the orchestrator knows exactly when a turn is in flight and does not have to infer it from file mtimes. The two-writer hazard is handled by an in-process lock per conversation id rather than an idle guard."
103
+ },
104
+
105
+ "telemetry": {
106
+ "cost": {
107
+ "from": "call-return",
108
+ "fields": ["usage.input_tokens", "usage.output_tokens", "usage.thinking_tokens", "usage.cache_read_tokens", "usage.total_tokens"],
109
+ "unit": "token",
110
+ "verified": true
111
+ },
112
+ "duration": { "from": "call-return", "field": "duration_seconds", "verified": true },
113
+ "context": { "from": "none", "note": "No context-percentage signal; approximate from input_tokens against the model's window if the window is known." },
114
+ "balance": { "from": "none", "note": "Never estimated." }
115
+ },
116
+
117
+ "directives": {
118
+ "todo": "Determine whether agy honours an always-included instruction file. Observed: a global rules preamble is replayed into responses, and one two-word prompt consumed 21140 input tokens — check what is being injected before blaming the model."
119
+ }
120
+ }
@@ -0,0 +1,229 @@
1
+ {
2
+ "id": "claude-code",
3
+ "name": "Claude Code",
4
+ "project_config": [".claude", ".mcp.json", "CLAUDE.md", "CLAUDE.local.md"],
5
+ "worktree_dirs": [".claude/worktrees"],
6
+ "worktree_dirs_note": "Claude Code keeps the worktrees it makes here and reads no configuration from them: a session started in one reads that worktree's own. polyctl skips a worktree of the repository only here (HARNESS-CONFIG).",
7
+ "verified": "full",
8
+ "actor_name": "claude",
9
+ "family": "anthropic",
10
+ "notes": "Works as implementer and as architect. When used as the architect it is the process running the orchestrator, so only send/resume matter.",
11
+ "send": {
12
+ "argv": [
13
+ "claude",
14
+ "-p",
15
+ "{prompt}"
16
+ ],
17
+ "cwd_matters": true,
18
+ "stdin": { "replaces": ["{prompt}"], "with": [],
19
+ "note": "Verified from the headless documentation (code.claude.com/docs/en/headless), read 2026-09-17: non-interactive mode reads stdin, its review example pipes a diff to `claude -p` with no prompt argument, and piped stdin is capped at 10MB. `claude --help` (2.1.261) lists the prompt as an optional argument." }
20
+ },
21
+ "resume": {
22
+ "argv": [
23
+ "claude",
24
+ "--resume",
25
+ "{session}",
26
+ "-p",
27
+ "{prompt}",
28
+ "--permission-mode",
29
+ "dontAsk",
30
+ "--allowedTools",
31
+ "Read,Grep,Glob,Write,Edit,mcp__polyctl__polyctl_inbox,mcp__polyctl__polyctl_ack,mcp__polyctl__polyctl_report,mcp__polyctl__polyctl_ask,mcp__polyctl__polyctl_decisions,mcp__polyctl__polyctl_propose,mcp__polyctl__polyctl_status,mcp__polyctl__polyctl_board,mcp__polyctl__polyctl_next,mcp__polyctl__polyctl_notices,mcp__polyctl__polyctl_fanout,mcp__polyctl__polyctl_watchdog,Bash(polyctl status:*),Bash(polyctl board:*),Bash(polyctl next:*),Bash(polyctl slice start:*),Bash(polyctl slice block:*),Bash(polyctl slice status:*),Bash(polyctl slices:*),Bash(polyctl writers),Bash(polyctl verify:*),Bash(polyctl review:*),Bash(polyctl commit-ok),Bash(polyctl commit-ok --verify),Bash(polyctl commit -m:*),Bash(polyctl commit -F:*),Bash(polyctl mail:*),Bash(polyctl ask:*),Bash(polyctl decisions:*),Bash(polyctl propose:*),Bash(polyctl doctor),Bash(polyctl watchdog explain:*),Bash(polyctl since:*),Bash(polyctl digest:*),Bash(polyctl fanout ok:*),Bash(polyctl fanout record:*),Bash(polyctl tail:*),Bash(git status:*),Bash(git log:*),Bash(git diff:*),Bash(git add:*),Bash(ls:*),Bash(cat:*),Bash(grep:*)"
32
+ ],
33
+ "continue_last": [
34
+ "claude",
35
+ "--continue",
36
+ "-p",
37
+ "{prompt}",
38
+ "--permission-mode",
39
+ "dontAsk"
40
+ ],
41
+ "stdin": { "replaces": ["{prompt}"], "with": [],
42
+ "note": "Verified as for send: -p with --resume is the non-interactive mode the headless documentation says reads stdin." },
43
+ "note": "Scoped rather than --dangerously-skip-permissions. The implementer is trusted with the tree — it must write code and run gates — but not with push, gh, or arbitrary shell; authority is withheld by polyctl, and the allowlist keeps the blast radius to the repo. The grant names every polyctl command and polyctl MCP tool the playbook's loop and the nudge tell the implementer to use (tests/test_grants_pinned.py), except `polyctl lock`, which runs any command: declared gates take the same lock through `polyctl verify`. The mode is pinned, as options.pin says: a -p run given no --permission-mode starts in permissions.defaultMode from the person's settings, and `claude -p --resume` in the mode a new -p run would, so an acceptEdits, auto or bypassPermissions default widened every nudge (code.claude.com/docs/en/permission-modes, 'Which mode a session starts in', and /docs/en/sessions, 'Permission mode on resume', read 2026-09-17)."
44
+ },
45
+ "options": {
46
+ "trust_none": ["--tools", "Read,Grep,Glob", "--permission-mode", "dontAsk", "--allowedTools", "Read,Grep,Glob", "--strict-mcp-config"],
47
+ "trust_none_note": "Only reading, whatever the person's settings hold: --tools leaves Read, Grep and Glob the only tools there are, so no allow rule in a settings file can hand a reviewer Edit or Bash; --allowedTools lets them read outside the reviewer's own directory; dontAsk denies anything else rather than asking; --strict-mcp-config starts no MCP server (#24).",
48
+ "pin": {
49
+ "implementer": ["--permission-mode", "dontAsk"],
50
+ "architect": ["--permission-mode", "dontAsk"],
51
+ "reviewer": ["--permission-mode", "dontAsk", "--tools", "Read,Grep,Glob"],
52
+ "note": "What a turn polyctl starts in each role carries, the bug hunter's as a reviewer's; a configured command that names none of it (a block composed before it was pinned) has it appended when the turn starts. Verified from code.claude.com/docs/en/cli-reference, read 2026-09-17: --permission-mode overrides defaultMode from settings files and takes default, acceptEdits, plan, auto, dontAsk or bypassPermissions (manual for default from 2.1.200); --tools restricts which tools are available at all, from 2.1.247. From /docs/en/permission-modes and /docs/en/headless: dontAsk, the mode given for locked-down scripts, denies every call that would otherwise prompt and still runs reads, the read-only command set and allow rules, including a person's own in their settings; deny rules hold in every mode; plan is no reviewer's mode, since where auto mode is available the classifier approves shell commands during planning. The Agent SDK passes --tools comma-joined, as --allowedTools (github.com/anthropics/claude-agent-sdk-python, _internal/transport/subprocess_cli.py)."
53
+ },
54
+ "mcp_isolation": { "required": ["--strict-mcp-config"], "forbidden": ["--mcp-config"],
55
+ "why": "an allow list gates permissions, not which MCP servers start (#24)" },
56
+ "model": [
57
+ "--model",
58
+ "{model}"
59
+ ],
60
+ "output_json": [
61
+ "--output-format",
62
+ "stream-json"
63
+ ],
64
+ "allowed_tools": [
65
+ "--allowedTools",
66
+ "{tools}"
67
+ ],
68
+ "trust_all": [
69
+ "--dangerously-skip-permissions"
70
+ ],
71
+ "implementer_tools": "Read,Grep,Glob,Write,Edit,mcp__polyctl__polyctl_inbox,mcp__polyctl__polyctl_ack,mcp__polyctl__polyctl_report,mcp__polyctl__polyctl_ask,mcp__polyctl__polyctl_decisions,mcp__polyctl__polyctl_propose,mcp__polyctl__polyctl_status,mcp__polyctl__polyctl_board,mcp__polyctl__polyctl_next,mcp__polyctl__polyctl_notices,mcp__polyctl__polyctl_fanout,mcp__polyctl__polyctl_watchdog,Bash(polyctl status:*),Bash(polyctl board:*),Bash(polyctl next:*),Bash(polyctl slice start:*),Bash(polyctl slice block:*),Bash(polyctl slice status:*),Bash(polyctl slices:*),Bash(polyctl writers),Bash(polyctl verify:*),Bash(polyctl review:*),Bash(polyctl commit-ok),Bash(polyctl commit-ok --verify),Bash(polyctl commit -m:*),Bash(polyctl commit -F:*),Bash(polyctl mail:*),Bash(polyctl ask:*),Bash(polyctl decisions:*),Bash(polyctl propose:*),Bash(polyctl doctor),Bash(polyctl watchdog explain:*),Bash(polyctl since:*),Bash(polyctl digest:*),Bash(polyctl fanout ok:*),Bash(polyctl fanout record:*),Bash(polyctl tail:*),Bash(git status:*),Bash(git log:*),Bash(git diff:*),Bash(git add:*),Bash(ls:*),Bash(cat:*),Bash(grep:*)",
72
+ "architect_tools": "Read,Grep,Glob,Edit(/.polyctl/backlog.md),Edit(/.polyctl/board.md),Edit(/.polyctl/inbox/**),Bash(polyctl status:*),Bash(polyctl board:*),Bash(polyctl next:*),Bash(polyctl slice:*),Bash(polyctl slices:*),Bash(polyctl mail:*),Bash(polyctl decide:*),Bash(polyctl decisions:*),Bash(polyctl propose:*),Bash(polyctl proposals:*),Bash(polyctl note:*),Bash(polyctl answer:*),Bash(polyctl source import),Bash(polyctl review:*),Bash(polyctl catchup),Bash(polyctl catchup --plan),Bash(polyctl doctor),Bash(polyctl doctor --check),Bash(polyctl writers),Bash(polyctl since:*),Bash(polyctl digest:*),Bash(polyctl notices:*),Bash(polyctl alarms),Bash(polyctl alarms list:*),Bash(polyctl cost:*),Bash(polyctl credits:*),Bash(polyctl tail:*),Bash(polyctl watchdog status:*),Bash(polyctl watchdog explain:*),Bash(polyctl watchdog trace:*),Bash(git status:*),Bash(ls:*),Bash(cat:*),Bash(head:*),Bash(tail:*),Bash(grep:*),Bash(ps:*),Bash(lsof:*)",
73
+ "architect_tools_note": "The architect's wake: `polyctl init` composes it from resume with this grant in place of the implementer's. It reads, edits the three coordination files a wake writes and nothing else, and runs the polyctl commands the playbook's routine and the wake and refill prompts name, with the read-only instruments. A rule given on the command line as Edit(/path) is anchored at the working directory, and an Edit rule covers every built-in tool that edits, Write included (code.claude.com/docs/en/permissions, 'Read and Edit', read 2026-09-17). No rule admits a write elsewhere: a * stands for any text, spaces included, so `Bash(rm agent-mail/*)` admitted `rm agent-mail/x src/app.py`, and git log, diff and show take --output=<file>; `polyctl mail ack` removes handled mail, and the read-only forms of git run with no rule in every mode."
74
+ },
75
+ "transcript": {
76
+ "kind": "jsonl",
77
+ "path": "~/.claude/projects/{escaped_cwd}/{session}.jsonl",
78
+ "escaped_cwd": "absolute cwd with '/' replaced by '-'",
79
+ "record": {
80
+ "time": "timestamp",
81
+ "kind": "type",
82
+ "text_keys": [
83
+ "message.content",
84
+ "content",
85
+ "text",
86
+ "message"
87
+ ]
88
+ },
89
+ "messages": { "prompt": ["user"], "reply": ["assistant"], "blocks": "message.content[]", "match": { "type": "text" },
90
+ "not_words": [{ "isMeta": true }, { "isCompactSummary": true }, { "origin.kind": "task-notification" }],
91
+ "harness_replies": [{ "message.model": "<synthetic>" }] },
92
+ "turn": { "end": ["result"],
93
+ "end_when": { "type": "assistant", "field": "message.stop_reason",
94
+ "values": ["end_turn", "stop_sequence", "refusal"] },
95
+ "conversation": ["user", "assistant"] },
96
+ "tool_call": { "type": "assistant", "blocks": "message.content[]", "match": { "type": "tool_use" },
97
+ "name": "name", "args": "input", "id": "id", "path_keys": ["file_path", "notebook_path"],
98
+ "write_words": ["write", "edit"] },
99
+ "subagents": {
100
+ "dir": "{session}/subagents",
101
+ "transcripts": [
102
+ { "path": "agent-{id}.jsonl", "named_by": "toolUseResult.agentId" },
103
+ { "path": "workflows/{id}/agent-*.jsonl", "named_by": "toolUseResult.runId" }
104
+ ],
105
+ "sidecar": { "path": "{name}.meta.json", "call": "toolUseId" },
106
+ "note": "A subagent writes its records to a transcript of its own under the session's directory: subagents/agent-<id>.jsonl for an agent a call starts, subagents/workflows/<run>/agent-<id>.jsonl for the agents a workflow run starts, each with a sidecar agent-<id>.meta.json. The result of the call that started an agent names it at toolUseResult.agentId, whether the agent ran to its end or went on in the background, and a workflow's result names its run at toolUseResult.runId; the sidecar of an agent a call started names the call at toolUseId, the only link for an agent another subagent started, whose call's result carries no toolUseResult. Its records are user, assistant and attachment records like the session's, but it writes a response's records as it streams them, each with the output tokens so far, so a response costs its highest record. No response is in both a subagent's transcript and its session's, nor in two subagents'; the usage and totalTokens a call's result carries sit on a user record, are not the subagent's spend, and are not read. The agents of a workflow run carry the prompt id current when the run started them, a later turn's for 961 of 3,268, so a prompt id does not join them. Verified on 2.1 session stores: every one of 3,563 subagent transcripts beside a session transcript is joined. A subagent at work is its implementer at work while the session's own transcript is quiet: in the 59 stores at rest that delegate, 77,402 of 257,598 subagent records were written with the session transcript silent for six minutes or more, and 143,529 while the session's turn read as ended. The session writes a record of each subagent it takes back: every one of the 444 closed turns a subagent wrote in ended at a record of the session, 251 at a task notification written 0.1 s after the last subagent write at the median, and no subagent transcript at rest was written after its session transcript, so one written after it is still working. A subagent's own records do not say it finished: its last record closes its turn in 194 of the 239 agents a call started and 430 of the 2,677 a workflow run started, whose 2,187 more end on the result of their StructuredOutput call."
107
+ },
108
+ "note": "No record starts a turn, so a prompt opens one. The session store writes no closing record (`result` closes a turn only in --output-format stream-json output): the response that ends a turn says so in message.stop_reason, which every record of that response carries. end_turn ends one, and so does stop_sequence, which marks a reply the harness writes itself (an API error, for one) and after which the store holds the next prompt or nothing, and so does refusal, after which the store held the next prompt; tool_use means the harness runs the calls and asks again, and after max_tokens it asks again too: another response of the same turn followed every one. A Stop hook runs after an end_turn response and writes nothing when it starts: its system record, stop_hook_summary, comes when it ends and not after every end_turn, and no hook went on with the turn, so the turn has ended at the response and the summary is bookkeeping. A tool call is a tool_use block in an assistant record's message.content, and its result a tool_result block in the user record that follows, which holds nothing else; the words of a prompt or a reply are its text blocks, or its content when that is a string. A user record holding isMeta true - a note the harness writes: a local command's caveat, a skill's instructions, another session's message - or isCompactSummary true, the summary of a compacted conversation, or origin.kind task-notification, a background task's end, is no one speaking. Every kind but user and assistant - titles, prompt queues, hook summaries, attachments, file history, and whatever kind a release adds - may follow a turn's end. Verified on 2.1 session stores. A record that holds no one's words still asks the model to answer: a task notification or a note after a turn's end opens the next turn, as a prompt does. Of the 5,035 turns the 419 stores at rest hold, 1,477 open at a task notification and 512 at a note, 295 of them another session's message (origin.kind peer), and 1,378 and 371 of those charge a response's tokens. A reply the harness writes itself holds message.model <synthetic> and no usage: all 515 in the sessions of those stores and all 180 in their subagents' transcripts, 693 of them ending at stop_sequence and 2 at refusal, 510 an error the service or the account returned (isApiErrorMessage: a usage limit, an API error, a failed authentication) and 185 the words No response requested. 328 of the 5,035 turns hold no reply but these and charge nothing - 180 an error after a person's prompt (96), a notification (79) or a note (5), and 148 No response requested after a note (133) or a notification (15) - so the model answered none of them; 187 more hold one beside the model's own response.",
109
+ "tail_bytes": 900000
110
+ },
111
+ "telemetry": {
112
+ "context": {
113
+ "from": "none",
114
+ "note": "No record carries a context percentage or the model's window: a response's usage says how many tokens it sent, not of how many, and a compaction record carries token counts only. A percentage would rest on a guessed window, so none is read."
115
+ },
116
+ "cost": {
117
+ "from": "transcript",
118
+ "type": "assistant",
119
+ "response": "message.id",
120
+ "fields": [
121
+ "message.usage.input_tokens",
122
+ "message.usage.cache_creation_input_tokens",
123
+ "message.usage.cache_read_input_tokens",
124
+ "message.usage.output_tokens"
125
+ ],
126
+ "unit": "token",
127
+ "model": "message.model",
128
+ "tokens": {
129
+ "input": "message.usage.input_tokens",
130
+ "cache_write_5m": ["message.usage.cache_creation.ephemeral_5m_input_tokens",
131
+ "message.usage.cache_creation_input_tokens"],
132
+ "cache_write_1h": "message.usage.cache_creation.ephemeral_1h_input_tokens",
133
+ "cache_read": "message.usage.cache_read_input_tokens",
134
+ "output": "message.usage.output_tokens"
135
+ },
136
+ "priced_when": [
137
+ {"field": "message.usage.speed", "values": ["standard", null]},
138
+ {"field": "message.usage.service_tier", "values": ["standard", null]},
139
+ {"field": "message.usage.inference_geo", "values": ["global", "not_available", null]}
140
+ ],
141
+ "counted": "Every token a response read or wrote, once per response: input_tokens (input after the last cache breakpoint), cache_creation_input_tokens (input written to the prompt cache), cache_read_input_tokens (input read from it) and output_tokens (thinking included).",
142
+ "not_counted": "server_tool_use (web search and fetch requests: counts of requests, not tokens); output_tokens_details and cache_creation (breakdowns already inside output_tokens and cache_creation_input_tokens); iterations (a per-iteration breakdown that repeats the total). The count weighs every token alike: a cache read is priced far below an input token and is most of a long session's tokens, so a turn's count follows its context size times its responses more closely than its price. `polyctl cost --usd` prices each kind at its own rate instead (`tokens`).",
143
+ "pricing": "How `polyctl cost --usd` reads a response for the price table: by the model at message.model, and by kind under the per-response reading, each kind at its own rate. usage.cache_creation breaks the cache writes down by how long the cache lives, five minutes or an hour, and an hour's write costs 1.6 times a five-minute one; a record without the breakdown is read as five-minute writes, the default duration. Measured on the 87,798 usage records of the 400 transcripts written last in the thirty days to 2026-09-26: every record carries the breakdown, 44,347 wrote to a one-hour cache and 43,158 to a five-minute one, and 8 hold a one-hour write that their total leaves out, priced as the breakdown says. A response at another speed (fast mode), service tier or inference geography than priced_when lists is not at the table's list prices and is reported unknown. Every record measured held speed standard or no speed, service_tier standard and inference_geo not_available, but for the replies the harness writes itself (model <synthetic>), which hold neither field and carry no tokens.",
144
+ "note": "One response is written as one record per content block, each repeating the response's usage, so a response is read once, by message.id, under the per-response reading (billing.fallback.reading); adding the records up counted about twice its tokens. A subagent's transcript writes each record with the output tokens so far, so a response costs the most its records reached. A store also writes a response again, turns after the first, and a resumed session's transcript can hold another's responses, so a response is read once in a reading rather than once in a turn.",
145
+ "verified": true
146
+ },
147
+ "failure": {
148
+ "from": "transcript",
149
+ "type": "user",
150
+ "blocks": "message.content[]",
151
+ "match": { "type": "tool_result" },
152
+ "field": "is_error",
153
+ "failed_when": true,
154
+ "text": "content",
155
+ "verified": true,
156
+ "note": "The harness's own verdict, one tool result per user record: is_error is true on a failed result of any tool, and a result that succeeded carries false or no is_error at all.",
157
+ "ends": {
158
+ "records": [
159
+ { "type": "user", "match": { "origin.kind": "task-notification" }, "field": "message.content" },
160
+ { "type": "attachment", "match": { "attachment.commandMode": "task-notification" }, "field": "attachment.prompt" }
161
+ ],
162
+ "status": ["<status>", "</status>"],
163
+ "failed_when": ["failed", "stopped"],
164
+ "id": ["<task-id>", "</task-id>"],
165
+ "text": ["<summary>", "</summary>"],
166
+ "note": "A task run in the background - a shell command, a monitor, a subagent, a workflow - ends after the call that started it returned, and the harness tells the session in a notification: a user record holding origin.kind task-notification when no turn runs, which opens the next turn, or an attachment record holding attachment.commandMode task-notification queued into the turn that runs. queue-operation records repeat its text while it waits, and are not read. Its text is one <task-notification> holding a <task-id> for each task it names, a <status> and a <summary>. In the 419 stores at rest the sessions hold 1,517 such user records and 1,771 such attachments, none holding two notifications; 1,010 carry no status, a monitor's or a workflow's progress event, and the others tell an end: 2,000 completed, 183 failed, 90 stopped and 5 killed. A failed end is a command that exited non-zero (116), an agent that terminated early or stalled (41), and a monitor's script (10), an MCP task (10) or a workflow's script (6) that failed. A stopped end is work a session's previous process ended before it finished, told when the session resumed: tasks it found no completion record for (64), background commands of the previous session (23), agents that did not finish before it ended (3). A killed end is a task stopped on purpose: by the person in 3, and 2 background commands. So failed and stopped are failures and killed is not. The call that started a task returned when the task began: 228 of the 273 failed and stopped ends name their call, and none of those calls has a failed result. An end is at times told twice, 9 of the 2,269 in those stores, so it is read once, by its task ids."
167
+ }
168
+ }
169
+ },
170
+ "billing": {
171
+ "fallback": {
172
+ "reading": "per-response",
173
+ "note": "How the panel and polyctl cost add this harness's usage records up. No transcripts are declared, so the offline credit estimate reads none of them: the harness bills no credit account that estimate stands in for, and a token is not a credit."
174
+ }
175
+ },
176
+ "sessions": {
177
+ "kind": "escaped-cwd",
178
+ "dir": "~/.claude/projects",
179
+ "transcript": "{session}.jsonl",
180
+ "cwd": "cwd",
181
+ "note": "A directory's name is its working directory with every character that is not a letter or a digit made a dash (code.claude.com/docs/en/sessions, read 2026-09-17), so it cannot be read back into a path: `cwd` names the record field holding the working directory, and a directory is placed by a value there that escapes to its name. user, assistant, attachment and system records carry it. A session moved with /cd is kept under the directory it moved to while its first records name the old one, so the newest records are read first. Verified on a 2.1 store: every one of 167 directories was placed from the last or the first 64 KB of one of its three newest transcripts, 158 of them by the last record that carries the field."
182
+ },
183
+ "busy": {
184
+ "mtime_file": "{session}.jsonl",
185
+ "idle_seconds": 240,
186
+ "note": "No status file; rely on write age alone."
187
+ },
188
+ "detect": {
189
+ "dirs": [".claude"],
190
+ "files": [".mcp.json", "CLAUDE.md"],
191
+ "binaries": ["claude"],
192
+ "processes": ["claude", "claude-code"],
193
+ "headless": ["-p", "--print"],
194
+ "install_dirs": ["~/.claude/local"],
195
+ "update": ["claude", "update"]
196
+ },
197
+ "directives": {
198
+ "steering_files": [
199
+ "CLAUDE.md",
200
+ ".claude/CLAUDE.md",
201
+ "~/.claude/CLAUDE.md"
202
+ ],
203
+ "steering_format": "markdown, always included",
204
+ "hooks": ".claude/settings.json (hooks key)",
205
+ "command_hooks": { "format": "pre-tool-use", "shell_tool": "Bash", "project_dir_env": "CLAUDE_PROJECT_DIR",
206
+ "files": ["~/.claude/settings.json", ".claude/settings.json", ".claude/settings.local.json"] },
207
+ "skills_dir": ".claude/skills",
208
+ "playbook": { "path": ".claude/skills/polyctl/SKILL.md", "header": "frontmatter" },
209
+ "rule_files": ["CLAUDE.md"],
210
+ "polyctl_files": [".claude/skills/polyctl/"]
211
+ },
212
+ "mcp": { "file": ".mcp.json", "remove_when_empty": true },
213
+ "quota": {
214
+ "provider": "claude",
215
+ "stops": [
216
+ { "words": "hit your session limit[^\\n]*", "hours": 5 },
217
+ { "words": "hit your weekly limit[^\\n]*", "hours": 168 },
218
+ { "words": "reached your [^\\n]{1,60}? limit\\.[^\\n]*", "hours": 168 },
219
+ { "words": "usage limit reached\\|(?P<epoch>\\d{9,11})", "hours": 5 }
220
+ ],
221
+ "resets_at": "quotaLimits.resetsAt",
222
+ "stops_note": "The words a turn ends on when a usage limit stops it: the reply the harness writes in the model's place (message.model <synthetic>, error rate_limit, apiErrorStatus 429), and what a headless run prints as it exits. Verified on 2.1 session stores: all 428 replies holding error rate_limit, in 59 stores and their subagents' transcripts, are one of three forms, and none of the 357 other replies the harness wrote in the model's place is: the session limit (hit your session limit · resets <time> (<zone>)), the weekly limit (hit your weekly limit · resets <time>, or resets <month> <day> at <time>), and a model's own allowance (reached your <model> limit. Run /usage-credits to continue or switch models with /model.), which names no reset. From 2.1.235 the reply records the limit beside its words, in quotaLimits: rateLimitType five_hour or seven_day, and resetsAt, the reset in epoch seconds, which 283 of them hold. On each of those 283 the reset the words name, read against the reply's own time within its limit's hours, is resetsAt: 210 session limits, 62 weekly limits that name their day, and 11 that name only the clock and were due 2 to 10 hours later, past a five-hour window. Older releases wrote the limit as usage limit reached|<epoch>, the reset after the bar."
223
+ },
224
+ "models": {
225
+ "default": "claude-sonnet-5",
226
+ "review": "claude-opus-5",
227
+ "_note": "polyctl init --profile and the reviewer default read these; change here when Anthropic ships new ids"
228
+ }
229
+ }
@@ -0,0 +1,57 @@
1
+ {
2
+ "id": "cloud-generic",
3
+ "name": "Generic cloud agent (pull-request delivered)",
4
+ "kind": "cloud",
5
+ "tier": 3,
6
+ "detect": { "headless": [] },
7
+ "verified": "partial",
8
+ "options": { "trust_none": null, "trust_none_why": "a cloud template: the runner it is bound to decides which tools the agent has" },
9
+ "notes": "Provider-agnostic tier-3 adapter: works with any cloud agent that delivers its result as a branch or pull request, with no vendor API and no vendor cooperation. Dispatch is out-of-band (assign an issue, click once in an IDE); everything after that is observed through git. Requires the GitHub CLI.",
10
+
11
+ "dispatch": {
12
+ "kind": "out-of-band",
13
+ "note": "The human or a vendor-specific adapter starts the task. This adapter is told the expected author/branch prefix and takes over from there.",
14
+ "optional_issue_assign": ["gh", "issue", "edit", "{issue}", "--add-assignee", "{agent_login}"]
15
+ },
16
+
17
+ "poll": {
18
+ "argv": ["gh", "pr", "list", "--search", "author:{agent_login} is:open",
19
+ "--json", "number,title,headRefName,updatedAt,isDraft,statusCheckRollup"],
20
+ "interval_seconds": 120,
21
+ "note": "Polling interval is measured in minutes, not seconds. Cloud tasks run for minutes to hours; a tight loop only burns API quota."
22
+ },
23
+
24
+ "result": {
25
+ "branch_field": "headRefName",
26
+ "pr_field": "number",
27
+ "diff": ["gh", "pr", "diff", "{pr}"],
28
+ "checks": ["gh", "pr", "checks", "{pr}"],
29
+ "fetch": ["git", "fetch", "origin", "refs/pull/{pr}/head"],
30
+ "fetch_note": "Measured against real GitHub, 2026-10-16: a fork PR's branch does not exist in the base repository - `git ls-remote refs/heads/<branch>` is empty for The-PR-Agent/pr-agent#4143, whose commits live only at refs/pull/4143/head - so fetching `{branch}` from origin fails ('couldn't find remote ref') for exactly the fork case this adapter exists for. The pull namespace fetches for fork and same-repo PRs alike (`pull/{pr}/head` and its full refs/ form both work); a same-repo PR's branch is additionally present under refs/heads."
31
+ },
32
+
33
+ "busy": {
34
+ "kind": "service-reported",
35
+ "running_when": "no pull request yet, or the pull request is still a draft",
36
+ "note": "There is no local file to watch and no two-writer hazard: the workspace is remote."
37
+ },
38
+
39
+ "telemetry": {
40
+ "cost": {"from": "none", "note": "Usually included in a plan and not itemised per task."},
41
+ "duration": {"from": "derived", "note": "Elapsed time between the dispatch event and the result event, both written to the event log."},
42
+ "size": {"from": "result", "fields": ["files_changed", "additions", "deletions"]}
43
+ },
44
+
45
+ "verification": {
46
+ "runs": "local",
47
+ "rule": "The delivered branch is untrusted code. Gates run locally against the merged result before anything lands. Auto-merge is never enabled, and a check written by the same agent that wrote the code is not a gate.",
48
+ "merge": ["polyctl", "queue", "merge", "{lane}"]
49
+ },
50
+
51
+ "brief_requirements": [
52
+ "exact acceptance boundary",
53
+ "files the agent may touch",
54
+ "gates that will judge the result",
55
+ "explicit statement that fixture or partial evidence does not count as done"
56
+ ]
57
+ }
@@ -0,0 +1,47 @@
1
+ {
2
+ "project_config": [".codex", "AGENTS.md", "AGENTS.override.md"],
3
+ "id": "codex", "name": "OpenAI Codex CLI", "verified": "partial",
4
+ "actor_name": "codex",
5
+ "family": "openai",
6
+ "models": {
7
+ "default": "gpt-6-astra",
8
+ "review": "gpt-6-luna",
9
+ "_note": "polyctl init --profile and the reviewer default read these; change here when OpenAI ships new ids"
10
+ },
11
+ "disclaimer": "The reviewer's command - exec with its prompt, --model, -c model_reasoning_effort and options.trust_none - was run against codex-cli 0.160.0 on 2026-10-05; the rest is written from the documented interface and not verified against an install. Flags drift; correct and open a PR.",
12
+ "send": { "argv": ["codex", "exec", "{prompt}"],
13
+ "stdin": { "replaces": ["{prompt}"], "with": ["-"],
14
+ "note": "Verified from the command reference (learn.chatgpt.com/docs/developer-commands, surface cli), read 2026-09-17: codex exec takes PROMPT as `string | - (read stdin)`, and `-` pipes the prompt from stdin." } },
15
+ "resume": { "argv": ["codex", "exec", "resume", "{session}", "{prompt}"], "continue_last": ["codex", "exec", "resume", "--last", "{prompt}"],
16
+ "stdin": { "replaces": ["{prompt}"], "with": ["-"],
17
+ "note": "Verified from the same reference: codex exec resume takes its PROMPT as `string | - (read stdin)` too." } },
18
+ "quota": { "provider": "codex" },
19
+ "options": {
20
+ "trust_none": ["--sandbox", "read-only", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "--ephemeral"],
21
+ "trust_none_note": "No flag removes codex exec's shell tool; its read-only sandbox leaves it reading. Measured on codex-cli 0.160.0, 2026-10-05: under --sandbox read-only, cat read a file, touch was refused (Operation not permitted) and curl resolved no host. Without --ignore-user-config the person's $CODEX_HOME/config.toml offered the model computer use, a browser and web search, and with it only the shell tool, waits and subagents. --ignore-rules leaves out the person's execpolicy rules, whose allow decisions approve commands without asking. polyctl runs a reviewer in a directory outside any repository, which codex exec refuses without --skip-git-repo-check, and --ephemeral keeps the review out of the person's sessions.",
22
+ "pin": {
23
+ "reviewer": ["--sandbox", "read-only"],
24
+ "note": "codex exec runs read-only unless told otherwise, and a person's config.toml may set sandbox_mode; a reviewer names its sandbox, so no setting widens it."
25
+ },
26
+ "mcp_isolation": { "required": ["--ignore-user-config"],
27
+ "why": "MCP servers and plugins live in $CODEX_HOME/config.toml, which codex loads unless told not to (#24)" },
28
+ "model": ["--model", "{model}"],
29
+ "effort": ["-c", "model_reasoning_effort={effort}"],
30
+ "effort_values": ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
31
+ "effort_note": "The values the Responses API named when it refused another, through codex-cli 0.160.0 on 2026-10-05; each model takes a subset, listed in ~/.codex/models_cache.json.",
32
+ "output_json": ["--json"],
33
+ "trust_all": ["--dangerously-bypass-approvals-and-sandbox"],
34
+ "sandbox": ["--sandbox", "{mode}"],
35
+ "sandbox_note": "codex exec takes --sandbox and codex exec resume does not (openai/codex issue 40149; rechecked on codex-cli 0.160.0, 2026-10-16: `codex exec resume --sandbox read-only` errors 'unexpected argument --sandbox found' and suggests passing it as a value, while `codex exec resume -c sandbox_mode=\"read-only\"` is accepted); a resume takes -c sandbox_mode=\"<mode>\", which every exec subcommand accepts.",
36
+ "bypass": {
37
+ "--dangerously-bypass-approvals-and-sandbox": { "roles": ["implementer"], "sandbox": true,
38
+ "why": "No documented combination runs an unattended implementer's loop without it. codex exec asks nobody - it answers every approval with never - and runs in a read-only sandbox unless told otherwise. Its workspace-write sandbox (-c sandbox_mode=\"workspace-write\" after exec resume; --full-auto is gone since 0.147.0) keeps <writable_root>/.git read-only and the network off, so an implementer could edit and test but never stage, commit or run its reviewer. The watchdog starts no turn with it until a person names codex in watchdog.bypass_adapters on this machine, and polyctl doctor names what that allows. Read on 2026-09-17 from learn.chatgpt.com/docs/sandboxing, /docs/non-interactive-mode, /docs/developer-commands and /docs/config-file/config-reference, and github.com/openai/codex (codex-rs/exec/src/cli.rs; issues 40149 and 7071)." }
39
+ }
40
+ },
41
+ "transcript": { "kind": "jsonl", "path": "~/.codex/sessions/**/rollout-*.jsonl", "todo": "confirm record shape" },
42
+ "busy": { "mtime_glob": "~/.codex/sessions/**/rollout-*.jsonl", "idle_seconds": 240 },
43
+ "detect": { "dirs": [".codex"], "binaries": ["codex"], "processes": ["codex"], "headless": ["exec"] },
44
+ "mcp": { "manual": "~/.codex/config.toml",
45
+ "snippet": "[mcp_servers.polyctl]\ncommand = \"{exe}\"\nargs = {args}" },
46
+ "directives": { "steering_files": ["AGENTS.md", "~/.codex/AGENTS.md"], "config": "~/.codex/config.toml" }
47
+ }
@@ -0,0 +1,45 @@
1
+ {
2
+ "id": "command-code", "name": "Command Code (cmd)", "verified": "partial",
3
+ "verified_version": "cmd 1.32.2",
4
+ "notes": "Command surface and session store verified on a real install. Rich CLI: print mode, JSON output, resume by id or transcript path, managed worktrees, model+effort, MCP, skills, and cross-tool import. Transcript field names not fully mapped, so telemetry is left partial.",
5
+ "detect": { "headless": ["--print"] },
6
+ "send": { "argv": ["cmd", "--print={prompt}", "--output-format=json", "--skip-onboarding"],
7
+ "stdin": { "replaces": ["--print={prompt}"], "with": ["--print"],
8
+ "note": "Verified from the headless documentation (commandcode.ai/docs/headless), read 2026-09-17: Command Code auto-detects piped input when no query argument is provided, as in `cat prompt.txt | cmd -p`; `cmd --help` (1.45.0) lists -p, --print [query] with the query optional." } },
9
+ "resume": { "argv": ["cmd", "--resume={session}", "--print={prompt}", "--output-format=json"],
10
+ "by_path": ["cmd", "--session={path}", "--print={prompt}", "--output-format=json"],
11
+ "continue_last": ["cmd", "--continue", "--print={prompt}", "--output-format=json"],
12
+ "stdin": { "replaces": ["--print={prompt}"], "with": ["--print"],
13
+ "note": "As send: the documentation says it of headless mode, whatever else the command carries." } },
14
+ "list_sessions": { "argv": ["cmd", "--resume"], "note": "interactive picker; prefer scanning ~/.commandcode/projects" },
15
+ "list_models": { "argv": ["cmd", "--list-models"] },
16
+ "options": {
17
+ "trust_none": null,
18
+ "trust_none_why": "no flag verified to deny every tool",
19
+ "model": ["--model={model}"], "effort": ["--effort={effort}"],
20
+ "effort_values": ["low","medium","high"],
21
+ "output_json": ["--output-format=json"], "max_turns": ["--max-turns={n}"],
22
+ "worktree": ["--worktree={name}"], "add_dir": ["--add-dir={dir}"],
23
+ "trust_all": ["--yolo"], "permission_mode": ["--permission-mode={mode}"],
24
+ "tools_all": ["--tools-all"], "local_only": ["--local-only"],
25
+ "bypass": {
26
+ "--yolo": { "roles": ["implementer"],
27
+ "why": "Kept: --permission-mode auto-accept approves edits and safe filesystem commands and no other shell command, and dont-ask runs only what allow rules name, which are written only in settings files (.commandcode/settings.json, ~/.commandcode/settings.json) polyctl does not write; a headless run with neither denies every write and shell command. Read on 2026-09-17 from commandcode.ai/docs/permissions and commandcode.ai/docs/headless." }
28
+ }
29
+ },
30
+ "transcript": {
31
+ "kind": "jsonl",
32
+ "path": "~/.commandcode/projects/{session}.jsonl",
33
+ "record": { "time": "timestamp", "kind": "type", "id": "id", "parent": "parentId", "text_keys": ["content","text","p"] },
34
+ "kinds_seen": ["user"], "todo": "map assistant/result/usage record shapes; then promote to full",
35
+ "checkpoints": "~/.commandcode/projects/{session}.checkpoints.jsonl"
36
+ },
37
+ "busy": { "mtime_file": "~/.commandcode/projects/{session}.jsonl", "idle_seconds": 240 },
38
+ "directives": {
39
+ "steering_files": ["AGENTS.md"], "init": ["cmd", "/init"],
40
+ "import_from": ["claude","codex","cursor","pi","opencode","gemini"],
41
+ "note": "cmd /import can seed AGENTS.md, skills, MCP and memory from another agent — useful when migrating a project into an orchestrated loop.",
42
+ "mcp": ["cmd","mcp"], "skills": ["cmd","skills"]
43
+ },
44
+ "telemetry": { "context": {"from":"none"}, "cost": {"from":"transcript","todo":"locate usage record"}, "balance": {"from":"none","note":"never estimated"} }
45
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "project_config": [".github/copilot-instructions.md", ".github/instructions", ".github/hooks", "AGENTS.md"],
3
+ "id": "copilot", "name": "GitHub Copilot CLI", "verified": "untested",
4
+ "disclaimer": "Written from documented interface, not verified against an install.",
5
+ "detect": { "headless": ["-p"] },
6
+ "send": { "argv": ["copilot", "-p", "{prompt}"],
7
+ "stdin": { "replaces": ["-p", "{prompt}"], "with": [],
8
+ "note": "Verified from Running GitHub Copilot CLI programmatically (docs.github.com/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically), read 2026-09-17: a prompt is piped to `copilot`, and piped input is ignored when -p or --prompt is given as well, so -p goes. Resuming with piped input is not documented, so resume declares none." } },
9
+ "resume": { "argv": ["copilot", "--resume", "{session}", "-p", "{prompt}"], "continue_last": ["copilot", "--continue", "-p", "{prompt}"] },
10
+ "quota": { "provider": "copilot" },
11
+ "options": { "trust_none": null, "trust_none_why": "no flag verified to deny every tool", "model": ["--model", "{model}"], "effort": null, "trust_all": ["--allow-all-tools"],
12
+ "bypass": { "--allow-all-tools": { "roles": ["implementer"],
13
+ "why": "Kept, as --allow-tool narrows nothing that matters here: the documentation tells subcommands apart only for git and gh, so the narrowest grant it documents for polyctl is shell(polyctl:*), which admits polyctl lock -- <command> and so any command, and COPILOT_ALLOW_ALL in the environment approves everything regardless. Read on 2026-09-17 from docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools and docs.github.com/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically." } } },
14
+ "transcript": { "kind": "unknown", "candidates": ["~/.copilot/history-session-state"] },
15
+ "busy": { "kind": "unknown" },
16
+ "directives": { "steering_files": [".github/copilot-instructions.md", "AGENTS.md"] }
17
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "project_config": [".cursor", ".cursorrules", "AGENTS.md"],
3
+ "id": "cursor-agent", "name": "Cursor Agent CLI", "verified": "documented",
4
+ "verified_source": "cursor.com/docs/cli (headless + using), Aug 2026 changelog; headless and reference/parameters re-read 2026-10-16, which still name the invoked command `agent` (install script at cursor.com/install), -p/--print, --force, --resume [chatId], --output-format (text, json, stream-json) and --model as declared here",
5
+ "detect": { "binaries": ["agent", "cursor-agent"], "processes": ["cursor-agent"], "headless": ["-p", "--print"] },
6
+ "important": "The invoked command is `agent`, not `cursor-agent`. The npm/binary is installed as cursor-agent but the CLI you run is `agent`. `-f`/`--force` (auto-approve) is REQUIRED for it to modify files in a headless run; without it the agent plans but changes nothing — a silent no-op that looks like failure.",
7
+ "send": { "argv": ["agent", "-p", "{prompt}", "--output-format", "json", "-f"] },
8
+ "resume": { "argv": ["agent", "--resume", "{session}", "-p", "{prompt}", "--output-format", "json", "-f"] },
9
+ "list_sessions": { "argv": ["agent", "ls"] },
10
+ "quota": { "provider": "cursor" },
11
+ "options": {
12
+ "trust_none": null,
13
+ "trust_none_why": "no documented flag denies tools in print mode",
14
+ "model": ["--model", "{model}"], "effort": null,
15
+ "output_text": ["--output-format", "text"],
16
+ "output_json": ["--output-format", "json"],
17
+ "output_stream": ["--output-format", "stream-json"],
18
+ "auto_approve": ["-f"],
19
+ "bypass": {
20
+ "-f": { "roles": ["implementer", "architect"],
21
+ "why": "Kept in every command: the headless page says print mode applies no change without --force, and the narrower approvals (permissions.allow in .cursor/cli.json or ~/.cursor/cli-config.json) live only in files polyctl does not write, cannot be given on the command line, and match a shell command by its first word, so Shell(git) admits a push. Read on 2026-09-17 from cursor.com/docs/cli/headless, cursor.com/docs/cli/reference/parameters and cursor.com/docs/cli/reference/permissions." }
22
+ }
23
+ },
24
+ "transcript": { "kind": "call-return", "note": "--output-format json returns a structured final result; also `agent ls` lists prior chats.",
25
+ "candidates_for_store": ["~/.cursor/cli","~/.config/cursor"] },
26
+ "busy": { "kind": "orchestrator-owned", "note": "print mode synchronous; Aug 2026 build retries wedged uploads on long headless sessions instead of hanging." },
27
+ "directives": { "steering_files": [".cursor/rules","AGENTS.md"], "mcp": ".cursor/mcp.json" },
28
+ "telemetry": { "cost": {"from":"call-return","todo":"confirm usage fields in json result"}, "balance": {"from":"none"} }
29
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "id": "deepseek", "name": "DeepSeek harness / CLI", "verified": "untested",
3
+ "disclaimer": "Written from documented interfaces. 'DeepSeek CLI' refers to several community and official harnesses; confirm which one is installed before relying on flags. The API is OpenAI-compatible, so an OpenAI-style adapter is a good fallback.",
4
+ "detect": { "headless": ["--prompt"] },
5
+ "send": { "argv": ["deepseek", "--prompt={prompt}"] },
6
+ "resume": { "argv": ["deepseek", "--session={session}", "--prompt={prompt}"], "note": "session support varies by harness" },
7
+ "options": { "trust_none": null, "trust_none_why": "no documented CLI mode without tools", "model": ["--model={model}"], "model_values": ["deepseek-chat","deepseek-reasoner"],
8
+ "effort": null, "effort_note": "deepseek-reasoner exposes reasoning; no separate effort flag.",
9
+ "output_json": ["--json"], "base_url": ["--base-url={url}"], "api_openai_compatible": true },
10
+ "transcript": { "kind": "unknown", "candidates": ["~/.deepseek","~/.config/deepseek"] },
11
+ "busy": { "kind": "unknown" },
12
+ "directives": { "steering_files": ["AGENTS.md"] }
13
+ }