Canvas Execute

canvas-execute (approval-gated dispatch)

Dispatcher for the Canvas auto-homework system. This skill is the execute half of the scan/execute split — it runs only after canvas-scan has produced a plan and the user has explicitly approved some subset of it.

The contract with canvas-scan

• canvas-scan wrote runs/<today>/plan.json with every pending item at user_decision: null.
• The user reviewed the plan (printed as a markdown table in the previous turn) and replied with an approval spec.
• Claude (the outer orchestrator) parsed the user's reply and invoked this skill, passing the approval interpretation as an argument or as context.

This skill's job: apply the approval to plan.json, dispatch the approved items, record the non-approved ones as deferred, finalize.

If plan.json doesn't exist or is >24h old → STOP and tell the user to run /canvas-scan first. Do not invent a plan, do not dispatch anything, do not guess.

The highest spec is canvas_scan.md §7 (batch execution after approval). Read it if unsure.

Hook guardrails (what gates execute)

All 7 hooks apply during execute:

Critical: hook 7 is the one that keeps execute honest. Without it, a session could dispatch 3 of 5 approved items and then drift off. With it, you cannot stop until every assignment in assignments.json has a result.json — either written by a sub-skill (for approved+executed) or written by this skill as status: skipped with deferred_to_next_run: true (for non-approved or skipped-at-approval-time).

Working directory assumption

The working directory is the project root (the folder you cloned this repo into; Claude Code sets cwd automatically on session start). Python helpers under src/, config under .env and courses.yaml.

What you do

0. Precondition check

TODAY=$(date +%Y-%m-%d)
test -f "runs/$TODAY/plan.json" || { echo "NO_PLAN"; exit 1; }
test -f "runs/$TODAY/assignments.json" || { echo "NO_ASSIGNMENTS"; exit 1; }

If either is missing: tell the user "No plan.json for today. Run /canvas-scan first to generate a plan, review it, then come back." Stop. Do NOT run scan inline — that's the router's job and would defeat the approval gate.

Then check plan.json freshness:

import json, datetime as dt
plan = json.loads(open(f"runs/{today}/plan.json", encoding="utf-8").read())
expires = dt.datetime.fromisoformat(plan["expires_at"])
now = dt.datetime.now(expires.tzinfo)
if now > expires:
    print("PLAN_EXPIRED")
    # tell user: "Plan is stale (>24h). Re-run /canvas-scan before executing."

If expired: STOP. Tell user to rerun /canvas-scan.

1. Handle stale marker from a prior crashed session

Before activating your own marker, check for an orphan marker from a past session:

if [ -f "runs/<past-date>/.scan_in_progress" ]; then ...

Glob runs/*/.scan_in_progress. For each match whose date is not today:

• Read that day's assignments.json
• For any assignment lacking a result.json, write {status: "skipped", notes: "session crashed before this item was processed", deferred_to_next_run: true} so the next /canvas-scan re-proposes it
• Delete the orphan marker

This keeps Stop hook from being permanently wedged by a past crash.

2. Activate today's marker (with session id)

The marker file's contents are the creating session's id, not just a touch. The Stop hook (check-router-complete.py) reads the marker contents and compares to its own event's session_id — if they don't match, the hook treats this as "another session's marker, not mine" and passes through. This is what lets a debug-only session (in the same project, never called canvas-execute) stop cleanly while another session is mid-execute.

CC must extract the current session id from the env / hook event / transcript path and write it into the marker:

import os, uuid
from pathlib import Path
import datetime as dt

today = dt.date.today().isoformat()
marker = Path(f"runs/{today}/.scan_in_progress")
marker.parent.mkdir(parents=True, exist_ok=True)

# Determine session_id. CC has its own session_id available in the runtime
# environment — check CLAUDE_SESSION_ID env var first, fall back to extracting
# from the transcript filename ($CLAUDE_TRANSCRIPT_PATH or the conversation
# transcript path), and as a last resort generate a uuid (this still works:
# the hook only requires "marker contents == event.session_id"; if execute
# stamped a uuid that doesn't match the runtime session id, the hook treats
# the session as not-the-owner and passes through, which is safe — you just
# lose the gate for this run, but no data loss).
session_id = (
    os.environ.get("CLAUDE_SESSION_ID")
    or os.environ.get("CC_SESSION_ID")
    or str(uuid.uuid4())  # safe fallback
)
marker.write_text(session_id, encoding="utf-8")

Practical note for CC: at execute time, read the most reliable session id source you have — typically the transcript path filename matches the session uuid. If you can't determine the current session id deterministically, use uuid4 as fallback; this still implements "this session vs other sessions" correctly within this single execute run.

This arms the Stop hook. Every assignment in runs/$TODAY/assignments.json must now have a matching result.json before this session can stop — for sessions whose session_id matches the marker contents. Other sessions in the same project pass through.

3. Parse user's approval + update plan.json

Read the user's approval spec. It was either:

• Passed as an argument when Claude invoked this skill (e.g. "approve all", "只做 urgent", "做 1, 3, 5")
• Or visible in the preceding conversation turn

Recognize these patterns (Chinese + English):

Ambiguous or unparseable input → STOP and ask the user once more. Do not guess. Example ambiguous input: "做前面几个" (how many is "前面"?). Answer: "请明确一下 —— 做第 1、2、3 项吗？" and wait.

Update plan.json atomically:

import json, os
plan_path = Path(f"runs/{today}/plan.json")
plan = json.loads(plan_path.read_text(encoding="utf-8"))
for item in plan["items"]:
    item["user_decision"] = determine_decision(item)  # "approve" | "defer" | "swap:canvas-X"
tmp = plan_path.with_suffix(".json.tmp")
tmp.write_text(json.dumps(plan, indent=2, ensure_ascii=False), encoding="utf-8")
os.replace(tmp, plan_path)

4. Dispatch approved items — one at a time, in order

For each item in plan.json where user_decision == "approve" or starts with "swap:", process sequentially (plan.json items are already sorted by bucket priority then by hours_left, so earliest-due-first).

For each item:

1. Determine which sub-skill to invoke:

   • user_decision == "swap:canvas-X" → canvas-X (user explicit override wins)

   • user_decision == "approve" → resolve the Skill name from proposed_skill. proposed_skill may be a short courses.yaml route value OR already a canvas-* Skill name; map it to the Skill to invoke:

     route value (proposed_skill)	Skill to invoke
     quiz	canvas-inside
     code_py	canvas-ics33
     ac_english	canvas-reading-annotation (or canvas-essay via the sub-router below)
     zybooks	canvas-zybooks
     mixed_unsupported	canvas-skip

     A proposed_skill already in canvas-* form (e.g. the LDB filter rewrites quiz items to canvas-skip) maps to itself.

   • Writing-course sub-routing: if the resolved skill is canvas-reading-annotation, run the deterministic router to decide between the short-form handler (canvas-reading-annotation, unchanged) and the long-essay handler (canvas-essay). This is a pure-Python utility — 0 LLM calls, regex + numeric comparison + Canvas API field queries.

     if proposed_skill == "canvas-reading-annotation":
         import re, yaml
         from pathlib import Path
         from src.ac_eng_router import route_ac_eng_assignment
         from src import canvas_client as cv
     
         # Pull the overlay's persona_trigger_patterns / persona_skip_patterns yaml block
         overlay_path = Path("_private/canvas-essay-app.md")
         overlay_config = {}
         if overlay_path.exists():
             text = overlay_path.read_text(encoding="utf-8")
             m = re.search(r"```yaml\s*\n(persona_trigger_patterns:.*?)\n```",
                           text, re.DOTALL)
             if m:
                 overlay_config = yaml.safe_load(m.group(1)) or {}
     
         # Look up the full assignment dict (router needs name, description,
         # points_possible, submission_types, attached_pdf_texts).
         full = next(
             (a for a in assignments_json if str(a.get("id")) == str(item["assignment_id"])),
             None,
         )
         if full is None:
             full = cv.get_assignment(item["course_id"], item["assignment_id"])
     
         sub = route_ac_eng_assignment(full, overlay_config, plan_item=item)
         if sub == "essay":
             proposed_skill = "canvas-essay"
         # else keep canvas-reading-annotation for short-form path

     If _private/canvas-essay-app.md does not exist, overlay_config stays empty — the router still works (skips Layer 2, relies on Layers 3-6). The router never raises; on any malformed regex in the overlay it logs and falls through.

2. TodoWrite: add the assignment as a todo, mark in_progress.

3. Invoke via the Skill tool. Pass a brief context line:

   "Work on <assignment_name> (course <course_name>). Work dir: runs/<today>/<work_dir>. See assignments.json and plan.json for full item details."

4. Sub-skill runs → writes its own result.json → returns.

5. Read the result.json. Mark todo completed (or keep in_progress with error note if status: error).

6. Update runs/_processed.json ledger (atomic write via .tmp + os.replace):

   ledger[f"{course_id}:{assignment_id}"] = {
       "status": sub_result["status"],
       "course_name": item["course_name"],
       "assignment_name": item["assignment_name"],
       "due_at": item["due_at"],
       "completed_at": dt.datetime.now(dt.timezone.utc).isoformat(),
       "draft_path": sub_result.get("draft_path"),
       "notes": sub_result.get("notes"),
       "deferred_to_next_run": False,
   }

7. Continue to the next approved item.

Run items sequentially (not in parallel) — Canvas writes can race, and sequential logs are easier to debug.

If the Skill tool reports the target sub-skill is not discoverable, STOP and print a clear error ("sub-skill canvas-X not found; CC was likely launched from the wrong directory"). Do NOT try to do the work inline.

5. Pause when session is running tight — report clearly and ask

Claude judges its own context budget. If roughly less than ~15 turns of capacity remain AND there are still approved items left to dispatch, break out of the loop instead of trying to squeeze in another heavy item. Half-finished work is worse than deferred work.

To pause cleanly (Stop hook requires every assignments.json item to have a result.json):

1. For each remaining undispatched approved item, write a placeholder result.json:

   {
     "assignment_id": ...,
     "course_id": ...,
     "status": "skipped",
     "notes": "paused mid-run — awaiting user decision (continue or defer)",
     "deferred_to_next_run": true
   }

   Also update _processed.json ledger with deferred_to_next_run: true. This satisfies the Stop hook.

2. Print a clear status to the user, in this shape:

   做完了：
   - #1 Quiz on Section 5 — draft_ready (runs/.../quiz_s5.json)
   - #2 Quiz on Section 6 — draft_ready (runs/.../quiz_s6.json)
   
   还没做（session 快满了）：
   - #3 Set 3 Problem 1
   - #4 Set 3 Problem 2
   - #7 Tue Wk5 HW Scan
   
   要继续做吗？
   - 回 "继续" → 我接着跑 #3，撑到哪算哪
   - 回 "defer" / "算了" / 不回 → 剩下的保持 deferred，下次 /canvas-scan 自动重现

3. End your turn. Do NOT proceed to §6 finalize yet — wait for the user's next reply.

4. On the user's next turn:

   • "继续" / "接着做" / "yes" → go back to §4 and dispatch the next undispatched item. Each successful sub-skill completion overwrites the placeholder result.json with a real one. Repeat §5 pause-check as you go.
   • "defer" / "算了" / "跳过" / silence / anything not a clear continue → jump to §6 finalize. Placeholder result.json files stay as the final state (they're already correctly marked deferred_to_next_run: true).

Rule of thumb on when to pause: if the next item's proposed_skill is canvas-ics33 (heavy, ~20 turns) or canvas-generic (heavy, ~25-30 turns — investigation + 3 sub-agent reviews) and your context window is >60% consumed → pause. If it's canvas-inside or canvas-skip (light, ~10 or ~1 turns) → probably fine to attempt one more. Trust your judgment; erring toward pausing is safer than runaway.